Bug Hunt Method Kit

A structured Markdown toolkit for safer bug-hunting notes, cleaner evidence, and stronger vulnerability reports.

Project site: przemyslav88.github.io/bug-hunt-method-kit

Bug hunting gets messy fast: half-formed ideas, unclear scope, screenshots in the wrong place, notes that mix proof with guesses, and reports that sound more certain than the evidence really is. Bug Hunt Method Kit gives that work a simple rhythm: scope the target, write one hypothesis, collect minimal evidence, challenge the impact, and decide whether the issue is reportable.

Not a target database. Not an exploit pack. Not a scanner. A practical method kit for responsible security research.

AI-Assisted Security Research OS

This repo also includes an AI-OS layer for using AI assistants responsibly during authorized bug hunting. The AI-OS defines operating principles, safety gates, modes, prompts, rubrics, schemas, and synthetic examples for AI-assisted evidence review and report preparation.

The human method kit helps you structure your research. The AI-OS helps an AI assistant follow the same structure without overclaiming, leaking sensitive data, or drifting outside scope.

Use This in 10 Minutes

1. Read ETHICS.md and confirm you only work where you have permission.
2. Open Getting Started for the beginner path.
3. Copy Session Brief into your private notes.
4. Define the scope, accounts, objects, stop conditions, and evidence rules.
5. Copy Test Case and write one hypothesis.
6. Use only tester-controlled accounts and objects.
7. Record only redacted facts in public-safe notes.
8. Run npm run check before sharing changes to this repo.
9. Compare your notes to the Full Toy IDOR Workflow.
10. Optional: after redacting evidence, use the Evidence Review Prompt to ask an AI assistant to review proof quality.

Why It Stands Out

• Built around the bug-hunting workflow: scope, hypothesis, test, evidence, triage, report.
• Public-safe by default: templates keep secrets, raw captures, screenshots, and private target notes out of the repo.
• Evidence-first: every review asks what the proof shows, what it does not show, and what a triager would reject.
• Beginner-friendly: the system explains scope, ownership, redaction, impact, and safe stopping points in plain English.
• Ready for disciplined collaboration: schemas, checks, issue templates, and a docs-quality workflow are included.

Best For / Not For

Best for:

• Learning disciplined bug-hunting workflow.
• Structuring evidence safely.
• Preparing cleaner vulnerability reports.
• Reviewing findings for weak proof or overclaims.
• Teaching responsible security testing with fake examples.

Not for:

• Finding bugs automatically.
• Exploit payloads.
• Recon automation.
• Testing without authorization.
• Storing private evidence.

Why This Exists

Many bug reports fail because the research process is not structured enough:

• the test idea is vague
• scope or permission is unclear
• notes mix facts, guesses, and private data
• evidence does not prove a security boundary was crossed
• impact is overstated
• the next test is unsafe or too broad
• the final report is hard for a triager to reproduce

This repo turns that chaos into a repeatable working method.

What Is Inside

• Knowledge wiki: reusable methodology, technique cards, SOPs, and pattern notes.
• Public-safe templates: session briefs, test cases, evidence logs, impact chains, finding dossiers, and pre-submission reviews.
• Review prompts: sanitized prompts for checking gaps, overclaims, and unclear wording without sharing private evidence.
• Toy examples: fake systems that teach authorization, object ownership, and cache boundaries.
• Quality tooling: Node-only checks for frontmatter, links, secrets, redaction risks, and generated indexes.
• Governance: ethics, publication boundaries, contribution rules, security policy, and GitHub templates.

What Is Not Inside

• No live target data.
• No private findings.
• No evidence dump.
• No exploit database.
• No authorization to test any real system.
• No secrets, tokens, cookies, or raw authentication material.
• No private bounty notes or target runbooks.

Who This Is For

• Bug bounty learners who need a safer note structure.
• Security researchers who want cleaner evidence and triage habits.
• Solo builders who want a practical process for responsible testing.
• Reviewers who want deterministic checklists before submitting a report.
• Maintainers who want educational material that does not publish target data.

Safety First, Always

Only test systems where you have clear permission. Do not brute force, perform credential attacks, probe OTP flows, test rate limits aggressively, complete payments, guess object identifiers, or interact with third-party accounts or data.

Read ETHICS.md and PUBLICATION_BOUNDARY.md before using the templates.

Quick Start

npm install
npm run check

Then:

1. Read ETHICS.md.
2. Read PUBLICATION_BOUNDARY.md.
3. Browse knowledge/index.md.
4. Pick a template from templates/.
5. Work only inside explicit authorization.
6. Keep private evidence outside this public repo.
7. Record facts, redactions, and stop conditions before testing.
8. Run npm run check before sharing changes.

The Core Workflow

1. Define scope, accounts, stop conditions, and evidence rules.
2. Pick one hypothesis and one changed value.
3. Map the boundary: actor, object, action, side effect, and impact.
4. Capture minimal redacted evidence.
5. Ask what the evidence proves and what it does not prove.
6. Use the pre-submission review template to challenge the finding.
7. Classify the result as reportable, informative, needs more proof, or discard.

flowchart LR
  Idea[Idea] --> Scope[Scope check]
  Scope --> Hypothesis[Safe hypothesis]
  Hypothesis --> Plan[Test plan]
  Plan --> Evidence[Minimal evidence]
  Evidence --> Redaction{Redaction needed?}
  Redaction -- Yes --> Redact[Redaction review]
  Redaction -- No --> Review[Evidence review]
  Redact --> Review
  Review --> Decision{Submission-ready?}
  Decision -- Yes --> Report[Responsible report]
  Decision -- No --> Learn[More proof, lesson, or discard]
  Report --> Learn[Post-submission learning]

Loading

See Architecture And Workflows for the full Mermaid diagrams.

Example Use Cases

• Turn a vague authorization idea into a safe two-account test plan.
• Review a finding draft for overclaims before submission.
• Convert public research into a toy example or technique card.
• Keep private proof out of public notes while preserving the lesson.
• Teach beginners how IDOR, cache boundaries, and event workflows are triaged.

Full Walkthroughs

• Toy IDOR Full Workflow
• Toy Cache Boundary Full Workflow
• Toy Webhook Event Full Workflow
• Not Reportable UI Artifact

Repository Map

• docs/ - public guidance, release notes, glossary, and standards.
• docs/architecture-and-workflows.md - Mermaid diagrams for repo architecture and logic flow.
• ai-os/ - AI operating principles, modes, gates, prompts, rubrics, schemas, and synthetic examples.
• knowledge/ - technique cards, SOPs, source-card templates, syntheses, schemas, and generated index.
• templates/ - reusable public-safe note and review templates.
• examples/ - fake toy scenarios for learning the workflow.
• playbooks/ - workflow recipes for safe reasoning.
• checklists/ - short copyable safety and review checks.
• tools/ - Node-only quality and safety checks.
• test-fixtures/ - safe and unsafe samples for checking the tools.
• reports/ - generated local reports only; kept empty in the public baseline.

Quality Checks

npm run check

This runs:

• wiki/frontmatter validation
• Markdown link checks
• secret-pattern checks
• redaction checks

The checks are intentionally cautious. A false positive is better than a leaked token, target note, or private evidence file.

Contributing

Contributions are welcome when they are generic, educational, and public-safe. Do not submit live target details, private evidence, secrets, or unresolved vulnerability information. See CONTRIBUTING.md.

Good contributions include safer templates, clearer explanations, generic technique cards, toy examples, schema improvements, and stronger redaction checks.

Support

Bug Hunt Method Kit is built as a public-safe learning project: clean templates, careful redaction checks, toy examples, and practical security-writing workflows.

If it helps you write clearer reports, avoid unsafe notes, or learn responsible testing faster, sponsoring the project is a kind way to support continued maintenance. Sponsorship is optional; using, sharing, improving, and giving thoughtful feedback are also genuinely appreciated.

License

The project uses Apache-2.0 at the repository root. Docs and templates are intended for educational reuse with attribution; see NOTICE.

Disclaimer

This project is for education and responsible methodology only. It provides no warranty and no permission to test any system. You are responsible for authorization, legal compliance, and safe handling of data.