@mitre/hdf-schema 3.3.2 → 3.4.1

package/dist/ts/hdf.ts

@@ -66,9 +66,6 @@ export interface HDFResults {
 
 /**
  * Information on a baseline that was evaluated, including any findings.
- *
- * Shared metadata fields for baselines. Used in both standalone baseline documents and
- * evaluated baseline results.
  */
 export interface EvaluatedBaseline {
     /**
@@ -172,8 +169,7 @@ export interface EvaluatedBaseline {
 }
 
 /**
- * A dependency for a baseline. Can include relative paths or URLs for where to find the
- * dependency.
+ * A dependency for a baseline. Can include relative paths or URLs for where to find the dependency.
  */
 export interface Dependency {
     /**
@@ -237,9 +233,9 @@ export interface RequirementGroup {
 }
 
 /**
- * A typed input parameter that bridges governance requirements and scanner automation.
- * Inputs carry expected configuration values with type information, comparison operators,
- * and validation constraints, enabling traceability from policy through to scan results.
+ * A typed input parameter that bridges governance requirements and scanner automation. Inputs carry
+ * expected configuration values with type information, comparison operators, and validation
+ * constraints, enabling traceability from policy through to scan results.
  */
 export interface Input {
     /**
@@ -280,8 +276,6 @@ export interface Input {
 }
 
 /**
- * Validation constraints for the input value.
- *
  * Validation constraints for an input value.
  */
 export interface InputConstraints {
@@ -305,8 +299,6 @@ export interface InputConstraints {
 }
 
 /**
- * The comparison operator used when evaluating this input against observed values.
- *
  * Comparison operator for evaluating the input value against observed values. Numeric:
  * eq/ne/lt/le/gt/ge. String: eq/ne/contains/matches. Collection: in/notIn.
  */
@@ -324,8 +316,6 @@ export enum ComparisonOperator {
 }
 
 /**
- * The data type of this input.
- *
  * The data type of the input value. Aligns with InSpec input types.
  */
 export enum InputType {
@@ -338,27 +328,8 @@ export enum InputType {
 }
 
 /**
- * Cryptographic integrity information for verifying this baseline has not been tampered
- * with.
- *
- * Cryptographic integrity information for verifying the HDF file has not been tampered
- * with. If algorithm is provided, checksum must also be provided, and vice versa.
- *
- * Cryptographic integrity information for verifying this file.
- *
- * Cryptographic integrity information for verifying this comparison document.
- *
- * Cryptographic integrity information for verifying this system document has not been
- * tampered with.
- *
- * Cryptographic integrity information for verifying this plan document has not been
- * tampered with.
- *
- * Cryptographic integrity information for verifying this amendments document has not been
- * tampered with.
- *
- * Cryptographic integrity information for verifying this evidence package has not been
- * tampered with.
+ * Cryptographic integrity information for verifying the HDF file has not been tampered with. If
+ * algorithm is provided, checksum must also be provided, and vice versa.
  */
 export interface Integrity {
     /**
@@ -381,41 +352,18 @@ export interface Integrity {
 }
 
 /**
- * The hash algorithm used for the checksum.
- *
- * Supported cryptographic hash algorithms for checksums and integrity verification.
+ * Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers
+ * container-image and other artifact digests that use it.
  */
 export enum HashAlgorithm {
+    Blake3 = "blake3",
     Sha256 = "sha256",
     Sha384 = "sha384",
     Sha512 = "sha512",
 }
 
 /**
- * SHA-256 checksum of the original baseline definition file (before execution). This is an
- * immutable reference to the baseline as defined, used to detect tampering with baseline
- * requirements or metadata.
- *
  * Cryptographic checksum for baseline integrity verification.
- *
- * SHA-256 checksum of the previous amendment in chronological order. Creates a
- * tamper-evident chain of amendments (similar to blockchain). Null for the first amendment
- * on a requirement.
- *
- * SHA-256 checksum of the raw results before any amendments (statusOverrides or POAMs).
- * Used to detect tampering with test results. Compare with currentChecksum to verify
- * amendment integrity.
- *
- * Optional cryptographic checksum for verifying the integrity of remediation resources
- * fetched from the URI. Recommended for security when referencing external automation
- * scripts.
- *
- * Cryptographic checksum of the source document for integrity verification.
- *
- * Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null
- * for the first amendment.
- *
- * Cryptographic checksum for verifying the referenced document's integrity.
  */
 export interface Checksum {
     /**
@@ -431,9 +379,6 @@ export interface Checksum {
 
 /**
  * A requirement that has been evaluated, including any findings.
- *
- * Core requirement fields shared between baseline requirements and evaluated requirements.
- * Contains the fundamental requirement definition without assessment results.
  */
 export interface EvaluatedRequirement {
     /**
@@ -581,14 +526,13 @@ export interface EvaluatedRequirement {
 
 /**
  * Represents a package referenced by a vulnerability finding or by an amendment's scope. On
- * Evaluated_Requirement.affectedPackages it says 'this CVE affects these package versions'.
- * On Standalone_Override.affectedPackages it says 'this amendment is scoped to these
- * packages' (used by VEX, OSCAL POA&M, FedRAMP component-aware amendments). NOT a
- * system-level component identifier — see `components[]` on hdf-system for those. Validity
- * requires at least one of: (name + version + ecosystem), purl alone, or cpe alone. purl
- * and cpe are self-describing identifiers that encode name/version implicitly, so either
- * may stand on its own; the name+version+ecosystem combination is the explicit form for
- * sources without formal identifiers.
+ * Evaluated_Requirement.affectedPackages it says 'this CVE affects these package versions'. On
+ * Standalone_Override.affectedPackages it says 'this amendment is scoped to these packages' (used
+ * by VEX, OSCAL POA&M, FedRAMP component-aware amendments). NOT a system-level component identifier
+ * — see `components[]` on hdf-system for those. Validity requires at least one of: (name + version
+ * + ecosystem), purl alone, or cpe alone. purl and cpe are self-describing identifiers that encode
+ * name/version implicitly, so either may stand on its own; the name+version+ecosystem combination
+ * is the explicit form for sources without formal identifiers.
  */
 export interface AffectedPackage {
     /**
@@ -679,16 +623,12 @@ export enum ControlType {
 }
 
 /**
- * Structured CVSS scoring data backing this override. Captures the rubric (which
- * Environmental/Threat metrics the consumer modified, the recomputed score) used to justify
- * a riskAdjustment. For other override types this is optional context.
- *
- * A CVSS (Common Vulnerability Scoring System) score record for a vulnerability finding.
- * Captures the vendor-supplied Base metric group and optional consumer-supplied Threat,
- * Environmental, and Supplemental metric groups. Supports all four CVSS major versions
- * (2.0, 3.0, 3.1, 4.0). Vector strings are validated against a permissive umbrella grammar;
- * semantic validation (correct metrics per version, correct values per metric) is performed
- * by the hdf-utilities `validateCvssVector` helper rather than at the schema layer.
+ * A CVSS (Common Vulnerability Scoring System) score record for a vulnerability finding. Captures
+ * the vendor-supplied Base metric group and optional consumer-supplied Threat, Environmental, and
+ * Supplemental metric groups. Supports all four CVSS major versions (2.0, 3.0, 3.1, 4.0). Vector
+ * strings are validated against a permissive umbrella grammar; semantic validation (correct metrics
+ * per version, correct values per metric) is performed by the hdf-utilities `validateCvssVector`
+ * helper rather than at the schema layer.
  */
 export interface Cvss {
     /**
@@ -761,15 +701,9 @@ export interface Cvss {
 }
 
 /**
- * Qualitative severity band corresponding to baseScore. CVSS 2.0 does not natively use
- * 'none' or 'critical' bands; map accordingly when populating.
- *
  * Qualitative CVSS severity band. Aligns with FIRST/NVD bands: none=0.0, low=0.1-3.9,
- * medium=4.0-6.9, high=7.0-8.9, critical=9.0-10.0. Distinct from the broader Severity enum
- * used on Requirement_Core (which includes 'informational').
- *
- * Qualitative severity band corresponding to computedScore. Same band convention as
- * baseSeverity.
+ * medium=4.0-6.9, high=7.0-8.9, critical=9.0-10.0. Distinct from the broader Severity enum used on
+ * Requirement_Core (which includes 'informational').
  */
 export enum CVSSSeverity {
     Critical = "critical",
@@ -804,29 +738,19 @@ export interface Description {
 }
 
 /**
- * The type of the most recent non-expired override or POAM governing this requirement.
- * Indicates why the requirement is in its current state (e.g., waiver, falsePositive,
- * riskAdjustment) or what remediation is being tracked (poam). Absent when no overrides or
- * POAMs apply.
- *
- * The type of amendment, aligned with FedRAMP deviation request categories. 'waiver': risk
- * accepted by Authorizing Official. 'attestation': manually verified by assessor. 'poam':
- * remediation tracked (no status change). 'inherited': control provided by another
- * component or system. 'falsePositive': scanner incorrectly identified a finding — for
- * compliance scans (STIG, CIS), the check actually passes, so status is typically set to
- * 'passed'; for vulnerability scans (CVE, SCA), the flagged vulnerability does not apply to
- * this system, so status is typically set to 'notApplicable'. The disposition field on the
- * requirement distinguishes false positives from genuinely not-applicable findings.
- * 'riskAdjustment': impact score adjusted based on environmental context (FedRAMP Risk
- * Adjustment); does not change pass/fail status, only impact via the impact field.
- * 'operationalRequirement': deviation required by operational constraints (FedRAMP
- * Operational Requirement); the finding cannot be remediated because the system requires
- * the affected functionality. Remains an open risk. Migration note: 'exception' was removed
- * in v3.1.0 — use 'waiver' with status 'notApplicable' instead.
- *
- * The type of override applied to this requirement.
- *
- * The type of amendment.
+ * The type of amendment, aligned with FedRAMP deviation request categories. 'waiver': risk accepted
+ * by Authorizing Official. 'attestation': manually verified by assessor. 'poam': remediation
+ * tracked (no status change). 'inherited': control provided by another component or system.
+ * 'falsePositive': scanner incorrectly identified a finding — for compliance scans (STIG, CIS), the
+ * check actually passes, so status is typically set to 'passed'; for vulnerability scans (CVE,
+ * SCA), the flagged vulnerability does not apply to this system, so status is typically set to
+ * 'notApplicable'. The disposition field on the requirement distinguishes false positives from
+ * genuinely not-applicable findings. 'riskAdjustment': impact score adjusted based on environmental
+ * context (FedRAMP Risk Adjustment); does not change pass/fail status, only impact via the impact
+ * field. 'operationalRequirement': deviation required by operational constraints (FedRAMP
+ * Operational Requirement); the finding cannot be remediated because the system requires the
+ * affected functionality. Remains an open risk. Migration note: 'exception' was removed in v3.1.0 —
+ * use 'waiver' with status 'notApplicable' instead.
  */
 export enum OverrideType {
     Attestation = "attestation",
@@ -839,20 +763,9 @@ export enum OverrideType {
 }
 
 /**
- * The current effective compliance status of this requirement after applying the most
- * recent non-expired override with a status field, or computed from results (worst-wins) if
- * no status-bearing overrides exist.
- *
- * The status of an individual test result. 'notApplicable' indicates the requirement does
- * not apply to the target. 'notReviewed' indicates the requirement was not assessed (e.g.,
- * requires manual verification).
- *
- * The status of this test within the requirement. Example: 'failed'.
- *
- * The new status this override sets for the requirement. Optional when only impact is being
- * overridden.
- *
- * The new status this amendment sets. Optional when only impact is being overridden.
+ * The status of an individual test result. 'notApplicable' indicates the requirement does not apply
+ * to the target. 'notReviewed' indicates the requirement was not assessed (e.g., requires manual
+ * verification).
  */
 export enum ResultStatus {
     Error = "error",
@@ -863,13 +776,9 @@ export enum ResultStatus {
 }
 
 /**
- * FIRST.org EPSS (Exploit Prediction Scoring System) score for this CVE finding. Used
- * alongside CVSS for prioritization — captures the probability the vulnerability will be
- * exploited.
- *
- * FIRST.org Exploit Prediction Scoring System (EPSS) data for a single vulnerability. All
- * three fields are required when an Epss object is present; the date disambiguates which
- * day's score this is, since EPSS recomputes daily.
+ * FIRST.org Exploit Prediction Scoring System (EPSS) data for a single vulnerability. All three
+ * fields are required when an Epss object is present; the date disambiguates which day's score this
+ * is, since EPSS recomputes daily.
  */
 export interface Epss {
     /**
@@ -892,8 +801,8 @@ export interface Epss {
 }
 
 /**
- * Supporting evidence for a finding or override, such as screenshots, code samples, log
- * excerpts, or URLs.
+ * Supporting evidence for a finding or override, such as screenshots, code samples, log excerpts,
+ * or URLs.
  */
 export interface Evidence {
     /**
@@ -933,41 +842,8 @@ export interface Evidence {
 }
 
 /**
- * Identity of who or what captured this evidence.
- *
- * Represents an identity that performed an action, such as capturing evidence or applying
- * an override.
- *
- * Identity of who created this POA&M. For simple cases, use type 'simple' with just an
- * identifier.
- *
- * Identity of who completed this milestone.
- *
- * The identity that created this signature.
- *
- * Identity of who applied this override. For simple cases, use type 'simple' with just an
- * identifier.
- *
- * Identity of the person or system that approved this override.
- *
- * Team or individual responsible for this component. Enables per-component ownership when
- * different teams manage different parts of a system.
- *
- * The identity of the person or system responsible for executing the test. This could be a
- * human auditor manually completing a checklist, an automated CI/CD system, or a security
- * tool. Optional field to support both automated and manual HDF generation.
- *
- * Team or individual responsible for this system's authorization and compliance. Maps to
- * OSCAL responsible-party with role 'system-owner'.
- *
- * Default identity of who created this amendments document. Individual overrides may
- * specify their own appliedBy.
- *
- * Identity of the authorizing official who approved these amendments.
- *
- * Identity of who applied this amendment.
- *
- * Identity of who prepared this evidence package.
+ * Represents an identity that performed an action, such as capturing evidence or applying an
+ * override.
  */
 export interface Identity {
     /**
@@ -981,8 +857,12 @@ export interface Identity {
     identifier: string;
     /**
      * The type of identifier. Use 'email' for email addresses, 'username' for user accounts,
-     * 'system' for automated systems, 'simple' for basic string identifiers without additional
-     * classification, or 'other' for custom identity systems.
+     * 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent'
+     * for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can
+     * apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and
+     * satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF,
+     * 'simple' for basic string identifiers without additional classification, or 'other' for
+     * custom identity systems.
      */
     type: IdentityType;
     [property: string]: any;
@@ -990,10 +870,15 @@ export interface Identity {
 
 /**
  * The type of identifier. Use 'email' for email addresses, 'username' for user accounts,
- * 'system' for automated systems, 'simple' for basic string identifiers without additional
- * classification, or 'other' for custom identity systems.
+ * 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent'
+ * for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can
+ * apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and
+ * satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF,
+ * 'simple' for basic string identifiers without additional classification, or 'other' for
+ * custom identity systems.
  */
 export enum IdentityType {
+    Agent = "agent",
     Email = "email",
     Other = "other",
     Simple = "simple",
@@ -1042,9 +927,9 @@ export interface Kev {
 }
 
 /**
- * Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance.
- * POAMs do NOT change the effectiveStatus - the requirement remains in its current state
- * while the POA&M tracks remediation efforts.
+ * Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance. POAMs do
+ * NOT change the effectiveStatus - the requirement remains in its current state while the POA&M
+ * tracks remediation efforts.
  */
 export interface Poam {
     /**
@@ -1129,21 +1014,9 @@ export enum MilestoneStatus {
 }
 
 /**
- * Optional digital signature for enhanced trust and non-repudiation.
- *
- * A digital signature following W3C Data Integrity Proofs pattern. Supports hardware
- * security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other cryptographic
- * signing methods via JWK, PEM, or Base58 key formats.
- *
- * Optional digital signature for enhanced trust and non-repudiation. Supports hardware
- * security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other signing
- * methods.
- *
- * Digital signature for non-repudiation.
- *
- * Document-level digital signature covering all amendments.
- *
- * Digital signature covering the entire evidence package.
+ * A digital signature following W3C Data Integrity Proofs pattern. Supports hardware security
+ * tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other cryptographic signing methods
+ * via JWK, PEM, or Base58 key formats.
  */
 export interface Signature {
     /**
@@ -1188,10 +1061,8 @@ export interface Signature {
 }
 
 /**
- * The verification method containing the public key for signature verification.
- *
- * Verification method containing the public key needed to verify a digital signature.
- * Supports multiple key formats including JWK (for RSA, EC), PEM, and Base58.
+ * Verification method containing the public key needed to verify a digital signature. Supports
+ * multiple key formats including JWK (for RSA, EC), PEM, and Base58.
  */
 export interface VerificationMethod {
     /**
@@ -1233,12 +1104,6 @@ export enum POAMType {
 
 /**
  * A reference to an external document.
- *
- * A reference using the 'ref' field.
- *
- * A URL pointing at the reference.
- *
- * A URI pointing at the reference.
  */
 export interface Reference {
     ref?: { [key: string]: any }[] | string;
@@ -1293,9 +1158,6 @@ export interface RequirementResult {
 }
 
 /**
- * Explicit severity rating. Typically derived from impact score but provided explicitly for
- * clarity.
- *
  * Severity rating for a requirement. Typically derived from the numeric impact score.
  */
 export enum Severity {
@@ -1307,8 +1169,6 @@ export enum Severity {
 }
 
 /**
- * The explicit location of the requirement within the source code.
- *
  * The explicit location of a requirement within source code.
  */
 export interface SourceLocation {
@@ -1324,9 +1184,9 @@ export interface SourceLocation {
 }
 
 /**
- * An intentional change to a requirement's compliance status and/or impact score. At least
- * one of status or impact must be set. Overrides change the effectiveStatus or impact of
- * the requirement. All overrides must have an expiration date to enforce periodic review.
+ * An intentional change to a requirement's compliance status and/or impact score. At least one of
+ * status or impact must be set. Overrides change the effectiveStatus or impact of the requirement.
+ * All overrides must have an expiration date to enforce periodic review.
  */
 export interface StatusOverride {
     /**
@@ -1395,11 +1255,8 @@ export interface StatusOverride {
 }
 
 /**
- * Override to the requirement's impact score. At least one of status or impact must be
- * set.
- *
- * An override to the requirement's impact score. The prior impact is the original result
- * value or the preceding override in the chain.
+ * An override to the requirement's impact score. The prior impact is the original result value or
+ * the preceding override in the chain.
  */
 export interface ImpactOverride {
     /**
@@ -1410,28 +1267,21 @@ export interface ImpactOverride {
 }
 
 /**
- * Structured controlled-vocabulary classification for why this override applies.
- * Complements (does not replace) the free-text 'reason' field. Most useful on falsePositive
- * and attestation overrides where the structured category enables filtering and lossless
- * round-trip with VEX / OSCAL / FedRAMP DR. See the Justification primitive for the
- * precedent vocabulary and rationale.
- *
- * Structured controlled-vocabulary reason for an override, complementing the free-text
- * 'reason' field. 'reason' carries the human-readable rationale an auditor reads;
- * 'justification' carries the machine-readable category enabling filtering, aggregation,
- * and lossless round-trip with structured ecosystems (VEX, OSCAL, FedRAMP DR). Both fields
- * may be present simultaneously and are NOT redundant: 'reason' explains the specific
- * circumstance; 'justification' classifies it. Authors SHOULD populate both when a
- * controlled-vocabulary value applies — the enum value alone is not self-explanatory to an
- * auditor. The vocabulary is drawn from the VEX ecosystem: the first five values are common
- * across OpenVEX, CSAF VEX, and CycloneDX VEX; the remaining six (requires_configuration /
- * requires_dependency / requires_environment / protected_by_compiler / protected_at_runtime
- * / protected_at_perimeter) are CycloneDX-specific and describe why the vulnerable code
- * path is unreachable in the deployed configuration. The enum is extended additively across
- * schema versions as other ecosystems' controlled vocabularies are integrated; documents
- * using values added in a newer schema version will fail validation against an older
- * schema. Consumers SHOULD validate against the schema version declared by the document
- * ($schema) rather than assume a fixed vocabulary.
+ * Structured controlled-vocabulary reason for an override, complementing the free-text 'reason'
+ * field. 'reason' carries the human-readable rationale an auditor reads; 'justification' carries
+ * the machine-readable category enabling filtering, aggregation, and lossless round-trip with
+ * structured ecosystems (VEX, OSCAL, FedRAMP DR). Both fields may be present simultaneously and are
+ * NOT redundant: 'reason' explains the specific circumstance; 'justification' classifies it.
+ * Authors SHOULD populate both when a controlled-vocabulary value applies — the enum value alone is
+ * not self-explanatory to an auditor. The vocabulary is drawn from the VEX ecosystem: the first
+ * five values are common across OpenVEX, CSAF VEX, and CycloneDX VEX; the remaining six
+ * (requires_configuration / requires_dependency / requires_environment / protected_by_compiler /
+ * protected_at_runtime / protected_at_perimeter) are CycloneDX-specific and describe why the
+ * vulnerable code path is unreachable in the deployed configuration. The enum is extended
+ * additively across schema versions as other ecosystems' controlled vocabularies are integrated;
+ * documents using values added in a newer schema version will fail validation against an older
+ * schema. Consumers SHOULD validate against the schema version declared by the document ($schema)
+ * rather than assume a fixed vocabulary.
  */
 export enum Justification {
     ComponentNotPresent = "component_not_present",
@@ -1448,19 +1298,12 @@ export enum Justification {
 }
 
 /**
- * How this requirement is intended to be verified. Disambiguates the two cases that null
- * 'code' overloads: 'manual-by-design' (the requirement is statement-form and not amenable
- * to automation, e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could
- * exist but does not yet, e.g. a STIG rule lacking a fix). 'automated' = a check exists and
- * runs without operator action; 'hybrid' = part automated, part manual. Optional: when
- * omitted, consumers should not infer a default.
- *
- * How a requirement is intended to be verified. Disambiguates the two cases that null
- * 'code' overloads: 'manual-by-design' (the requirement is statement-form and not amenable
- * to automation, e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could
- * exist but does not yet, e.g. a STIG rule lacking a fix). 'automated' = a check exists and
- * runs without operator action; 'hybrid' = part automated, part manual. Named '_Enum' to
- * disambiguate from the unrelated Verification_Method DID-context struct.
+ * How a requirement is intended to be verified. Disambiguates the two cases that null 'code'
+ * overloads: 'manual-by-design' (the requirement is statement-form and not amenable to automation,
+ * e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could exist but does not yet,
+ * e.g. a STIG rule lacking a fix). 'automated' = a check exists and runs without operator action;
+ * 'hybrid' = part automated, part manual. Named '_Enum' to disambiguate from the unrelated
+ * Verification_Method DID-context struct.
  */
 export enum VerificationMethodEnum {
     Automated = "automated",
@@ -1493,39 +1336,21 @@ export interface SupportedPlatform {
 }
 
 /**
- * A system component. Uses discriminated union pattern with 'type' field as discriminator.
- * Superset of Target with identity, external IDs, and SBOM support.
- *
- * A physical or virtual server, workstation, or network device.
- *
- * Base properties shared by all component types. Extends the Target concept with stable
- * identity, external references, and SBOM embedding.
- *
- * A static container image (not running).
- *
- * A running container instance.
- *
- * A container orchestration platform (Kubernetes, OpenShift, ECS, etc.).
- *
- * A cloud provider account (AWS account, Azure subscription, GCP project).
- *
- * A specific cloud resource (EC2 instance, S3 bucket, Azure VM, etc.).
- *
- * A code repository (for SAST tools).
- *
- * A running application or API (for DAST tools).
- *
- * A software artifact or dependency (for SCA tools).
- *
- * A network segment or network device.
- *
- * A database instance.
+ * A system component. Uses discriminated union pattern with 'type' field as discriminator. Superset
+ * of Target with identity, external IDs, and SBOM support.
  */
 export interface Component {
     /**
      * Names of baselines that apply to this component.
      */
     baselineRefs?: string[];
+    /**
+     * Component-scoped Bills of Materials (SBOM, ai-model, dataset, or any reserved bomType),
+     * each carried by passthrough (ref/document) or normalized. Replaces the former
+     * sbom/sbomRef/sbomFormat trio; a component may carry several BOMs (e.g. an SBOM plus an
+     * ai-model BOM). See primitives/bom.schema.json.
+     */
+    boms?: BillOfMaterials[];
     /**
      * Stable UUID (RFC 4122) for this component. Required in hdf-system documents, optional in
      * hdf-results. Enables cross-document correlation, diffing, and data flow references.
@@ -1545,6 +1370,15 @@ export interface Component {
      * System-specific overrides for baseline input values.
      */
     inputOverrides?: InputOverride[];
+    /**
+     * Cryptographic integrity of this component's underlying artifact — model weights or
+     * shards, dataset archive, container image, or package bytes. An array supports
+     * multi-file/sharded artifacts. This is the single, generic home for artifact/subject
+     * integrity across all component types (it replaced the former per-type Container_Image
+     * digest and Artifact checksum fields). Distinct from BOM-document integrity (Bom.hashes[])
+     * and from the document tamper-evidence Integrity type.
+     */
+    integrity?: Checksum[];
     /**
      * Optional key-value labels for flexible grouping. Well-known keys: system, component,
      * environment, region, team. Values must be strings.
@@ -1559,33 +1393,37 @@ export interface Component {
      * different teams manage different parts of a system.
      */
     owner?: Identity;
-    /**
-     * Embedded CycloneDX or SPDX SBOM document representing this component's software
-     * inventory. The sbomFormat field determines which format constraints apply.
-     */
-    sbom?: any;
-    /**
-     * Format of the SBOM (embedded or referenced). Required when sbom or sbomRef is present.
-     */
-    sbomFormat?: SBOMFormat;
-    /**
-     * URI reference to an external CycloneDX or SPDX SBOM document for this component. May be a
-     * relative path, absolute URI, or fragment identifier.
-     */
-    sbomRef?: string;
     /**
      * Label selector to match targets belonging to this component during migration. Targets
      * with matching labels are automatically included.
      */
     targetSelector?: { [key: string]: string };
     /**
-     * Component type discriminator. Same values as Target types.
+     * Component type discriminator. Same values as Target types, plus aiModel and dataset (thin
+     * AI subject components whose detail lives in an attached ai-model / dataset BOM).
      */
     type: TargetType;
     /**
-     * Fully qualified domain name.
+     * Directory domain the host is a member of — Active Directory / NetBIOS / LDAP domain (ECS
+     * host.domain semantics), NOT necessarily the DNS suffix of the FQDN. A standalone or
+     * workgroup host has a hostname but no domain. Not derivable from the FQDN; populate only
+     * from a source that carries directory membership.
+     */
+    domain?: string;
+    /**
+     * Fully qualified domain name (e.g. 'web01.prod.example.com'). Distinct from 'hostname'
+     * (short) and 'domain' (directory domain). ECS recommends storing this lowercase; the
+     * schema does not enforce case so source fidelity is preserved on round-trip.
      */
     fqdn?: string;
+    /**
+     * Short, OS-reported host name (the unqualified machine name, e.g. 'web01'). Kept distinct
+     * from 'fqdn' because an FQDN is not reliably decomposable into hostname + domain
+     * (standalone/workgroup hosts have no domain; a directory domain is not the FQDN's DNS
+     * suffix). Aligns with ECS host.hostname and DISA STIG CKL HOST_NAME. Store the short name
+     * the source reports; do not derive it from the FQDN.
+     */
+    hostname?: string;
     /**
      * IP address of the host.
      */
@@ -1602,10 +1440,6 @@ export interface Component {
      * Operating system version.
      */
     osVersion?: string;
-    /**
-     * Image digest for immutable reference.
-     */
-    digest?: string;
     /**
      * Container image ID.
      */
@@ -1654,6 +1488,11 @@ export interface Component {
      * Package version.
      *
      * Database version.
+     *
+     * Model version, revision, or checkpoint tag.
+     *
+     * Dataset version, release identifier, or — for highly dynamic datasets — a timestamped
+     * release marker.
      */
     version?: string;
     /**
@@ -1700,10 +1539,6 @@ export interface Component {
      * Environment. Example: 'production', 'staging', 'development'.
      */
     environment?: string;
-    /**
-     * Package checksum for verification.
-     */
-    checksum?: string;
     /**
      * Package manager. Example: 'npm', 'maven', 'pip', 'nuget'.
      */
@@ -1732,12 +1567,319 @@ export interface Component {
      * Database port.
      */
     port?: number;
+    /**
+     * Provider/registry identifier for the model. Examples: a Hugging Face repo id
+     * ('meta-llama/Llama-2-7b-hf') or a model purl. Correlates the component to its ai-model
+     * BOM(s) and to lineage references from other models.
+     */
+    modelId?: string;
+    /**
+     * Provider/registry identifier for the dataset. Examples: a Hugging Face dataset repo id
+     * ('HuggingFaceH4/ultrachat_200k'), a DOI, or a dataset purl. Correlates the component to
+     * its dataset BOM(s) and to datasetRefs from ai-model components.
+     */
+    datasetId?: string;
     [property: string]: any;
 }
 
+export interface BillOfMaterials {
+    /**
+     * The manifest kind. Determines which normalized type-extension (model/dataset/packages)
+     * may appear.
+     */
+    bomType: string;
+    /**
+     * Normalized dataset extension. Permitted only when bomType is dataset.
+     */
+    dataset?: DatasetBOMExtension;
+    /**
+     * Passthrough by embedding: the native manifest carried opaquely (e.g. a raw CycloneDX or
+     * SPDX object). HDF does not constrain its internal shape — full manifest validation is a
+     * tool-level concern.
+     */
+    document?: { [key: string]: any };
+    /**
+     * Source manifest format the BOM was produced from or references. Examples: cyclonedx,
+     * cyclonedx-ml, spdx, spdx-ai, huggingface, croissant. Free-form so new formats need no
+     * schema change; the converter that emits the BOM owns the value.
+     */
+    format: string;
+    /**
+     * Integrity of the carried BOM *document* itself (the referenced/embedded manifest file),
+     * NOT the integrity of the BOM's subject artifact. Subject/artifact integrity (model
+     * weights, dataset archive) is a component-level concern, not carried here. Subject
+     * identity is inherited from the host component/system; per-node identity lives in the
+     * type-extension.
+     */
+    hashes?: Checksum[];
+    /**
+     * Optional license of the BOM document as a whole (SPDX license expression). Nullable and
+     * often meaningless (CBOM algorithms, many HBOM parts have no license); per-node licenses
+     * live in the type-extension, not here.
+     */
+    license?: null | string;
+    /**
+     * Normalized ai-model extension. Permitted only when bomType is ai-model.
+     */
+    model?: AIModelBOMExtension;
+    /**
+     * Normalized sbom extension: the flattened software package inventory. Permitted only when
+     * bomType is sbom.
+     */
+    packages?: SBOMPackage[];
+    /**
+     * Passthrough by reference: URI (relative path, absolute URI, or fragment) to the native
+     * manifest document. Present for externally-hosted BOMs.
+     */
+    ref?: string;
+    /**
+     * Optional stable identifier for this BOM document (e.g. CycloneDX serialNumber, SPDX
+     * documentNamespace). Correlates the same BOM across evidence packages.
+     */
+    uniqueId?: string;
+}
+
 /**
- * An override of a baseline input value for a specific component. Enables system-specific
- * tailoring of baseline parameters.
+ * Normalized dataset fields (SPDX 3.0 Dataset profile / MLCommons Croissant aligned). All optional;
+ * open for partial-fidelity passthrough of unmapped native fields. Symmetric with
+ * AI_Model_Extension: carries the dataset's own lineage (baseDatasetRefs/derivation) just as the
+ * model extension carries baseModelRef/adaptationType.
+ */
+export interface DatasetBOMExtension {
+    /**
+     * References to the source dataset(s) this one was derived from — a dataset componentId, or
+     * a dataset BOM uniqueId/URI when no component exists. The lineage edge parallel to
+     * ai-model's baseModelRef; the base dataset may carry its own dataset BOM.
+     */
+    baseDatasetRefs?: string[];
+    /**
+     * Sensitivity/classification of the data. Examples: public, internal, confidential, pii,
+     * phi.
+     */
+    dataClassification?: string;
+    /**
+     * Physical format of the dataset. Examples: parquet, csv, jsonl, tfrecord, webdataset.
+     */
+    datasetFormat?: string;
+    /**
+     * Relationship of this dataset to baseDatasetRefs, parallel to the model extension's
+     * adaptationType. Minimal + extensible: filtered (subset by rule), augmented
+     * (added/synthesized records), merged (union of sources), sampled (statistical draw).
+     */
+    derivation?: DatasetDerivationType;
+    /**
+     * Free-text statement of the dataset's intended use (CISA/G7 minimum element).
+     */
+    intendedUse?: string;
+    /**
+     * Content modality/kind of the data (CISA/G7 'Dataset content: modality'). Examples: text,
+     * image, tabular, timeseries, audio. DISTINCT from datasetFormat, which is the physical
+     * encoding (parquet/csv). Resolves SPDX 3.0 dataset_datasetType, which is content-kind, not
+     * physical format. String or array of strings.
+     */
+    modality?: string[] | string;
+    /**
+     * Free-text description of the dataset's origin and collection process (CISA/G7 'Dataset
+     * provenance'; SPDX 3.0 dataset_dataCollectionProcess).
+     */
+    provenance?: string;
+    /**
+     * Number of records/examples in the dataset.
+     */
+    recordCount?: number;
+    /**
+     * Free-text summary of the dataset's statistical properties (CISA/G7 minimum element;
+     * open-ended by design). Intentionally free-text and will remain so permanently:
+     * recordCount is the one structured statistic, and restructuring this into an object later
+     * would break existing consumers, so it stays a string (additive-only).
+     */
+    statisticalProperties?: string;
+    [property: string]: any;
+}
+
+/**
+ * Relationship of this dataset to baseDatasetRefs, parallel to the model extension's
+ * adaptationType. Minimal + extensible: filtered (subset by rule), augmented
+ * (added/synthesized records), merged (union of sources), sampled (statistical draw).
+ */
+export enum DatasetDerivationType {
+    Augmented = "augmented",
+    Filtered = "filtered",
+    Merged = "merged",
+    Sampled = "sampled",
+}
+
+/**
+ * Normalized AI-model fields, aligned to the CISA/G7 'SBOM for AI' minimum elements. All fields
+ * optional (standards-correct; only the EU AI Act makes a subset binding for high-risk/GPAI). Left
+ * open (additionalProperties: true) so a converter can carry unmapped native fields opaquely
+ * (partial-fidelity pattern). Subject name/version are inherited from the host aiModel component,
+ * not repeated here.
+ */
+export interface AIModelBOMExtension {
+    /**
+     * Lineage relationship to baseModelRef, adopting Hugging Face's base_model_relation
+     * vocabulary (the only typed lineage enum in the ecosystem).
+     */
+    adaptationType?: ModelAdaptationType;
+    /**
+     * Reference to the base model this one was adapted from (e.g. a Hugging Face repo id or
+     * purl). Correlates the lineage edge; the base model itself may carry its own ai-model BOM.
+     */
+    baseModelRef?: string;
+    /**
+     * References to the training/evaluation datasets this model was produced from — preferably
+     * a dataset component's componentId (correlating to a first-class dataset subject rather
+     * than duplicating dataset detail, per ADR §10), or a dataset BOM uniqueId/URI when no
+     * component exists.
+     */
+    datasetRefs?: string[];
+    /**
+     * Training hyper-parameters as name/value pairs (epochs, learning-rate, batch-size). This
+     * is the set of training knobs, NOT the model's trainable parameterCount — the two are
+     * routinely conflated. CISA/G7 'Model properties: hyper-parameters'; SPDX 3.0
+     * ai_hyperparameter.
+     */
+    hyperparameters?: Hyperparameter[];
+    /**
+     * Model input/output properties (CISA/G7 minimum element): I/O data types, modality,
+     * context/sequence length, and tokenizer. Sourced from CycloneDX
+     * modelParameters.inputs[].format / outputs[].format. All sub-fields optional.
+     */
+    inputOutput?: InputOutput;
+    /**
+     * Free-text statement of intended use and out-of-scope uses (CISA/G7 minimum element).
+     */
+    intendedUse?: string;
+    /**
+     * Model's learning/training paradigm. Free-text because the value set varies across
+     * standards. Examples: supervised, self-supervised, semi-supervised, reinforcement.
+     * Cross-standard intersection: SPDX 3.0 ai_typeOfModel ∩ CycloneDX
+     * modelParameters.approach.type ∩ CISA/G7 learning type.
+     */
+    learningApproach?: string;
+    /**
+     * Model architecture family. Examples: transformer, cnn, diffusion, mixture-of-experts.
+     */
+    modelArchitecture?: string;
+    /**
+     * Total trainable parameter count. No native CycloneDX/SPDX field exists; first-class here
+     * because the EU AI Act keys GPAI obligations off model scale.
+     */
+    parameterCount?: number;
+    /**
+     * Reported evaluation metrics as name/value pairs. Values are free-text because metrics are
+     * heterogeneous (accuracy, f1, BLEU, latency). The item stays open (additionalProperties:
+     * true) to carry native CycloneDX slice/confidenceInterval detail opaquely. Cross-standard
+     * intersection: SPDX 3.0 ai_metric ∩ CycloneDX quantitativeAnalysis.performanceMetrics ∩
+     * CISA/G7 KPI cluster.
+     */
+    performanceMetrics?: PerformanceMetric[];
+    /**
+     * On-disk weight serialization format. Security-critical yet under-modeled by BOM specs:
+     * pickle/pytorch permits arbitrary code execution on load; safetensors does not. Examples:
+     * safetensors, pytorch, gguf, onnx, tensorflow.
+     */
+    serializationFormat?: string;
+    /**
+     * The ML task the model performs. Free-text. Examples: text-classification,
+     * sentiment-analysis, object-detection, translation. Sourced from CycloneDX
+     * modelParameters.task (SPDX 3.0 ai_domain is domain-level/adjacent, not the task); CISA/G7
+     * intended-application.
+     */
+    task?: string;
+    [property: string]: any;
+}
+
+/**
+ * Lineage relationship to baseModelRef, adopting Hugging Face's base_model_relation
+ * vocabulary (the only typed lineage enum in the ecosystem).
+ */
+export enum ModelAdaptationType {
+    Adapter = "adapter",
+    Finetune = "finetune",
+    Merge = "merge",
+    Quantized = "quantized",
+}
+
+export interface Hyperparameter {
+    /**
+     * Hyper-parameter name. Examples: epochs, learning-rate, batch-size.
+     */
+    name?: string;
+    /**
+     * Hyper-parameter value (free-text).
+     */
+    value?: string;
+    [property: string]: any;
+}
+
+/**
+ * Model input/output properties (CISA/G7 minimum element): I/O data types, modality,
+ * context/sequence length, and tokenizer. Sourced from CycloneDX
+ * modelParameters.inputs[].format / outputs[].format. All sub-fields optional.
+ */
+export interface InputOutput {
+    /**
+     * Maximum context/sequence length the model accepts, in tokens.
+     */
+    contextLength?: number;
+    /**
+     * Input/output data types. Examples: string, byte[], float32, image.
+     */
+    dataTypes?: string[];
+    /**
+     * Input/output modalities. String or array of strings. Examples: text, image, audio.
+     * Symmetric with Dataset_Extension.modality.
+     */
+    modality?: string[] | string;
+    /**
+     * Tokenizer used for the model's input encoding. Examples: BPE, SentencePiece, tiktoken.
+     */
+    tokenizer?: string;
+    [property: string]: any;
+}
+
+export interface PerformanceMetric {
+    /**
+     * Metric name. Examples: accuracy, f1, BLEU, latency.
+     */
+    name?: string;
+    /**
+     * Reported metric value, free-text because metrics are heterogeneous (percentages, scores,
+     * milliseconds).
+     */
+    value?: string;
+    [property: string]: any;
+}
+
+/**
+ * A single normalized software package entry within an sbom BOM. Minimal identity + version for
+ * querying/diffing; the full native record remains available via passthrough (document/ref).
+ */
+export interface SBOMPackage {
+    /**
+     * SPDX license identifiers/expressions for this package.
+     */
+    licenses?: string[];
+    /**
+     * Package name.
+     */
+    name: string;
+    /**
+     * Package URL (purl) — the preferred cross-BOM identity key when present.
+     */
+    purl?: string;
+    /**
+     * Package version.
+     */
+    version?: string;
+    [property: string]: any;
+}
+
+/**
+ * An override of a baseline input value for a specific component. Enables system-specific tailoring
+ * of baseline parameters.
  */
 export interface InputOverride {
     /**
@@ -1773,17 +1915,11 @@ export enum CloudProvider {
 }
 
 /**
- * Format of the SBOM (embedded or referenced). Required when sbom or sbomRef is present.
- */
-export enum SBOMFormat {
-    Cyclonedx = "cyclonedx",
-    Spdx = "spdx",
-}
-
-/**
- * Component type discriminator. Same values as Target types.
+ * Component type discriminator. Same values as Target types, plus aiModel and dataset (thin
+ * AI subject components whose detail lives in an attached ai-model / dataset BOM).
  */
 export enum TargetType {
+    AIModel = "aiModel",
     Application = "application",
     Artifact = "artifact",
     CloudAccount = "cloudAccount",
@@ -1792,25 +1928,14 @@ export enum TargetType {
     ContainerInstance = "containerInstance",
     ContainerPlatform = "containerPlatform",
     Database = "database",
+    Dataset = "dataset",
     Host = "host",
     Network = "network",
     Repository = "repository",
 }
 
 /**
- * Information about the tool that generated this file.
- *
  * Information about the tool that generated this HDF file.
- *
- * The tool that generated this file.
- *
- * Information about the tool that generated this comparison.
- *
- * Information about the tool that generated this system document.
- *
- * Information about the tool that generated this plan.
- *
- * Information about the tool that generated this document.
  */
 export interface Generator {
     /**
@@ -1825,15 +1950,9 @@ export interface Generator {
 }
 
 /**
- * Optional reference to automated remediation resources (Ansible playbooks, Terraform
- * scripts, etc.) for fixing failing requirements found in this assessment.
- *
- * Reference to automated remediation resources for implementing security controls. Points
- * to external automation content like Ansible playbooks, Terraform scripts, or
- * vendor-provided remediation tools.
- *
- * Optional reference to automated remediation resources (Ansible playbooks, Terraform
- * scripts, etc.) for implementing the security controls defined in this baseline.
+ * Reference to automated remediation resources for implementing security controls. Points to
+ * external automation content like Ansible playbooks, Terraform scripts, or vendor-provided
+ * remediation tools.
  */
 export interface Remediation {
     /**
@@ -1852,12 +1971,8 @@ export interface Remediation {
 }
 
 /**
- * Information about the test execution environment where the security tool was run.
- * Distinct from targets (what is being tested).
- *
- * Information about the test execution environment. This is distinct from the target being
- * scanned - the runner is where the security tool executes, while targets are what is being
- * assessed.
+ * Information about the test execution environment. This is distinct from the target being scanned
+ * - the runner is where the security tool executes, while targets are what is being assessed.
  */
 export interface Runner {
     /**
@@ -1875,7 +1990,18 @@ export interface Runner {
      */
     containerImage?: string;
     /**
-     * The hostname of the runner system. Example: 'ci-runner-01', 'jenkins-agent-03',
+     * The directory domain the runner system belongs to (Active Directory / NetBIOS / LDAP),
+     * NOT the DNS suffix of the FQDN. Example: 'CORP'.
+     */
+    domain?: string;
+    /**
+     * The fully qualified domain name of the runner system, when known. Distinct from the short
+     * 'hostname'; kept separate for the same reason as on host components (an FQDN is not
+     * reliably decomposable). Example: 'ci-runner-01.build.example.com'.
+     */
+    fqdn?: string;
+    /**
+     * The short hostname of the runner system. Example: 'ci-runner-01', 'jenkins-agent-03',
      * 'k8s-node-worker-03'.
      */
     hostname?: string;
@@ -1898,8 +2024,6 @@ export interface Runner {
 }
 
 /**
- * Statistics for the assessment run, including duration and result counts.
- *
  * Statistics for the assessment run(s) such as duration and result counts.
  */
 export interface Statistics {
@@ -1915,8 +2039,6 @@ export interface Statistics {
 }
 
 /**
- * Breakdowns of requirement statistics by result status.
- *
  * Statistics for requirement results, grouped by status.
  */
 export interface StatisticHash {
@@ -1944,17 +2066,7 @@ export interface StatisticHash {
 }
 
 /**
- * Statistics for requirements that encountered an error during assessment.
- *
  * Statistics for a given item, such as the total count.
- *
- * Statistics for requirements that failed.
- *
- * Statistics for requirements that are not applicable to the target.
- *
- * Statistics for requirements that were not reviewed (manual check required).
- *
- * Statistics for requirements that passed.
  */
 export interface StatisticBlock {
     /**
@@ -1965,12 +2077,8 @@ export interface StatisticBlock {
 }
 
 /**
- * The security tool that produced the assessment data in this file.
- *
- * The security tool that produced the assessment data represented in this HDF file. Aligns
- * with SARIF, OSCAL, and CycloneDX terminology.
- *
- * The security tool that produced the assessment data in this source.
+ * The security tool that produced the assessment data represented in this HDF file. Aligns with
+ * SARIF, OSCAL, and CycloneDX terminology.
  */
 export interface Tool {
     /**
@@ -1992,11 +2100,8 @@ export interface Tool {
 }
 
 /**
- * Information on the set of requirements that can be assessed, including baseline metadata
- * and requirement definitions.
- *
- * Shared metadata fields for baselines. Used in both standalone baseline documents and
- * evaluated baseline results.
+ * Information on the set of requirements that can be assessed, including baseline metadata and
+ * requirement definitions.
  */
 export interface HDFBaseline {
     /**
@@ -2079,9 +2184,6 @@ export interface HDFBaseline {
 
 /**
  * A requirement definition without assessment results.
- *
- * Core requirement fields shared between baseline requirements and evaluated requirements.
- * Contains the fundamental requirement definition without assessment results.
  */
 export interface BaselineRequirement {
     /**
@@ -2157,8 +2259,8 @@ export interface BaselineRequirement {
 }
 
 /**
- * Structured comparison between two or more HDF security assessment documents. Supports
- * temporal, baseline, fleet, and multi-source comparison modes.
+ * Structured comparison between two or more HDF security assessment documents. Supports temporal,
+ * baseline, fleet, and multi-source comparison modes.
  */
 export interface HDFComparison {
     /**
@@ -2175,7 +2277,8 @@ export interface HDFComparison {
      */
     comparisonMode: ComparisonMode;
     /**
-     * Comparison of components between two system documents. Used in systemDrift mode.
+     * Comparison of components between two system documents. Used in systemDrift mode. A
+     * component's BOM changes surface as a field change on its boms[] here.
      */
     componentDiffs?: ComponentDiff[];
     /**
@@ -2203,7 +2306,11 @@ export interface HDFComparison {
      */
     matching?: MatchingConfig;
     /**
-     * Comparison of packages between two SBOMs. Used in systemDrift mode for SBOM comparison.
+     * RESERVED — not emitted by the current systemDrift comparison. systemDrift now reports a
+     * component's BOM changes as a field change on its boms[] (see componentDiffs), and
+     * standalone SBOM package diffing is a separate `hdf diff <sbom> <sbom>` output shape. This
+     * field is retained for a future normalized package-level diff; consumers must not expect
+     * it from today's systemDrift output.
      */
     packageDiffs?: PackageDiff[];
     /**
@@ -2253,8 +2360,6 @@ export interface Annotation {
 }
 
 /**
- * The category of this annotation.
- *
  * The category of an annotation attached to a comparison.
  */
 export enum AnnotationCategory {
@@ -2305,13 +2410,11 @@ export enum BaselineDiffState {
 }
 
 /**
- * The mode of comparison being performed.
- *
- * The mode of comparison. 'temporal' compares the same target over time. 'baseline'
- * compares against a golden reference. 'fleet' compares across multiple systems.
- * 'multiSource' compares outputs from different scanners. 'baselineEvolution' compares two
- * baseline documents to detect requirement changes between versions. 'systemDrift' compares
- * two system documents to detect component-level changes.
+ * The mode of comparison. 'temporal' compares the same target over time. 'baseline' compares
+ * against a golden reference. 'fleet' compares across multiple systems. 'multiSource' compares
+ * outputs from different scanners. 'baselineEvolution' compares two baseline documents to detect
+ * requirement changes between versions. 'systemDrift' compares two system documents to detect
+ * component-level changes.
  */
 export enum ComparisonMode {
     Baseline = "baseline",
@@ -2516,8 +2619,6 @@ export interface ScannerConflict {
 }
 
 /**
- * How the conflict was resolved.
- *
  * How a conflict between multiple scanner results was resolved.
  */
 export enum ConflictResolution {
@@ -2544,13 +2645,9 @@ export interface Value {
 }
 
 /**
- * The strategy that was used to match this requirement across sources.
- *
- * The strategy used to match requirements across sources. 'exactId' matches by identical
- * IDs. 'mappedId' uses an ID mapping table. 'cciMatch'/'nistMatch' match by framework
- * identifiers. 'fuzzyTitle'/'fuzzyContent' use text similarity.
- *
- * The primary strategy used to match requirements across sources.
+ * The strategy used to match requirements across sources. 'exactId' matches by identical IDs.
+ * 'mappedId' uses an ID mapping table. 'cciMatch'/'nistMatch' match by framework identifiers.
+ * 'fuzzyTitle'/'fuzzyContent' use text similarity.
  */
 export enum MatchStrategy {
     CciMatch = "cciMatch",
@@ -2562,12 +2659,10 @@ export enum MatchStrategy {
 }
 
 /**
- * The state of this requirement in the comparison.
- *
- * SARIF-compatible vocabulary extended for security. 'new' = present only in new source,
- * 'absent' = present only in old, 'unchanged' = same effective status, 'updated' = status
- * changed (generic), 'fixed' = was failing now passing, 'regressed' = was passing now
- * failing, 'moved' = reorganized same content, 'split'/'merged' = reserved for v1.1.
+ * SARIF-compatible vocabulary extended for security. 'new' = present only in new source, 'absent' =
+ * present only in old, 'unchanged' = same effective status, 'updated' = status changed (generic),
+ * 'fixed' = was failing now passing, 'regressed' = was passing now failing, 'moved' = reorganized
+ * same content, 'split'/'merged' = reserved for v1.1.
  */
 export enum RequirementState {
     Absent = "absent",
@@ -2586,8 +2681,6 @@ export enum FormatVersion {
 }
 
 /**
- * Configuration for how requirements were matched across sources.
- *
  * Configuration for how requirements are matched across sources.
  */
 export interface MatchingConfig {
@@ -2615,15 +2708,22 @@ export interface MatchingConfig {
 }
 
 /**
- * Comparison of a single package between two SBOM versions, matched by purl.
+ * Comparison of a single BOM node between two BOM versions, matched by purl (software) or
+ * identifier (models, datasets, hardware, crypto).
  */
 export interface PackageDiff {
+    /**
+     * Generic identity key for matching a BOM node across versions when no purl applies — e.g.
+     * a Hugging Face model ref, dataset uniqueId, crypto algorithm OID, or hardware part
+     * number. At least one of purl or identifier is required.
+     */
+    identifier?: string;
     /**
      * License identifiers for this package.
      */
     licenses?: string[];
     /**
-     * Human-readable package name.
+     * Human-readable node name.
      */
     name?: string;
     /**
@@ -2635,9 +2735,11 @@ export interface PackageDiff {
      */
     oldVersion?: string;
     /**
-     * Package URL (purl) used as the identity key for matching across SBOMs.
+     * Package URL (purl) — the preferred identity key for matching software packages across
+     * BOMs. Optional: BOM nodes without a purl (AI models, datasets, hardware parts, crypto
+     * algorithms) key on identifier instead.
      */
-    purl: string;
+    purl?: string;
     /**
      * The state of this package: added (new in new SBOM), removed (absent from new SBOM),
      * updated (version changed), unchanged.
@@ -2727,8 +2829,6 @@ export enum OriginalFormat {
 }
 
 /**
- * The role of this source in the comparison.
- *
  * The role of a source document in the comparison.
  */
 export enum SourceRole {
@@ -2815,8 +2915,6 @@ export interface ComparisonSummary {
 }
 
 /**
- * State counts broken down by severity level.
- *
  * Breakdown of state counts by severity level.
  */
 export interface SeverityBreakdown {
@@ -2840,15 +2938,7 @@ export interface SeverityBreakdown {
 }
 
 /**
- * State counts for critical severity requirements.
- *
  * Counts of requirements in each state.
- *
- * State counts for high severity requirements.
- *
- * State counts for low severity requirements.
- *
- * State counts for medium severity requirements.
  */
 export interface StateCounts {
     /**
@@ -2926,8 +3016,8 @@ export interface PerSourceSummary {
 }
 
 /**
- * Describes a system's authorization boundary, components, and interconnections. Maps to
- * OSCAL SSP system-characteristics and FedRAMP system inventory.
+ * Describes a system's authorization boundary, components, and interconnections. Maps to OSCAL SSP
+ * system-characteristics and FedRAMP system inventory.
  */
 export interface HDFSystem {
     /**
@@ -2938,6 +3028,13 @@ export interface HDFSystem {
      * Current Authorization to Operate (ATO) status.
      */
     authorizationStatus?: AuthorizationStatus;
+    /**
+     * System-scoped Bills of Materials whose subject is the authorization boundary rather than
+     * a single component (e.g. a SaaSBOM of services, a KBOM of cluster inventory, an OBOM).
+     * Component-scoped BOMs (SBOM, ai-model) attach on the component instead. See
+     * primitives/bom.schema.json.
+     */
+    boms?: BillOfMaterials[];
     /**
      * Description of the system's authorization boundary. Example: network CIDR blocks, cloud
      * VPC IDs, physical locations.
@@ -2949,7 +3046,8 @@ export interface HDFSystem {
     categorizationLevel?: CategorizationLevel;
     /**
      * System components within the authorization boundary. Uses the full polymorphic Component
-     * type with stable identity (componentId), external references, and SBOM support.
+     * type with stable identity (componentId), external references, and generalized BOM
+     * attachment (boms[]).
      */
     components: Component[];
     /**
@@ -3012,8 +3110,6 @@ export interface HDFSystem {
 }
 
 /**
- * Current Authorization to Operate (ATO) status.
- *
  * Authorization to Operate (ATO) status for the system.
  */
 export enum AuthorizationStatus {
@@ -3026,8 +3122,6 @@ export enum AuthorizationStatus {
 }
 
 /**
- * FIPS 199 security categorization (impact level).
- *
  * FIPS 199 security categorization level (impact level).
  */
 export enum CategorizationLevel {
@@ -3037,10 +3131,10 @@ export enum CategorizationLevel {
 }
 
 /**
- * Declares a control's designation within a system — whether it is common (provided by
- * another component or system), system-specific (implemented locally), or hybrid (shared
- * responsibility). Maps to NIST SP 800-53 Appendix C control designations and OSCAL SSP
- * by-component provided/inherited semantics.
+ * Declares a control's designation within a system — whether it is common (provided by another
+ * component or system), system-specific (implemented locally), or hybrid (shared responsibility).
+ * Maps to NIST SP 800-53 Appendix C control designations and OSCAL SSP by-component
+ * provided/inherited semantics.
  */
 export interface ControlDesignation {
     /**
@@ -3089,9 +3183,9 @@ export enum Designation {
 }
 
 /**
- * A data flow between two endpoints. The 'from' endpoint is always a local component; the
- * 'to' endpoint can be local, cross-system, or external. Use 'direction' to indicate
- * whether data flows one-way or both ways.
+ * A data flow between two endpoints. The 'from' endpoint is always a local component; the 'to'
+ * endpoint can be local, cross-system, or external. Use 'direction' to indicate whether data flows
+ * one-way or both ways.
  */
 export interface DataFlow {
     /**
@@ -3140,8 +3234,8 @@ export enum Direction {
 }
 
 /**
- * Defines an assessment plan — what baselines to run against which targets, with resolved
- * inputs and scheduling. Maps to OSCAL Assessment Plan.
+ * Defines an assessment plan — what baselines to run against which targets, with resolved inputs
+ * and scheduling. Maps to OSCAL Assessment Plan.
  */
 export interface HDFPlan {
     /**
@@ -3195,8 +3289,8 @@ export interface HDFPlan {
 }
 
 /**
- * A single assessment within a plan — defines which baseline to run against which targets
- * with what configuration.
+ * A single assessment within a plan — defines which baseline to run against which targets with what
+ * configuration.
  */
 export interface Assessment {
     /**
@@ -3232,8 +3326,6 @@ export interface Assessment {
 }
 
 /**
- * Runner/scanner configuration for this assessment.
- *
  * Configuration for the assessment runner/scanner.
  */
 export interface RunnerConfig {
@@ -3249,8 +3341,6 @@ export interface RunnerConfig {
 }
 
 /**
- * Optional scheduling configuration for recurring assessments.
- *
  * Scheduling configuration for recurring assessments.
  */
 export interface Schedule {
@@ -3279,10 +3369,8 @@ export interface Schedule {
 }
 
 /**
- * The type of assessment plan.
- *
- * The type of assessment. 'automated' for scanner-driven, 'manual' for human-performed,
- * 'hybrid' for both.
+ * The type of assessment. 'automated' for scanner-driven, 'manual' for human-performed, 'hybrid'
+ * for both.
  */
 export enum PlanType {
     Automated = "automated",
@@ -3291,8 +3379,8 @@ export enum PlanType {
 }
 
 /**
- * Waivers, attestations, and POA&Ms that modify requirement compliance status or impact.
- * Amendments are standalone documents that can be applied to results via merge operations.
+ * Waivers, attestations, and POA&Ms that modify requirement compliance status or impact. Amendments
+ * are standalone documents that can be applied to results via merge operations.
  */
 export interface HDFAmendments {
     /**
@@ -3350,18 +3438,18 @@ export interface HDFAmendments {
 }
 
 /**
- * A standalone override to a requirement's compliance status or risk impact. Validation has
- * two branches gated on 'type': when type is 'operationalRequirement', neither 'status' nor
- * 'impact' may be set — the override records accepted risk without changing the finding
- * (documentation-only). For all other types, at least one of 'status' or 'impact' must be
- * set. This rule aligns with: (1) OSCAL Assessment Results — finding.target.status and
+ * A standalone override to a requirement's compliance status or risk impact. Validation has two
+ * branches gated on 'type': when type is 'operationalRequirement', neither 'status' nor 'impact'
+ * may be set — the override records accepted risk without changing the finding
+ * (documentation-only). For all other types, at least one of 'status' or 'impact' must be set. This
+ * rule aligns with: (1) OSCAL Assessment Results — finding.target.status and
  * finding.associated-risk[].facet[] are separate axes
- * (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/); (2)
- * FedRAMP deviation request types — Risk Adjustment changes impact only, Operational
- * Requirement documents acceptance only, False Positive changes status
- * (https://www.ignyteplatform.com/blog/fedramp/fedramp-deviation-requests-submit/); (3)
- * NIST SP 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from
- * control assessment status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).
+ * (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/); (2) FedRAMP
+ * deviation request types — Risk Adjustment changes impact only, Operational Requirement documents
+ * acceptance only, False Positive changes status
+ * (https://www.ignyteplatform.com/blog/fedramp/fedramp-deviation-requests-submit/); (3) NIST SP
+ * 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from control assessment
+ * status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).
  */
 export interface StandaloneOverride {
     /**
@@ -3459,9 +3547,8 @@ export interface StandaloneOverride {
 }
 
 /**
- * Bundles references to all HDF documents for audit, authorization, and compliance review.
- * Each content entry references a document by type, URI, and checksum for integrity
- * verification.
+ * Bundles references to all HDF documents for audit, authorization, and compliance review. Each
+ * content entry references a document by type, URI, and checksum for integrity verification.
  */
 export interface HDFEvidencePackage {
     /**
@@ -3476,6 +3563,13 @@ export interface HDFEvidencePackage {
      * Description of the evidence package's purpose and scope.
      */
     description?: string;
+    /**
+     * References to external native-format evidence (log/telemetry corpora and other artifacts)
+     * carried by URI + integrity hash + format discriminator, without recreating the data
+     * inside HDF. Logs in ECS/OCSF/etc. are legitimate accreditation evidence; HDF indexes them
+     * here rather than transcoding them.
+     */
+    externalEvidence?: ExternalEvidenceReference[];
     /**
      * Information about the tool that generated this document.
      */
@@ -3529,10 +3623,8 @@ export interface HDFEvidencePackage {
 }
 
 /**
- * Summary of assessment completeness and compliance status.
- *
- * Informational summary of assessment completeness. Not authoritative — tools should
- * compute these from the referenced documents.
+ * Informational summary of assessment completeness. Not authoritative — tools should compute these
+ * from the referenced documents.
  */
 export interface CompletenessCheck {
     /**
@@ -3563,8 +3655,6 @@ export interface CompletenessCheck {
 }
 
 /**
- * SBOM coverage across system components.
- *
  * SBOM coverage statistics for the system.
  */
 export interface SBOMCoverage {
@@ -3580,7 +3670,7 @@ export interface SBOMCoverage {
 }
 
 /**
- * A reference to an HDF document or SBOM included in the evidence package.
+ * A reference to an HDF document or BOM/manifest included in the evidence package.
  */
 export interface ContentReference {
     /**
@@ -3608,16 +3698,95 @@ export interface ContentReference {
 }
 
 /**
- * The type of HDF document being referenced.
- *
- * The type of document referenced in the evidence package.
+ * The type of document referenced in the evidence package. 'bom' covers any
+ * Bill-of-Materials/manifest document (SBOM, AI model/dataset, and reserved future kinds) — its
+ * specific kind is carried by the referenced document's bomType, not by a per-kind Content_Type
+ * value.
  */
 export enum ContentType {
+    BOM = "bom",
     HdfAmendments = "hdf-amendments",
     HdfBaseline = "hdf-baseline",
     HdfComparison = "hdf-comparison",
     HdfPlan = "hdf-plan",
     HdfResults = "hdf-results",
     HdfSystem = "hdf-system",
-    Sbom = "sbom",
+}
+
+/**
+ * A reference to external native-format evidence (log/telemetry corpus or other artifact) carried
+ * by URI + integrity hash + format discriminator. Reference-only: the artifact is never embedded
+ * (corpora can be huge) or transcoded (that would be lossy) — it stays canonical in its native
+ * format and HDF acts as the structured index.
+ */
+export interface ExternalEvidenceReference {
+    /**
+     * Cryptographic checksum of the referenced artifact for integrity verification.
+     */
+    checksum?: Checksum;
+    /**
+     * Optional human-readable description of this evidence entry.
+     */
+    description?: string;
+    /**
+     * The native format discriminator of the referenced artifact.
+     */
+    format: string;
+    /**
+     * Optional producer-declared version of the format (e.g. ECS '9.4.0', OCSF '1.8.0').
+     * Free-text and untrusted — HDF does not validate it against a registry.
+     */
+    formatVersion?: string;
+    /**
+     * Optional IANA media type describing the on-disk serialization, orthogonal to 'format'
+     * (the semantic standard). Examples: application/x-ndjson, application/json,
+     * application/vnd.apache.parquet, text/csv.
+     */
+    mediaType?: string;
+    /**
+     * Optional descriptive metadata about the referenced corpus. Does not affect integrity.
+     */
+    metadata?: ExternalEvidenceMetadata;
+    /**
+     * URI to the external native-format evidence artifact (log/telemetry corpus, etc.). Can be
+     * a relative path or absolute URL. The data stays canonical in its native format — HDF
+     * references it, never parses or transcodes it.
+     */
+    uri: string;
+    [property: string]: any;
+}
+
+/**
+ * Descriptive metadata about a referenced external evidence corpus. Does not affect integrity.
+ */
+export interface ExternalEvidenceMetadata {
+    /**
+     * The tool/pipeline that collected or produced the corpus. Example: 'aws-security-lake',
+     * 'elastic-agent'.
+     */
+    collector?: string;
+    /**
+     * Approximate number of records/events in the referenced corpus.
+     */
+    recordCount?: number;
+    /**
+     * The time window the referenced evidence covers.
+     */
+    timeRange?: ExternalEvidenceTimeRange;
+    [property: string]: any;
+}
+
+/**
+ * The time window a referenced external evidence corpus covers.
+ */
+export interface ExternalEvidenceTimeRange {
+    /**
+     * End of the time window the corpus covers (ISO 8601).
+     */
+    end?: Date;
+    /**
+     * Start of the time window the corpus covers (ISO 8601).
+     */
+    start?: Date;
+    [property: string]: any;
 }