HackAgent: a red-team harness for LLM agents, judged by a second LLM

The gap HackAgent targets: agents that act, not models that answer

Most prompt-security tooling was built around a single request and a single response. An agent is a different object. It holds a goal, calls tools, and can be redirected mid-task. HackAgent's README names four threat classes it automates against: prompt injection, jailbreaking, goal hijacking and tool misuse. The fourth is the one that separates this project from a chatbot filter test. Tool misuse only exists if the agent has tools, and the README's framing assumes it does. The intended user is a security researcher, a developer or an AI safety practitioner who has an agent in a repository and wants to know what a hostile input can make it do. The README also states the constraint plainly: HackAgent is for authorized testing only, and the Do and Don't list puts testing your own agents and authorized pentesting on one side, and testing systems without permission on the other. That boundary is not decoration. A tool that generates jailbreak prompts against a third-party endpoint is a different legal object from one that generates them against your own staging deployment.

The pipeline: generator, attack engine, target, judge

The architecture table in the README lists four components. The Attack Engine orchestrates and names its techniques: AdvPrefix, AutoDAN-Turbo, PAIR, TAP, FlipAttack, BoN, h4rm3l, CipherChat, PAP and Static Template. The Generator is an LLM role that writes adversarial prompts. The Judge is a second LLM role that decides whether an attack bypassed the target's safety measures. The Target Agent is your system under test, reached through one of the supported frameworks. Datasets supply the seed material, either as pre-built benchmark presets or as custom JSON loaded from HuggingFace, a file, or a URL. The data flow is therefore a loop, not a scan: the generator produces a prompt, the engine sends it to the target, the judge reads the response and scores it, and the outcome feeds the next iteration for the iterative techniques. Two consequences follow from that shape. First, the number of model calls per campaign is a multiple of the number of attempts, and the judge is a second model on top of the generator and the target. Second, the verdict is an LLM judgement, not an assertion. If your judge is weak or aligned toward leniency, your findings shift with it. The README does not document a judge-validation procedure, so treat judge choice as an experimental variable you control rather than a fixed property of the tool.

Install paths: pip, or a per-platform archive with a Playwright caveat

The README gives a three-command install: create a virtual environment with python3 -m venv .venv, activate it, then pip install hackagent. Python 3.10 or later is required, per the badge. The README states that no API key is required and that it works locally out of the box, which is consistent with local SQLite reporting but does not mean the generator and judge run without a model. For machines without Python, each GitHub release ships a self-contained archive: hackagent-<version>-linux-x86_64.tar.gz, hackagent-<version>-macos-arm64.tar.gz, hackagent-<version>-macos-x86_64.tar.gz, and hackagent-<version>-windows-x86_64.zip. Extract and run the hackagent launcher inside the folder, and keep the folder intact because the launcher loads libraries next to itself. There is one documented exception. The WEB provider drives a real browser through Playwright, and the README notes that Playwright's browser binaries cannot be embedded in the archive or the PyPI package, so you must run playwright install once before using hackagent web-based targets. That is the only subcommand the README shows by name. Reporting is toggled by mode: local mode writes results to SQLite and serves a built-in dashboard through hackagent web, while cloud mode syncs runs to app.hackagent.dev when an API key is configured. If you run in cloud mode, results leave your machine, which is worth deciding before the first campaign rather than after.

Where the design costs you: judge variance, token spend, and thin docs

The judge is the weak point. An LLM deciding whether a jailbreak succeeded has no ground truth to check against, and the README offers no calibration guidance, no agreement metric against human labels, and no recommended judge model. Two runs with different judge models can produce different pass rates on identical target responses. For a research writeup that may be acceptable if you report the judge alongside the number. For a CI gate it is not, because a flaky gate gets disabled. The second cost is spend. Every technique in the Attack Engine that iterates multiplies calls, and you are paying for three roles at once: generator, target, and judge. The README does not publish per-technique call counts, so budget by running a single technique against a trivial target first and reading the SQLite results before launching a full preset. The third issue is documentation depth. The README names ten attack techniques and four frameworks but documents the configuration surface for none of them. There is no example of a target adapter, no config file schema, and no worked campaign in the README itself. The docs site and the API schema are linked, and that is where the missing detail presumably lives, but a reader of the README alone cannot wire up a target without going there. Version cadence is brisk: v0.10.1 in May 2026, v0.11.0 in July, v0.12.0 later in July, with the last push to main in September 2026. A pre-1.0 project moving that fast will rename things, so pin the version in your environment rather than tracking main.

Alternatives and the actual difference in approach

The closest well-known comparison is Garak, an LLM vulnerability scanner. The difference is the unit of analysis. Garak probes a model endpoint with a large library of static and semi-static probes and reports hit rates, which is fast, cheap and reproducible because the probe set is fixed. HackAgent targets an agent through a framework adapter and generates prompts with an LLM during the run, which is slower, costlier, and non-reproducible in the strict sense, but it can reach behaviour that a fixed probe library cannot: multi-turn goal drift, tool-call sequences, and attacks that adapt to the target's refusals. If your question is whether a model will emit disallowed text, a fixed probe set answers it more cheaply. If your question is whether your LangChain agent can be talked into calling a tool it should not, the fixed probe set has nothing to say, because the probe does not know your tool schema. A second alternative is writing the harness yourself against the OpenAI SDK. That gives you full control over the judge and the scoring, at the cost of reimplementing the ten techniques listed in the Attack Engine table. The honest framing is that HackAgent's value is the technique library and the framework adapters, not the loop, which is easy to write and hard to write well.

Licence, maintenance and what a fork inherits

HackAgent is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes. It also includes an explicit patent grant, which matters if you plan to build a product around the attack engine. The repository carries a SECURITY.md and a responsible-disclosure document under docs/docs/security, and the README's disclaimer states the authors are not responsible for misuse. None of that is legal advice; if you intend to redistribute a modified copy or run campaigns against systems you do not own, get your own reading. On maintenance, the release history shows roughly six to eight weeks between minor versions across three releases in 2026, and the README documents commitizen and ruff badges, which suggests conventional commits and enforced linting. That is a reasonable signal about process discipline, though it says nothing about whether a given attack technique will keep working as target frameworks change their APIs. The upgrade cost is concentrated in one place: target adapters. Attack techniques are internal to the project, but an adapter for LangChain or the OpenAI SDK breaks when those libraries break, so pin both HackAgent and your target framework, and re-run one known campaign after each bump to confirm the adapter still reaches the agent.

Editorial conclusion

Adopt HackAgent if you own the agent under test, can point it at a LangChain, OpenAI SDK, LiteLLM or Google ADK target, and are willing to pay for generator and judge tokens. Do not adopt it if you need deterministic, reproducible verdicts or a scanner that runs without an LLM in the loop. Before trusting any result, verify three things in your own environment: that the judge model is not the same model as the target, that a known-benign prompt is scored as a pass, and that your SQLite results file is where you expect it after a run.

Official sources

1. AISecurityLab/hackagent on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases