@mitre/hdf-fixtures

Shared real-world HDF reference fixtures for cross-package consumers (parsers, validators, hdf-extension-graph, hdf-generators, legacyhdf-to-hdf converter).

Why this package exists. Real-world test data was historically scattered across converter packages, with no shared discovery mechanism. Packages that needed it most (parsers, validators) couldn't see the wild-data samples that already existed elsewhere. The class-of-bug fixed by hdf-libs-2nm0 / hdf-libs-828d (parsers rejecting real InSpec output with bare timestamps) went undetected for exactly that reason — the bug-exhibiting file lived in hdf-extension-graph/test/fixtures/ and never reached the parser's tests. See bead hdf-libs-e95o for the architecture rationale.

Boundary rule

• Converter fixtures stay where they are unless multiple packages actively consume them. A converter's fixtures/input/ and fixtures/expected/ are the converter's tested contract.
• Inclusion requires real multi-consumer usage — at least two workspace packages actively load the file. "Might be useful someday" or "good for parity-test breadth" are not sufficient justification. When in doubt, leave the file where it is and migrate later once the second consumer materializes.
• No duplicates. If a fixture is going to be used by two packages, it lives here exactly once and both consumers import it. The original location's file gets deleted; consumer test code is updated.

Layout

hdf-fixtures/
├── results/     — HDF Results docs
├── baseline/    — HDF Baseline docs
├── amendments/  — HDF Amendments docs
└── inspec/      — InSpec runner output (non-HDF)

The inspec/ directory holds InSpec runner output (the input format for legacyhdf-to-hdf — not HDF), kept here for cross-language parser parity tests that verify both languages reject non-HDF inputs the same way, AND for the legacyhdf-to-hdf converter's own tests (which load them via the materialize-to-tmp-file helper in converter_test.go).

Fixture provenance

All fixtures here are real tool output, never fabricated (per CLAUDE.md's fixture-integrity rule).

results/ — HDF Results docs

| File | Source | Consumers | |------|--------|-----------| | inspec-multilayered.json | InSpec runner, multi-overlay scan | hdf-extension-graph TS + Go tests + hdf-parsers parser parity test. The bug-exhibiting fixture for hdf-libs-2nm0 — bare timestamps that broke parsers before #83/#828d landed. Moved from hdf-extension-graph/test/fixtures/multilayered-inspec.json. | | minimal.json | Hand-crafted minimal valid HDF Results doc | hdf-to-xml converter (TS + Go) + hdf-parsers integration test + hdf-validators integration test. The smallest schema-valid HDF Results document — single baseline, one passing requirement. Moved from hdf-converters/converters/hdf-to-xml/fixtures/input/minimal.json. |

baseline/ — HDF Baseline docs

| File | Source | Consumers | |------|--------|-----------| | win2022-stig.json | Windows Server 2022 STIG | hdf-generators TS + Go integration tests + hdf-parsers parser parity test. Was previously duplicated across hdf-generators/go/testdata/ and hdf-generators/test/fixtures/. |

amendments/ — HDF Amendments docs

| File | Source | Consumers | |------|--------|-----------| | uc-01-fixed-amendments.json | HDF form of the CSAF spec example 2022-evd-uc-01-f-001.json — produced by csaf-vex-to-hdf from that upstream VEX advisory. An open POA&M (vendor claims fixed, milestone still pending). | hdf-to-csaf-vex converter (TS + Go, incl. its golden) + hdf-to-oscal-poam converter (TS + Go golden). Moved from hdf-converters/converters/hdf-to-csaf-vex/fixtures/input/. | | multi-cve-amendments.json | HDF form of the CSAF advisory sec-vex-2022-0001.json — produced by csaf-vex-to-hdf from that upstream VEX advisory. Three overrides across three distinct CVE-shaped requirementIds (the Log4Shell family: CVE-2021-44228/45046/45105), all falsePositive. A multi-override amendments doc for meaningful export-side output-count anchors (bead hdf-libs-j0ok). | hdf-to-oscal-poam, hdf-to-csaf-vex, hdf-to-cyclonedx-vex, hdf-to-openvex output-count anchors (TS + Go). |

inspec/ — InSpec runner output (NOT HDF)

The input format for legacyhdf-to-hdf (which converts these to HDF). Kept here because both that converter's tests AND the cross-language parser parity test consume them. Each exercises a different timestamp format / runner config.

| File | Notes | Consumers | |------|-------|-----------| | ubi9-scan.json | UBI9 container scan, -05:00 offset | legacyhdf-to-hdf converter (TS + Go) + hdf-cli legacyhdf test + parser parity test | | container-scan.json | Generic container scan, -05:00 offset | same | | three-layer-overlay.json | Three-layer overlay chain, +00:00 offset | same | | wrapper.json | InSpec wrapper-profile structure | legacyhdf-to-hdf converter (TS + Go) + hdf-parsers flatten integration test | | three-layer-rhel7.json | Three-layer RHEL7 overlay (was Three_Layer_RHEL7_Overlay_Example.json) | hdf-parsers flatten integration test. Moved from hdf-schema/test/fixtures/. |

Validation gate

fixtures_gate_test.go walks every HDF document in results/, baseline/ and amendments/ and validates against the appropriate schema (replaces the per-converter snapshot coverage hdf-cli's converter_fixture_roundtrip_test.go previously provided for these specific files now that they live here). inspec/* is exempt — those files are non-HDF by design.

Usage

TypeScript:

import { results, baseline, amendments, inspec } from '@mitre/hdf-fixtures';

// On-disk path (for tools that need a file argument):
const path = results.inspecMultilayered.path;

// Or read the bytes directly:
const raw = results.inspecMultilayered.read();

Go:

import fixtures "github.com/mitre/hdf-libs/hdf-fixtures"

data := fixtures.Results.InspecMultilayered // []byte, //go:embed'd at build

When to add a new fixture

Add a fixture here when two or more workspace packages already need it — not preemptively. If only one package needs it, keep it local to that package; promote it here when a second consumer materializes.

Each new fixture must:

1. Come from a real tool run (no fabrication).
2. Be added to this README with provenance AND the list of consumers.
3. Be wired into both src/index.ts (TS) and fixtures.go (Go) so both sides have parallel access.
4. Have its original location deleted (no duplicates) and every consumer updated to import from here.
5. Be added to the group map in fixtures_gate_test.go, which validates each fixture against its schema. That map is hand-maintained: a fixture missing from it is never validated, and nothing reports the omission.