HDF System

Describes a system's authorization boundary, components, and interconnections. Maps to OSCAL SSP system-characteristics and FedRAMP system inventory.


Version	`v3.4.0`
`$id`	`https://mitre.github.io/hdf-libs/schemas/hdf-system/v3.4.0`
Download	hdf-system.schema.json

Properties

Field	Type	Required	Description
`systemId`	`string` (uuid)	no	Stable UUID (RFC 4122) for this system. Enables cross-document correlation independent of file location. Optional in casual use, expected in production documents.
`owner`	`Identity`	no	Team or individual responsible for this system's authorization and compliance. Maps to OSCAL responsible-party with role 'system-owner'.
`name`	`string`	yes	Human-readable system name. Example: 'Enterprise Portal Production'.
`identifier`	`string`	no	System identifier from an authoritative source. Example: eMASS system ID, FedRAMP package ID.
`identifierScheme`	`string` (uri-reference)	no	URI identifying the scheme of the system identifier. Example: 'https://emass.mil', 'https://fedramp.gov'.
`description`	`string`	no	Description of the system's purpose and mission.
`authorizationStatus`	`Authorization_Status`	no	Current Authorization to Operate (ATO) status.
`authorizationDate`	`string` (date-time)	no	Date the current authorization status was granted. ISO 8601 format.
`categorizationLevel`	`Categorization_Level`	no	FIPS 199 security categorization (impact level).
`boundaryDescription`	`string`	no	Description of the system's authorization boundary. Example: network CIDR blocks, cloud VPC IDs, physical locations.
`components`	`Component`[]	yes	System components within the authorization boundary. Uses the full polymorphic Component type with stable identity (componentId), external references, and generalized BOM attachment (boms[]).
`controlDesignations`	`Control_Designation`[]	no	Declares which controls are common, hybrid, or system-specific, and which component provides them. Maps to NIST SP 800-53 control designations and OSCAL leveraged-authorizations.
`dataFlows`	`Data_Flow`[]	no	Inter-component data flows describing how components communicate. Supports local, cross-system, and external flows. Replaces the interconnections[] field.
`boms`	`Bom`[]	no	System-scoped Bills of Materials whose subject is the authorization boundary rather than a single component (e.g. a SaaSBOM of services, a KBOM of cluster inventory, an OBOM). Component-scoped BOMs (SBOM, ai-model) attach on the component instead. See primitives/bom.schema.json.
`labels`	Map<string, `string`>	no	Optional key-value labels for grouping and querying systems.
`integrity`	`Integrity`	no	Cryptographic integrity information for verifying this system document has not been tampered with.
`version`	`string`	no	Version of this system document.
`generator`	`Generator`	no	Information about the tool that generated this system document.

Example

json

{
  "name": "Enterprise Portal Production",
  "identifier": "SYS-2024-00142",
  "identifierScheme": "https://emass.mil",
  "authorizationStatus": "authorized",
  "authorizationDate": "2025-06-15T00:00:00Z",
  "categorizationLevel": "moderate",
  "boundaryDescription": "All resources in prod VPC (10.0.0.0/16)",
  "components": [
    {
      "name": "WebTier",
      "type": "application",
      "componentId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "description": "RHEL 9 web servers running the portal",
      "baselineRefs": [
        "RHEL9-STIG",
        "DISA-Container-STIG"
      ],
      "boms": [
        {
          "bomType": "sbom",
          "format": "cyclonedx",
          "ref": "https://artifacts.agency.gov/sbom/webtier-2026-03.cdx.json"
        }
      ]
    },
    {
      "name": "DatabaseTier",
      "type": "database",
      "componentId": "11111111-2222-3333-4444-555555555555",
      "baselineRefs": [
        "PostgreSQL-15-STIG"
      ]
    }
  ],
  "dataFlows": [
    {
      "from": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "to": "11111111-2222-3333-4444-555555555555",
      "protocol": "jdbc",
      "port": 5432,
      "direction": "unidirectional",
      "description": "Web tier connects to database"
    }
  ]
}

Embedded Primitives

These types are embedded from shared primitive schemas.

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

json

{
  "$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

json

{
  "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

json

{
  "$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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "$comment": "v3.1.x-style requirement: classification fields omitted. Consumers must continue to handle this shape under v3.4.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.

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

json

{
  "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

json

{
  "$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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "$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"
}

data-flow

Cross_System_Reference

Reference to a component in a different system document, enabling cross-boundary data flow modeling.

Field	Type	Required	Description
`systemRef`	`string` (uri-reference)	yes	URI reference to the hdf-system document containing the target component. May be a relative path, absolute URI, or fragment identifier.
`componentId`	`string` (uuid)	yes	UUID of the component in the referenced system.

External_Endpoint

An endpoint outside all modeled systems (e.g., a third-party API, public internet, or partner system not represented in HDF).

Field	Type	Required	Description
`external`	`"true"`	yes	Must be true. Discriminator indicating this endpoint is outside all modeled systems.
`description`	`string`	yes	Human-readable description of the external endpoint. Example: 'Third-party payment gateway (Stripe API)'.

Data_Flow_Endpoint

A data flow endpoint: either a local component (UUID), a component in another system (cross-system reference), or an external endpoint outside all modeled systems.

Data_Flow

A data flow between two endpoints. The 'from' endpoint is always a local component; the 'to' endpoint can be local, cross-system, or external. Use 'direction' to indicate whether data flows one-way or both ways.

Field	Type	Required	Description
`from`	`string` (uuid)	yes	UUID of the local component that is one end of this data flow. Always references a component in the current system document.
`to`	`Data_Flow_Endpoint`	yes	The other end of this data flow. Can be a local component (UUID), a cross-system component reference, or an external endpoint.
`protocol`	`string`	no	Communication protocol. Examples: 'http', 'https', 'grpc', 'ssh', 'jdbc', 'k8s-api', 'socket', 'sftp'.
`port`	`integer`	no	Network port number.
`direction`	`"unidirectional"` \| `"bidirectional"`	no	Data flow direction. 'unidirectional' means data flows from→to only. 'bidirectional' means data flows in both directions (e.g., request/response).
`description`	`string`	no	Human-readable description of this data flow's purpose and the data exchanged.
`authentication`	`string`	no	Authentication mechanism used for this connection. Examples: 'mTLS', 'OAuth2', 'API key', 'SAML', 'Kerberos'.

Example

json

{
  "from": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "to": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "protocol": "https",
  "port": 443,
  "direction": "bidirectional",
  "description": "REST API calls from WebTier to API Gateway",
  "authentication": "mTLS"
}

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

json

{
  "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

json

{
  "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

json

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

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

json

{
  "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

json

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

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

json

{
  "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."
}

HDF System ​

Properties ​

Example ​

Embedded Primitives ​

affected-package ​

Affected_Package ​

amendments ​

Override_Type ​

Justification ​

Impact_Override ​

Standalone_Override ​

bom ​

Bom_Type ​

Bom ​

AI_Model_Extension ​

Dataset_Extension ​

SBOM_Package ​

common ​

Hash_Algorithm ​

Requirement_Group ​

Dependency ​

Reference ​

Source_Location ​

Supported_Platform ​

Checksum ​

Identity ​

Evidence ​

Remediation ​

Verification_Method ​

Milestone ​

Signature ​

Baseline_Metadata ​

Requirement_Core ​

Verification_Method_Enum ​

Severity ​

Cloud_Provider ​

component ​

Base_Component ​

Component ​

Host_Component ​

Container_Image_Component ​

Container_Instance_Component ​

Container_Platform_Component ​

Cloud_Account_Component ​

Cloud_Resource_Component ​

Repository_Component ​

Application_Component ​

Artifact_Component ​

Network_Component ​

Database_Component ​

AI_Model_Component ​

Dataset_Component ​

cvss ​

Cvss_Severity ​

Cvss ​

data-flow ​

Cross_System_Reference ​

External_Endpoint ​

Data_Flow_Endpoint ​

Data_Flow ​

extensions ​

Status_Override ​

POAM ​

Generator ​

Tool ​

Integrity ​

result ​

Result_Status ​

Requirement_Result ​

Requirement_Description ​

system ​

Authorization_Status ​

Categorization_Level ​

Input_Override ​

Target_Selector ​

Control_Designation ​

HDF System

Properties

Example

Embedded Primitives

affected-package

Affected_Package

amendments

Override_Type

Justification

Impact_Override

Standalone_Override

bom

Bom_Type

Bom

AI_Model_Extension

Dataset_Extension

SBOM_Package

common

Hash_Algorithm

Requirement_Group

Dependency

Reference

Source_Location

Supported_Platform

Checksum

Identity

Evidence

Remediation

Verification_Method

Milestone

Signature

Baseline_Metadata

Requirement_Core

Verification_Method_Enum

Severity

Cloud_Provider

component

Base_Component

Component

Host_Component

Container_Image_Component

Container_Instance_Component

Container_Platform_Component

Cloud_Account_Component

Cloud_Resource_Component

Repository_Component

Application_Component

Artifact_Component

Network_Component

Database_Component

AI_Model_Component

Dataset_Component

cvss

Cvss_Severity

Cvss

data-flow

Cross_System_Reference

External_Endpoint

Data_Flow_Endpoint

Data_Flow

extensions

Status_Override

POAM

Generator

Tool

Integrity

result

Result_Status

Requirement_Result

Requirement_Description

system

Authorization_Status

Categorization_Level

Input_Override

Target_Selector

Control_Designation