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 pathcategory/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. |
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 ownfindings/FIND-{NNN}.mdfile
Verification and Report Status Semantics
verification_status: verifiedmeans independent evidence supports the claim; for a negative result, it means reproduced coverage rather than a vulnerability.verification_status: false_positivemeans the claim was refuted.verification_status: unverifiedmeans evidence is insufficient or blocked.verification_rationaleexplains the verdict with positive and equivalent negative-control evidence. The proof producer cannot self-approve.report_status: draft | completedescribes 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/.
