VulnClaw: an LLM-driven penetration testing CLI built on MCP tool calls

The problem VulnClaw targets: tool selection, not tool scarcity

A penetration tester does not lack tools. The bottleneck is deciding which one to run next against what, and then reading the output well enough to pick the following step. VulnClaw takes that decision layer and hands it to a language model. The README frames the loop as four rounds: information gathering (fingerprinting, port scanning, directory enumeration), vulnerability discovery (injection points, known CVEs, misconfiguration), exploitation (PoC validation, privilege acquisition), and report generation with a Python PoC script. The intended user is someone doing authorized testing, CTF competition, security teaching or red team exercises, who types a target in natural language and lets the agent choose the tools. That is a narrower claim than "automated pentesting" and a more defensible one. The project is a Python package, MIT licensed, installable from PyPI, and it also ships a web UI on 127.0.0.1:7788 and a TUI workbench.

How the agent loop actually works: AgentState, evidence, and two gates

The default engine is described as model-led, similar in shape to Claude Code or Codex: the model decides the next step, when to call a tool, when to finish, when to ask, and when to declare no path forward. There is no fixed round count in the solve mode. Tool results are written into AgentState.evidence with the raw text preserved, while the active context receives only a high-signal preview by default; the model retrieves the original with evidence_search and evidence_view. Two mechanisms sit on top of that. The first is a lightweight correction layer that records repeated calls, failures, elapsed time and new findings before and after each tool call, suppresses repeated reads of the same evidence range, and triggers a stall guard when consecutive evidence turns come back empty. The second is the anti-hallucination gate: a claimed flag or conclusion is only accepted if it appears character for character in real tool output. That gate is the single most consequential design decision in the project, because a model that can invent a flag will end a CTF run with a false success. A separate NO_PATH gate blocks the model from declaring a dead end while high-signal material such as source sinks, forms and parameters, request surface, local proof or response differences remains unexplored.

MCP services and the built-in tool surface

VulnClaw connects to four MCP services. The fetch and memory services are local implementations that work out of the box; chrome-devtools and burp point at external MCP servers for browser automation and HTTP capture and replay. On top of MCP, the README lists a set of built-in tools. http_probe_batch compares multiple URL, parameter, header, body or raw URL variants in one call and returns full response bodies by default, printing the actual request surface (method, URL, params, headers, cookies, body) into model-visible output. Traffic evidence is stored per run scope as an append-only JSONL index plus raw request and response files under evidence/traffic/, with traffic_list, traffic_view, traffic_repeat and traffic_sitemap tools reading and writing it directly. source_extract re-reads historical evidence and pins dangerous sinks, forms and endpoint signals. shell_command exists for local verification such as php -r deserialization checks or rg file searches, with raw stdout and stderr written to evidence. runtime_diff_probe targets cases where a regex or string filter disagrees with the runtime parser, generating candidates the filter misses and the parser accepts. python_execute is available for payload construction and response parsing. There is also a codec tool covering 29 operations including Base64, Hex, URL, AES, JWT and Morse, so the model does not guess at encodings.

Getting it running: config keys, doctor, and the Docker caveat

Installation is pip install vulnclaw, or a source install with git clone followed by pip install -e . Python 3.10 or newer is required. Setup is four commands: vulnclaw config provider minimax (the README also lists openai, anthropic, deepseek, zhipu, moonshot, qwen, siliconflow and ollama), then optionally vulnclaw config set llm.base_url and llm.model for a custom endpoint, then vulnclaw config set llm.api_key with your key. There is an alternative path, vulnclaw login, which the README describes as a ChatGPT subscription browser login requiring no API key, and it explicitly points at docs/keyless-auth.md and warns about terms-of-service risk. After that, bare vulnclaw opens the CLI or REPL, and vulnclaw tui opens the workbench. Environment checking is vulnclaw doctor, which reports Python and Node.js versions, whether npx and nmap are present, the provider, auth mode, credential status, base URL and model, and the enabled MCP services with priority markers. The Docker route uses cp .env.example .env, then docker compose up --build, with state persisted to the /data volume. The README carries a warning that matters: inside the container, localhost means the container itself, so scanning a host service requires host.docker.internal.

Where it stops being the right tool

The README is unusually direct about one limitation: python_execute is described as a high-risk experimental capability that should not be treated as a strong isolation sandbox. If your threat model requires untrusted code to run in a real sandbox, this tool is the wrong place to get it. A second limitation is structural rather than stated. The whole system depends on a language model choosing tools and interpreting output, which means variance between runs and between providers. The correction layer and the stall guard exist precisely because models loop, repeat reads and give up early; the presence of those guards is evidence that the failure modes are real. Third, the persistent mode runs cycles of 100 rounds by default across 10 cycles, which is 1000 rounds, and generates a report each cycle. That is a lot of model calls and a lot of traffic against a target. Fourth, the skill system changed shape: the 50 skills covering CTF, web, internal network, reverse engineering and vulnerability validation are now exposed only as a reference index, and the model has to call load_skill_reference to read the body. The README states this is no longer a mandatory script injected into context. That is a reasonable choice, but it means skill quality now depends on the model deciding to look, and a model that does not look gets none of that knowledge.

How it differs from a scripted scanner such as Nuclei

The closest comparison in kind is a template-driven scanner like Nuclei. Nuclei runs a fixed set of YAML templates against a target and reports matches; the detection logic is written by a human in advance, the output is deterministic, and the same input produces the same result. VulnClaw inverts all three properties. There are no templates in the detection path; the model picks the tool and constructs the request. Output varies with the provider and the sampling. And the interesting work happens when a template would not have matched, which is exactly the case runtime_diff_probe is built for: a filter that strips a pattern while the underlying parser still accepts it. The trade is real in both directions. Nuclei gives you reproducibility and a low marginal cost per target. VulnClaw gives you improvisation on targets where no template exists, at the cost of nondeterminism and a model bill. They are not substitutes, and running VulnClaw where a template would have sufficed is an expensive way to get a less reliable answer.

Maintenance, versioning and the licence

The repository is active, not archived. The most recent push and the v0.3.9 release both fall on 2026-09-05, with v0.3.8 about a month earlier and v0.3.7 five days before that. The version cadence suggests frequent small releases rather than long stabilization windows, so pinning a version for a team deployment is worth considering. Upgrading means pip install --upgrade vulnclaw, and because configuration lives in the config store rather than the package, a provider or model change survives the upgrade; what does not necessarily survive is tool behaviour, since the tool surface has grown across 0.3.x releases. The project is MIT licensed, which permits commercial and closed-source use and modification, and requires the licence text and copyright notice to be preserved. That is the extent of what can be said from the repository metadata. Whether an LLM-driven tool that sends target data to a third-party API provider fits your engagement terms is a separate question, and the answer depends on your contract and your provider, not on the licence.

Editorial conclusion

Adopt VulnClaw if you already run authorized tests or CTF work and want the model to drive tool selection rather than you typing every command; its evidence gate and traffic replay tools are the parts worth evaluating first. Do not adopt it as an unattended scanner against production, and do not treat the python_execute tool as a sandbox, because the README says it is not one. Verify three things before trusting a run: that vulnclaw doctor reports your provider and MCP services as enabled, that evidence/traffic/ is actually being written on your target, and that any flag or finding the model reports appears verbatim in the raw tool output.

Official sources

1. License: MIT
2. Netw0rkNoob/VulnClaw on GitHub
3. Project website
4. README
5. Releases