@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

Fixtures here are real tool output, or a schema-valid document derived from one, never invented data — a converter tested against invented data proves nothing about real data. The one hand-authored file, results/minimal.json, exists to be the smallest schema-valid HDF Results document and is validated as such; it asserts nothing about any tool's output shape.

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.
duplicate-baselines.json	Prisma Cloud HDF results (prisma-to-hdf) — 16 baselines, 94 requirements, repeated (name, id) keys. Constructed for merge/correlation testing, PR #362.	hdf-engine TS + Go (filter/query index-uniqueness) + hdf-cli MCP tools (inspect/aggregate/compliance). Moved from hdf-engine/testdata/duplicate-baselines.json and hdf-cli/internal/mcp/tools/testdata/duplicate-baselines.json.
merge-grype.json	Grype HDF results (grype-to-hdf, Grype 0.79.3) — one baseline, duplicate requirement ids. Constructed for merge/correlation testing, PR #362.	hdf-engine TS + Go (merge parity) + hdf-cli MCP tools (query correlation, multi-source). Moved from hdf-engine/testdata/merge-grype.json and hdf-cli/internal/mcp/tools/testdata/grype-duplicate-ids.json.
merge-zap.json	OWASP ZAP HDF results (zap-to-hdf, ZAP 2.7.0) — four baselines/components, no ids. Constructed for merge/correlation testing, PR #362.	hdf-engine TS + Go (merge parity) + hdf-cli MCP tools (inspect, sources, query multi-source) + hdf-cli MCP evals (sources validation). Moved from hdf-engine/testdata/merge-zap.json and hdf-cli/internal/mcp/tools/testdata/zap-webgoat.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

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.