@mitre/hdf-schema 3.2.0 → 3.3.0

package/dist/go/hdf.go

@@ -253,7 +253,7 @@ type Input struct {
 	// The data type of this input.                                                                                
 	Type                                                                                       *InputType          `json:"type,omitempty"`
 	// The input value. Type should match the declared type field. Accepts any JSON value.                         
-	Value interface{} `json:"value,omitempty"`
+	Value                                                                                      interface{}         `json:"value,omitempty"`
 }
 
 // Validation constraints for the input value.
@@ -338,6 +338,19 @@ type Checksum struct {
 // Core requirement fields shared between baseline requirements and evaluated requirements.
 // Contains the fundamental requirement definition without assessment results.
 type EvaluatedRequirement struct {
+	// Packages affected by this vulnerability finding. Vulnerability-finding-scoped — see                              
+	// components[] on hdf-system for component-level package inventories. One entry per matched                        
+	// package signature (scanners often report multiple CPE variations per CVE).                                       
+	AffectedPackages                                                                            []AffectedPackage       `json:"affectedPackages,omitempty"`
+	// Structured CVSS scoring data for vulnerability findings. One entry per CVE — a finding                           
+	// may match multiple CVEs (common in vulnerability scanners). Captures vendor-supplied Base                        
+	// metrics plus optional consumer-owned Threat / Environmental / Supplemental groups for                            
+	// risk adjustment. See cvss.schema.json.                                                                           
+	Cvss                                                                                        []Cvss                  `json:"cvss,omitempty"`
+	// Common Weakness Enumeration IDs associated with this finding. Use CWE-N format with no                           
+	// leading zeros (matches the MITRE catalog convention). For NIST control mappings derived                          
+	// from CWE, see tags.nist.                                                                                         
+	Cwe                                                                                         []string                `json:"cwe,omitempty"`
 	// Array of labeled descriptions. At least one description with label 'default' must be                             
 	// present. Convention: place default description first. Common labels: 'default', 'check',                         
 	// 'fix', 'rationale'.                                                                                              
@@ -355,9 +368,16 @@ type EvaluatedRequirement struct {
 	// recent non-expired override with a status field, or computed from results (worst-wins) if                        
 	// no status-bearing overrides exist.                                                                               
 	EffectiveStatus                                                                             *ResultStatus           `json:"effectiveStatus,omitempty"`
+	// 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.                                                                                                       
+	Epss                                                                                        *Epss                   `json:"epss,omitempty"`
 	// Supporting evidence for this requirement's findings, such as screenshots, code samples,                          
 	// or log excerpts.                                                                                                 
 	Evidence                                                                                    []Evidence              `json:"evidence,omitempty"`
+	// CISA Known Exploited Vulnerabilities (KEV) catalog status. When inKev=true, dateAdded and                        
+	// dueDate carry the federal patching deadline.                                                                     
+	Kev                                                                                         *Kev                    `json:"kev,omitempty"`
 	// Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance.                          
 	// POAMs do NOT change effectiveStatus - they track the work being done to address a                                
 	// failure. Separate from statusOverrides which DO change status.                                                   
@@ -412,6 +432,98 @@ type EvaluatedRequirement struct {
 	VerificationMethod                                                                          *VerificationMethodEnum `json:"verificationMethod,omitempty"`
 }
 
+// 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.
+type AffectedPackage struct {
+	// Optional CPE 2.3 URI identifying the affected product. Validated leniently: only the                
+	// 'cpe:2.3:' prefix and the part-type letter ('a' application, 'h' hardware, 'o' operating            
+	// system) are enforced here. Use `hdf-utilities.parseCpe` for full-grammar parsing.                   
+	// Example: 'cpe:2.3:a:openssl:openssl:1.1.1k:*:*:*:*:*:*:*'.                                          
+	Cpe                                                                                         *string    `json:"cpe,omitempty"`
+	// The packaging ecosystem the package belongs to. Use 'generic' for hardware, firmware, or            
+	// anything outside the listed language/OS package managers.                                           
+	Ecosystem                                                                                   *Ecosystem `json:"ecosystem,omitempty"`
+	// Optional version string identifying the first release that contains the fix for the                 
+	// vulnerability. Use the same version syntax as `version`. Example: '1.1.1l' fixes                    
+	// 'openssl@1.1.1k'.                                                                                   
+	FixedInVersion                                                                              *string    `json:"fixedInVersion,omitempty"`
+	// The package name as published in its ecosystem. Examples: 'openssl' (rpm), 'lodash'                 
+	// (npm), 'org.apache.logging.log4j:log4j-core' (maven, group:artifact).                               
+	Name                                                                                        *string    `json:"name,omitempty"`
+	// Optional Package URL (PURL) identifying the affected package. Validated leniently: only             
+	// the 'pkg:TYPE/' scheme prefix is enforced here, where TYPE follows the PURL grammar (a              
+	// letter followed by letters, digits, '.', '+', or '-') and is matched case-insensitively             
+	// to mirror `hdf-utilities.parsePurl`'s accept-and-warn behavior. Use `parsePurl` for full            
+	// PURL parsing. Example: 'pkg:rpm/redhat/openssl@1.1.1k-7.el8_4?arch=x86_64'.                         
+	Purl                                                                                        *string    `json:"purl,omitempty"`
+	// The exact version of the package that the vulnerability scanner observed. Use the                   
+	// ecosystem's native version string verbatim (e.g., '1.1.1k-7.el8_4' for rpm, '4.17.20' for           
+	// npm).                                                                                               
+	Version                                                                                     *string    `json:"version,omitempty"`
+}
+
+// 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.
+type Cvss struct {
+	// The Base score (0.0–10.0) computed from the base vector. Reflects the intrinsic,                       
+	// vendor-published severity before consumer enrichment.                                                  
+	BaseScore                                                                                   *float64      `json:"baseScore,omitempty"`
+	// Qualitative severity band corresponding to baseScore. CVSS 2.0 does not natively use                   
+	// 'none' or 'critical' bands; map accordingly when populating.                                           
+	BaseSeverity                                                                                *CVSSSeverity `json:"baseSeverity,omitempty"`
+	// Optional Base metric group vector string as emitted by the source (e.g.,                               
+	// 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'). For CVSS 2.0 the version prefix is                    
+	// omitted. Some vendor tools emit a final baseScore without the vector — in that case this               
+	// field is absent and the score cannot be recomputed or decomposed. The pattern accepts any              
+	// version-prefixed or prefix-less metric token sequence; semantic validity of individual                 
+	// metrics is checked by hdf-utilities, not by the schema.                                                
+	BaseVector                                                                                  *string       `json:"baseVector,omitempty"`
+	// Optional final score after combining Base + Threat + Environmental metrics. This is the                
+	// score consumers should treat as authoritative for risk decisions when present.                         
+	ComputedScore                                                                               *float64      `json:"computedScore,omitempty"`
+	// Qualitative severity band corresponding to computedScore. Same band convention as                      
+	// baseSeverity.                                                                                          
+	ComputedSeverity                                                                            *CVSSSeverity `json:"computedSeverity,omitempty"`
+	// Optional score (0.0–10.0) recomputed after applying Environmental metrics.                             
+	EnvironmentalScore                                                                          *float64      `json:"environmentalScore,omitempty"`
+	// Optional Environmental metric group vector segment (e.g., 'MAV:N/CR:H/IR:H/AR:H').                     
+	// Consumer-supplied — reflects the deployment context (criticality, mitigations, network                 
+	// exposure).                                                                                             
+	EnvironmentalVector                                                                         *string       `json:"environmentalVector,omitempty"`
+	// Optional identifier the CVSS data is associated with — most commonly a CVE ID (e.g.,                   
+	// 'CVE-2024-12345'), but may also be a vendor advisory ID, GHSA, or similar.                             
+	Source                                                                                      *string       `json:"source,omitempty"`
+	// Optional Supplemental metric group vector segment (CVSS 4.0 only). Examples:                           
+	// 'S:P/AU:N/V:C/RE:M/U:Amber'. Per CVSS 4.0 spec, supplemental metrics convey additional                 
+	// context but have no impact on the computed score.                                                      
+	SupplementalVector                                                                          *string       `json:"supplementalVector,omitempty"`
+	// Optional score (0.0–10.0) recomputed after applying Threat metrics. Always less than or                
+	// equal to baseScore in practice.                                                                        
+	ThreatScore                                                                                 *float64      `json:"threatScore,omitempty"`
+	// Optional Threat metric group vector segment (e.g., 'E:U/RL:O/RC:C' for CVSS 3.1, or 'E:A'              
+	// for CVSS 4.0). Consumer-supplied — captures real-world exploitation and remediation                    
+	// context the vendor cannot know.                                                                        
+	ThreatVector                                                                                *string       `json:"threatVector,omitempty"`
+	// The CVSS specification version this entry conforms to. Vendor scanners typically emit 3.1              
+	// or 4.0; legacy data may use 2.0 or 3.0.                                                                
+	Version                                                                                     Version       `json:"version"`
+}
+
 type Description struct {
 	// The description text content.                                                                   
 	Data                                                                                        string `json:"data"`
@@ -420,6 +532,26 @@ type Description struct {
 	Label                                                                                       string `json:"label"`
 }
 
+// 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.
+type Epss struct {
+	// ISO 8601 date (YYYY-MM-DD) on which FIRST.org published this EPSS score.                        
+	Date                                                                                       string  `json:"date"`
+	// Rank of this score relative to all scored CVEs, expressed as a value between 0.0 and 1.0        
+	// inclusive. A percentile of 0.99 means this CVE is scored at or above 99% of all scored          
+	// CVEs.                                                                                           
+	Percentile                                                                                 float64 `json:"percentile"`
+	// Exploit probability as a value between 0.0 and 1.0 inclusive. Higher values indicate            
+	// greater predicted likelihood of exploitation in the next 30 days. Example: 0.97532 means        
+	// roughly a 97.5% predicted probability.                                                          
+	Score                                                                                      float64 `json:"score"`
+}
+
 // Supporting evidence for a finding or override, such as screenshots, code samples, log
 // excerpts, or URLs.
 type Evidence struct {
@@ -478,15 +610,32 @@ type Evidence struct {
 //
 // Identity of who prepared this evidence package.
 type Identity struct {
-	// Optional description of the identity or identity system, particularly useful when type is          
-	// 'other'.                                                                                           
-	Description                                                                                 *string   `json:"description,omitempty"`
-	// The identifier value. Example: 'user@example.com', 'jdoe', 'automated-scanner-01'.                 
-	Identifier                                                                                  string    `json:"identifier"`
-	// 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.                                            
-	Type                                                                                        OwnerType `json:"type"`
+	// Optional description of the identity or identity system, particularly useful when type is             
+	// 'other'.                                                                                              
+	Description                                                                                 *string      `json:"description,omitempty"`
+	// The identifier value. Example: 'user@example.com', 'jdoe', 'automated-scanner-01'.                    
+	Identifier                                                                                  string       `json:"identifier"`
+	// 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.                                               
+	Type                                                                                        IdentityType `json:"type"`
+}
+
+// CISA Known Exploited Vulnerabilities (KEV) catalog status. When inKev=true, dateAdded and
+// dueDate carry the federal patching deadline.
+type Kev struct {
+	// ISO 8601 calendar date (YYYY-MM-DD) the vulnerability was added to the CISA KEV catalog.          
+	// Required when inKev is true.                                                                      
+	DateAdded                                                                                    *string `json:"dateAdded,omitempty"`
+	// ISO 8601 calendar date (YYYY-MM-DD) by which federal agencies must remediate per CISA BOD         
+	// 22-01. Normally later than dateAdded, but the schema does not enforce ordering because            
+	// CISA occasionally adjusts published dates. Required when inKev is true.                           
+	DueDate                                                                                      *string `json:"dueDate,omitempty"`
+	// Whether this vulnerability is currently in the CISA Known Exploited Vulnerabilities               
+	// catalog. When true, dateAdded and dueDate are required.                                           
+	InKev                                                                                        bool    `json:"inKev"`
+	// CISA's notes describing the vulnerability, observed exploitation, or remediation guidance.        
+	Notes                                                                                        *string `json:"notes,omitempty"`
 }
 
 // Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance.
@@ -516,21 +665,21 @@ type PoamElement struct {
 	// The type of POA&M. 'remediation' fixes root cause. 'mitigation' reduces risk via                    
 	// compensating controls. 'riskAcceptance' documents decision to accept risk.                          
 	// 'vendorDependency' tracks a fix that depends on a vendor releasing a patch or update.               
-	Type                                                                                       PoamType    `json:"type"`
+	Type                                                                                       POAMType    `json:"type"`
 }
 
 // A milestone or task within a POA&M remediation plan.
 type Milestone struct {
-	// Actual completion timestamp. ISO 8601 format.           
-	CompletedAt                                     *time.Time `json:"completedAt,omitempty"`
-	// Identity of who completed this milestone.               
-	CompletedBy                                     *Identity  `json:"completedBy,omitempty"`
-	// Description of this milestone or task.                  
-	Description                                     string     `json:"description"`
-	// Estimated completion date. ISO 8601 format.             
-	EstimatedCompletion                             time.Time  `json:"estimatedCompletion"`
-	// Current status of this milestone.                       
-	Status                                          Status     `json:"status"`
+	// Actual completion timestamp. ISO 8601 format.                
+	CompletedAt                                     *time.Time      `json:"completedAt,omitempty"`
+	// Identity of who completed this milestone.                    
+	CompletedBy                                     *Identity       `json:"completedBy,omitempty"`
+	// Description of this milestone or task.                       
+	Description                                     string          `json:"description"`
+	// Estimated completion date. ISO 8601 format.                  
+	EstimatedCompletion                             time.Time       `json:"estimatedCompletion"`
+	// Current status of this milestone.                            
+	Status                                          MilestoneStatus `json:"status"`
 }
 
 // Optional digital signature for enhanced trust and non-repudiation.
@@ -598,7 +747,7 @@ type VerificationMethod struct {
 //
 // A URI pointing at the reference.
 type Reference struct {
-	Ref *Ref `json:"ref,omitempty"`
+	Ref *Ref    `json:"ref,omitempty"`
 	URL *string `json:"url,omitempty"`
 	URI *string `json:"uri,omitempty"`
 }
@@ -646,6 +795,10 @@ type StatusOverride struct {
 	// Identity of who applied this override. For simple cases, use type 'simple' with just an                  
 	// identifier.                                                                                              
 	AppliedBy                                                                                   Identity        `json:"appliedBy"`
+	// 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.                                     
+	Cvss                                                                                        *Cvss           `json:"cvss,omitempty"`
 	// Supporting evidence for this override, such as screenshots demonstrating manual                          
 	// verification for attestations.                                                                           
 	Evidence                                                                                    []Evidence      `json:"evidence,omitempty"`
@@ -654,6 +807,12 @@ type StatusOverride struct {
 	ExpiresAt                                                                                   time.Time       `json:"expiresAt"`
 	// Override to the requirement's impact score. At least one of status or impact must be set.                
 	Impact                                                                                      *ImpactOverride `json:"impact,omitempty"`
+	// 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.                                                                      
+	Justification                                                                               *Justification  `json:"justification,omitempty"`
 	// 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.                                                                                        
@@ -744,9 +903,9 @@ type Component struct {
 	Owner                                                                                       *Identity         `json:"owner,omitempty"`
 	// Embedded CycloneDX or SPDX SBOM document representing this component's software                            
 	// inventory. The sbomFormat field determines which format constraints apply.                                 
-	Sbom interface{} `json:"sbom,omitempty"`
+	Sbom                                                                                        interface{}       `json:"sbom,omitempty"`
 	// Format of the SBOM (embedded or referenced). Required when sbom or sbomRef is present.                     
-	SbomFormat                                                                                  *SbomFormat       `json:"sbomFormat,omitempty"`
+	SbomFormat                                                                                  *SBOMFormat       `json:"sbomFormat,omitempty"`
 	// 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           `json:"sbomRef,omitempty"`
@@ -754,7 +913,7 @@ type Component struct {
 	// with matching labels are automatically included.                                                           
 	TargetSelector                                                                              map[string]string `json:"targetSelector,omitempty"`
 	// Component type discriminator. Same values as Target types.                                                 
-	Type                                                                                        Copyright         `json:"type"`
+	Type                                                                                        TargetType        `json:"type"`
 	// Fully qualified domain name.                                                                               
 	FQDN                                                                                        *string           `json:"fqdn,omitempty"`
 	// IP address of the host.                                                                                    
@@ -798,7 +957,7 @@ type Component struct {
 	// Cloud account identifier.                                                                                  
 	AccountID                                                                                   *string           `json:"accountId,omitempty"`
 	// Cloud provider.                                                                                            
-	Provider *CloudProvider `json:"provider,omitempty"`
+	Provider                                                                                    *CloudProvider    `json:"provider,omitempty"`
 	// Cloud region, if applicable.                                                                               
 	//                                                                                                            
 	// Cloud region where the resource resides.                                                                   
@@ -850,7 +1009,7 @@ type InputOverride struct {
 	// Rationale for why this override is needed.                                                          
 	Justification                                                                              *string     `json:"justification,omitempty"`
 	// The overridden value. Should match the type of the original input.                                  
-	Value interface{} `json:"value,omitempty"`
+	Value                                                                                      interface{} `json:"value"`
 }
 
 // Information about the tool that generated this file.
@@ -1147,10 +1306,10 @@ type BaselineDiff struct {
 
 // Comparison of a single component between two system document versions.
 type ComponentDiff struct {
-	// Component snapshot from the new system document.                                                
-	After interface{} `json:"after,omitempty"`
-	// Component snapshot from the old system document.                                                
-	Before interface{} `json:"before,omitempty"`
+	// Component snapshot from the new system document. Null when state is 'absent'.                   
+	After                                                                            interface{}       `json:"after,omitempty"`
+	// Component snapshot from the old system document. Null when state is 'new'.                      
+	Before                                                                           interface{}       `json:"before,omitempty"`
 	// Detailed field-level changes between the before and after component snapshots.                  
 	FieldChanges                                                                     []FieldChange     `json:"fieldChanges,omitempty"`
 	// Component name used for matching across system versions.                                        
@@ -1162,9 +1321,9 @@ type ComponentDiff struct {
 // A single field-level change between two versions of a requirement.
 type FieldChange struct {
 	// The new value of the field (for 'add' and 'replace' operations).                    
-	NewValue interface{} `json:"newValue,omitempty"`
+	NewValue                                                                   interface{} `json:"newValue,omitempty"`
 	// The previous value of the field (for 'remove' and 'replace' operations).            
-	OldValue interface{} `json:"oldValue,omitempty"`
+	OldValue                                                                   interface{} `json:"oldValue,omitempty"`
 	// The type of change operation.                                                       
 	Op                                                                         Op          `json:"op"`
 	// JSON Pointer path to the changed field.                                             
@@ -1175,13 +1334,13 @@ type FieldChange struct {
 // before/after snapshots.
 type RequirementDiff struct {
 	// The requirement as it appeared in the new source. Null when state is 'absent'.                                   
-	After interface{} `json:"after,omitempty"`
+	After                                                                                        interface{}            `json:"after"`
 	// Sensitive data from the new source that should not be included in the main after snapshot.                       
 	AfterSensitive                                                                               map[string]interface{} `json:"afterSensitive,omitempty"`
 	// IDs of annotations attached to this requirement diff.                                                            
 	AnnotationIDS                                                                                []string               `json:"annotationIds,omitempty"`
 	// The requirement as it appeared in the old/reference source. Null when state is 'new'.                            
-	Before interface{} `json:"before,omitempty"`
+	Before                                                                                       interface{}            `json:"before"`
 	// Sensitive data from the old source that should not be included in the main before                                
 	// snapshot.                                                                                                        
 	BeforeSensitive                                                                              map[string]interface{} `json:"beforeSensitive,omitempty"`
@@ -1237,7 +1396,7 @@ type Value struct {
 	// Human-readable label for the source.                                    
 	SourceLabel                                                    string      `json:"sourceLabel"`
 	// The value reported by this source for the conflicting field.            
-	Value interface{} `json:"value,omitempty"`
+	Value                                                          interface{} `json:"value"`
 }
 
 // Configuration for how requirements were matched across sources.
@@ -1500,7 +1659,7 @@ type DataFlow struct {
 	Protocol                                                                                    *string     `json:"protocol,omitempty"`
 	// The other end of this data flow. Can be a local component (UUID), a cross-system                     
 	// component reference, or an external endpoint.                                                        
-	To interface{} `json:"to,omitempty"`
+	To                                                                                          interface{} `json:"to"`
 }
 
 // Defines an assessment plan — what baselines to run against which targets, with resolved
@@ -1614,47 +1773,74 @@ type HDFAmendments struct {
 	Version                                                                                   *string              `json:"version,omitempty"`
 }
 
-// A standalone amendment that modifies a requirement's compliance status and/or impact
-// score. At least one of status or impact must be set. Extends the inline Override concept
-// with requirementId and baselineRef for use outside of results documents.
+// 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).
 type StandaloneOverride struct {
-	// When this amendment was applied. ISO 8601 format.                                                        
-	AppliedAt                                                                                   time.Time       `json:"appliedAt"`
-	// Identity of who applied this amendment.                                                                  
-	AppliedBy                                                                                   Identity        `json:"appliedBy"`
-	// Name of the baseline containing the requirement. Required when the system has multiple                   
-	// baselines with potentially overlapping requirement IDs.                                                  
-	BaselineRef                                                                                 *string         `json:"baselineRef,omitempty"`
-	// componentId of the component this amendment is scoped to. When set, the amendment only                   
-	// applies to the specified component. When omitted, the amendment applies system-wide.                     
-	ComponentRef                                                                                *string         `json:"componentRef,omitempty"`
-	// Supporting evidence (screenshots, logs, URLs, documents).                                                
-	Evidence                                                                                    []Evidence      `json:"evidence,omitempty"`
-	// When this amendment expires and must be reviewed. No permanent amendments. ISO 8601                      
-	// format.                                                                                                  
-	ExpiresAt                                                                                   time.Time       `json:"expiresAt"`
-	// Override to the requirement's impact score. At least one of status or impact must be set.                
-	Impact                                                                                      *ImpactOverride `json:"impact,omitempty"`
-	// componentId of the local component that provides this control. Set when the provider is                  
-	// in the same system. Omit for external or cross-system providers; the reason field                        
-	// explains the source. Primarily used with type 'inherited'.                                               
-	InheritedFrom                                                                               *string         `json:"inheritedFrom,omitempty"`
-	// Remediation milestones (primarily for POA&M type amendments).                                            
-	Milestones                                                                                  []Milestone     `json:"milestones,omitempty"`
-	// Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null                 
-	// for the first amendment.                                                                                 
-	PreviousChecksum                                                                            *Checksum       `json:"previousChecksum,omitempty"`
-	// Justification for this amendment.                                                                        
-	Reason                                                                                      string          `json:"reason"`
-	// The ID of the requirement being amended. Must match a requirement ID in the referenced                   
-	// baseline.                                                                                                
-	RequirementID                                                                               string          `json:"requirementId"`
-	// Digital signature for non-repudiation.                                                                   
-	Signature                                                                                   *Signature      `json:"signature,omitempty"`
-	// The new status this amendment sets. Optional when only impact is being overridden.                       
-	Status                                                                                      *ResultStatus   `json:"status,omitempty"`
-	// The type of amendment.                                                                                   
-	Type                                                                                        OverrideType    `json:"type"`
+	// Software packages this amendment is scoped to, distinct from componentRef (which scopes                    
+	// to an HDF-internal Component by UUID). Use when the source amendment format references                     
+	// packages by purl/cpe/name+version — e.g., VEX `affects[]` / `products[]`, OSCAL POA&M                      
+	// `subjects[]`, FedRAMP component-aware amendments. Symmetric with                                           
+	// Evaluated_Requirement.affectedPackages, which scopes findings to the same package                          
+	// vocabulary. When omitted, the amendment applies system-wide (or only to componentRef when                  
+	// that is set).                                                                                              
+	AffectedPackages                                                                            []AffectedPackage `json:"affectedPackages,omitempty"`
+	// When this amendment was applied. ISO 8601 format.                                                          
+	AppliedAt                                                                                   time.Time         `json:"appliedAt"`
+	// Identity of who applied this amendment.                                                                    
+	AppliedBy                                                                                   Identity          `json:"appliedBy"`
+	// Name of the baseline containing the requirement. Required when the system has multiple                     
+	// baselines with potentially overlapping requirement IDs.                                                    
+	BaselineRef                                                                                 *string           `json:"baselineRef,omitempty"`
+	// componentId of the component this amendment is scoped to. When set, the amendment only                     
+	// applies to the specified component. When omitted, the amendment applies system-wide.                       
+	ComponentRef                                                                                *string           `json:"componentRef,omitempty"`
+	// 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.                                       
+	Cvss                                                                                        *Cvss             `json:"cvss,omitempty"`
+	// Supporting evidence (screenshots, logs, URLs, documents).                                                  
+	Evidence                                                                                    []Evidence        `json:"evidence,omitempty"`
+	// When this amendment expires and must be reviewed. No permanent amendments. ISO 8601                        
+	// format.                                                                                                    
+	ExpiresAt                                                                                   time.Time         `json:"expiresAt"`
+	// Override to the requirement's impact score. At least one of status or impact must be set.                  
+	Impact                                                                                      *ImpactOverride   `json:"impact,omitempty"`
+	// componentId of the local component that provides this control. Set when the provider is                    
+	// in the same system. Omit for external or cross-system providers; the reason field                          
+	// explains the source. Primarily used with type 'inherited'.                                                 
+	InheritedFrom                                                                               *string           `json:"inheritedFrom,omitempty"`
+	// 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.                                                                        
+	Justification                                                                               *Justification    `json:"justification,omitempty"`
+	// Remediation milestones (primarily for POA&M type amendments).                                              
+	Milestones                                                                                  []Milestone       `json:"milestones,omitempty"`
+	// Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null                   
+	// for the first amendment.                                                                                   
+	PreviousChecksum                                                                            *Checksum         `json:"previousChecksum,omitempty"`
+	// Justification for this amendment.                                                                          
+	Reason                                                                                      string            `json:"reason"`
+	// The ID of the requirement being amended. Must match a requirement ID in the referenced                     
+	// baseline.                                                                                                  
+	RequirementID                                                                               string            `json:"requirementId"`
+	// Digital signature for non-repudiation.                                                                     
+	Signature                                                                                   *Signature        `json:"signature,omitempty"`
+	// The new status this amendment sets. Optional when only impact is being overridden.                         
+	Status                                                                                      *ResultStatus     `json:"status,omitempty"`
+	// The type of amendment.                                                                                     
+	Type                                                                                        OverrideType      `json:"type"`
 }
 
 // Bundles references to all HDF documents for audit, authorization, and compliance review.
@@ -1784,6 +1970,23 @@ const (
 	Sha512 HashAlgorithm = "sha512"
 )
 
+// The packaging ecosystem the package belongs to. Use 'generic' for hardware, firmware, or
+// anything outside the listed language/OS package managers.
+type Ecosystem string
+
+const (
+	Cargo   Ecosystem = "cargo"
+	Deb     Ecosystem = "deb"
+	Gem     Ecosystem = "gem"
+	Generic Ecosystem = "generic"
+	Go      Ecosystem = "go"
+	Maven   Ecosystem = "maven"
+	Npm     Ecosystem = "npm"
+	Nuget   Ecosystem = "nuget"
+	Pypi    Ecosystem = "pypi"
+	RPM     Ecosystem = "rpm"
+)
+
 // Whether the requirement is mandatory within its baseline. Distinct from severity (risk
 // weight) and status (lifecycle state). Maps cleanly onto: FedRAMP rev5 OSCAL 'CORE' prop,
 // FedRAMP 20x inline 'Optional:' markers, CMMC sublevel rows, and CIS Implementation Group
@@ -1814,6 +2017,36 @@ const (
 	Technical   ControlType = "technical"
 )
 
+// 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.
+type CVSSSeverity string
+
+const (
+	CVSSSeverityCritical CVSSSeverity = "critical"
+	CVSSSeverityHigh     CVSSSeverity = "high"
+	CVSSSeverityLow      CVSSSeverity = "low"
+	CVSSSeverityMedium   CVSSSeverity = "medium"
+	None                 CVSSSeverity = "none"
+)
+
+// The CVSS specification version this entry conforms to. Vendor scanners typically emit 3.1
+// or 4.0; legacy data may use 2.0 or 3.0.
+type Version string
+
+const (
+	The20 Version = "2.0"
+	The30 Version = "3.0"
+	The31 Version = "3.1"
+	The40 Version = "4.0"
+)
+
 // 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
@@ -1876,47 +2109,47 @@ const (
 // 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.
-type OwnerType string
+type IdentityType string
 
 const (
-	Email       OwnerType = "email"
-	PurpleOther OwnerType = "other"
-	Simple      OwnerType = "simple"
-	TypeSystem  OwnerType = "system"
-	Username    OwnerType = "username"
+	Email              IdentityType = "email"
+	IdentityTypeOther  IdentityType = "other"
+	IdentityTypeSystem IdentityType = "system"
+	Simple             IdentityType = "simple"
+	Username           IdentityType = "username"
 )
 
 // The type of evidence being provided.
 type EvidenceType string
 
 const (
-	Code        EvidenceType = "code"
-	File        EvidenceType = "file"
-	FluffyOther EvidenceType = "other"
-	Log         EvidenceType = "log"
-	Screenshot  EvidenceType = "screenshot"
-	URL         EvidenceType = "url"
+	Code              EvidenceType = "code"
+	EvidenceTypeOther EvidenceType = "other"
+	File              EvidenceType = "file"
+	Log               EvidenceType = "log"
+	Screenshot        EvidenceType = "screenshot"
+	URL               EvidenceType = "url"
 )
 
 // Current status of this milestone.
-type Status string
+type MilestoneStatus string
 
 const (
-	Completed  Status = "completed"
-	InProgress Status = "inProgress"
-	Pending    Status = "pending"
+	Completed  MilestoneStatus = "completed"
+	InProgress MilestoneStatus = "inProgress"
+	Pending    MilestoneStatus = "pending"
 )
 
 // The type of POA&M. 'remediation' fixes root cause. 'mitigation' reduces risk via
 // compensating controls. 'riskAcceptance' documents decision to accept risk.
 // 'vendorDependency' tracks a fix that depends on a vendor releasing a patch or update.
-type PoamType string
+type POAMType string
 
 const (
-	Mitigation       PoamType = "mitigation"
-	RiskAcceptance   PoamType = "riskAcceptance"
-	TypeRemediation  PoamType = "remediation"
-	VendorDependency PoamType = "vendorDependency"
+	Mitigation          POAMType = "mitigation"
+	POAMTypeRemediation POAMType = "remediation"
+	RiskAcceptance      POAMType = "riskAcceptance"
+	VendorDependency    POAMType = "vendorDependency"
 )
 
 // Explicit severity rating. Typically derived from impact score but provided explicitly for
@@ -1926,11 +2159,49 @@ const (
 type Severity string
 
 const (
-	Critical      Severity = "critical"
-	Informational Severity = "informational"
-	Medium        Severity = "medium"
-	SeverityHigh  Severity = "high"
-	SeverityLow   Severity = "low"
+	Informational    Severity = "informational"
+	SeverityCritical Severity = "critical"
+	SeverityHigh     Severity = "high"
+	SeverityLow      Severity = "low"
+	SeverityMedium   Severity = "medium"
+)
+
+// 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.
+type Justification string
+
+const (
+	ComponentNotPresent                         Justification = "component_not_present"
+	InlineMitigationsAlreadyExist               Justification = "inline_mitigations_already_exist"
+	ProtectedAtPerimeter                        Justification = "protected_at_perimeter"
+	ProtectedAtRuntime                          Justification = "protected_at_runtime"
+	ProtectedByCompiler                         Justification = "protected_by_compiler"
+	RequiresConfiguration                       Justification = "requires_configuration"
+	RequiresDependency                          Justification = "requires_dependency"
+	RequiresEnvironment                         Justification = "requires_environment"
+	VulnerableCodeCannotBeControlledByAdversary Justification = "vulnerable_code_cannot_be_controlled_by_adversary"
+	VulnerableCodeNotInExecutePath              Justification = "vulnerable_code_not_in_execute_path"
+	VulnerableCodeNotPresent                    Justification = "vulnerable_code_not_present"
 )
 
 // How this requirement is intended to be verified. Disambiguates the two cases that null
@@ -1966,30 +2237,28 @@ const (
 )
 
 // Format of the SBOM (embedded or referenced). Required when sbom or sbomRef is present.
-type SbomFormat string
+type SBOMFormat string
 
 const (
-	Cyclonedx SbomFormat = "cyclonedx"
-	Spdx      SbomFormat = "spdx"
+	Cyclonedx SBOMFormat = "cyclonedx"
+	Spdx      SBOMFormat = "spdx"
 )
 
-// A human readable/meaningful reference. Example: a book title.
-//
-// IP address of the host.
-type Copyright string
+// Component type discriminator. Same values as Target types.
+type TargetType string
 
 const (
-	Application       Copyright = "application"
-	Artifact          Copyright = "artifact"
-	CloudAccount      Copyright = "cloudAccount"
-	CloudResource     Copyright = "cloudResource"
-	ContainerImage    Copyright = "containerImage"
-	ContainerInstance Copyright = "containerInstance"
-	ContainerPlatform Copyright = "containerPlatform"
-	Database          Copyright = "database"
-	Host              Copyright = "host"
-	Network           Copyright = "network"
-	Repository        Copyright = "repository"
+	Application       TargetType = "application"
+	Artifact          TargetType = "artifact"
+	CloudAccount      TargetType = "cloudAccount"
+	CloudResource     TargetType = "cloudResource"
+	ContainerImage    TargetType = "containerImage"
+	ContainerInstance TargetType = "containerInstance"
+	ContainerPlatform TargetType = "containerPlatform"
+	Database          TargetType = "database"
+	Host              TargetType = "host"
+	Network           TargetType = "network"
+	Repository        TargetType = "repository"
 )
 
 // The category of this annotation.
@@ -2011,10 +2280,10 @@ const (
 type BaselineDiffState string
 
 const (
-	PurpleUnchanged BaselineDiffState = "unchanged"
-	PurpleUpdated   BaselineDiffState = "updated"
-	StateAbsent     BaselineDiffState = "absent"
-	StateNew        BaselineDiffState = "new"
+	BaselineDiffStateAbsent    BaselineDiffState = "absent"
+	BaselineDiffStateNew       BaselineDiffState = "new"
+	BaselineDiffStateUnchanged BaselineDiffState = "unchanged"
+	BaselineDiffStateUpdated   BaselineDiffState = "updated"
 )
 
 // The mode of comparison being performed.
@@ -2123,10 +2392,10 @@ const (
 type PackageDiffState string
 
 const (
-	Added           PackageDiffState = "added"
-	FluffyUnchanged PackageDiffState = "unchanged"
-	FluffyUpdated   PackageDiffState = "updated"
-	Removed         PackageDiffState = "removed"
+	Added                     PackageDiffState = "added"
+	PackageDiffStateUnchanged PackageDiffState = "unchanged"
+	PackageDiffStateUpdated   PackageDiffState = "updated"
+	Removed                   PackageDiffState = "removed"
 )
 
 // The original format of the source document before conversion to HDF.
@@ -2357,8 +2626,3 @@ func marshalUnion(pi *int64, pf *float64, pb *bool, ps *string, haveArray bool,
 	}
 	return nil, errors.New("Union must not be null")
 }
-
-// Backward-compatible aliases for renamed constants.
-const (
-	CopyrightApplication = Application
-)