Bug Hunt Planner

Use this skill to turn a target, scope, specialty, or area of interest into a practical vulnerability hunting plan. Use conventional practitioner language: scope, recon, discovery, enumeration, fingerprinting, mapping, scanning, probing, fuzzing, exploitation, impact, reporting, retesting, and monitoring. See GLOSSARY.md for shared term definitions.

Do not assume active testing is allowed. Start passive, keep scope explicit, and escalate only under target authorization plus a matching durable approval for the specific action — a target grant establishes scope, not technique authority (see docs/durable-approvals.md).

Approval gates (summary; details in Discovery Lanes and below): every plan must mark each experiment passive or approval-gated. Active scans, fuzzing, exploit payloads, credential tests, browser mutation, downloads, writes, and shell commands require target authorization plus a matching durable approval per docs/durable-approvals.md. Record authorization assumptions in the plan's Scope, and route durable Evidence through the Evidence Interface (src/server/evidence/artifact-service.ts) rather than terminal text.

Handoffs: Feed output Leads and Experiments into web-inspection-forensics (web surface), reverse-engineering-analysis (binaries/bundles), or exploitation-sandbox (PoC). Start from risk-discovery when your input is a broad request like "find the highest-risk areas." Start from proactive-security-strategy when your input is a CVE or patch rather than a live Target.

Quick Start

1. Define scope: program rules, assets, identities, environments, rate limits, excluded actions, proof limits, and reporting requirements.
2. Pick the specialty: web, API, mobile, cloud, network, internal/AD, binary, firmware, supply chain, smart contract, AI/LLM, or mixed.
3. Run the repeatable hunt spine: attack-surface mapping -> vulnerability hunting -> business-logic/API review -> secrets and sensitive-data review -> reporting and proof.
4. Build a baseline map: assets, endpoints, versions, identities, trust boundaries, inputs, outputs, dependencies, and exposed admin/control surfaces.
5. Generate leads: changed surface, complex input, weak boundary, high-value data, privileged action, parser, auth/session edge, deserialization, file handling, SSRF-like egress, tenant isolation, or dependency risk.
6. Convert each lead into an experiment: question, hypothesis, prediction, method, tool, stop condition, safety limit, and expected proof.
7. Run the smallest useful test, record observations, then branch: deepen, pivot, chain, report, monitor, or discard.

Canonical Loop

Narrow a promising surface

Partition a large surface by the component that actually enforces identity, input interpretation, or state, then compare representative paths before going deep. A large authentication API might split into legacy/current routes, direct/SDK access, interactive/service identities, recovery flows and batch operations. Rank these by observed complexity, recent changes, attacker control and consequence, with a cheap check that can distinguish each lead from intended behavior.

Move from subsystem to boundary to operation to input/state. Write the hypothesis as a causal prediction with a counterexample that would refute it. Compare official versioned documentation, SDK defaults and source, and observed errors when an integration's contract is unclear. Missing documentation is an open question; surprising error behavior is evidence to investigate. Neither is itself a vulnerability. Use spec-implementation-review to trace requirements and implementation.

After each result, explicitly choose to narrow further, examine a sibling, change method, or return to another mapped surface. Keep unexplored branches visible. Do not spend the entire budget mutating one input after the evidence points elsewhere. Fuzz state sequences and environment behavior when byte mutation misses the suspected mechanism; choose an oracle that can observe the relevant failure.

Automate a repeatable experiment with a suitable existing tool or small script when that improves evidence. Metasploit modules and resource scripts still require inspection of effective targets, options, payloads, side effects and cleanup; a module named "check" is not proof that it is passive. Preserve approvals for the actual action.

For dependency choice, unfamiliar publishers, release changes, or worsening threat reports, load package-risk-review. Verify generated package names against the intended project and registry before recommending installation.

Before reporting a serious candidate, hand a separate reviewer the hypothesis, scope, raw evidence, counterevidence and remaining approval/budget limits. Their goal is to reconstruct the claim and decide accepted, rejected or missing proof. Require attacker control, supported reachability, a demonstrated security consequence, exclusion of harness or environment errors, and a stated duplicate-check scope. Keep the reviewer free to reject the candidate; feed that disposition back into discovery. If an independent reviewer is unavailable, preserve the candidate and disclose the missing validation rather than silently self-certifying it.

Evaluate each branch

Use this loop for every branch:

1. Observe: gather facts from docs, public data, captures, code, binaries, logs, traffic, responses, or diffs.
2. Model: describe the system, trust boundary, input path, state transition, or privilege relationship.
3. Hypothesize: state one testable failure mode and why it might be reachable.
4. Experiment: choose the least invasive tool or manual test that can falsify the idea.
5. Evaluate: decide whether the result is confirmed, promising, ambiguous, noisy, blocked, or dead.
6. Act: report, reproduce locally, chain with another primitive, broaden recon, narrow the test, or add monitoring.

Stage Vocabulary

• Scoping: rules, permission, assets, accounts, safe limits, proof expectations.
• Reconnaissance: broad information gathering from public, passive, or provided sources.
• Discovery: finding assets, routes, files, packages, services, identities, flows, and dependencies.
• Enumeration: systematically listing instances of a known thing, such as endpoints, parameters, buckets, ports, roles, or packages.
• Fingerprinting: identifying technology, versions, frameworks, cloud services, protocols, build systems, and behavioral traits.
• Mapping: connecting components, data flow, auth flow, trust boundaries, privileges, and attack paths.
• Scanning: automated checks across known surface; useful for coverage, noisy when over-trusted.
• Probing: small manual tests to learn behavior without attempting full exploitation.
• Fuzzing: generated or mutated input exploration for parsers, APIs, binaries, smart contracts, and state machines.
• Validation: proving reachability, controllability, impact, and repeatability within program rules.
• Impact analysis: explaining consequence, affected data/action, privilege change, blast radius, and business meaning.
• Reporting: clear reproduction, evidence, severity rationale, cleanup, and remediation hints.
• Retesting: verifying the fix and checking nearby variants.
• Monitoring: watching assets, versions, commits, releases, docs, APIs, and behavior for drift.

Repeatable Web/API Hunt Spine

Use this process when the user asks for a full bug hunt, first-pass target sweep, or "find issues" workflow over a web or API Target. It keeps the common bug bounty sequence, but converts every step into ExploitHunter's scoped, evidence-backed, approval-aware model.

1. Attack-surface mapping. Combine multiple allowed sources instead of trusting one source: program scope, user-provided assets, DNS and certificate records, prior captures, route maps, robots/sitemaps, crawl output, APIs, JS bundles, source maps, packages, and observed technologies. Save source provenance and normalize the map before testing.
2. Liveness and fingerprinting. Identify which hosts, routes, ports, frameworks, APIs, and control surfaces appear reachable. Passive or low-impact checks can enrich the map; active port sweeps, crawling beyond the starting surface, and scanner templates need explicit approval, rate limits, and stop conditions.
3. URL, parameter, and object inventory. Build a deduplicated list of pages, API routes, methods, parameters, object IDs, state-changing actions, auth-required surfaces, and high-value data flows. Prefer artifacts and structured records over ad hoc terminal text.
4. Vulnerability-class triage. Sample across input handling, access control/auth/session, information disclosure/debug, exposed files/directories, browser/API security posture, and known-version risk before deepening one class. Scanner output is lead generation, not proof.
5. Business-logic and API review. Manually model auth boundaries, account roles, ownership assumptions, object references, state transitions, GraphQL or RPC methods, rate limits, and payment or workflow edges. These branches usually need human context and careful non-destructive validation.
6. Secrets and sensitive-data review. Inspect client bundles, source maps, config-looking files, error messages, logs, exposed metadata, and uploaded artifacts for tokens, internal endpoints, keys, passwords, and private data. Record secrets exactly and treat validity checks as approval-gated.
7. Proof and reporting. Promote only evidence-backed Signals into candidate Findings. A report needs affected surface, exact evidence artifact, reproducible steps within proof limits, impact, severity rationale, cleanup needs, remediation idea, and open uncertainty.

Advanced focus rules:

• Spend extra attention on boring-looking endpoints such as health, metrics, debug, console, admin, status, source-map, backup, and config surfaces; many are information-disclosure or pivot points rather than final findings.
• Treat forwarding, original-URL, host, client-IP, cache, and content-negotiation headers as trust-boundary clues. Header tampering tests are active unless performed against local artifacts or approved lab targets.
• Track duplicate parameters, array parameters, JSON body variants, and object IDs as parser/authz hypotheses. Parameter pollution and cross-account object checks require approval when they touch a live Target.
• Preserve error messages, stack traces, status transitions, and verbose JSON/XML responses as Evidence before summarizing; error text can be the most useful map of framework, path, credential, or internal-service assumptions.
• Automate collection and normalization where approved, then manually investigate the highest-confidence leads. Do not let broad automation replace model-building, proof limits, or evidence review.

Specialty Entry Points

Choose the row that best matches the work, then adapt from TAXONOMY.md:

• Web/API: recon -> route and endpoint discovery -> auth/session mapping -> parameter and state probing -> vuln-class tests -> impact chain.
• Mobile: app acquisition -> static triage -> storage/IPC/deeplink review -> traffic analysis -> backend API testing -> device-specific proof.
• Cloud: asset inventory -> IAM mapping -> exposed service review -> config drift checks -> privilege/path analysis -> controlled validation.
• Network/Internal: host discovery -> port scanning -> service enumeration -> version fingerprinting -> vuln validation -> scoped lateral/privilege checks.
• Binary/Firmware: acquisition -> static triage -> unpack/deobfuscate -> diff/reverse -> harness/fuzz -> crash/exploitability analysis.
• Supply Chain: package inventory -> dependency/advisory audit -> changelog and patch diffing -> reachable usage analysis -> local reproduction.
• Smart Contract: architecture/state model -> automated scan -> manual invariant review -> fork/unit simulation -> exploit proof and economic impact.
• AI/LLM: surface inventory -> instruction/data/tool boundary mapping -> prompt/tool injection tests -> guardrail and stop detection -> exfiltration and authorization impact. Use llm-security-testing for dedicated LLM modes, jailbreak/guardrail bypass assessment, bypass hypotheses, tool misuse, tool disclosure, hardening guidance, and user-safe stop messaging.

Broad Discovery Lanes

When planning a broad scan or first-pass target sweep, use Discovery Lanes to keep coverage wide. The plan should sample across lanes before deepening one candidate, especially under tight time, cost, or tool budgets.

Default web/API lanes:

1. Input handling: search/input routes, reflected values, query/body parameters, parser errors, template/script sinks, path/file parameters.
2. Access control and auth/session: login/logout/reset/profile/account flows, object IDs, tenant/user boundaries, cookies, JWT/OAuth/SAML hints, anonymous-vs-auth behavior.
3. Information disclosure and debug: stack traces, verbose errors, framework/version banners, internal paths, debug endpoints, source maps, build metadata.
4. Exposed files and directories: directory listings, backups, logs, uploads, config-looking assets, source maps, .bak/.old files, privacy/security files.
5. Browser/API security posture: CSP/HSTS/X-Frame-Options/CORS, CSRF behavior, cache headers, WebSockets/SSE, API versioning, rate-limit clues, client-side route guards.

Planning rules:

• Prefer 3-5 distinct Evidence-backed lanes over many variants of one lane.
• For each lane, define the cheapest observation that can falsify or support it.
• Mark each experiment as passive or approval-gated; active scans, fuzzing, exploit payloads, credential tests, browser mutation, downloads, writes, and shell commands require explicit approval.
• If a lane has no evidence yet, put it in Open Questions rather than padding findings.
• Use the lane name as the Likely vulnerability class or Class field when reporting Leads, Signals, and Experiments.

Output Shape

For each plan, return:

• Scope: what is allowed, what is excluded, what proof is acceptable, and the assumptions this plan makes about authorization status (target grant, durable approvals on record, and what still needs one).
• Stage: current stage and why it is the right next stage.
• Hunt Spine Progress: attack-surface mapping, vulnerability hunting, business-logic/API review, secrets/sensitive-data review, and reporting/proof status.
• Discovery Lane Coverage: for broad scans, which lanes have leads and which remain open questions.
• Leads: ranked observations or suspected failure modes.
• Experiments: question, hypothesis, prediction, method/tool, safety limit, expected evidence, stop condition.
• Decision tree: what to do if confirmed, refuted, ambiguous, blocked, or out of scope.
• Monitoring: what to watch later and what change would reopen the hunt.

A compact one-shot template with the same output sections lives in PLANNER-PROMPT.md; where the two differ, this SKILL.md is canonical.

References

Use these as naming anchors, not rigid process law:

• NIST SP 800-115: planning, discovery, attack, reporting.
• PTES: pre-engagement, intelligence gathering, threat modeling, vulnerability analysis, exploitation, post-exploitation, reporting.
• OWASP WSTG: web testing categories such as information gathering, configuration, identity, authentication, authorization, session management, input validation, error handling, cryptography, business logic, client-side, and API testing.