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
- hyper-spec:artifactKind
- 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 a metadata.component of type 'data' 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.properties MUST carry hyper-spec:caseId, hyper-spec:findingId, and hyper-spec:promotedFromAnalysis (the identifier of the transient analysis this finding was promoted from), each a non-empty string.
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
- hyper-spec:caseId
- required-fields
- hyper-spec:findingId
- required-fields
- hyper-spec:promotedFromAnalysis
FND-003 Finding Document MUST
components[] MUST carry exactly one data component: the finding document, with hyper-spec:artifactClass 'finding' and at least one hash entry. Every hash entry MUST carry alg 'SHA-384' or 'SHA-512' and lowercase hexadecimal content whose length matches the algorithm: 96 characters for SHA-384, 128 for SHA-512. Both values are members of the CycloneDX hash algorithm enumeration. 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.
- allowed-algorithms
- SHA-384
- allowed-algorithms
- SHA-512
- artifact-class
- finding
FND-004 Provenance Reference MUST
externalReferences MUST carry an entry of type 'attestation' marked hyper-spec:role 'provenanceRef', whose url is a document-form BOM-Link to an analysis-provenance/v1 attestation whose claim targets this finding version, paired with at least one hash of that attestation. 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 And Disclosability MUST
A finding's approvals are the finding-approval/v1 attestations whose claim targets this finding version. For a finding to be disclosable — composed into a publication — exactly one of those MUST be a current terminal finding-approved signed by an identity distinct from the author.
The checker side of maker-checker, recorded on the checker's object. An approval is written after the finding is signed and a finding may collect several outcomes over its review loop, so the join is held by the approval and resolved from it; the disclosability condition is the verifier's at publication composition, needing the approval's predicate and a Fulcio identity comparison that no document schema can perform.
- 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 under the same serialNumber, with a new document hash and a fresh analysis-provenance, which re-enters review. A version is superseded when a higher version of the same serialNumber exists. Every earlier version MUST be retained 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. Supersession is carried by the envelope: the serialNumber is the finding's identity across versions (FND-001) and the version orders them, so no property records it and a frozen version never has to be rewritten to say it was replaced. References to a superseded version keep resolving, and the hash proves the reviewed bytes.
- trigger
- finding-approval/v1 changes-requested