agentleFS
zyphr-labszyphr-labs/bounty-harness/.claude/CLAUDE.md

bounty-harness

CLAUDE.md1 starsChanged 3 months agoMITView on GitHub

The harness is deliberately small: Do not move bug bounty logic into the harness. Add or change workflows inside the relevant skill package. External tools are managed through a registry so agents never invent install commands. Commands: - bin/bb-tools list — all tools in registry - bin/bb-tools list --installed — only installed - bin/bb-tools list --missing — required by skills but missing - bin/bb-tools doctor — health check all tools - bin/bb-tools doctor --skill <skill> — health check for one…

  • Reads credentials

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Do not move bug bounty logic into the harness.

    line 22
  2. Distinctive:

    All workflows assume this PATH.

    line 56
  3. Very specific:

    When the user drops a bare URL or asks to "find everything / hunt this / run for a while," use the campaign skill instead of issuing the 13 …

    line 105
  4. Very specific:

    Every skill lives at .claude/skills/<skill>/.

    line 119
  5. Very specific:

    Always prefer bin/bb-run <skill> <workflow> after context is initialized.

    line 129
  6. Very specific:

    If multiple skills match, pick the most specific vulnerability class after recon.

    line 230
  7. Distinctive:

    Do not report scanner output as a finding until impact is verified and false-positive signals are ruled out.

    line 245
  8. Distinctive:

    Check authorization and scope before intrusive, authenticated, destructive, or high-volume workflows.

    line 249
  9. Distinctive:

    Use rate limits from context or the workflow.

    line 250
  10. Distinctive:

    Do not test explicit out-of-scope hosts.

    line 251
  11. Distinctive:

    Do not exploit data-modifying paths without approval.

    line 252
  12. Distinctive:

    Do not store secrets in logs or commits.

    line 253
  13. Very specific:

    Run gitleaks detect --source .

    line 254

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

BountyHarness Agent Guide

Architecture

Fat Skills = scripts, payloads, wordlists, runbooks, evidence rules, standards mappings, and runnable commands live in .claude/skills/.
Thin Harness = context initialization, context validation, and selected workflow execution only.
Agent Role = dispatch, triage, report. Do not invent flags or ad-hoc pipelines when a skill workflow exists.

The harness is deliberately small:

FileJob
bin/bb-initCreates .bb/context.env and .bb/context.json.
bin/bb-validateChecks context and scope file presence.
bin/bb-runRuns one command from .claude/skills/<skill>/skill.yaml. Traces every run; circuit-breaker blocks a target after repeated consecutive failures (tools/circuit_breaker.py reset clears).
bin/bb-huntAutonomous campaign: bootstraps context from a URL, then runs recon → plan → execute → report unattended (thin wrapper over the campaign skill).
bin/bb-toolsInstall, update, verify, and lock external tools.
tools/validate_skills.pyScores skill package quality.

Do not move bug bounty logic into the harness. Add or change workflows inside the relevant skill package.

Tool Registry

External tools are managed through a registry so agents never invent install commands.

FilePurpose
tools/registry/*.yamlCanonical tool definitions with install method, version/health check, capabilities, risk tier
tools/capabilities.yamlMaps capability names (e.g., subdomain_enum, crawl) to tools
tools/safety_profiles.yamlSafety tiers: passive, active-safe, intrusive, destructive-manual
bin/bb-toolsThin harness command: install, doctor, lock, verify

Commands:

  • bin/bb-tools list — all tools in registry
  • bin/bb-tools list --installed — only installed
  • bin/bb-tools list --missing — required by skills but missing
  • bin/bb-tools doctor — health check all tools
  • bin/bb-tools doctor --skill <skill> — health check for one skill
  • bin/bb-tools install --profile projectdiscovery — install PD suite
  • bin/bb-tools install --profile recon — install recon tools
  • bin/bb-tools install <tool> — install single tool
  • bin/bb-tools lock — write .bb/tool-lock.json
  • bin/bb-tools verify — verify lock against installed versions

bb-validate checks that the tool registry is populated and warns about missing tools. bb-run warns when a selected workflow needs a tool that is not on PATH.

Environment

export PATH="/opt/homebrew/bin:$HOME/.pdtm/go/bin:$HOME/go/bin:$HOME/Library/Python/3.14/bin:$PATH"

All workflows assume this PATH. Prefer Homebrew tool builds when both Homebrew and Go/Python installs exist.

RunContext

bin/bb-init writes the canonical context to .bb/context.env and .bb/context.json.

Common variables:

VariableMeaning
TARGETPrimary target domain.
PROGRAMBug bounty program name.
TARGET_HOSTHostname version of target.
TARGET_URLScheme and host URL.
OUTDIROutput directory for the current run.
EVIDENCE_DIRDefault evidence directory.
SCOPE_FILELocal authorization or scope file.
AUTH_HEADEROptional auth header for authenticated workflows.
COOKIE_JAROptional cookie jar path.
RATE_LIMITDefault rate limit.
CONCURRENCYDefault concurrency.
USER_AGENTSecurity research user agent.

Workflow-specific variables are allowed, but skill.yaml should provide safe defaults where practical. Examples: QUERY, PLAN, PLAN_OUTPUT, DOMAIN_PROFILE, COVERAGE_MATRIX, ARCHETYPES_FILE, SURFACES_FILE.

Default Workflow

For a new target with no prior recon:

1. bin/bb-init <target> --program <program> --scope-file <scope>
2. bin/bb-validate
3. bin/bb-run recon passive-subdomains
4. bin/bb-run recon live-discovery
5. bin/bb-run recon js-recon
6. bin/bb-run domain-model classify
7. bin/bb-run domain-model map-surfaces
8. bin/bb-run domain-model profile
9. bin/bb-run technique-kb match
10. bin/bb-run planner generate-plan-safe
11. bin/bb-run planner visualize-plan
12. Run selected vulnerability skills from the plan.
13. bin/bb-run reporting <workflow> when evidence is ready.

For a target with prior recon, load the most specific skill directly and use the workflows in that skill's skill.yaml.

Autonomous Campaign

When the user drops a bare URL or asks to "find everything / hunt this / run for a while," use the campaign skill instead of issuing the 13 steps by hand:

bin/bb-hunt <url> --time-budget 2h                 # active-safe by default
bin/bb-hunt <url> --scope-file <auth> --max-tier intrusive --time-budget 3h
bin/bb-run campaign status                          # progress

bin/bb-hunt bootstraps its own context (no prior bb-init needed), then runs recon → domain-model → technique-kb → planner, parses plan.json for skill priority, and executes every applicable skill workflow filtered by safety tier, then reporting. It is bounded by --time-budget, resumable, and continues past individual workflow failures.

Agent responsibilities around the campaign (see .claude/skills/campaign/SKILL.md): (1) confirm authorization; (2) use web search + vuln-intel/osint to understand the target before/while it runs; (3) monitor bin/bb-run campaign status; (4) triage candidates through the matching verify workflow and impact-verifier; (5) report only impact-verified findings. The safety ceiling defaults to intrusive but is auto-capped to active-safe unless a non-empty --scope-file is supplied.

Skill Loading

Every skill lives at .claude/skills/<skill>/.

File or directoryPurpose
SKILL.mdHuman-facing router, workflow selection, evidence notes, references.
skill.yamlMachine-executable workflow registry consumed by bin/bb-run.
scripts/Prebuilt command implementations.
runbooks/Manual triage and execution guidance.
payloads/Static payloads, test cases, or fixtures.

Always prefer bin/bb-run <skill> <workflow> after context is initialized. If you must run a command manually, copy it from skill.yaml or a runbook and preserve the same output paths.

Skill Catalog

#SkillPurpose
1reconSubdomains, live hosts, crawling, JavaScript recon, asset inventory.
2xssReflected, stored, DOM, blind XSS, CSP and context checks.
3sqliError, blind, time-based, union, and NoSQL injection probes.
4ssrfDirect, blind, parser-bypass, and cloud metadata SSRF testing.
5rceCommand injection, SSTI, LFI/RFI, and execution checks.
6authJWT, OAuth, session, MFA, password reset, and auth race testing.
7apiREST, GraphQL, BOLA/IDOR, mass assignment, and rate-limit testing.
8file-uploadExtension bypass, content-type bypass, polyglots, SVG and upload checks.
9cors-csrfCORS misconfigurations, CSRF, SameSite, and origin behavior.
10race-conditionConcurrent requests, TOCTOU, redeem/retry, and timing-window testing.
11cloudS3, bucket exposure, cloud asset, IAM, and metadata-adjacent checks.
12mobileAPK analysis, deeplinks, and cert-pinning helper workflows.
13osintEmail, username, GitHub, Google dork, and public-source discovery.
14privescLinux, Docker, SUID, capabilities, cron, and container escape enumeration.
15nuclei-scannerScope-aware nuclei template execution and result validation.
16reportingEvidence manifests, CVSS, single finding reports, and batch report export.
17ai-llmPrompt injection, tool abuse, data exfiltration, and LLM trust-boundary testing.
18modern-browserWebGPU, WASM, XS-Leaks, browser isolation, and client-side protocol edge cases.
19http-protocolRequest smuggling, cache poisoning, parser differentials, and HTTP edge cases.
20domain-modelTarget archetype classification and attack surface mapping.
21standard-catalogCanonical standards references for WSTG, ASVS, API Top 10, VRT, CWE, MASVS, KEV, and PortSwigger topics.
22coverageCoverage ledger and gap reporting across security standards.
23technique-kbStructured technique catalog with preconditions, signals, evidence, safety, and workflow mappings.
24plannerDomain-driven ranked test plan generator and visualizer.
25auto-researchPublic security knowledge import, normalization, deduplication, and candidate review.
26evaluation-harnessVulnerable-by-design fixtures and precision/recall/F1 skill evaluation.
27skill-scientistHypothesize, design, run, review, and propose skill improvements.
28personaAttacker/victim/admin persona management, credential storage, session validation.
29traffic-corpusHAR/Burp/mitmproxy traffic import, route normalization, object extraction.
30asset-graphSQLite-based persistent asset graph with delta, hotlist, and planner integration.
31cross-accountCross-persona request replay for BOLA/IDOR/tenant isolation testing.
32business-logicWorkflow state machine testing for skip, repeat, reorder, race, and invariants.
33oob-infraInteractsh-based OOB callback infrastructure for blind vulnerability detection.
34impact-verifierCandidate-to-bounty-grade verification gate with impact classification.
35agent-safetyAI agent guardrails against prompt injection in target content.
36program-memoryPer-program knowledge persistence across engagements.
37vuln-intelCVE tracking, disclosed report hunting, PoC discovery, security news aggregation.
38scope-managerScope definition, validation, versioning, and guardrails for engagements.
39campaignAutonomous end-to-end run: recon → domain-model → plan → priority-ordered multi-skill execution → reporting, from one URL, bounded by a time budget.
40cicd-securityCI/CD pipeline hunting: workflow injection, runner poisoning, OIDC theft.
41graphql-auditGraphQL security: introspection, batching abuse, IDOR via aliasing, depth bombs.
42web3-auditSmart contract audit: DeFi bug classes, Foundry PoC, kill signals.
43meme-coin-auditToken rug-pull detection, Solana SPL risks, DEX liquidity attacks.
44triage-validationPre-report validation gate: 7-question gate and submission checklists.
45identity-domainNo-creds identity infra recon: NTLM leaks, ADCS/ADFS endpoints, Entra tenant metadata, SPN OSINT.
46binary-analysisDesktop/native binary triage and MCP-driven x64dbg dynamic analysis for shipped executables.
47enrichmentPost-processing enrichment for verified findings — report drafts, PoC diffs, and triage chips (Kritt-style post-scripts with supplemental re-runs).
48sastSAST integration with SARIF parsing (Semgrep, Trivy, Bearer)

Dispatch Rules

User intentFirst skill
Bare URL, "find everything", "hunt this", "run for a while", autonomous/unattended scancampaign (bin/bb-hunt <url>)
New target, scan domain, enumerate, map attack surfacerecon then domain-model then planner
XSS, cross-site scripting, JavaScript injection, CSP bypassxss
SQL injection, NoSQL injection, database error, blind SQLsqli
SSRF, metadata endpoint, internal URL fetch, webhook URL fetchssrf
RCE, command injection, SSTI, LFI, deserializationrce
Login, JWT, OAuth, session, MFA, password resetauth
REST, GraphQL, BOLA, IDOR, mass assignment, rate limitapi
File upload, SVG, polyglot, content type, extension bypassfile-upload
CORS, CSRF, SameSite, origin reflectioncors-csrf
Race condition, concurrent requests, TOCTOUrace-condition
S3, bucket, IAM, cloud asset, metadatacloud
APK, IPA, Android, iOS, deeplink, Fridamobile
OSINT, email, username, GitHub dork, Google dorkosint
Privilege escalation, SUID, capabilities, Docker escapeprivesc
Nuclei, CVE scan, template scan, automated vulnerability scannuclei-scanner
Report, writeup, PoC, evidence exportreporting
LLM, prompt injection, tool abuse, AI agent securityai-llm
WebGPU, WASM, XS-Leaks, browser isolationmodern-browser
HTTP smuggling, cache poisoning, parser differentialhttp-protocol
Standards lookup or mappingstandard-catalog
Coverage gaps or quality dashboardcoverage
Technique lookup, matching, or precondition analysistechnique-kb
Ranked plan from recon dataplanner
Import new public researchauto-research
Measure skill precision/recall/F1evaluation-harness
Propose new skill experimentsskill-scientist

| Authenticated testing, multi-account, session management | persona then cross-account | | Import traffic, build replay corpus | traffic-corpus | | Asset relationship graph, hotlists, delta analysis | asset-graph | | IDOR, BOLA, tenant isolation, cross-account diffs | cross-account | | Workflow abuse, state transitions, business invariants | business-logic | | Blind vulns, OOB callbacks, interactsh management | oob-infra | | Verify finding impact before reporting | impact-verifier | | Protect AI agent from prompt injection | agent-safety | | Program knowledge, false-positive history | program-memory | | Latest CVEs, disclosed reports, PoCs for target | vuln-intel | | Scope validation, out-of-scope guardrails | scope-manager | | ADFS, certsrv, NTLM leaks, Entra tenant, SPN leaks on scope | identity-domain | | Analyze a downloadable desktop binary / packed executable | binary-analysis |

If multiple skills match, pick the most specific vulnerability class after recon. If no skill matches but a domain is provided, start with recon. If scope is unclear, ask for authorization before intrusive testing.

Evidence Standard

For every confirmed finding, collect:

ArtifactSaved as
Full request with headersevidence/<finding>/request.txt
Full response headers and bodyevidence/<finding>/response.txt
Screenshot or visual proofevidence/<finding>/screenshot.png
Reproduction command or scriptevidence/<finding>/poc.sh
Timestampincluded in manifest or filenames
Tool versionsevidence manifest

Do not report scanner output as a finding until impact is verified and false-positive signals are ruled out.

Safety Rules

  • Check authorization and scope before intrusive, authenticated, destructive, or high-volume workflows.
  • Use rate limits from context or the workflow.
  • Do not test explicit out-of-scope hosts.
  • Do not exploit data-modifying paths without approval.
  • Do not store secrets in logs or commits.
  • Run gitleaks detect --source . --no-git -v before committing generated evidence that could contain tokens.

Validation

make test
python3 tools/validate_skills.py

Expected healthy state: all skills pass the validator and Python scripts compile.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.