OPEN SOURCE DEEP DIVE
Claude-BugHunter: Agent Skills and Orchestration for Authorized Security Testing
A reusable Agent Skills framework for authorized security testing, encoding recon, triage, validation, and reporting with code-enforced scope.
1. Positioning: a reusable knowledge system for authorized security work
Claude-BugHunter is not an autonomous attack button. It is a structured body of security-testing knowledge assembled for authorized bug bounty programs, web application assessments, and external red-team engagements. Its central idea is to encode the judgments that experienced testers repeat across engagements: which class of evidence matters at a given surface, when a candidate should be rejected, how to keep testing inside an agreed scope, and what a useful report must contain.
The repository combines four layers. Methodology skills establish workflow discipline and red-team habits. Specialized hunting skills cover web application classes, enterprise identity platforms, infrastructure control planes, mobile reconnaissance, and reporting. Validation and evidence-hygiene skills turn observations into defensible findings. A deterministic Python engine handles scope checks, surface mapping, ranking, dispatch, state, and reporting. The current snapshot contains 83 skills, 15 slash commands, and 681 patterns distilled from public reports, with 433 patterns individually cited and auditable.
The licensing reflects that split. Source code is MIT-licensed, while methodology documents, wordlists, and other written content use CC BY 4.0. For teams evaluating reuse, that distinction is operationally important: software integration and editorial reuse have different obligations.
The project is therefore best understood as a workbench for a competent operator. It supplies context and orchestration, but it cannot establish authorization, interpret every business process, or accept responsibility for a finding. Those remain human decisions.
2. Skill and command architecture: progressive context instead of one enormous prompt
The core content lives in skills. Each skill has a name, a routing description, and a Markdown body. The hunting layer is split by vulnerability class, framework, or enterprise product rather than compressed into a general “security” instruction. Identity platforms, virtualization control planes, VPN appliances, API authorization, file handling, authentication flows, and business logic each receive separate material. This structure supports progressive disclosure: an agent can load the few references relevant to the current endpoint and technology signature instead of carrying the entire repository in every context.
The 15 slash commands represent workflow entry points. Scope, reconnaissance, surface mapping, hunting, validation, reporting, and memory maintenance each have an explicit step. Skills answer “what should I examine on this kind of surface?”; commands answer “where am I in the engagement and what should be produced next?” That separation is useful because the same knowledge can support a conversational session, a scripted command-line run, or a more constrained review process.
The repository also ships a CLI with deterministic reconnaissance, surface, classification, triage, and report commands. It is intended for repeatable discovery, laboratory verification, and scheduled jobs. The command-line path does not eliminate human judgment. In particular, the triage command checks whether finding text contains evidence for the seven validation questions; it is a keyword-based gate, not a semantic proof that a vulnerability exists. A structured pass still needs an operator to review the actual request, impact, and program rules.
Source attribution is visible throughout the architecture documentation. Most skills are original, some are community contributions, and a smaller set is vendored from an upstream project. That provenance matters in security tooling because two skills with similar names may represent very different assumptions, maintenance histories, and quality levels.
3. The deterministic engine: map the cheaply observable surface before spending on agents
The engine’s default run is reconnaissance, ranking, and mapping. It deliberately stops before active testing. Deterministic Python and external tools collect service fingerprints, JavaScript endpoint references, historical parameters, OpenAPI descriptions, and redacted secret indicators. Ranking assigns each work item a priority based on its vulnerability class, parameter context, and discovery source. Mapping turns the ranked surface into an arsenal document: each endpoint or parameter is paired with the relevant hunting skill and a starting request.
This ordering is one of the project’s strongest design choices. Breadth-first discovery is inexpensive, repeatable, and easy to audit. Language-model judgment is reserved for the smaller set of areas that appear worth investigating. A default run produces a local map without launching hunting agents; the operator must explicitly add the hunt option before the engine dispatches active work. Parallel execution, validation, and confirmation are layered on only after that decision.
The engine does not pretend that every phase requires a model. Passive enumeration, live probing, endpoint extraction, parameter discovery, classification, scope filtering, state writes, and de-duplication are ordinary code. That makes failures easier to reproduce and lets the operator inspect the map even when no model budget is spent.
The CLI follows the same philosophy. Reconnaissance writes a manifest and a live-host report. Surface ranking reads that manifest. Classification uses URL patterns and skill descriptions to propose relevant classes. Each output is a handoff artifact, not a hidden chain of model calls.
4. Scope and safety: real code enforcement, but not a hard sandbox
The scope module accepts domains, wildcard domains, CIDR ranges, and regular expressions. Its policy is default-deny and deny-wins: a target must match an inclusion rule and must not match an exclusion rule. The engine checks scope when reconnaissance discoveries are added and again before an active test is dispatched. That second check is important because it prevents a discovered but out-of-scope host from becoming a work item merely because it appeared in a page or parameter.
In the default active mode, the rules injected into every hunting agent require read-only, non-destructive behavior. The instructions prohibit sending email, creating accounts, writing or deleting data, purging caches, flooding targets, and exercising exposed credentials. A separate intrusive flag must be enabled before those constraints change.
The engine also performs a deterministic audit after a finding. It scans the request, evidence, and reported contacted hosts for addresses outside scope and flags any mismatch for review. This is a useful defense-in-depth signal, but it is not containment. The audit happens after the agent has produced the evidence; it cannot undo a request that already crossed the boundary.
Most importantly, the active agents are launched with permission checks bypassed and with broad command-line, network, and Burp access. The repository says this directly, and reviewers should not soften it into “sandboxed execution.” The code-enforced scope gate and instruction-level read-only policy reduce accidental drift, but a production deployment still needs independent egress controls, isolated test identities, rate limits, immutable logs, and a human stop authority. Scope validation is a control, not the whole security architecture.
5. State and memory: long engagements become inspectable artifacts
Long-running assessments fail in ordinary ways: a session ends, context is lost, a researcher changes shifts, or a promising observation is separated from the evidence that explains it. The engine creates a directory per engagement and persists the current phase, targets, discovered surface, tested items, candidates, confirmed findings, logs, and evidence. The primary state file is written through a temporary file and atomic replacement, so an interrupted process does not leave a half-written JSON document in the normal path.
This state model makes resumption and review possible. A fresh process can reload the worklist and continue a later phase without reconstructing the prior conversation. A reviewer can compare what was discovered, what was tested, and why a candidate was promoted or rejected. The evidence directory and append-only log make the report traceable to concrete artifacts.
Cross-engagement memory is optional. Confirmed findings are de-duplicated by host, URL, parameter, and vulnerability class. Negative outcomes are aggregated by technology-stack signature and class. After five negatives with zero confirmations for the same stack and class, the engine may skip that class on later work under the same signature. This can save tokens in repetitive engagements, but it is a heuristic. Incorrect fingerprints or a narrow historical sample may suppress a productive path, so memory should be audited as a cost optimization rather than treated as evidence that a class is impossible.
The memory design is also privacy-sensitive. The ledger is stored outside the repository by default, but it can contain target names, URLs, finding categories, severity, and evidence references. Teams should define retention, access control, encryption, and deletion rules before using it across client engagements.
6. Multi-harness support: portable knowledge, partially portable orchestration
The skills use the common agent-skills format, so the same Markdown knowledge can be installed into Claude Code, OpenAI Codex, OpenCode, Hermes, and Google AntiGravity. The installation scripts target each harness’s skill directory, and Burp MCP configuration can be translated into the local configuration format. This gives teams a practical migration path when models or command-line environments change.
The repository is candid about what does not move. The 83 skills and the Burp server integration are broadly portable. Claude Code-specific slash commands, the plugin marketplace flow, and the hunt-dispatch subagent routing do not automatically transfer. Other harnesses receive the knowledge layer, not an identical orchestration experience. The Python engine can run independently, but its default agent adapter invokes the Claude command line, so a model change requires an integration review rather than a simple directory copy.
The larger architectural lesson is to separate four concerns: domain knowledge, workflow control, model adapters, and external tool access. A new model should not force a rewrite of the reference material. A change in Burp or another tool should be isolated to the integration layer. Scope policy and audit logic should remain in deterministic code that is easier to test and inspect than a long instruction prompt.
7. Evaluation: a working harness, but not yet evidence of broad capability gain
The public evaluation compares the same model with skills enabled and disabled. The only populated baseline uses three OWASP Juice Shop challenges. Both conditions solved all three. The skills-off run used a median of two turns and cost 0.178 dollars; the skills-on run used three turns and cost 0.254 dollars. That result validates the reset, execution, and self-grading loop. It does not show that the skill bundle improves problem solving on familiar targets. On this sample, the extra context increased turns and cost.
The repository also contains a PortSwigger Academy adapter, which is a more useful direction because those labs are less likely to be memorized. However, launching instances requires Academy credentials and manual browser interaction, and the required comparative baseline is not populated. Before making claims about skill value, the project needs more target diversity, repeated runs, confidence intervals, and scores that separate discovery from validation and reporting quality.
Coverage evidence has similar limits. The repository indexes 91 CVE identifiers, but its generated snapshot shows zero coverage among 53 recent CISA KEV entries from vendors considered in scope. Of the 681 disclosed-report patterns, 433 have individually auditable descriptions. The remaining material may still be useful, but it cannot be independently checked at the same level. “Battle-tested” appears as an author claim on the project page; the public comparison does not establish that claim across organizations, business logic, or complex production systems.
These limits do not make the project uninteresting. They make its contribution more precise: it demonstrates a thoughtful way to package security knowledge and deterministic workflow around an agent, while leaving a concrete evaluation program for others to continue.
8. Responsible deployment: authorization, minimum impact, and human review come first
Claude-BugHunter is appropriate for security teams working on assets they own or have explicit written permission to assess. It can help organize a program’s scope, improve consistency in reconnaissance, preserve evidence, surface knowledge that might otherwise be missed, and produce a more reviewable work record. It is also a useful reference for builders outside security because the same patterns apply to any high-impact agent: deterministic preparation, opt-in execution, durable state, explicit policy boundaries, and artifacts that a human can inspect.
The tool is not authorization. A configuration file does not create legal permission, and a successful scope match does not prove that a test method is allowed by the program. Before deployment, a team should establish verified engagement terms, explicit allow and deny lists, isolated accounts, rate limits, data-handling rules, an emergency stop process, and a named human owner. State-changing tests should remain off by default and require approval. Evidence containing personal data, customer records, or third-party service data should be redacted and retained only as long as necessary.
The project is most valuable when it strengthens the operator’s review process rather than replacing it. Its deterministic map shows where effort may be worthwhile. Its scope gate reduces a specific class of dispatch errors. Its state makes a long engagement auditable. None of those controls removes the need to verify impact, follow platform rules, or stop when a proposed test would cross an operational boundary. The repository is available at github.com/elementalsouls/Claude-BugHunter.