docs(fda): component support metadata and the cyber device evidence pack

docs/content/asset_modelling/locations/PRO__exporting_sboms_and_vex.md

@@ -37,6 +37,15 @@ GET /api/v2/sbom/{asset_id}/?spec=spdx
 
 The response is a downloadable JSON document (`Content-Disposition: attachment`). Components carry their Package URL, group/namespace, version, artifact hashes (algorithms each specification supports), and — when the SBOM import recorded one — the license expression for this Asset's use of the component.
 
+Where a component records supplier and support facts, the export carries them too. CycloneDX
+writes the supplier as the component's `supplier` object, and the support facts as properties named
+`defectdojo:support_level` and `defectdojo:end_of_support_date`. SPDX writes the supplier as the
+package's supplier and the end of support date as `validUntilDate`.
+
+A component whose support level is unknown emits no support property at all. The document says
+nothing rather than saying unknown, because a consumer reading a property named support level
+should be reading a claim somebody made, not a placeholder.
+
 Without a `version`, the export describes the Asset's **current** inventory, and its `dependencies` section declares root → component edges only: the aggregate inventory is a set of libraries, not a graph.
 
 ### Exporting one release

docs/content/asset_modelling/locations/PRO__working_with_sboms.md

@@ -24,9 +24,45 @@ Every Dependency is uniquely identified by a pURL, decomposed into atomic fields
 | `artifact_hashes` *(optional)* | Fingerprints | SHA256 sums |
 | `license_expression` *(optional)* | SPDX license expression | `Apache-2.0`, `MIT` |
 | `file_path` *(optional)* | Where the library was found in the project | `package-lock.json` |
+| `supplier_name` *(optional)* | The manufacturer or supplier of this component version | `Example Supplier` |
+| `supplier_url` *(optional)* | A link supporting the supplier or support claim | `https://example.test/support` |
+| `support_level` *(optional)* | How the supplier supports this version | `actively_maintained`, `security_fixes_only`, `community_only`, `unsupported`, `end_of_life`, `unknown` |
+| `end_of_support_date` *(optional)* | The date after which the supplier no longer supports this version | `2030-01-01` |
+| `support_source` *(optional)* | Where the support facts came from | `import`, `manual`, `unknown` |
 
 This atomic decomposition is what makes pURL-based search useful: you can ask *"all `pypi` packages in the `django` namespace at version 4.x"* and DefectDojo can answer that without parsing a free-text string.
 
+## Supplier and Support Metadata
+
+Who supplies a component and how long they will support it are facts a bill of materials is often
+asked for and rarely carries. DefectDojo records them on the component, alongside where each fact
+came from.
+
+Unknown is a valid answer and is stored as unknown. DefectDojo never infers a support level or an
+end of support date from a version number, a release date or a project's activity. A fabricated
+support claim in a regulated bill of materials is a problem for whoever relies on it, so the only
+support facts recorded are the ones somebody supplied.
+
+An import reads these from the document where the format carries them. CycloneDX supplies the
+supplier from the component's supplier, publisher or author, in that order, and reads support
+level and end of support date from component properties. SPDX supplies the supplier from the
+supplier or originator field, and reads an end of support date from `validUntilDate` where the
+document has one. Anything absent stays unknown.
+
+### Which value wins
+
+A component's support facts can come from three places, and they resolve in this order:
+
+1. A per snapshot override, where a specific release carries a different support contract from the
+   component in general.
+2. The value recorded on the component itself, whether that came from an import or from somebody
+   editing it.
+3. Unknown.
+
+An edit made by hand survives later imports of the same component. Re-importing a document does
+not overwrite a support level somebody corrected, and `support_source` records which case applies,
+so a reviewer can tell an imported fact from an entered one.
+
 ## Owned-By vs Used-By
 
 When a Dependency is associated with an Asset, the Asset Reference carries an optional **relationship** describing *how* the library belongs to the Asset:

docs/content/federal_compliance/fda_cyber_device_pack.md

@@ -0,0 +1,137 @@
+---
+title: "FDA Cyber Device Evidence Pack"
+description: "Record a cyber device profile, track the section 524B lifecycle metrics, and export the evidence pack an assessor reviews"
+weight: 9
+audience: pro
+---
+
+Section 524B of the Federal Food, Drug, and Cosmetic Act asks the manufacturer of a cyber device
+for four things: a plan to monitor and address vulnerabilities after release, updates on a
+justified cycle with a faster route for the severe ones, a software bill of materials, and the
+processes around all of it. DefectDojo already holds much of the underlying record. These features
+add the few facts it cannot infer, work out where each obligation stands, and produce the workbook
+and bill of materials an assessor reviews.
+
+DefectDojo records and reports what the manufacturer supplies. It does not assess whether a
+software bill of materials is complete or accurate, and it does not determine whether a submission
+satisfies the FDA. Those are decisions for the manufacturer and its reviewers.
+
+The cyber device features are released behind a feature flag. An administrator turns them on per
+instance from the Feature Flags page before they are generally available.
+
+## The cyber device profile
+
+An Asset that is a cyber device carries a profile recording what the assessment needs to know
+about it:
+
+- Whether the Asset is a cyber device at all, which is what brings the rest into scope.
+- A device identifier, either the unique device identifier or an internal model code.
+- The submission stage, premarket or postmarket, so a reviewer knows which one this is.
+- The routine security update cycle in days, and the reasoning behind that interval.
+
+The cycle and its justification are recorded together on purpose. The statute asks for a cycle
+that is reasonably justified, so an interval with no reasoning attached is reported as a partial
+answer rather than a complete one.
+
+The profile also carries the security contact and the vulnerability disclosure policy link. These
+are the same two fields the EU regulatory profile uses, because they answer the same question for
+both regulators.
+
+## The seven elements per component
+
+Section 524B and the accompanying minimum elements guidance expect a bill of materials to answer
+seven things about each component. DefectDojo records all seven:
+
+| Element | Where it comes from |
+|---|---|
+| Asset location | The Asset the component was found on |
+| Component name | The imported bill of materials |
+| Version | The imported bill of materials |
+| Supplier | The imported document, or recorded by hand |
+| Support level | The imported document, or recorded by hand |
+| End of support date | The imported document, or recorded by hand |
+| Known vulnerabilities | The findings linked to that component |
+
+Unknown is a valid answer for the support facts and is reported as unknown. DefectDojo does not
+guess a support level or an end of support date. See
+[Working with SBOMs](../../asset_modelling/locations/pro__working_with_sboms) for how imports supply
+these and which value wins when more than one source has an opinion.
+
+## The three lifecycle metrics
+
+Three numbers describe how the manufacturer handles what it finds. Each is measured over the
+assessment period and can be read on its own or as part of the evidence pack.
+
+**How much of what was found got fixed.** The share of vulnerabilities identified in the period
+that were remediated, overall and by severity, with the ones still open listed.
+
+**How long a fix took.** The time from identifying a vulnerability to shipping the patch, reported
+as a mean and a median, overall and by severity, alongside how many are still open and how old
+they are.
+
+**How long the fix took to arrive.** Releasing a patch is not the same as deploying it. This
+measures the time from a release being available to it reaching the devices in the field, and
+names the releases that have no completion recorded and the ones with no release date, because a
+gap in the record is the thing a reviewer most needs to see.
+
+## The assessment
+
+The bundled catalog holds 13 controls across the four families the statute names: postmarket
+monitoring, updates and patches, bill of materials, and processes. Every control statement in the
+catalog is a paraphrase written for DefectDojo, alongside the statute section it refers to. The
+statute and guidance text is not reproduced. Read the source before relying on a wording here.
+
+Nine of the 13 are evidenced from data DefectDojo already holds:
+
+| Control | Read from |
+|---|---|
+| Coordinated vulnerability disclosure | The security contact and the disclosure policy link on the profile |
+| A justified update cycle | The cycle and rationale on the profile |
+| Out of cycle updates for critical vulnerabilities | Critical findings measured against the recorded cycle |
+| Updates reaching the field | The field implementation metric |
+| A bill of materials covering every kind of component | The component inventory and when it was last imported |
+| Machine readable and carrying the minimum elements | The components available to export and how many name a supplier |
+| Support level and end of support per component | The share of components with a known support level |
+| Known vulnerabilities per component | The findings linked to components |
+| Lifecycle metrics tracked and reviewed | The three metrics above |
+
+The remaining four are the manufacturer's own process and paperwork: the monitoring plan, the
+watch on third party and open source components, lifecycle risk management, and security testing.
+DefectDojo holds no record of any of them, so each is declared manual with a note naming the
+evidence to attach.
+
+Two behaviours are worth knowing before reading a result. A period with no critical findings
+reports the out of cycle control as not applicable rather than as a pass, because nothing was
+asked of the process. The support coverage control fails when too much of the inventory has an
+unknown support level, and names the components responsible so somebody can go and find out; the
+threshold is 90 percent of components.
+
+An Asset with no cyber device profile does not fail. Every automated control reports that what it
+reads is absent and says what to record, because a device nobody has configured yet is not a
+device that is out of compliance.
+
+## The evidence pack
+
+Generating a pack produces three files. Each is recorded with its SHA-256 and its size, and the
+same assessment always produces the same bytes, so the hash attests to the evidence rather than to
+one particular download.
+
+- An OSCAL assessment results document, validated against its schema.
+- The workbook, which has no validator and is recorded as not validated rather than claiming a
+  check that never ran.
+- The bill of materials itself, exported as CycloneDX, so the pack ships the document rather than
+  a description of it. It is recorded as not validated for the same reason.
+
+On top of the obligation sheets every regulatory pack carries, the cyber device workbook adds
+three:
+
+- **Component inventory**, one row per component with all seven elements and where each support
+  fact came from.
+- **Lifecycle metrics**, the three metrics above, overall and by severity.
+- **Release history**, every release in the period with when it shipped, when it reached the
+  field, and how long that took, including the releases that cannot yet be measured.
+
+## Related pages
+
+[CRA and DORA Evidence Packs](../eu_evidence_packs) share the assessment screens and the export
+pipeline described here.