HDF Comparison — v3.3.0

Structured comparison between two or more HDF security assessment documents. Supports temporal, baseline, fleet, and multi-source comparison modes.

Version	v3.3.0
$id	https://mitre.github.io/hdf-libs/schemas/hdf-comparison/v3.3.0
Download	hdf-comparison.schema.json

Properties

Field	Type	Required	Description
formatVersion	"1.0.0"	yes	Schema version for this comparison format.
comparisonMode	Comparison_Mode	yes	The mode of comparison being performed.
timestamp	string (date-time)	no	When this comparison was performed.
generator	Generator	no	Information about the tool that generated this comparison.
sources	Source[]	yes	The source documents being compared. At least two sources are required.
matching	Matching_Config	no	Configuration for how requirements were matched across sources.
summary	Comparison_Summary	yes	Summary statistics for the overall comparison.
baselineDiffs	Baseline_Diff[]	no	Comparison of baselines between sources.
requirementDiffs	Requirement_Diff[]	yes	Detailed comparison of individual requirements between sources.
componentDiffs	Component_Diff[]	no	Comparison of components between two system documents. Used in systemDrift mode. A component's BOM changes surface as a field change on its boms[] here.
packageDiffs	Package_Diff[]	no	RESERVED — not emitted by the current systemDrift comparison. systemDrift now reports a component's BOM changes as a field change on its boms[] (see componentDiffs), and standalone SBOM package diffing is a separate hdf diff <sbom> <sbom> output shape. This field is retained for a future normalized package-level diff; consumers must not expect it from today's systemDrift output.
systemRef	string (uri-reference)	no	URI identifying the system being compared in systemDrift mode.
drift	Requirement_Diff[]	no	External/metadata changes separate from status changes (Terraform pattern).
annotations	Map<string, Annotation>	no	Map of annotation IDs to annotation objects, providing context or action items for requirement diffs.
integrity	Integrity	no	Cryptographic integrity information for verifying this comparison document.
extensions	Map<string, any>	no	Reserved for tool-specific data not defined in the HDF standard.

Embedded Primitives

These types are embedded from shared primitive schemas.

https://mitre.github.io/hdf-libs/schemas/hdf-results

Evaluated_Baseline

Information on a baseline that was evaluated, including any findings.

Field	Type	Required	Description
depends	Dependency[]	no	The set of dependencies this baseline depends on.
parentBaseline	string	no	The name of the parent baseline if this is a dependency of another.
description	string	no	The description - should be more detailed than the summary.
integrity	Integrity	no	Cryptographic integrity information for verifying this baseline has not been tampered with.
originalChecksum	Checksum	no	SHA-256 checksum of the original baseline definition file (before execution). This is an immutable reference to the baseline as defined, used to detect tampering with baseline requirements or metadata.
resultsChecksum	Checksum	no	SHA-256 checksum of the raw results before any amendments (statusOverrides or POAMs). Used to detect tampering with test results. Compare with currentChecksum to verify amendment integrity.
statusMessage	string	no	An explanation of the baseline status. Example: why it was skipped, failed to load, or any other status details.
requirements	Evaluated_Requirement[]	yes	The set of requirements including any findings. A baseline must have at least one requirement.
groups	Requirement_Group[]	no	A set of descriptions for the requirement groups.
inputs	Input[]	no	Typed inputs used to parameterize this baseline at execution time. See the Input primitive for the full schema.
extensions	Map<string, any>	no	Reserved for tool-specific baseline metadata not defined in the HDF standard.

Evaluated_Requirement

A requirement that has been evaluated, including any findings.

Field	Type	Required	Description
descriptions	Requirement_Description[]	yes	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'.
severity	Severity	no	Explicit severity rating. Typically derived from impact score but provided explicitly for clarity.
sourceLocation	Source_Location	no	The explicit location of the requirement within the source code.
results	Requirement_Result[]	yes	The set of all tests within the requirement and their results.
statusOverrides	Status_Override[]	no	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.
poams	POAM[]	no	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.
effectiveStatus	Result_Status	no	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.
effectiveImpact	number	no	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.
disposition	Override_Type	no	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.
evidence	Evidence[]	no	Supporting evidence for this requirement's findings, such as screenshots, code samples, or log excerpts.
cvss	Cvss[]	no	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.
epss	Epss	no	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.
kev	Kev	no	CISA Known Exploited Vulnerabilities (KEV) catalog status. When inKev=true, dateAdded and dueDate carry the federal patching deadline.
cwe	string[]	no	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.
affectedPackages	Affected_Package[]	no	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).

Example

{
  "$comment": "Passing requirement — no overrides, no disposition",
  "id": "SV-230222",
  "title": "RHEL 9 must use SSH protocol version 2",
  "impact": 0.7,
  "tags": {
    "nist": [
      "SC-8"
    ]
  },
  "descriptions": [
    {
      "label": "default",
      "data": "SSH must use protocol version 2."
    }
  ],
  "results": [
    {
      "status": "passed",
      "codeDesc": "sshd_config Protocol is expected to eq 2",
      "startTime": "2026-01-15T10:00:00Z"
    }
  ],
  "effectiveStatus": "passed"
}

affected-package

Affected_Package

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.

Field	Type	Required	Description
name	string	no	The package name as published in its ecosystem. Examples: 'openssl' (rpm), 'lodash' (npm), 'org.apache.logging.log4j:log4j-core' (maven, group:artifact).
version	string	no	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).
ecosystem	"npm" | "pypi" | "rpm" | "deb" | "maven" | "gem" | "nuget" | "go" | "cargo" | "generic"	no	The packaging ecosystem the package belongs to. Use 'generic' for hardware, firmware, or anything outside the listed language/OS package managers.
cpe	string	no	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🅰️openssl:openssl:1.1.1k::::::😗'.
purl	string	no	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'.
fixedInVersion	string	no	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'.

Example

{
  "$comment": "RPM ecosystem with full CPE + PURL — typical Grype/Trivy output for a RHEL host scan.",
  "name": "openssl",
  "version": "1.1.1k-7.el8_4",
  "ecosystem": "rpm",
  "cpe": "cpe:2.3:a:openssl:openssl:1.1.1k:*:*:*:*:*:*:*",
  "purl": "pkg:rpm/redhat/openssl@1.1.1k-7.el8_4?arch=x86_64",
  "fixedInVersion": "1.1.1l"
}

amendments

Override_Type

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.

Justification

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.

Impact_Override

An override to the requirement's impact score. The prior impact is the original result value or the preceding override in the chain.

Field	Type	Required	Description
value	number	yes	The overridden impact score (0.0–1.0).

Standalone_Override

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).

Field	Type	Required	Description
type	Override_Type	yes	The type of amendment.
requirementId	string	yes	The ID of the requirement being amended. Must match a requirement ID in the referenced baseline.
baselineRef	string	no	Name of the baseline containing the requirement. Required when the system has multiple baselines with potentially overlapping requirement IDs.
status	Result_Status	no	The new status this amendment sets. Optional when only impact is being overridden.
impact	Impact_Override	no	Override to the requirement's impact score. At least one of status or impact must be set.
reason	string	yes	Justification for this amendment.
appliedBy	Identity	yes	Identity of who applied this amendment.
appliedAt	string (date-time)	yes	When this amendment was applied. ISO 8601 format.
expiresAt	string (date-time)	yes	When this amendment expires and must be reviewed. No permanent amendments. ISO 8601 format.
evidence	Evidence[]	no	Supporting evidence (screenshots, logs, URLs, documents).
signature	Signature	no	Digital signature for non-repudiation.
previousChecksum	Checksum	no	Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null for the first amendment.
cvss	Cvss	no	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.
justification	Justification	no	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.
milestones	Milestone[]	no	Remediation milestones (primarily for POA&M type amendments).
inheritedFrom	string (uuid)	no	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'.
componentRef	string (uuid)	no	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.
affectedPackages	Affected_Package[]	no	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).

Example

{
  "type": "waiver",
  "requirementId": "SV-257777",
  "baselineRef": "RHEL9-STIG",
  "status": "passed",
  "reason": "Compensating control: session timeout set to 15 min",
  "appliedBy": {
    "type": "email",
    "identifier": "ao@agency.gov"
  },
  "appliedAt": "2026-01-15T10:00:00Z",
  "expiresAt": "2026-06-30T00:00:00Z",
  "evidence": [
    {
      "type": "url",
      "data": "https://jira.agency.gov/CYBER-4521",
      "description": "ISSM approval with compensating control documentation"
    }
  ]
}

bom

Bom_Type

Discriminator for the manifest kind. Reserved, CycloneDX-aligned set: sbom (software), ai-model, dataset, hbom (hardware), cbom (cryptography), saasbom (services), obom (operations), mbom (manufacturing), kbom (Kubernetes). Normalized now: sbom, ai-model, dataset; reserved + passthrough-capable now, normalized in later releases: the rest. Custom or experimental kinds MUST use an 'x-' prefix (e.g. 'x-threat-model') so they cannot collide with a value later promoted into the reserved set; a non-'x-' value outside the reserved set is invalid. Adding a reserved value is a schema version bump. VEX/VDR/SecurityProfile are vulnerability assertions, not BOMs, and are intentionally excluded.

Bom

Field	Type	Required	Description
bomType	Bom_Type	yes	The manifest kind. Determines which normalized type-extension (model/dataset/packages) may appear.
format	string	yes	Source manifest format the BOM was produced from or references. Examples: cyclonedx, cyclonedx-ml, spdx, spdx-ai, huggingface, croissant. Free-form so new formats need no schema change; the converter that emits the BOM owns the value.
ref	string (uri-reference)	no	Passthrough by reference: URI (relative path, absolute URI, or fragment) to the native manifest document. Present for externally-hosted BOMs.
document	object	no	Passthrough by embedding: the native manifest carried opaquely (e.g. a raw CycloneDX or SPDX object). HDF does not constrain its internal shape — full manifest validation is a tool-level concern.
hashes	Checksum[]	no	Integrity of the carried BOM document itself (the referenced/embedded manifest file), NOT the integrity of the BOM's subject artifact. Subject/artifact integrity (model weights, dataset archive) is a component-level concern, not carried here. Subject identity is inherited from the host component/system; per-node identity lives in the type-extension.
uniqueId	string	no	Optional stable identifier for this BOM document (e.g. CycloneDX serialNumber, SPDX documentNamespace). Correlates the same BOM across evidence packages.
license	string,null	no	Optional license of the BOM document as a whole (SPDX license expression). Nullable and often meaningless (CBOM algorithms, many HBOM parts have no license); per-node licenses live in the type-extension, not here.
model	AI_Model_Extension	no	Normalized ai-model extension. Permitted only when bomType is ai-model.
dataset	Dataset_Extension	no	Normalized dataset extension. Permitted only when bomType is dataset.
packages	SBOM_Package[]	no	Normalized sbom extension: the flattened software package inventory. Permitted only when bomType is sbom.

Example

{
  "$comment": "Passthrough SBOM by external reference — the universal escape hatch, available to every bomType.",
  "bomType": "sbom",
  "format": "cyclonedx",
  "ref": "https://artifacts.agency.gov/sbom/webtier.cdx.json",
  "hashes": [
    {
      "algorithm": "sha256",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ]
}

AI_Model_Extension

Normalized AI-model fields, aligned to the CISA/G7 'SBOM for AI' minimum elements. All fields optional (standards-correct; only the EU AI Act makes a subset binding for high-risk/GPAI). Left open (additionalProperties: true) so a converter can carry unmapped native fields opaquely (partial-fidelity pattern). Subject name/version are inherited from the host aiModel component, not repeated here.

Field	Type	Required	Description
modelArchitecture	string	no	Model architecture family. Examples: transformer, cnn, diffusion, mixture-of-experts.
parameterCount	integer	no	Total trainable parameter count. No native CycloneDX/SPDX field exists; first-class here because the EU AI Act keys GPAI obligations off model scale.
serializationFormat	string	no	On-disk weight serialization format. Security-critical yet under-modeled by BOM specs: pickle/pytorch permits arbitrary code execution on load; safetensors does not. Examples: safetensors, pytorch, gguf, onnx, tensorflow.
adaptationType	"finetune" | "adapter" | "quantized" | "merge"	no	Lineage relationship to baseModelRef, adopting Hugging Face's base_model_relation vocabulary (the only typed lineage enum in the ecosystem).
baseModelRef	string	no	Reference to the base model this one was adapted from (e.g. a Hugging Face repo id or purl). Correlates the lineage edge; the base model itself may carry its own ai-model BOM.
datasetRefs	string[]	no	References to the training/evaluation datasets this model was produced from — preferably a dataset component's componentId (correlating to a first-class dataset subject rather than duplicating dataset detail, per ADR §10), or a dataset BOM uniqueId/URI when no component exists.
intendedUse	string	no	Free-text statement of intended use and out-of-scope uses (CISA/G7 minimum element).
learningApproach	string	no	Model's learning/training paradigm. Free-text because the value set varies across standards. Examples: supervised, self-supervised, semi-supervised, reinforcement. Cross-standard intersection: SPDX 3.0 ai_typeOfModel ∩ CycloneDX modelParameters.approach.type ∩ CISA/G7 learning type.
task	string	no	The ML task the model performs. Free-text. Examples: text-classification, sentiment-analysis, object-detection, translation. Sourced from CycloneDX modelParameters.task (SPDX 3.0 ai_domain is domain-level/adjacent, not the task); CISA/G7 intended-application.
performanceMetrics	Map<string, any>[]	no	Reported evaluation metrics as name/value pairs. Values are free-text because metrics are heterogeneous (accuracy, f1, BLEU, latency). The item stays open (additionalProperties: true) to carry native CycloneDX slice/confidenceInterval detail opaquely. Cross-standard intersection: SPDX 3.0 ai_metric ∩ CycloneDX quantitativeAnalysis.performanceMetrics ∩ CISA/G7 KPI cluster.
hyperparameters	object[]	no	Training hyper-parameters as name/value pairs (epochs, learning-rate, batch-size). This is the set of training knobs, NOT the model's trainable parameterCount — the two are routinely conflated. CISA/G7 'Model properties: hyper-parameters'; SPDX 3.0 ai_hyperparameter.
inputOutput	Map<string, any>	no	Model input/output properties (CISA/G7 minimum element): I/O data types, modality, context/sequence length, and tokenizer. Sourced from CycloneDX modelParameters.inputs[].format / outputs[].format. All sub-fields optional.

Dataset_Extension

Normalized dataset fields (SPDX 3.0 Dataset profile / MLCommons Croissant aligned). All optional; open for partial-fidelity passthrough of unmapped native fields. Symmetric with AI_Model_Extension: carries the dataset's own lineage (baseDatasetRefs/derivation) just as the model extension carries baseModelRef/adaptationType.

Field	Type	Required	Description
recordCount	integer	no	Number of records/examples in the dataset.
datasetFormat	string	no	Physical format of the dataset. Examples: parquet, csv, jsonl, tfrecord, webdataset.
dataClassification	string	no	Sensitivity/classification of the data. Examples: public, internal, confidential, pii, phi.
intendedUse	string	no	Free-text statement of the dataset's intended use (CISA/G7 minimum element).
modality	string,array	no	Content modality/kind of the data (CISA/G7 'Dataset content: modality'). Examples: text, image, tabular, timeseries, audio. DISTINCT from datasetFormat, which is the physical encoding (parquet/csv). Resolves SPDX 3.0 dataset_datasetType, which is content-kind, not physical format. String or array of strings.
provenance	string	no	Free-text description of the dataset's origin and collection process (CISA/G7 'Dataset provenance'; SPDX 3.0 dataset_dataCollectionProcess).
statisticalProperties	string	no	Free-text summary of the dataset's statistical properties (CISA/G7 minimum element; open-ended by design). Intentionally free-text and will remain so permanently: recordCount is the one structured statistic, and restructuring this into an object later would break existing consumers, so it stays a string (additive-only).
baseDatasetRefs	string[]	no	References to the source dataset(s) this one was derived from — a dataset componentId, or a dataset BOM uniqueId/URI when no component exists. The lineage edge parallel to ai-model's baseModelRef; the base dataset may carry its own dataset BOM.
derivation	"filtered" | "augmented" | "merged" | "sampled"	no	Relationship of this dataset to baseDatasetRefs, parallel to the model extension's adaptationType. Minimal + extensible: filtered (subset by rule), augmented (added/synthesized records), merged (union of sources), sampled (statistical draw).

SBOM_Package

A single normalized software package entry within an sbom BOM. Minimal identity + version for querying/diffing; the full native record remains available via passthrough (document/ref).

Field	Type	Required	Description
name	string	yes	Package name.
version	string	no	Package version.
purl	string	no	Package URL (purl) — the preferred cross-BOM identity key when present.
licenses	string[]	no	SPDX license identifiers/expressions for this package.

common

Hash_Algorithm

Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers container-image and other artifact digests that use it.

Requirement_Group

Describes a group of requirements, such as those defined in a single file.

Field	Type	Required	Description
id	string	yes	The unique identifier for the group. Example: the relative path to the file specifying the requirements.
title	string	no	The title of the group - should be human readable.
requirements	string[]	yes	The set of requirements as specified by their ids in this group. Example: 'SV-238196'.

Dependency

A dependency for a baseline. Can include relative paths or URLs for where to find the dependency.

Field	Type	Required	Description
name	string	no	The name or assigned alias.
url	string (uri-reference)	no	The address of the dependency.
branch	string	no	The branch name for a git repo.
path	string	no	The relative path if the dependency is locally available.
statusMessage	string	no	The reason for the status if it is 'failed' or 'skipped'.
status	string	no	The status. Should be: 'loaded', 'failed', or 'skipped'.
git	string (uri)	no	The location of the git repo. Example: 'https://github.com/my-org/ubuntu-22.04-stig-baseline.git'.
supermarket	string	no	The 'user/profilename' attribute for a Supermarket server.
compliance	string	no	The 'user/profilename' attribute for an Automate server.

Example

{
  "name": "ubuntu-22.04-baseline",
  "url": "https://github.com/my-org/ubuntu-22.04-stig-baseline",
  "git": "https://github.com/my-org/ubuntu-22.04-stig-baseline.git",
  "branch": "main",
  "status": "loaded"
}

Reference

A reference to an external document.

Source_Location

The explicit location of a requirement within source code.

Field	Type	Required	Description
ref	string	no	Path to the file that this requirement originates from.
line	number	no	The line on which this requirement is located.

Example

{
  "ref": "controls/SV-260476.rb",
  "line": 1
}

Supported_Platform

A supported platform target. Example: the platform name being 'ubuntu'.

Field	Type	Required	Description
platformFamily	string	no	The platform family. Example: 'redhat'.
platformName	string	no	The platform name - can include wildcards. Example: 'debian'.
platform	string	no	The location of the platform. Can be: 'os', 'aws', 'azure', or 'gcp'.
release	string	no	The release of the platform. Example: '20.04' for 'ubuntu'.

Checksum

Cryptographic checksum for baseline integrity verification.

Field	Type	Required	Description
algorithm	Hash_Algorithm	yes	The hash algorithm used for the checksum.
value	string	yes	The checksum value.

Example

{
  "algorithm": "sha256",
  "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Identity

Represents an identity that performed an action, such as capturing evidence or applying an override.

Field	Type	Required	Description
identifier	string	yes	The identifier value. Example: 'user@example.com', 'jdoe', 'automated-scanner-01'.
type	"email" | "username" | "system" | "agent" | "simple" | "other"	yes	The type of identifier. Use 'email' for email addresses, 'username' for user accounts, 'system' for deterministic non-interactive automation (CI jobs, cron, scanners), 'agent' for an AI/LLM agent acting with autonomy — kept distinct from 'system' so auditors can apply AI-specific scrutiny (e.g. 'an LLM proposed this' vs a deterministic job) and satisfy AI-source disclosure under frameworks like the EU AI Act and NIST AI RMF, 'simple' for basic string identifiers without additional classification, or 'other' for custom identity systems.
description	string	no	Optional description of the identity or identity system, particularly useful when type is 'other'.

Example

{
  "type": "email",
  "identifier": "admin@example.com"
}

Evidence

Supporting evidence for a finding or override, such as screenshots, code samples, log excerpts, or URLs.

Field	Type	Required	Description
type	"screenshot" | "code" | "log" | "url" | "file" | "other"	yes	The type of evidence being provided.
data	string	yes	The evidence content. For screenshots/files: base64-encoded data or URL. For code/logs: the raw text. For URLs: the URL string.
description	string	no	Human-readable description of what this evidence shows.
mimeType	string	no	MIME type of the evidence. Example: 'image/png', 'text/plain', 'application/json'.
encoding	string	no	Encoding used for the data. Example: 'base64', 'utf-8'.
size	number	no	Size of the evidence data in bytes.
capturedAt	string (date-time)	no	Timestamp when this evidence was captured. ISO 8601 format.
capturedBy	Identity	no	Identity of who or what captured this evidence.

Example

{
  "type": "screenshot",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "description": "Screenshot showing firewall configuration with required ports blocked",
  "mimeType": "image/png",
  "encoding": "base64",
  "size": 95,
  "capturedAt": "2025-12-14T10:30:00Z",
  "capturedBy": {
    "identifier": "security-auditor@example.com",
    "type": "email"
  }
}

Remediation

Reference to automated remediation resources for implementing security controls. Points to external automation content like Ansible playbooks, Terraform scripts, or vendor-provided remediation tools.

Field	Type	Required	Description
uri	string (uri)	yes	URI pointing to automated remediation resources (Ansible playbooks, Terraform scripts, etc.). Examples: GitHub repository, DISA STIG Supplemental Automation Content, vendor-provided scripts.
checksum	Checksum	no	Optional cryptographic checksum for verifying the integrity of remediation resources fetched from the URI. Recommended for security when referencing external automation scripts.

Example

{
  "uri": "https://github.com/ansible-lockdown/RHEL9-STIG/tree/main/tasks"
}

Verification_Method

Verification method containing the public key needed to verify a digital signature. Supports multiple key formats including JWK (for RSA, EC), PEM, and Base58.

Field	Type	Required	Description
type	string	yes	The type of verification method. Example: 'JsonWebKey2020', 'RsaVerificationKey2018', 'Ed25519VerificationKey2020'.
controller	string	yes	The entity that controls this verification method. Can be a DID, URI, or other identifier.
publicKeyJwk	Map<string, any>	no	Public key in JSON Web Key format.
publicKeyPem	string	no	Public key in PEM format. Example: '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'.
publicKeyBase58	string	no	Public key in Base58 format, commonly used with Ed25519 keys.

Milestone

A milestone or task within a POA&M remediation plan.

Field	Type	Required	Description
description	string	yes	Description of this milestone or task.
estimatedCompletion	string (date-time)	yes	Estimated completion date. ISO 8601 format.
status	"pending" | "inProgress" | "completed"	yes	Current status of this milestone.
completedAt	string (date-time)	no	Actual completion timestamp. ISO 8601 format.
completedBy	Identity	no	Identity of who completed this milestone.

Signature

A digital signature following W3C Data Integrity Proofs pattern. Supports hardware security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other cryptographic signing methods via JWK, PEM, or Base58 key formats.

Field	Type	Required	Description
type	string	yes	The signature suite type. Example: 'JsonWebSignature2020', 'RsaSignature2018', 'Ed25519Signature2020'.
created	string (date-time)	yes	When the signature was created. ISO 8601 format.
creator	Identity	yes	The identity that created this signature.
signatureValue	string	yes	The base64-encoded or base58-encoded signature value.
proofPurpose	string	yes	The purpose of this signature. Example: 'attestation', 'authentication', 'assertionMethod'.
verificationMethod	Verification_Method	yes	The verification method containing the public key for signature verification.
nonce	string	no	Random value to prevent replay attacks.
challenge	string	no	Challenge value from the verifier, used in challenge-response authentication.
domain	string	no	Domain restriction for the signature, prevents cross-domain replay attacks.

Example

{
  "type": "JsonWebSignature2020",
  "created": "2025-12-14T10:00:00Z",
  "creator": {
    "identifier": "security-team@example.com",
    "type": "email"
  },
  "signatureValue": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..MEYCIQDvKbtLRhWAa",
  "proofPurpose": "attestation",
  "verificationMethod": {
    "type": "JsonWebKey2020",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyJwk": {
      "kty": "RSA",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtV",
      "e": "AQAB"
    }
  }
}

Baseline_Metadata

Shared metadata fields for baselines. Used in both standalone baseline documents and evaluated baseline results.

Field	Type	Required	Description
name	string	no	The name - must be unique.
title	string	no	The title - should be human readable.
maintainer	string	no	The maintainer(s).
copyright	string	no	The copyright holder(s).
copyrightEmail	string	no	The email address or other contact information of the copyright holder(s).
license	string	no	The copyright license. Example: 'Apache-2.0'.
summary	string	no	The summary. Example: the Security Technical Implementation Guide (STIG) header.
version	string	no	The version of the baseline.
supports	Supported_Platform[]	no	The set of supported platform targets.
status	string	no	The status. Example: 'loaded'.
labels	Map<string, string>	no	Optional key-value labels for flexible grouping. Well-known keys: system, component, environment, region, team. Values must be strings.

Example

{
  "name": "rhel-9-stig-baseline",
  "title": "Red Hat Enterprise Linux 9 STIG Baseline",
  "maintainer": "MITRE SAF Team",
  "copyright": "The MITRE Corporation",
  "copyrightEmail": "saf@mitre.org",
  "license": "Apache-2.0",
  "summary": "InSpec baseline for RHEL 9 STIG compliance",
  "version": "1.0.0",
  "supports": [
    {
      "platformName": "redhat",
      "platformFamily": "redhat",
      "release": "9"
    }
  ],
  "status": "loaded"
}

Requirement_Core

Core requirement fields shared between baseline requirements and evaluated requirements. Contains the fundamental requirement definition without assessment results.

Field	Type	Required	Description
id	string	no	The requirement identifier. Example: 'SV-238196'.
title	string	no	The title - is nullable.
descriptions	object[]	no	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'.
impact	number	no	The impactfulness or severity (0.0 to 1.0).
refs	Reference[]	no	The set of references to external documents.
tags	Map<string, any>	no	A set of tags - usually metadata like CCI, STIG ID, severity.
code	string	no	The raw source code of the requirement. Set to null for manual-only requirements or requirements not yet implemented; use verificationMethod to disambiguate manual-by-design from manual-pending-automation. Note that if this is an overlay, it does not include the underlying source code.
sourceLocation	Source_Location	no	The explicit location of the requirement within the source code.
controlType	"policy" | "procedure" | "technical" | "management" | "operational"	no	Classification of the control's nature, aligning with NIST SP 800-53 / SP 800-53A categories. 'policy' = an authored governance statement; 'procedure' = a documented process; 'technical' = an enforced technical configuration; 'management' = a programmatic/management activity; 'operational' = a recurring operational activity (e.g. AT, IR, MA families). Optional: when omitted, consumers may infer heuristically from family/id but should not assume a default.
verificationMethod	Verification_Method_Enum	no	How this requirement is intended to be verified. Disambiguates the two cases that null 'code' overloads: 'manual-by-design' (the requirement is statement-form and not amenable to automation, e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could exist but does not yet, e.g. a STIG rule lacking a fix). 'automated' = a check exists and runs without operator action; 'hybrid' = part automated, part manual. Optional: when omitted, consumers should not infer a default.
applicability	"required" | "optional" | "advisory"	no	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 memberships (IG1/IG2/IG3 may carry richer semantics; layer those onto props[]/tags{}). Optional: when omitted, consumers should treat the requirement as 'required' by convention.

Example

{
  "$comment": "v3.1.x-style requirement: classification fields omitted. Consumers must continue to handle this shape under v3.3.0 (backward compatibility).",
  "id": "SV-238196",
  "title": "The Ubuntu operating system must enforce password complexity",
  "impact": 0.5,
  "tags": {
    "nist": [
      "IA-5"
    ],
    "severity": "medium",
    "cci": [
      "CCI-000192"
    ]
  },
  "refs": [
    {
      "url": "https://public.cyber.mil/stigs/"
    }
  ],
  "descriptions": [
    {
      "label": "default",
      "data": "Use of a complex password helps to increase the time and resources required to compromise the password."
    },
    {
      "label": "check",
      "data": "Verify the value of 'minlen' in /etc/security/pwquality.conf."
    }
  ]
}

Verification_Method_Enum

How a requirement is intended to be verified. Disambiguates the two cases that null 'code' overloads: 'manual-by-design' (the requirement is statement-form and not amenable to automation, e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could exist but does not yet, e.g. a STIG rule lacking a fix). 'automated' = a check exists and runs without operator action; 'hybrid' = part automated, part manual. Named '_Enum' to disambiguate from the unrelated Verification_Method DID-context struct.

Severity

Severity rating for a requirement. Typically derived from the numeric impact score.

Cloud_Provider

Cloud service provider identifier.

comparison

Requirement_State

SARIF-compatible vocabulary extended for security. 'new' = present only in new source, 'absent' = present only in old, 'unchanged' = same effective status, 'updated' = status changed (generic), 'fixed' = was failing now passing, 'regressed' = was passing now failing, 'moved' = reorganized same content, 'split'/'merged' = reserved for v1.1.

Change_Reason

The reason a requirement's state changed between sources.

Comparison_Mode

The mode of comparison. 'temporal' compares the same target over time. 'baseline' compares against a golden reference. 'fleet' compares across multiple systems. 'multiSource' compares outputs from different scanners. 'baselineEvolution' compares two baseline documents to detect requirement changes between versions. 'systemDrift' compares two system documents to detect component-level changes.

Source_Role

The role of a source document in the comparison.

Original_Format

The original format of the source document before conversion to HDF.

Match_Strategy

The strategy used to match requirements across sources. 'exactId' matches by identical IDs. 'mappedId' uses an ID mapping table. 'cciMatch'/'nistMatch' match by framework identifiers. 'fuzzyTitle'/'fuzzyContent' use text similarity.

Conflict_Resolution

How a conflict between multiple scanner results was resolved.

Annotation_Category

The category of an annotation attached to a comparison.

Field_Change

A single field-level change between two versions of a requirement.

Field	Type	Required	Description
op	"add" | "remove" | "replace"	yes	The type of change operation.
path	string	yes	JSON Pointer path to the changed field.
oldValue	any	no	The previous value of the field (for 'remove' and 'replace' operations).
newValue	any	no	The new value of the field (for 'add' and 'replace' operations).

Source

A source document participating in the comparison.

Field	Type	Required	Description
role	Source_Role	yes	The role of this source in the comparison.
label	string	yes	Human-readable label for this source. Example: 'Before remediation scan'.
uri	string (uri)	no	URI pointing to the source document.
originalFormat	Original_Format	no	The original format of the source document before conversion to HDF.
checksum	Checksum	no	Cryptographic checksum of the source document for integrity verification.
assessmentTimestamp	string (date-time)	no	When the source assessment was performed. ISO 8601 format.
tool	Tool	no	The security tool that produced the assessment data in this source.
components	Component[]	no	The components assessed in this source.
baselineRef	object	no	Reference to the baseline used in this source assessment.

Matching_Config

Configuration for how requirements are matched across sources.

Field	Type	Required	Description
primaryStrategy	Match_Strategy	yes	The primary strategy used to match requirements across sources.
fallbackStrategies	Match_Strategy[]	no	Ordered list of fallback strategies tried when the primary strategy fails to find a match.
minimumConfidence	number	no	Minimum confidence score (0-1) required to accept a match.
mappingTableUri	string (uri)	no	URI pointing to an external mapping table used for ID translation.
fingerprintFields	string[]	no	Fields used to compute a fingerprint for fuzzy matching.

State_Counts

Counts of requirements in each state.

Field	Type	Required	Description
fixed	integer	no	Number of requirements that changed from failing to passing.
regressed	integer	no	Number of requirements that changed from passing to failing.
new	integer	no	Number of requirements present only in the new source.
absent	integer	no	Number of requirements present only in the old source.
unchanged	integer	no	Number of requirements with the same effective status.
updated	integer	no	Number of requirements with a generic status change.
moved	integer	no	Number of requirements that were reorganized without content change.

Severity_Breakdown

Breakdown of state counts by severity level.

Field	Type	Required	Description
critical	State_Counts	no	State counts for critical severity requirements.
high	State_Counts	no	State counts for high severity requirements.
medium	State_Counts	no	State counts for medium severity requirements.
low	State_Counts	no	State counts for low severity requirements.

Per_Source_Summary

Summary statistics for a single source in a multi-source comparison.

Field	Type	Required	Description
sourceIndex	integer	yes	Zero-based index into the sources array identifying which source this summary is for.
label	string	yes	Human-readable label for this source.
fixed	integer	no	Number of requirements that changed from failing to passing.
regressed	integer	no	Number of requirements that changed from passing to failing.
new	integer	no	Number of requirements present only in the new source.
absent	integer	no	Number of requirements present only in the old source.
unchanged	integer	no	Number of requirements with the same effective status.
updated	integer	no	Number of requirements with a generic status change.
moved	integer	no	Number of requirements that were reorganized without content change.

Comparison_Summary

Summary statistics for the overall comparison.

Field	Type	Required	Description
total	integer	yes	Total number of unique requirements across all sources.
matchedCount	integer	yes	Number of requirements successfully matched between sources.
unmatchedOldCount	integer	yes	Number of requirements in the old source with no match in the new source.
unmatchedNewCount	integer	yes	Number of requirements in the new source with no match in the old source.
new	integer	no	Number of requirements present only in the new source.
absent	integer	no	Number of requirements present only in the old source.
unchanged	integer	no	Number of requirements with the same effective status.
updated	integer	no	Number of requirements with a generic status change.
fixed	integer	no	Number of requirements that changed from failing to passing.
regressed	integer	no	Number of requirements that changed from passing to failing.
moved	integer	no	Number of requirements that were reorganized without content change.
oldCompliancePercent	number	no	Compliance percentage of the old source (0-100).
newCompliancePercent	number	no	Compliance percentage of the new source (0-100).
complianceDelta	number	no	Change in compliance percentage (new - old).
averageMatchConfidence	number	no	Average confidence score across all requirement matches (0-1).
bySeverity	Severity_Breakdown	no	State counts broken down by severity level.
perSource	Per_Source_Summary[]	no	Summary statistics for each individual source in a multi-source comparison.

Baseline_Diff

Comparison of a baseline between sources.

Field	Type	Required	Description
name	string	yes	Name of the baseline being compared.
state	"new" | "absent" | "unchanged" | "updated"	yes	The state of this baseline in the comparison.
oldVersion	string	no	Version of the baseline in the old source.
newVersion	string	no	Version of the baseline in the new source.
mappingSource	string	no	The source of any ID mapping used to correlate requirements across baseline versions.

Component_Diff

Comparison of a single component between two system document versions.

Field	Type	Required	Description
name	string	yes	Component name used for matching across system versions.
state	"new" | "absent" | "unchanged" | "updated"	yes	The state of this component in the comparison.
before	Component | null	no	Component snapshot from the old system document. Null when state is 'new'.
after	Component | null	no	Component snapshot from the new system document. Null when state is 'absent'.
fieldChanges	Field_Change[]	no	Detailed field-level changes between the before and after component snapshots.

Package_Diff

Comparison of a single BOM node between two BOM versions, matched by purl (software) or identifier (models, datasets, hardware, crypto).

Field	Type	Required	Description
purl	string	no	Package URL (purl) — the preferred identity key for matching software packages across BOMs. Optional: BOM nodes without a purl (AI models, datasets, hardware parts, crypto algorithms) key on identifier instead.
identifier	string	no	Generic identity key for matching a BOM node across versions when no purl applies — e.g. a Hugging Face model ref, dataset uniqueId, crypto algorithm OID, or hardware part number. At least one of purl or identifier is required.
name	string	no	Human-readable node name.
state	"added" | "removed" | "updated" | "unchanged"	yes	The state of this package: added (new in new SBOM), removed (absent from new SBOM), updated (version changed), unchanged.
oldVersion	string	no	Package version in the old SBOM.
newVersion	string	no	Package version in the new SBOM.
licenses	string[]	no	License identifiers for this package.

Example

{
  "$comment": "Software package diff keyed by purl (the SBOM case).",
  "purl": "pkg:npm/express@4.18.2",
  "name": "express",
  "state": "updated",
  "oldVersion": "4.18.1",
  "newVersion": "4.18.2"
}

Scanner_Conflict

A conflict between scanner results for the same requirement.

Field	Type	Required	Description
field	string	yes	The field where the conflict occurs.
values	object[]	yes	The conflicting values from each source.
resolvedIndex	integer	no	Index of the source whose value was chosen as the resolution.
resolution	Conflict_Resolution	no	How the conflict was resolved.

Annotation

An annotation attached to a comparison, providing context or action items.

Field	Type	Required	Description
label	string	yes	Human-readable label for this annotation.
description	string	no	Detailed description of the annotation.
category	Annotation_Category	no	The category of this annotation.
needsConfirmation	boolean	no	Whether this annotation requires human confirmation before acting on it.

Requirement_Diff

A comparison of a single requirement between sources, including state, changes, and full before/after snapshots.

Field	Type	Required	Description
id	string	yes	The canonical requirement identifier used for this diff.
state	Requirement_State	yes	The state of this requirement in the comparison.
changeReasons	Change_Reason[]	yes	The reasons for the state change.
before	Evaluated_Requirement | null	yes	The requirement as it appeared in the old/reference source. Null when state is 'new'.
after	Evaluated_Requirement | null	yes	The requirement as it appeared in the new source. Null when state is 'absent'.
fieldChanges	Field_Change[]	yes	Detailed field-level changes between the before and after versions.
oldId	string	no	The requirement ID in the old source, if different from the canonical id.
newId	string	no	The requirement ID in the new source, if different from the canonical id.
title	string	no	The requirement title for human readability.
oldEffectiveStatus	string	no	The effective status of the requirement in the old source.
newEffectiveStatus	string	no	The effective status of the requirement in the new source.
oldImpact	number	no	The impact score of the requirement in the old source (0-1).
newImpact	number	no	The impact score of the requirement in the new source (0-1).
matchStrategy	Match_Strategy	no	The strategy that was used to match this requirement across sources.
matchConfidence	number	no	Confidence score for the match (0-1).
matchManual	boolean	no	Whether the match was manually confirmed by a human.
annotationIds	string[]	no	IDs of annotations attached to this requirement diff.
sourceIndex	integer	no	Index into the sources array for multi-source comparisons.
conflicts	Scanner_Conflict[]	no	Conflicts between multiple scanner results for this requirement.
beforeSensitive	Map<string, any>	no	Sensitive data from the old source that should not be included in the main before snapshot.
afterSensitive	Map<string, any>	no	Sensitive data from the new source that should not be included in the main after snapshot.

component

Base_Component

Base properties shared by all component types. Extends the Target concept with stable identity, external references, generalized BOM attachment (boms[]), and unified artifact integrity (integrity[]).

Field	Type	Required	Description
type	"host" | "containerImage" | "containerInstance" | "containerPlatform" | "cloudAccount" | "cloudResource" | "repository" | "application" | "artifact" | "network" | "database" | "aiModel" | "dataset"	yes	Component type discriminator. Same values as Target types, plus aiModel and dataset (thin AI subject components whose detail lives in an attached ai-model / dataset BOM).
name	string	yes	Human-readable name for this component.
componentId	string (uuid)	no	Stable UUID (RFC 4122) for this component. Required in hdf-system documents, optional in hdf-results. Enables cross-document correlation, diffing, and data flow references.
description	string	no	Description of this component's role or purpose.
owner	Identity	no	Team or individual responsible for this component. Enables per-component ownership when different teams manage different parts of a system.
externalIds	Map<string, string>	no	Map of external identifier scheme to value. Well-known schemes: aws (instance ID), azure (resource ID), cmdb (asset ID), emass (system ID), cve (CVE ID). Custom schemes are allowed.
labels	Map<string, string>	no	Optional key-value labels for flexible grouping. Well-known keys: system, component, environment, region, team. Values must be strings.
boms	Bom[]	no	Component-scoped Bills of Materials (SBOM, ai-model, dataset, or any reserved bomType), each carried by passthrough (ref/document) or normalized. Replaces the former sbom/sbomRef/sbomFormat trio; a component may carry several BOMs (e.g. an SBOM plus an ai-model BOM). See primitives/bom.schema.json.
integrity	Checksum[]	no	Cryptographic integrity of this component's underlying artifact — model weights or shards, dataset archive, container image, or package bytes. An array supports multi-file/sharded artifacts. This is the single, generic home for artifact/subject integrity across all component types (it replaced the former per-type Container_Image digest and Artifact checksum fields). Distinct from BOM-document integrity (Bom.hashes[]) and from the document tamper-evidence Integrity type.
baselineRefs	string[]	no	Names of baselines that apply to this component.
inputOverrides	Input_Override[]	no	System-specific overrides for baseline input values.
targetSelector	Target_Selector	no	Label selector to match targets belonging to this component during migration. Targets with matching labels are automatically included.

Example

{
  "type": "aiModel",
  "name": "Llama-2-7b-chat (finetuned)",
  "componentId": "b7c8d9e0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
  "owner": {
    "type": "email",
    "identifier": "ml-platform@agency.gov"
  },
  "integrity": [
    {
      "algorithm": "sha256",
      "value": "d1f2e3a4b5c6978869504132a1b2c3d4e5f6071829304152637485960a1b2c3d"
    }
  ],
  "boms": [
    {
      "bomType": "ai-model",
      "format": "cyclonedx-ml",
      "model": {
        "adaptationType": "finetune"
      }
    }
  ]
}

Component

A system component. Uses discriminated union pattern with 'type' field as discriminator. Superset of Target with identity, external IDs, and SBOM support.

Host_Component

A physical or virtual server, workstation, or network device.

Field	Type	Required	Description
type	"host"	no
hostname	string	no	Short, OS-reported host name (the unqualified machine name, e.g. 'web01'). Kept distinct from 'fqdn' because an FQDN is not reliably decomposable into hostname + domain (standalone/workgroup hosts have no domain; a directory domain is not the FQDN's DNS suffix). Aligns with ECS host.hostname and DISA STIG CKL HOST_NAME. Store the short name the source reports; do not derive it from the FQDN.
fqdn	string (hostname)	no	Fully qualified domain name (e.g. 'web01.prod.example.com'). Distinct from 'hostname' (short) and 'domain' (directory domain). ECS recommends storing this lowercase; the schema does not enforce case so source fidelity is preserved on round-trip.
domain	string	no	Directory domain the host is a member of — Active Directory / NetBIOS / LDAP domain (ECS host.domain semantics), NOT necessarily the DNS suffix of the FQDN. A standalone or workgroup host has a hostname but no domain. Not derivable from the FQDN; populate only from a source that carries directory membership.
ipAddress	string (ipv4) | string (ipv6)	no	IP address of the host.
macAddress	string	no	MAC address in colon-separated hexadecimal format.
osName	string	no	Operating system name.
osVersion	string	no	Operating system version.

Example

{
  "$comment": "Domain-joined host carrying all three identity fields separately: short hostname, FQDN, and the (distinct) directory domain. HOST_NAME and HOST_FQDN from a STIG checklist map here; note the AD domain differs from the FQDN's DNS suffix.",
  "type": "host",
  "name": "web-server-prod-01",
  "componentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "hostname": "web01",
  "fqdn": "web01.prod.example.com",
  "domain": "CORP",
  "ipAddress": "10.0.1.50",
  "osName": "Ubuntu",
  "osVersion": "22.04 LTS",
  "externalIds": {
    "cmdb": "ASSET-12345",
    "aws": "i-0abc123def456789"
  }
}

Container_Image_Component

A static container image (not running). Image integrity — formerly the 'digest' field — is expressed via the shared Base_Component.integrity array.

Field	Type	Required	Description
type	"containerImage"	no
imageId	string	no	Container image ID.
registry	string	no	Container registry. Example: 'docker.io'.
repository	string	no	Repository name. Example: 'library/nginx'.
tag	string	no	Image tag. Example: '1.25'.

Example

{
  "type": "containerImage",
  "name": "nginx",
  "registry": "docker.io",
  "repository": "library/nginx",
  "tag": "1.25-alpine",
  "integrity": [
    {
      "algorithm": "sha256",
      "value": "a9286defaba7b3a519d585ba0e37d0b2cbee74ebfe590960b0b1d6a5e97d1e1d"
    }
  ]
}

Container_Instance_Component

A running container instance.

Field	Type	Required	Description
type	"containerInstance"	no
containerId	string	no	Running container ID.
image	string	no	Image the container was started from.
runtime	string	no	Container runtime. Example: 'docker', 'containerd', 'cri-o'.

Container_Platform_Component

A container orchestration platform (Kubernetes, OpenShift, ECS, etc.).

Field	Type	Required	Description
type	"containerPlatform"	no
platformType	string	no	Platform type. Example: 'kubernetes', 'openshift', 'ecs', 'docker-swarm'.
clusterName	string	no	Cluster name.
namespace	string	no	Namespace within the cluster, if applicable.
version	string	no	Platform version.

Cloud_Account_Component

A cloud provider account (AWS account, Azure subscription, GCP project).

Field	Type	Required	Description
type	"cloudAccount"	no
provider	Cloud_Provider	no	Cloud provider.
accountId	string	no	Cloud account identifier.
region	string	no	Cloud region, if applicable.

Example

{
  "type": "cloudAccount",
  "name": "Production AWS Account",
  "componentId": "f1e2d3c4-b5a6-4978-8069-1a2b3c4d5e6f",
  "provider": "aws",
  "accountId": "123456789012",
  "region": "us-east-1"
}

Cloud_Resource_Component

A specific cloud resource (EC2 instance, S3 bucket, Azure VM, etc.).

Field	Type	Required	Description
type	"cloudResource"	no
provider	Cloud_Provider	no	Cloud provider.
resourceType	string	no	Type of cloud resource. Example: 'ec2:instance', 's3:bucket'.
resourceId	string	no	Provider-specific resource identifier.
arn	string	no	Amazon Resource Name (AWS only).
region	string	no	Cloud region where the resource resides.

Repository_Component

A code repository (for SAST tools).

Field	Type	Required	Description
type	"repository"	no
url	string (uri)	no	Repository URL.
branch	string	no	Branch that was scanned.
commit	string	no	Commit SHA that was scanned.

Application_Component

A running application or API (for DAST tools).

Field	Type	Required	Description
type	"application"	no
url	string (uri)	no	Application URL (for DAST tools).
version	string	no	Application version.
environment	string	no	Environment. Example: 'production', 'staging', 'development'.

Artifact_Component

A software artifact or dependency (for SCA tools). Package integrity — formerly the 'checksum' field — is expressed via the shared Base_Component.integrity array.

Field	Type	Required	Description
type	"artifact"	no
packageManager	string	no	Package manager. Example: 'npm', 'maven', 'pip', 'nuget'.
packageName	string	no	Package name.
version	string	no	Package version.

Example

{
  "type": "artifact",
  "name": "express",
  "packageManager": "npm",
  "packageName": "express",
  "version": "4.18.2",
  "integrity": [
    {
      "algorithm": "sha512",
      "value": "cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"
    }
  ]
}

Network_Component

A network segment or network device.

Field	Type	Required	Description
type	"network"	no
cidr	string	no	Network CIDR block.
gateway	string	no	Network gateway address.

Database_Component

A database instance.

Field	Type	Required	Description
type	"database"	no
engine	string	no	Database engine. Example: 'postgresql', 'mysql', 'oracle', 'mssql'.
version	string	no	Database version.
host	string	no	Database host.
port	integer	no	Database port.

AI_Model_Component

A thin AI-model component: identity and correlation only (parallel to Host_Component's fqdn/ip). All model detail — architecture, parameter count, serialization format, lineage — lives in an attached ai-model BOM (boms[]), never on the component itself.

Field	Type	Required	Description
type	"aiModel"	no
modelId	string	no	Provider/registry identifier for the model. Examples: a Hugging Face repo id ('meta-llama/Llama-2-7b-hf') or a model purl. Correlates the component to its ai-model BOM(s) and to lineage references from other models.
version	string	no	Model version, revision, or checkpoint tag.

Example

{
  "type": "aiModel",
  "name": "Llama-2-7b-chat (finetuned)",
  "componentId": "b7c8d9e0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
  "modelId": "acme/llama-2-7b-chat-support",
  "version": "1.2.0",
  "integrity": [
    {
      "algorithm": "sha256",
      "value": "d1f2e3a4b5c6978869504132a1b2c3d4e5f6071829304152637485960a1b2c3d"
    }
  ],
  "boms": [
    {
      "bomType": "ai-model",
      "format": "cyclonedx-ml",
      "model": {
        "modelArchitecture": "transformer",
        "parameterCount": 6738415616,
        "serializationFormat": "safetensors",
        "adaptationType": "finetune",
        "baseModelRef": "meta-llama/Llama-2-7b-hf"
      }
    }
  ]
}

Dataset_Component

A thin dataset component: identity and correlation only, symmetric with AI_Model_Component. All dataset detail — record count, format, classification, lineage — lives in an attached dataset BOM (boms[]), never on the component itself.

Field	Type	Required	Description
type	"dataset"	no
datasetId	string	no	Provider/registry identifier for the dataset. Examples: a Hugging Face dataset repo id ('HuggingFaceH4/ultrachat_200k'), a DOI, or a dataset purl. Correlates the component to its dataset BOM(s) and to datasetRefs from ai-model components.
version	string	no	Dataset version, release identifier, or — for highly dynamic datasets — a timestamped release marker.

Example

{
  "type": "dataset",
  "name": "UltraChat-200k (filtered)",
  "componentId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "datasetId": "acme/ultrachat-200k-filtered",
  "version": "2026-06-01",
  "integrity": [
    {
      "algorithm": "sha256",
      "value": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
  ],
  "boms": [
    {
      "bomType": "dataset",
      "format": "croissant",
      "dataset": {
        "recordCount": 180000,
        "datasetFormat": "parquet",
        "dataClassification": "public",
        "baseDatasetRefs": [
          "HuggingFaceH4/ultrachat_200k"
        ],
        "derivation": "filtered"
      }
    }
  ]
}

cvss

Cvss_Severity

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').

Cvss

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.

Field	Type	Required	Description
version	"2.0" | "3.0" | "3.1" | "4.0"	yes	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.
source	string	no	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.
baseVector	string	no	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.
baseScore	number	no	The Base score (0.0–10.0) computed from the base vector. Reflects the intrinsic, vendor-published severity before consumer enrichment.
baseSeverity	Cvss_Severity	no	Qualitative severity band corresponding to baseScore. CVSS 2.0 does not natively use 'none' or 'critical' bands; map accordingly when populating.
threatVector	string	no	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.
threatScore	number	no	Optional score (0.0–10.0) recomputed after applying Threat metrics. Always less than or equal to baseScore in practice.
environmentalVector	string	no	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).
environmentalScore	number	no	Optional score (0.0–10.0) recomputed after applying Environmental metrics.
supplementalVector	string	no	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.
computedScore	number	no	Optional final score after combining Base + Threat + Environmental metrics. This is the score consumers should treat as authoritative for risk decisions when present.
computedSeverity	Cvss_Severity	no	Qualitative severity band corresponding to computedScore. Same band convention as baseSeverity.

Example

{
  "$comment": "Base-only: vendor-supplied CVSS 3.1 data exactly as a scanner (e.g., Nessus, Grype) would emit it. No consumer enrichment yet.",
  "version": "3.1",
  "source": "CVE-2024-12345",
  "baseVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
  "baseScore": 9.8,
  "baseSeverity": "critical"
}

epss

Epss

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.

Field	Type	Required	Description
score	number	yes	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.
percentile	number	yes	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.
date	string (date)	yes	ISO 8601 date (YYYY-MM-DD) on which FIRST.org published this EPSS score.

Example

{
  "$comment": "High exploit probability and high percentile, characteristic of a widely-exploited vulnerability like Log4Shell (CVE-2021-44228) shortly after disclosure.",
  "score": 0.97532,
  "percentile": 0.99987,
  "date": "2026-05-26"
}

extensions

Status_Override

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.

Field	Type	Required	Description
type	Override_Type	yes	The type of override applied to this requirement.
status	Result_Status	no	The new status this override sets for the requirement. Optional when only impact is being overridden.
impact	Impact_Override	no	Override to the requirement's impact score. At least one of status or impact must be set.
reason	string	yes	Explanation for why this override was applied.
appliedBy	Identity	yes	Identity of who applied this override. For simple cases, use type 'simple' with just an identifier.
appliedAt	string (date-time)	yes	Timestamp when this override was applied. ISO 8601 format.
expiresAt	string (date-time)	yes	Timestamp when this override expires and must be reviewed/renewed. REQUIRED - no permanent overrides allowed. ISO 8601 format.
signature	Signature	no	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.
evidence	Evidence[]	no	Supporting evidence for this override, such as screenshots demonstrating manual verification for attestations.
previousChecksum	Checksum	no	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.
cvss	Cvss	no	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.
justification	Justification	no	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.

Example

{
  "type": "waiver",
  "status": "notApplicable",
  "reason": "This control does not apply to containerized environments as the application runs in ephemeral containers without persistent storage",
  "appliedBy": {
    "identifier": "security-team@example.com",
    "type": "email"
  },
  "appliedAt": "2025-12-01T10:00:00Z",
  "expiresAt": "2026-12-01T00:00:00Z"
}

POAM

Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance. POAMs do NOT change the effectiveStatus - the requirement remains in its current state while the POA&M tracks remediation efforts.

Field	Type	Required	Description
type	"remediation" | "mitigation" | "riskAcceptance" | "vendorDependency"	yes	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.
explanation	string	yes	Detailed explanation of the plan, including what actions will be taken.
appliedBy	Identity	yes	Identity of who created this POA&M. For simple cases, use type 'simple' with just an identifier.
appliedAt	string (date-time)	yes	Timestamp when this POA&M was created. ISO 8601 format.
expiresAt	string (date-time)	no	Optional expiration date for this POA&M requiring review/renewal. ISO 8601 format.
milestones	Milestone[]	no	Optional array of milestones tracking progress toward completion.
signature	Signature	no	Optional digital signature for enhanced trust and non-repudiation.
evidence	Evidence[]	no	Supporting evidence for this POA&M, such as documentation of compensating controls or mitigation implementation.
previousChecksum	Checksum	no	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.

Example

{
  "type": "remediation",
  "explanation": "Upgrade OpenSSL to version 3.0.x to address CVE-2024-XXXXX vulnerability. Root cause: outdated dependency version in base image.",
  "appliedBy": {
    "identifier": "devops-team@example.com",
    "type": "email"
  },
  "appliedAt": "2025-12-01T09:00:00Z",
  "milestones": [
    {
      "description": "Update base Docker image to use OpenSSL 3.0.x",
      "estimatedCompletion": "2025-12-15T00:00:00Z",
      "status": "completed",
      "completedAt": "2025-12-10T16:30:00Z",
      "completedBy": {
        "identifier": "alice.smith",
        "type": "username"
      }
    },
    {
      "description": "Deploy updated image to production",
      "estimatedCompletion": "2025-12-20T00:00:00Z",
      "status": "inProgress"
    },
    {
      "description": "Verify vulnerability no longer present via security scan",
      "estimatedCompletion": "2025-12-22T00:00:00Z",
      "status": "pending"
    }
  ]
}

Generator

Information about the tool that generated this HDF file.

Field	Type	Required	Description
name	string	yes	The name of the software that produced this HDF file. Example: 'gosec-to-hdf'.
version	string	yes	The version of the tool. Example: '5.22.3'.

Tool

The security tool that produced the assessment data represented in this HDF file. Aligns with SARIF, OSCAL, and CycloneDX terminology.

Field	Type	Required	Description
name	string	no	The name of the security tool that produced the data. Examples: 'gosec', 'Semgrep', 'OpenSCAP', 'AWS Config', 'Nessus'. Omit if the tool cannot be identified.
version	string	no	Version of the source tool, if available in the tool's output. Example: '5.22.3'.
format	string	no	The file format, if it is a recognized named format shared by multiple tools. Examples: 'SARIF', 'XCCDF'. Omit for tool-specific formats where the tool name already implies the format (Nessus XML, gosec JSON).

Integrity

Cryptographic integrity information for verifying the HDF file has not been tampered with. If algorithm is provided, checksum must also be provided, and vice versa.

Field	Type	Required	Description
algorithm	Hash_Algorithm	no	The hash algorithm used for the checksum.
checksum	string	no	The checksum value.
signature	string	no	Optional cryptographic signature.
signedBy	string	no	Identifier of who signed this file.

Example

{
  "algorithm": "sha256",
  "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

kev

Kev

Field	Type	Required	Description
inKev	boolean	yes	Whether this vulnerability is currently in the CISA Known Exploited Vulnerabilities catalog. When true, dateAdded and dueDate are required.
dateAdded	string (date)	no	ISO 8601 calendar date (YYYY-MM-DD) the vulnerability was added to the CISA KEV catalog. Required when inKev is true.
dueDate	string (date)	no	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.
notes	string	no	CISA's notes describing the vulnerability, observed exploitation, or remediation guidance.

Example

{
  "$comment": "High-urgency case: recently added KEV entry with a short federal patching deadline.",
  "inKev": true,
  "dateAdded": "2026-03-15",
  "dueDate": "2026-04-05",
  "notes": "Active ransomware exploitation observed; apply vendor patch immediately."
}

parameter

Input_Type

The data type of the input value. Aligns with InSpec input types.

Comparison_Operator

Comparison operator for evaluating the input value against observed values. Numeric: eq/ne/lt/le/gt/ge. String: eq/ne/contains/matches. Collection: in/notIn.

Input_Constraints

Validation constraints for an input value.

Field	Type	Required	Description
min	number	no	Minimum allowed value (for Numeric inputs).
max	number	no	Maximum allowed value (for Numeric inputs).
pattern	string	no	Regular expression pattern the value must match (for String inputs).
allowedValues	any[]	no	Enumeration of permitted values.

Input

A typed input parameter that bridges governance requirements and scanner automation. Inputs carry expected configuration values with type information, comparison operators, and validation constraints, enabling traceability from policy through to scan results.

Field	Type	Required	Description
name	string	yes	The input name. Must be unique within a baseline or results document. Example: 'max_concurrent_sessions'.
type	Input_Type	no	The data type of this input.
value	any	no	The input value. Type should match the declared type field. Accepts any JSON value.
description	string	no	Human-readable description of what this input controls.
required	boolean	no	Whether this input must be provided. Defaults to false if omitted.
sensitive	boolean	no	Whether this input contains sensitive data (passwords, keys). Sensitive values should be redacted in output. Defaults to false if omitted.
operator	Comparison_Operator	no	The comparison operator used when evaluating this input against observed values.
constraints	Input_Constraints	no	Validation constraints for the input value.

Example

{
  "name": "max_concurrent_sessions",
  "type": "Numeric",
  "value": 3,
  "description": "Maximum concurrent sessions per user",
  "required": true,
  "sensitive": false,
  "operator": "le",
  "constraints": {
    "min": 1,
    "max": 100
  }
}

result

Result_Status

The status of an individual test result. 'notApplicable' indicates the requirement does not apply to the target. 'notReviewed' indicates the requirement was not assessed (e.g., requires manual verification).

Requirement_Result

A test within a requirement and its results and findings such as how long it took to run.

Field	Type	Required	Description
status	Result_Status	yes	The status of this test within the requirement. Example: 'failed'.
codeDesc	string	yes	A description of this test. Example: 'limits.conf * is expected to include ["hard", "maxlogins", "10"]'.
runTime	number	no	The execution time in seconds for the test.
startTime	string (date-time)	yes	The time at which the test started.
resource	string	no	The resource used in the test. Example: 'file', 'command', 'service'.
resourceId	string	no	The unique identifier of the resource. Example: '/etc/passwd'.
message	string	no	An explanation of the test result. Typically provided for failed tests, errors, or to explain why a test was not applicable or not reviewed.
exception	string	no	The type of exception if an exception was thrown.
backtrace	string[]	no	The stacktrace/backtrace of the exception if one occurred.

Example

{
  "status": "passed",
  "codeDesc": "File /etc/ssh/sshd_config content is expected to match /Protocol\\s+2/",
  "startTime": "2025-06-15T10:30:00Z",
  "runTime": 0.015
}

Requirement_Description

A labeled description for a requirement, such as fix text or check instructions.

Field	Type	Required	Description
label	string	yes	The type of description. Examples: 'fix', 'check', 'rationale'.
data	string	yes	The text of the description.

Example

{
  "label": "default",
  "data": "Verify the SSH daemon is configured to only use FIPS-validated key exchange algorithms."
}

runner

Runner

Information about the test execution environment. This is distinct from the target being scanned - the runner is where the security tool executes, while targets are what is being assessed.

Field	Type	Required	Description
name	string	yes	The name of the runner environment. Examples: 'ubuntu', 'macos', 'windows', 'docker', 'kubernetes-pod', 'manual'.
release	string	no	The version/release of the operating system or runtime. Example: '20.04', '13.2', '11'.
architecture	string	no	The CPU architecture of the runner system. Example: 'x86_64', 'arm64', 'aarch64'.
hostname	string	no	The short hostname of the runner system. Example: 'ci-runner-01', 'jenkins-agent-03', 'k8s-node-worker-03'.
fqdn	string	no	The fully qualified domain name of the runner system, when known. Distinct from the short 'hostname'; kept separate for the same reason as on host components (an FQDN is not reliably decomposable). Example: 'ci-runner-01.build.example.com'.
domain	string	no	The directory domain the runner system belongs to (Active Directory / NetBIOS / LDAP), NOT the DNS suffix of the FQDN. Example: 'CORP'.
containerImage	string	no	The container image used for the test execution. Example: 'inspec/inspec:latest', 'ghcr.io/my-org/scanner:v2.1.0'. Useful for CI/CD pipelines where tests run in containers.
containerId	string	no	The container instance identifier. Example: 'a1b2c3d4e5f6', 'security-scan-job-xyz123'. Can be a Docker container ID, Kubernetes pod name, or other container runtime identifier.
operator	Identity	no	The identity of the person or system responsible for executing the test. This could be a human auditor manually completing a checklist, an automated CI/CD system, or a security tool. Optional field to support both automated and manual HDF generation.

Example

{
  "name": "docker",
  "release": "20.04",
  "architecture": "x86_64",
  "hostname": "github-runner-prod-01",
  "fqdn": "github-runner-prod-01.build.example.com",
  "domain": "CORP",
  "containerImage": "ghcr.io/inspec/inspec:5.22.3",
  "containerId": "security-scan-job-a1b2c3d4",
  "operator": {
    "identifier": "github-actions",
    "type": "system",
    "description": "Automated CI/CD pipeline"
  }
}

statistics

Statistic_Block

Statistics for a given item, such as the total count.

Field	Type	Required	Description
total	integer	yes	The total count. Example: the total number of requirements in a given category for a run.

Statistic_Hash

Statistics for requirement results, grouped by status.

Field	Type	Required	Description
passed	Statistic_Block	no	Statistics for requirements that passed.
failed	Statistic_Block	no	Statistics for requirements that failed.
notApplicable	Statistic_Block	no	Statistics for requirements that are not applicable to the target.
notReviewed	Statistic_Block	no	Statistics for requirements that were not reviewed (manual check required).
error	Statistic_Block	no	Statistics for requirements that encountered an error during assessment.

Statistics

Statistics for the assessment run(s) such as duration and result counts.

Field	Type	Required	Description
duration	number	no	How long (in seconds) this assessment run took.
requirements	Statistic_Hash	no	Breakdowns of requirement statistics by result status.

system

Authorization_Status

Authorization to Operate (ATO) status for the system.

Categorization_Level

FIPS 199 security categorization level (impact level).

Input_Override

An override of a baseline input value for a specific component. Enables system-specific tailoring of baseline parameters.

Field	Type	Required	Description
baselineRef	string	no	Name of the baseline this override applies to. If omitted, applies to all baselines that define this input.
inputName	string	yes	Name of the input being overridden. Must match an Input.name in the referenced baseline.
value	any	yes	The overridden value. Should match the type of the original input.
justification	string	no	Rationale for why this override is needed.
approvedBy	Identity	no	Identity of the person or system that approved this override.

Target_Selector

A label selector that matches targets by label key-value pairs. All specified labels must match (AND logic). Example: { "labels.component": "WebTier" } matches targets with labels.component = "WebTier".

Control_Designation

Declares a control's designation within a system — whether it is common (provided by another component or system), system-specific (implemented locally), or hybrid (shared responsibility). Maps to NIST SP 800-53 Appendix C control designations and OSCAL SSP by-component provided/inherited semantics.

Field	Type	Required	Description
controlId	string	yes	The control identifier (e.g., 'SC-7', 'AC-2 (1)'). Must match a NIST tag in a baseline requirement's tags.
designation	"common" | "system-specific" | "hybrid"	yes	NIST SP 800-53 control designation. 'common': fully provided by another component or system. 'system-specific': implemented by the inheriting component(s) only. 'hybrid': shared responsibility between provider and inheritor.
providedBy	string (uuid)	no	componentId of a local component that provides this control. Omit when the provider is an external system.
systemRef	string (uri-reference)	no	Reference to another hdf-system document whose component provides this control. Use when the provider is in a different system. Omit when the provider is local.
inheritedBy	string (uuid)[]	no	componentIds that inherit this control. If omitted, all components in the system inherit it.
description	string	yes	Justification for this designation — who provides the control, why it's inherited, and any relevant authorization references.

Example

{
  "controlId": "IA-2",
  "designation": "common",
  "providedBy": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "inheritedBy": [
    "11111111-2222-3333-4444-555555555555"
  ],
  "description": "User identification and authentication provided by Keycloak SSO via SAML 2.0."
}