@mitre/hdf-schema 3.0.1 → 3.1.0

package/LICENSE.md

@@ -0,0 +1,55 @@
+# License
+
+Copyright © 2025 The MITRE Corporation.
+
+Approved for Public Release; Distribution Unlimited. Case Number 18-3678.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain a
+copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+
+## Redistribution Terms
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright/digital
+  rights legend, this list of conditions and the following Notice.
+- Redistributions in binary form must reproduce the above
+  copyright/digital rights legend, this list of conditions and the
+  following Notice in the documentation and/or other materials provided
+  with the distribution.
+- Neither the name of The MITRE Corporation nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+## Notice
+
+The MITRE Corporation grants permission to reproduce, distribute, modify, and
+otherwise use this software to the extent permitted by the licensed terms
+provided in the LICENSE file included with this project.
+
+This software was produced by The MITRE Corporation for the U.S. Government
+under contract. As such the U.S. Government has certain use and data
+rights in this software. No use other than those granted to the U.S.
+Government, or to those acting on behalf of the U.S. Government, under
+these contract arrangements is authorized without the express written
+permission of The MITRE Corporation.
+
+Some files in this codebase were generated by generative AI, under the
+direction and review of The MITRE Corporation employees, for the purpose of
+development efficiency. All AI-generated code functionality was validated
+by standard quality and assurance testing.
+
+For further information, please contact The MITRE Corporation,
+Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539,
+(703) 983-6000.

package/README.md

@@ -7,7 +7,7 @@ JSON schemas and multi-language type definitions for **Heimdall Data Format (HDF
 HDF is a standardized format for representing security assessment results. This package provides:
 
 - **JSON Schemas** for validating HDF documents
-- **Generated types** for TypeScript, Go, and Python
+- **Generated types** for TypeScript and Go
 
 ## Installation
 
@@ -17,31 +17,67 @@ npm install @mitre/hdf-schema
 
 ## Schema Types
 
-### HDF Results
+Seven document types covering the full security assessment lifecycle:
 
-Assessment results from running security checks against target systems. Contains:
+### HDF Results (`hdf-results`)
 
-- Target system information (hosts, containers, cloud accounts, etc.)
-- Evaluated baselines with requirement results
-- Pass/fail status for each check
-- Statistics and timing data
+Assessment findings from running security checks against target systems. The primary output of converters. Contains evaluated baselines with requirement results, components (hosts, containers, cloud resources), status overrides with disposition tracking, and statistics.
 
-### HDF Baseline
+### HDF Baseline (`hdf-baseline`)
 
-Security requirement definitions without results. Contains:
+Security requirement definitions without results — the "what to check" document. Contains requirement metadata (title, descriptions, severity, impact), check/fix instructions, framework mappings (NIST, CCI), and dependency information.
 
-- Requirement metadata (title, description, severity)
-- Check and fix instructions
-- Framework mappings (NIST, CIS, etc.)
-- Dependencies between requirements
+### HDF System (`hdf-system`)
+
+Authorization boundary definition. Describes a system's components (with polymorphic types: host, container, cloud account, application, etc.), data flows between components, and control designations (common/hybrid/system-specific).
+
+### HDF Plan (`hdf-plan`)
+
+Assessment plan linking baselines to system components. Defines what will be assessed, how, and by whom. References baselines, systems, and runner configurations.
+
+### HDF Amendments (`hdf-amendments`)
+
+Standalone amendment documents containing waivers, attestations, POA&Ms, and other overrides. Applied to results via `hdf amend apply` to track adjudication decisions (false positives, risk adjustments, operational requirements).
+
+### HDF Evidence Package (`hdf-evidence-package`)
+
+Bundles references to all documents needed for a compliance review — results, baselines, system, plan, and amendments — with checksums for integrity verification.
+
+### HDF Comparison (`hdf-comparison`)
+
+Output of the diff engine. Structural comparison between two or more HDF documents showing requirement-level changes, status transitions, and field diffs.
 
 ## Usage
 
+### Importing Schemas
+
+Schemas can be imported in two ways:
+
+```typescript
+// Named exports from the barrel (all schemas available)
+import { hdfResultsSchema, hdfBaselineSchema, hdfSystemSchema } from '@mitre/hdf-schema';
+
+// Sub-path imports (one schema per import, tree-shakeable)
+import type { HdfResults } from '@mitre/hdf-schema/hdf-results';
+import type { HdfBaseline } from '@mitre/hdf-schema/hdf-baseline';
+import type { HdfSystem } from '@mitre/hdf-schema/hdf-system';
+import type { HdfPlan } from '@mitre/hdf-schema/hdf-plan';
+import type { HdfAmendments } from '@mitre/hdf-schema/hdf-amendments';
+import type { HdfEvidencePackage } from '@mitre/hdf-schema/hdf-evidence-package';
+import type { HdfComparison } from '@mitre/hdf-schema/hdf-comparison';
+```
+
+Helper functions (severity mapping, effective status computation):
+
+```typescript
+import { severityToImpact, impactToSeverity, computeEffectiveStatus } from '@mitre/hdf-schema/helpers';
+```
+
 ### Validating Documents (TypeScript/JavaScript)
 
 ```typescript
 import Ajv from 'ajv';
-import hdfResultsSchema from '@mitre/hdf-schema/schemas/hdf-results.schema.json';
+import { hdfResultsSchema } from '@mitre/hdf-schema';
 
 const ajv = new Ajv({ strict: false });
 const validate = ajv.compile(hdfResultsSchema);
@@ -58,8 +94,8 @@ if (!isValid) {
 import type { HdfResults, HdfBaseline } from '@mitre/hdf-schema';
 
 function processResults(results: HdfResults) {
-  for (const baseline of results.profiles) {
-    for (const requirement of baseline.controls) {
+  for (const baseline of results.baselines) {
+    for (const requirement of baseline.requirements) {
       console.log(`${requirement.id}: ${requirement.results[0]?.status}`);
     }
   }
@@ -69,39 +105,33 @@ function processResults(results: HdfResults) {
 ### Using Generated Types (Go)
 
 ```go
-import "github.com/mitre/hdf-libs/hdf-schema/dist/go/hdf"
+import hdf "github.com/mitre/hdf-libs/hdf-schema/dist/go"
 
 func main() {
-    data := []byte(`{"platform": {...}, "profiles": [...]}`)
-    results, err := hdf.UnmarshalHdfResults(data)
+    data := []byte(`{"baselines": [...]}`)
+    results, err := hdf.UnmarshalHDFResults(data)
     if err != nil {
         panic(err)
     }
-    fmt.Println(results.Version)
+    for _, baseline := range results.Baselines {
+        fmt.Printf("%s: %d requirements\n", baseline.Name, len(baseline.Requirements))
+    }
 }
 ```
 
-### Using Generated Types (Python)
-
-```python
-from hdf_results import HdfResults
-import json
-
-with open('results.json') as f:
-    data = json.load(f)
-    results = HdfResults.from_dict(data)
-    print(results.version)
-```
-
 ## Schema Files
 
 | File | Description |
 |------|-------------|
-| `src/schemas/hdf-results.schema.json` | Results schema (modular, uses $ref) |
-| `src/schemas/hdf-baseline.schema.json` | Baseline schema (modular, uses $ref) |
+| `src/schemas/hdf-results.schema.json` | Assessment findings (modular, uses $ref) |
+| `src/schemas/hdf-baseline.schema.json` | Requirement definitions without results |
+| `src/schemas/hdf-system.schema.json` | Authorization boundary, components, data flows |
+| `src/schemas/hdf-plan.schema.json` | Assessment plan linking baselines to components |
+| `src/schemas/hdf-amendments.schema.json` | Waivers, attestations, POA&Ms |
+| `src/schemas/hdf-evidence-package.schema.json` | Bundle of references to all documents |
+| `src/schemas/hdf-comparison.schema.json` | Differential analysis between assessments |
 | `src/schemas/primitives/*.schema.json` | Shared type definitions |
-| `dist/schemas/hdf-results.schema.json` | Bundled results schema (self-contained) |
-| `dist/schemas/hdf-baseline.schema.json` | Bundled baseline schema (self-contained) |
+| `dist/schemas/*.schema.json` | Bundled schemas (self-contained, all $refs inlined) |
 
 ### Modular vs Bundled Schemas
 
@@ -115,9 +145,8 @@ After building, types are available in:
 
 | Language | Location |
 |----------|----------|
-| TypeScript | `dist/ts/hdf-results.ts`, `dist/ts/hdf-baseline.ts` |
-| Go | `dist/go/hdf_results.go`, `dist/go/hdf_baseline.go` |
-| Python | `dist/python/hdf_results.py`, `dist/python/hdf_baseline.py` |
+| TypeScript | `dist/ts/hdf-*.ts` (7 files, one per schema) |
+| Go | `dist/go/hdf.go` (single file containing all types) |
 
 ## Development
 
@@ -144,7 +173,7 @@ This package has two version numbers that serve different purposes:
 
 - **Package version** (`package.json` `version`): Follows npm semver. Bumped on every release — bug fixes, new helpers, type generation improvements, dependency updates. This is what consumers see in `npm install @mitre/hdf-schema@3.0.1`.
 
-- **Schema version** (`$id` URL in each `.schema.json`): Identifies the schema structure itself. Only changes when the schema structure changes — new fields, removed fields, type changes, constraint changes. Example: `https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.0.0`.
+- **Schema version** (`$id` URL in each `.schema.json`): Identifies the schema structure itself. Only changes when the schema structure changes — new fields, removed fields, type changes, constraint changes. Example: `https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.1.0`.
 
 These versions are aligned at major boundaries (both are 3.x to signal this is the successor to the heimdall2 v2.x ecosystem) but can diverge at minor/patch levels. A package patch release (e.g., 3.0.1 → 3.0.2) that only fixes a converter bug or updates a helper function does not change the schema `$id`. A schema structural change (e.g., adding a new required field) bumps the schema version in the `$id` URL regardless of where the package version stands.
 
@@ -153,3 +182,17 @@ The `$id` URLs are also the canonical hosted location for each schema: `https://
 ### JSON Schema dialect
 
 All schemas use **JSON Schema draft/2020-12**.
+
+### Hosted schema documentation
+
+Interactive schema reference documentation is published at:
+**<https://mitre.github.io/hdf-libs/schemas/>**
+
+### What's new in v3.1.0
+
+- **`disposition`** field on `EvaluatedRequirement` — the type of the governing override or POAM (e.g., `waiver`, `falsePositive`, `riskAdjustment`). Indicates why a requirement is in its current state.
+- **`effectiveImpact`** field on `EvaluatedRequirement` — the computed impact score (0.0–1.0) after applying the most recent non-expired impact override.
+- **`Impact_Override`** type on `Status_Override` and `Standalone_Override` — object with a `value` field (0.0–1.0). At least one of `status` or `impact` must be set (enforced via `anyOf`).
+- **`Override_Type` expansion** — added `falsePositive`, `riskAdjustment`, `operationalRequirement`; removed `exception` (use `waiver` with `status: "notApplicable"` instead).
+- **`vendorDependency`** added to POAM type enum.
+- **Breaking:** The `./schemas/<name>.schema.json` sub-path export was removed. Use named imports from the barrel (`import { hdfResultsSchema } from '@mitre/hdf-schema'`) instead.

package/dist/go/hdf.go

@@ -342,8 +342,18 @@ type EvaluatedRequirement struct {
 	// present. Convention: place default description first. Common labels: 'default', 'check',                        
 	// 'fix', 'rationale'.                                                                                             
 	Descriptions                                                                                []Description          `json:"descriptions"`
-	// The current effective status of this requirement after applying the most recent                                 
-	// non-expired override, or computed from results if no overrides exist.                                           
+	// 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.                                                                                                    
+	Disposition                                                                                 *OverrideType          `json:"disposition,omitempty"`
+	// The current effective impact score (0.0–1.0) after applying the most recent non-expired                         
+	// override with an impact field. Absent when no impact overrides apply; consumers should                          
+	// use the requirement's impact field in that case.                                                                
+	EffectiveImpact                                                                             *float64               `json:"effectiveImpact,omitempty"`
+	// 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.                                                                              
 	EffectiveStatus                                                                             *ResultStatus          `json:"effectiveStatus,omitempty"`
 	// Supporting evidence for this requirement's findings, such as screenshots, code samples,                         
 	// or log excerpts.                                                                                                
@@ -359,9 +369,10 @@ type EvaluatedRequirement struct {
 	Severity                                                                                    *Severity              `json:"severity,omitempty"`
 	// The explicit location of the requirement within the source code.                                                
 	SourceLocation                                                                              *SourceLocation        `json:"sourceLocation,omitempty"`
-	// Chronological history of all status overrides applied to this requirement. Status                               
-	// overrides are intentional changes to the compliance status (waivers, attestations). Most                        
-	// recent override should be first in array. Preserves full audit trail.                                           
+	// Chronological history of all overrides applied to this requirement. Overrides are                               
+	// intentional changes to the compliance status and/or impact score (waivers, attestations,                        
+	// false positives, risk adjustments). Most recent override should be first in array.                              
+	// Preserves full audit trail.                                                                                     
 	StatusOverrides                                                                             []StatusOverride       `json:"statusOverrides,omitempty"`
 	// The requirement identifier. Example: 'SV-238196'.                                                               
 	ID                                                                                          string                 `json:"id"`
@@ -421,8 +432,8 @@ type Evidence struct {
 //
 // The identity that created this signature.
 //
-// Identity of who applied this status override. For simple cases, use type 'simple' with
-// just an identifier.
+// 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.
 //
@@ -482,6 +493,7 @@ type PoamElement struct {
 	Signature                                                                                  *Signature  `json:"signature,omitempty"`
 	// 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"`
 }
 
@@ -603,36 +615,48 @@ type SourceLocation struct {
 	Ref                                                       *string  `json:"ref,omitempty"`
 }
 
-// An intentional change to a requirement's compliance status (waiver or attestation).
-// Status overrides change the effectiveStatus of the requirement. All status 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.
 type StatusOverride struct {
-	// Timestamp when this status override was applied. ISO 8601 format.                                    
-	AppliedAt                                                                                  time.Time    `json:"appliedAt"`
-	// Identity of who applied this status override. For simple cases, use type 'simple' with               
-	// just an identifier.                                                                                  
-	AppliedBy                                                                                  Identity     `json:"appliedBy"`
-	// Supporting evidence for this status override, such as screenshots demonstrating manual               
-	// verification for attestations.                                                                       
-	Evidence                                                                                   []Evidence   `json:"evidence,omitempty"`
-	// Timestamp when this status override expires and must be reviewed/renewed. REQUIRED - no              
-	// permanent status overrides allowed. ISO 8601 format.                                                 
-	ExpiresAt                                                                                  time.Time    `json:"expiresAt"`
-	// 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.                                                                                    
-	PreviousChecksum                                                                           *Checksum    `json:"previousChecksum,omitempty"`
-	// Explanation for why this status override was applied.                                                
-	Reason                                                                                     string       `json:"reason"`
-	// 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.                                                                                             
-	Signature                                                                                  *Signature   `json:"signature,omitempty"`
-	// The new status this override sets for the requirement. This intentionally changes the                
-	// compliance status.                                                                                   
-	Status                                                                                     ResultStatus `json:"status"`
-	// The type of status override applied to this requirement.                                             
-	Type                                                                                       OverrideType `json:"type"`
+	// Timestamp when this override was applied. ISO 8601 format.                                               
+	AppliedAt                                                                                   time.Time       `json:"appliedAt"`
+	// Identity of who applied this override. For simple cases, use type 'simple' with just an                  
+	// identifier.                                                                                              
+	AppliedBy                                                                                   Identity        `json:"appliedBy"`
+	// Supporting evidence for this override, such as screenshots demonstrating manual                          
+	// verification for attestations.                                                                           
+	Evidence                                                                                    []Evidence      `json:"evidence,omitempty"`
+	// Timestamp when this override expires and must be reviewed/renewed. REQUIRED - no                         
+	// permanent overrides allowed. 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"`
+	// 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.                                                                                        
+	PreviousChecksum                                                                            *Checksum       `json:"previousChecksum,omitempty"`
+	// Explanation for why this override was applied.                                                           
+	Reason                                                                                      string          `json:"reason"`
+	// 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.                                                                                                 
+	Signature                                                                                   *Signature      `json:"signature,omitempty"`
+	// The new status this override sets for the requirement. Optional when only impact is being                
+	// overridden.                                                                                              
+	Status                                                                                      *ResultStatus   `json:"status,omitempty"`
+	// The type of override applied to this requirement.                                                        
+	Type                                                                                        OverrideType    `json:"type"`
+}
+
+// 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.
+type ImpactOverride struct {
+	// The overridden impact score (0.0–1.0).        
+	Value                                    float64 `json:"value"`
 }
 
 // A supported platform target. Example: the platform name being 'ubuntu'.
@@ -1514,7 +1538,7 @@ type Schedule struct {
 	StartDate                                                                                  *time.Time `json:"startDate,omitempty"`
 }
 
-// Waivers, attestations, exceptions, and POA&Ms that modify requirement compliance status.
+// 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.
 type HDFAmendments struct {
 	// Unique identifier for this amendments document. Useful for cross-referencing when                           
@@ -1536,7 +1560,7 @@ type HDFAmendments struct {
 	Labels                                                                                    map[string]string    `json:"labels,omitempty"`
 	// Human-readable name for this amendments document. Example: 'Portal Q1 2026 Waivers'.                        
 	Name                                                                                      string               `json:"name"`
-	// The set of amendments (waivers, attestations, exceptions, POA&Ms).                                          
+	// The set of amendments (waivers, attestations, POA&Ms, and other overrides).                                 
 	Overrides                                                                                 []StandaloneOverride `json:"overrides"`
 	// Document-level digital signature covering all amendments.                                                   
 	Signature                                                                                 *Signature           `json:"signature,omitempty"`
@@ -1546,46 +1570,47 @@ type HDFAmendments struct {
 	Version                                                                                   *string              `json:"version,omitempty"`
 }
 
-// A standalone amendment that modifies a requirement's compliance status. Extends the
-// inline Status_Override concept with requirementId and baselineRef for use outside of
-// results documents.
+// 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.
 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"`
-	// 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. For POA&Ms, this is the current status (POA&Ms track             
-	// work, they don't change status).                                                                     
-	Status                                                                                     ResultStatus `json:"status"`
-	// The type of amendment.                                                                               
-	Type                                                                                       OverrideType `json:"type"`
+	// 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"`
 }
 
 // Bundles references to all HDF documents for audit, authorization, and compliance review.
@@ -1715,8 +1740,44 @@ const (
 	Sha512 HashAlgorithm = "sha512"
 )
 
-// The current effective status of this requirement after applying the most recent
-// non-expired override, or computed from results if no overrides exist.
+// 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.
+type OverrideType string
+
+const (
+	Attestation            OverrideType = "attestation"
+	FalsePositive          OverrideType = "falsePositive"
+	Inherited              OverrideType = "inherited"
+	OperationalRequirement OverrideType = "operationalRequirement"
+	OverrideTypeWaiver     OverrideType = "waiver"
+	Poam                   OverrideType = "poam"
+	RiskAdjustment         OverrideType = "riskAdjustment"
+)
+
+// 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.,
@@ -1724,11 +1785,10 @@ const (
 //
 // The status of this test within the requirement. Example: 'failed'.
 //
-// The new status this override sets for the requirement. This intentionally changes the
-// compliance status.
+// The new status this override sets for the requirement. Optional when only impact is being
+// overridden.
 //
-// The new status this amendment sets. For POA&Ms, this is the current status (POA&Ms track
-// work, they don't change status).
+// The new status this amendment sets. Optional when only impact is being overridden.
 type ResultStatus string
 
 const (
@@ -1775,12 +1835,14 @@ const (
 
 // 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
 
 const (
-	Mitigation      PoamType = "mitigation"
-	RiskAcceptance  PoamType = "riskAcceptance"
-	TypeRemediation PoamType = "remediation"
+	Mitigation       PoamType = "mitigation"
+	RiskAcceptance   PoamType = "riskAcceptance"
+	TypeRemediation  PoamType = "remediation"
+	VendorDependency PoamType = "vendorDependency"
 )
 
 // Explicit severity rating. Typically derived from impact score but provided explicitly for
@@ -1797,24 +1859,6 @@ const (
 	SeverityLow   Severity = "low"
 )
 
-// The type of status override applied to this requirement.
-//
-// The type of amendment. 'waiver': risk accepted (AO). 'attestation': manually verified
-// (assessor). 'exception': not applicable (system owner + AO). 'poam': remediation tracked
-// (no status change). 'inherited': control provided by another component or system
-// (overrides to notApplicable/passed).
-//
-// The type of amendment.
-type OverrideType string
-
-const (
-	Attestation        OverrideType = "attestation"
-	Exception          OverrideType = "exception"
-	Inherited          OverrideType = "inherited"
-	OverrideTypeWaiver OverrideType = "waiver"
-	Poam               OverrideType = "poam"
-)
-
 type CloudProvider string
 
 const (