Hypermedia Security: Finding BOM Specification
v1.0.0Hypermedia AuL2
Finding BOM (promoted analyst conclusion; maker-signed; independently approved)
The L2 Finding BOM: one per promoted finding, signed by its author, born at promotion. It turns a disposable transient analysis into a durable, non-repudiable, independently-approved deliverable: the finding document with its hash, the lineage back to the analysis it was promoted from, and one reference each to the attestation that authenticates it (analysis-provenance/v1) and the attestation that checks it (finding-approval/v1). Under changes-requested it is superseded by a new signed version linked to the old; nothing is edited in place, nothing is deleted.
Validate against: /schemas/finding/v1.schema.json
Relationships
References
- references →Hypermedia Security: Analysis Provenance Specification
- references →Hypermedia Security: Finding Approval Specification
- target-standard →Hypermedia Security: Analysis Provenance Specification
- target-standard →Hypermedia Security: Finding Approval Specification
Referenced by
About this standard
- artifact-kind
- BOM (L2 — one per promoted finding)
Sources
- cyclonedx.org
- CycloneDX 1.7 — document mechanics (serialNumber/version, data component + hashes, enveloped JSF signature) verified from the schema file (SPEC-6)
- www.rfc-editor.org
- RFC 2119 (as clarified by RFC 8174) — requirement key words; only capitalised forms are normative
- sec.hypermedia.au
- website
FND-001 CycloneDX Document MUST
A Finding BOM MUST be a CycloneDX 1.7 BOM with bomFormat 'CycloneDX', specVersion '1.7', a urn:uuid serialNumber, a positive integer version, metadata.timestamp (ISO-8601), and metadata.component naming the finding.
The serialNumber is the finding's permanent identity across its versions; the version advances only under the review loop (FND-006). BOM-Links from the approval attestation and from publications resolve against this document.
FND-002 Finding Identity MUST
metadata MUST carry cyberbench:caseId, cyberbench:findingId, and cyberbench:promotedFromAnalysis (the identifier of the transient analysis this finding was promoted from).
promotedFromAnalysis is the lineage back to the moment of promotion — the analysis run that became this finding. Most analyses are discarded and never enter the graph; promotion is the event that creates this object and freezes its provenance.
- required-fields
- cyberbench:caseId,cyberbench:findingId,cyberbench:promotedFromAnalysis
FND-003 Finding Document MUST
components[] MUST carry exactly one data component: the finding document, with a SHA-256 hash of its bytes and cyberbench:artifactClass 'finding'. The hash is the finding's integrity anchor and the value every BOM-Link to this finding pairs with.
One finding, one document, one hash. The document's hash is what the approval attestation approves (version-specific), what a publication composes, and what the Evidence Record covers at finalisation.
- artifact-class
- finding
FND-004 Provenance Reference MUST
metadata MUST carry cyberbench:provenanceRef, resolving (BOM-Link + paired hash) to an analysis-provenance/v1 attestation whose claim targets this finding version. The Finding BOM's signing identity MUST equal the provenance attestation's author.
The finding and its authentication set are two signatures by the same maker over the same conclusion: the finding says what was concluded, the provenance says exactly what produced it. A finding whose provenanceRef does not resolve, or whose author identities diverge, fails verification.
- target-standard
- https://sec.hypermedia.au/standards/analysis-provenance/v1
FND-005 Approval Reference MUST
metadata MUST carry cyberbench:approvalRef, resolving (BOM-Link + paired hash) to a finding-approval/v1 attestation targeting this finding version. For a finding to be disclosable — composed into a publication — that approval MUST be a current terminal finding-approved signed by an identity distinct from the author.
The checker side of maker-checker, referenced from the maker's object. The disclosability condition is enforced by the verifier at publication composition (it requires resolving the approval's predicate and comparing Fulcio identities, which no document schema can do).
- target-standard
- https://sec.hypermedia.au/standards/finding-approval/v1
FND-006 Versioning And Supersession MUST NOT
The version MUST bump when the review outcome is changes-requested: the author revises, producing a new signed Finding version with a new document hash, which links to and supersedes the prior version and re-enters review with a fresh analysis-provenance. The superseded version MUST be retained, marked superseded, and MUST NOT be edited or deleted.
Revision is a new object, never an edit — the review trail keeps every version and every signed outcome, so 'what changed and why' is always answerable from the record. References to a superseded version keep resolving (the hash proves the reviewed bytes); only the current version with a terminal approval is disclosable.
- trigger
- finding-approval/v1 changes-requested