Finding Protocol — One Canonical File

A canonical finding records observed facts, evidence, independent verification, and supported report detail in one file. Engagement summaries link to this canonical finding. Assignment order and completion decisions belong to the active workflow.

File Naming Convention

For workflow version 2 use system artifact tools. A vulnerability is saved as findings/{severity}_{number}_{title}.md, e.g. findings/high_01_cross-tenant-document-read.md. The system issues its UUID, stable human ID (FIND-01), number and filename. Never count files to allocate IDs. UUID relationships survive filename, title and severity changes.

The orchestrator alone registers drafts and commits them with artifact tools. An unassigned proof producer returns candidate title, severity rationale, structured metadata, body and exact evidence paths to the orchestrator; it does not invent a UUID or write another finding file. A verifier/reporter edits only the committed UUID/path explicitly assigned to it. Without artifact tools, return observations for the orchestrator's info_entry records.

Observations, negative results, hypotheses, blocked and untested coverage are info_entry records in findings/info_observations-and-negative-results.md. Explicit HYP/AP/PATH documents have descriptive names and UUID links. Inspect prior results before creating a distinct hypothesis; preserve refutations.

Many edits may update one draft. Commit only at a plan, experiment, verification or publication milestone. A revision and SHA-256 pin the saved content; UUID alone proves neither integrity nor truth. Preserve raw evidence separately.

Pinned legacy workflows continue using findings/FIND-{NNN}.md. Examples below illustrate metadata and evidence; resolve actual paths through the registry in v2.

Do not create empty scaffold directories or placeholder files before there is a real artifact to write.

Initial Template

Every operational finding uses this minimal Markdown structure with YAML frontmatter — required fields only:

---
id: FIND-001
severity: critical
severity_rationale: "Why this severity applies to this target and observed impact"
result_kind: vulnerability # vulnerability | negative_result | observation | hypothesis
verification_status: unverified # verified | false_positive | unverified
report_status: draft # draft | complete; report quality, separate from verification
title: <one-line summary>
cwe: CWE-89               # optional; only if evidence supports classification
vrt: server-side-injection/sql-injection/blind   # optional Bugcrowd VRT path (category/sub-category/variant)
agent: recon | exploit | postexploit | analyst | ...
objective_id: <server-issued-objective-id>
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 records evidence-supported follow-up suggestions or blockers. It does not authorize additional work.

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

When a CVSS score is recorded, always store its vector and version alongside the numeric score. Use the deterministic cvss_score tool for CVSS 3.1; never infer a numeric score from a severity label.

Classification fields (CWE + VRT)

• cwe — the CWE identifier (e.g. CWE-89). Add only when evidence supports the classification; an unknown CWE is more honest than a guessed one.
• 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:

Evidence and Event References

Raw evidence uses findings/evidence/FIND-{NNN}_{description}.txt and must support the finding. A finding event in timeline.jsonl references the same finding and actual objective ID:

{"ts":"...","type":"finding","id":"FIND-001","severity":"critical","agent":"recon","objective":"<server-issued-objective-id>"}

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

Verification and Report Status Semantics

• verification_status: verified means independent evidence supports the claim; for a negative result, it means reproduced coverage rather than a vulnerability.
• verification_status: false_positive means the claim was refuted.
• verification_status: unverified means evidence is insufficient or blocked.
• verification_rationale explains the verdict with positive and equivalent negative-control evidence. The proof producer cannot self-approve.
• report_status: draft | complete describes documentation quality separately from technical verification. Complete detail is supported by the saved finding and referenced evidence, including justified versioned CVSS metrics where applicable.
• Eligibility, duplicates, and presentation defects do not change technical validity.

Keep the stable findings/FIND-{NNN}.md as the canonical record. Summaries link here rather than copying the finding into report/.