Architecture And Workflows

This page shows how Bug Hunt Method Kit is organized and how a safe research idea moves through the system.

The diagrams are public-safe. They use toy/generic concepts only and do not represent any live target, private evidence, or real vulnerability.

Repository Architecture

flowchart TB
  Reader[Reader or contributor] --> Entry[README and docs]
  Entry --> Ethics[Ethics and publication boundary]
  Entry --> Wiki[Knowledge wiki]
  Entry --> Templates[Public-safe templates]
  Entry --> Examples[Toy examples]
  Entry --> AIOS[AI-OS layer]

  Wiki --> Techniques[Technique cards]
  Wiki --> SOPs[SOPs]
  Wiki --> Sources[Source card template]
  Wiki --> Syntheses[Pattern syntheses]
  Wiki --> Index[Generated knowledge index]

  Templates --> SessionBrief[Session brief]
  Templates --> TestCase[Test case]
  Templates --> EvidenceLog[Evidence log]
  Templates --> FindingDossier[Finding dossier]
  Templates --> Review[Pre-submission review]
  Templates --> ReviewPrompt[Sanitized review prompt]

  Examples --> ToyAPI[Toy API scenarios]
  Examples --> ToyWorkflows[Toy workflows]

  AIOS --> Modes[AI modes]
  AIOS --> Gates[Decision gates]
  AIOS --> Rubrics[Evidence and reportability rubrics]
  AIOS --> Prompts[Safe prompt pack]
  AIOS --> Schemas[Structured output schemas]

  Tools[Node quality tools] --> Frontmatter[Frontmatter check]
  Tools --> Links[Link check]
  Tools --> Secrets[Secret pattern check]
  Tools --> Redaction[Redaction check]
  Tools --> GenerateIndex[Generate index]

  Frontmatter --> Check[npm run check]
  Links --> Check
  Secrets --> Check
  Redaction --> Check

  Check --> Actions[GitHub Docs Quality action]
  Actions --> PR[Pull request review]

  Ethics --> Guardrail[Public-safe boundary]
  Templates --> Guardrail
  Tools --> Guardrail
  PR --> Guardrail

Plain-English Read

Bug Hunt Method Kit has four user-facing layers:

• Docs explain the rules and standards.
• Knowledge pages teach reusable security reasoning.
• Templates guide safe note-taking and review.
• Toy examples show the workflow without touching real targets.
• AI-OS gives AI assistants safe modes, decision gates, prompt templates, rubrics, and schemas.

The tools sit underneath those layers and check for broken links, missing frontmatter, likely secrets, and public-safety issues before changes are merged.

AI-OS Workflow

flowchart TD
  Scope["01 Scope Intake"] --> Authorized{"Authorized and in scope?"}
  Authorized -- "No" --> Stop["Stop or ask for scope"]
  Authorized -- "Yes" --> Hypothesis["02 Hypothesis Generation"]
  Hypothesis --> Plan["03 Test Planning"]
  Plan --> HumanTest["Human performs authorized test"]
  HumanTest --> Evidence["04 Evidence Review"]
  Evidence --> UnsafeEvidence{"Secrets or private data present?"}
  UnsafeEvidence -- "Yes" --> RedactFirst["06 Redaction Review"]
  RedactFirst --> SafeEvidence{"Safe enough to continue?"}
  SafeEvidence -- "No" --> StopRedact["Redact more or stop"]
  SafeEvidence -- "Yes" --> Reportability["05 Reportability Assessment"]
  UnsafeEvidence -- "No" --> Reportability
  Reportability --> ReportReady{"Submission-ready?"}
  ReportReady -- "No" --> MoreProof["Needs more proof, learning note, or discard"]
  ReportReady -- "Yes" --> FinalRedaction["06 Redaction Review"]
  FinalRedaction --> Draft["07 Report Drafting"]
  Draft --> HumanSubmit["Human final review and submission"]
  HumanSubmit --> Learning["08 Post-Submission Learning"]
  MoreProof --> Learning

Boundary Proof Model

flowchart LR
  A[Actor] --> B[Object]
  B --> C[Action]
  C --> D[Expected Boundary]
  D --> E[Observed Behavior]
  E --> F[Impact]
  F --> G[Reportability Decision]

Logic Workflow

flowchart TD
  Start[Start with an idea] --> Scope{Authorization and scope clear?}
  Scope -- No --> StopScope[Stop or ask for permission]
  Scope -- Yes --> Plan[Create a session brief]

  Plan --> Boundary[Map actor, object, action, side effect, and impact]
  Boundary --> Safety{Uses only tester-controlled accounts and objects?}
  Safety -- No --> StopSafety[Stop and redesign safely]
  Safety -- Yes --> Hypothesis[Write one hypothesis]

  Hypothesis --> OneVariable[Choose one changed value]
  OneVariable --> Expected[Define expected secure result]
  Expected --> EvidencePlan[Define minimal redacted evidence]

  EvidencePlan --> Test{Safe to run?}
  Test -- No --> Toy[Use toy or local example instead]
  Test -- Yes --> Observe[Record sanitized result]
  Toy --> Observe

  Observe --> Proves{Evidence proves a boundary crossing?}
  Proves -- No --> Informative[Informative, hardening, or discard]
  Proves -- Yes --> Impact{Realistic security impact?}

  Impact -- No --> MoreProof[Needs more proof or discard]
  Impact -- Yes --> Review[Run pre-submission review]

  Review --> Reject{Likely triage rejection?}
  Reject -- Yes --> MoreProof
  Reject -- No --> Report[Prepare responsible report]

  Informative --> Log[Log lesson safely]
  MoreProof --> Log
  Report --> PrivateEvidence[Keep private evidence outside public repo]
  PrivateEvidence --> Disclosure[Use authorized disclosure channel]

Decision Rule

The workflow does not ask “does this look suspicious?” It asks:

What does the evidence prove, what does it not prove, and is the next step safe?

That question keeps the system practical and reduces noisy or unsafe reports.

Public-Safety Boundary

flowchart LR
  Public[Bug Hunt Method Kit public repo] --> Safe[Generic methods, templates, toy examples, and checks]
  Public --> AIOSPublic[AI-OS prompts, rubrics, schemas, and synthetic examples]
  Private[Private research workspace] --> Sensitive[Evidence, target notes, screenshots, captures, and reports]

  Safe --> Publish[Safe to publish after review]
  AIOSPublic --> Publish
  Sensitive --> KeepPrivate[Keep private and redact before sharing]

  Publish -. never include .-> Sensitive

The public repo teaches the shape of responsible work. It does not store the private proof from real testing.