finding-protocol

# Finding Protocol — Operational Tier The operational tier captures the minimum information another agent (or the orchestrator) needs to make a decision. It is not the report deliverable — the deliverable is generated at engagement end by the orchestrator from operational findings + attack-path narrative (see `skills/decepticon/final-report/SKILL.md`). ## File Naming Convention `findings/FIND-{NNN}.md` The file name and the `id` field in YAML frontmatter (FIND-001, FIND-002, ...) use the same canonical cross-reference. Determine the next ID by counting existing files: `ls findings/*.md | wc -l`. Do not create empty scaffold directories or placeholder files before there is a real artifact to write. ## Operational Template Every operational finding uses this minimal Markdown structure with YAML frontmatter — required fields only: ```markdown --- id: FIND-001 severity: critical title: <one-line summary> cwe: CWE-89 # optional at operational tier; REQUIRED at deliverable promotion vrt: server-side-injection/sql-injection/blind # optional Bugcrowd VRT path (category/sub-category/variant) agent: recon | exploit | postexploit | analyst | ... objective_id: OBJ-001 discovered_at: "2026-04-06T14:23:11Z" evidence_pointer: findings/evidence/FIND-001_<slug>.txt location: http:https://app.example.com/admin/users # optional but recommended stable locator --- ## Description 2-4 sentences: what the issue is and where. ## Evidence - <pointer 1>: <one-line per pointer> - <pointer 2>: <one-line per pointer> ## Verification Required before a finding is marked confirmed: - status: `confirmed` or `rejected` - positive command and discriminating success signal - equivalent negative-control command and expected baseline signal - `findings/evidence/FIND-001_verification.json` from `validate_workspace_finding` - CVSS vector string when confirmed ## Next next agent should: <action> OR blocking — <reason> ``` The `## Next` section is the decision-support hook — the orchestrator reads it to choose the next dispatch. ## Severity Guide (operational, principle-only) - **CRITICAL**: Immediate exploitation, data breach, full compromise - **HIGH**: Known CVE, significant misconfiguration, privilege escalation - **MEDIUM**: Information disclosure, weak configuration - **LOW**: Hardening recommendation, informational - **INFORMATIONAL**: Observation, no direct security impact CVSS-numeric ranges live in deliverable tier (see final-report skill). When a CVSS score is recorded, always store the **vector string** (CVSS v4.0, e.g. `CVSS:4.0/AV:N/AC:L/...`) alongside the numeric score — the vector encodes the version and makes the score reproducible/auditable (per FIRST CVSS v4.0). A bare number is ambiguous between v3.1 and v4.0. ## Classification fields (CWE + VRT) - `cwe` — the CWE identifier (e.g. `CWE-89`). Optional at operational tier (recon often cannot determine it; exploit usually can), **required** when the finding is promoted to the deliverable tier. - `vrt` — Bugcrowd Vulnerability Rating Taxonomy path `category/sub-category/variant` (e.g. `server-side-injection/sql-injection/blind`). Optional but recommended; it carries a machine-readable cross-walk to CVSS/CWE and a P1–P5 priority, and keeps classifications interoperable with bug-bounty triage. See the VRT at github.com/bugcrowd/vulnerability-rating-taxonomy. ## Location `location` is optional but recommended when a finding has a crisp target. It is a stable, typed `scheme:value` locator for cross-run correlation; do not put the location only in the description. Omit it for domain-wide policy weaknesses or findings without a specific locator. The outer scheme classifies the finding location; its value may itself contain colons (for example, `http:https://...` or `cloud:aws:iam-role:...`). Write the outer scheme in lowercase. Use exactly one of these schemes and normalize the value before writing it: | Scheme | Value | Normalization | | --- | --- | --- | | `http` | URL | Lowercase scheme and host; remove fragment and default port; preserve path and query. | | `net` | `protocol://host:port` | Lowercase protocol and DNS host; use an IP address as written; include port. | | `code` | repository-relative path with optional `#L<line>` | Use `/` separators and the repository-relative path. | | `pkg` | package name with optional `@version` | Use the ecosystem's canonical package name and exact version. | | `cloud` | `provider:resource-type:resource-id` | Lowercase provider and resource type; preserve the provider resource ID. | | `identity` | `provider:principal` | Lowercase provider; preserve the canonical principal identifier. | | `mobile` | `platform:package-or-bundle-id` | Lowercase platform and use the canonical application identifier. | | `device` | `manufacturer:model[:firmware]` | Use manufacturer and model identifiers; include the exact firmware version when relevant. | ## After Creating a Finding 1. Save raw evidence to `findings/evidence/FIND-{NNN}_{description}.txt` only when it supports the finding. 2. Append a timeline entry to `timeline.jsonl` for the real finding event: `{"ts":"...","type":"finding","id":"FIND-001","severity":"critical","agent":"recon","objective":"OBJ-001"}` ## Rules - One Markdown file per finding — do NOT bundle multiple vulnerabilities - ALL agent documents use Markdown format — never write JSON as a deliverable document - Do NOT create `findings.md`; each finding lives in its own `findings/FIND-{NNN}.md` file ## Promotion to Deliverable Tier When the orchestrator runs the final-report skill at engagement end, operational findings are promoted to deliverable-tier finding documents under `report/` with the heavyweight schema (CVSS score + vector, CWE, VRT, MITRE, affected_target, affected_component, confidence, phase, detected, remediation_priority, plus full body sections). See `skills/decepticon/final-report/SKILL.md` for the deliverable template. **Two-tier naming — the key vs. the deliverable:** - **Operational tier** (`findings/FIND-{NNN}.md`) keeps the *stable* `FIND-NNN` key for the whole engagement. Severity and title may change as the exploit confirms impact, but the filename never does — so every cross- reference (`shells.json` / `creds` `finding_id`, `attack-paths/PATH-NNN` `finding_ids`, `timeline.jsonl`, `evidence/FIND-NNN_*.txt`) stays intact. - **Deliverable tier** (`report/<severity><NN>-<slug>.md`) is the terminal snapshot generated once at engagement end, when severity is final. It uses a human-readable, severity-sorted name — e.g. `report/critical01-struts-rce.md`, `report/high01-git-config-disclosure.md`. The `<NN>` is a per-severity counter (`critical01`, `critical02`, `high01`, …) so a plain `ls report/` lists findings worst-first. The frontmatter still carries `id: FIND-NNN`, so the readable deliverable remains traceable back to its operational finding and to the attack-path / shell / credential cross-references.