@mitre/hdf-schema 3.6.0-rc.5 → 3.7.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +10 -4
  2. package/dist/go/hdf.go +30 -12
  3. package/dist/index.js +28 -28
  4. package/dist/schemas/hdf-amendments.schema.json +100 -69
  5. package/dist/schemas/hdf-baseline.schema.json +105 -74
  6. package/dist/schemas/hdf-comparison.schema.json +201 -176
  7. package/dist/schemas/hdf-evidence-package.schema.json +105 -75
  8. package/dist/schemas/hdf-plan.schema.json +106 -75
  9. package/dist/schemas/hdf-requirement-change-event.schema.json +191 -169
  10. package/dist/schemas/hdf-results.schema.json +176 -150
  11. package/dist/schemas/hdf-system.schema.json +123 -96
  12. package/dist/ts/hdf.d.ts +24 -2
  13. package/dist/ts/hdf.ts +24 -2
  14. package/package.json +2 -2
package/dist/schemas/hdf-results.schema.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.5.0",
3
+ "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.7.0",
4
4
  "type": "object",
5
5
  "unevaluatedProperties": false,
6
6
  "required": [
@@ -10,7 +10,7 @@
10
10
  "externalReferences": {
11
11
  "type": "array",
12
12
  "items": {
13
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
13
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
14
14
  },
15
15
  "description": "Optional references to external artifacts (CTI/STIX, BOMs, advisories, runbooks, or any URI-addressable artifact) relevant to this assessment as a whole. Inert context; see External_Reference."
16
16
  },
@@ -27,7 +27,7 @@
27
27
  "components": {
28
28
  "type": "array",
29
29
  "items": {
30
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0#/$defs/Component"
30
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0#/$defs/Component"
31
31
  },
32
32
  "description": "The components that were assessed. Each component describes a system element (host, container, cloud resource, application, etc.) with optional identity, SBOM, and external references."
33
33
  },
@@ -39,27 +39,38 @@
39
39
  "description": "Information on the baselines that were evaluated, including findings."
40
40
  },
41
41
  "statistics": {
42
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.5.0#/$defs/Statistics",
42
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.7.0#/$defs/Statistics",
43
43
  "description": "Statistics for the assessment run, including duration and result counts."
44
44
  },
45
45
  "generator": {
46
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Generator",
46
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Generator",
47
47
  "description": "Information about the tool that generated this file."
48
48
  },
49
49
  "tool": {
50
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Tool",
50
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Tool",
51
51
  "description": "The security tool that produced the assessment data in this file."
52
52
  },
53
53
  "integrity": {
54
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Integrity",
54
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Integrity",
55
55
  "description": "Cryptographic integrity information for verifying this file."
56
56
  },
57
+ "preAmendmentChecksum": {
58
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
59
+ "description": "Hash of this results document as it stood immediately before the most recent amendment application. Written by `hdf amend apply` when it applies at least one override; an apply that matches nothing leaves the document untouched. The hash covers the results file's RAW BYTES as read, not a canonical form, so reproducing it requires the byte-identical original — reformatting or re-serializing the source changes the value. Only the most recent pre-application state is recorded: applying amendments to an already-amended document REPLACES this value, so it is a single link back one step, not a growing chain. Distinct from the `previousChecksum` inside an override, which chains amendments to each other and is computed over a canonical JSON form.",
60
+ "$comment": "Example 1: the real SHA-256 of hdf-converters/converters/nessus-to-hdf/fixtures/expected/sample.nessus.hdf.json, reproducible with `shasum -a 256` on that file — chosen over a synthetic digest so a reader can verify the hash basis is the raw file bytes.",
61
+ "examples": [
62
+ {
63
+ "algorithm": "sha256",
64
+ "value": "9599ce7889e99b70ef5d0f3efa4215e35059c10a7e89b9314cbf4ded8fdbad38"
65
+ }
66
+ ]
67
+ },
57
68
  "runner": {
58
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.5.0#/$defs/Runner",
69
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.7.0#/$defs/Runner",
59
70
  "description": "Information about the test execution environment where the security tool was run. Distinct from targets (what is being tested)."
60
71
  },
61
72
  "remediation": {
62
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Remediation",
73
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Remediation",
63
74
  "description": "Optional reference to automated remediation resources (Ansible playbooks, Terraform scripts, etc.) for fixing failing requirements found in this assessment."
64
75
  },
65
76
  "systemRef": {
@@ -73,7 +84,7 @@
73
84
  "description": "Reference to an hdf-plan document describing the assessment plan that produced these results. May be a relative path, absolute URI, or fragment identifier."
74
85
  },
75
86
  "derivation": {
76
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.5.0#/$defs/Derivation",
87
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.7.0#/$defs/Derivation",
77
88
  "description": "Present ONLY on reconciled result sets: lineage recording the seed snapshot and event watermark this document was reassembled from (ADR-0005). Documents produced directly by a scan omit this field. When present, generator names the reconciling tool."
78
89
  },
79
90
  "extensions": {
@@ -171,14 +182,14 @@
171
182
  ],
172
183
  "allOf": [
173
184
  {
174
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Baseline_Metadata"
185
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Baseline_Metadata"
175
186
  }
176
187
  ],
177
188
  "properties": {
178
189
  "depends": {
179
190
  "type": "array",
180
191
  "items": {
181
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Dependency"
192
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Dependency"
182
193
  },
183
194
  "description": "The set of dependencies this baseline depends on."
184
195
  },
@@ -191,15 +202,15 @@
191
202
  "description": "The description - should be more detailed than the summary."
192
203
  },
193
204
  "integrity": {
194
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Integrity",
205
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Integrity",
195
206
  "description": "Cryptographic integrity information for verifying this baseline has not been tampered with."
196
207
  },
197
208
  "originalChecksum": {
198
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
209
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
199
210
  "description": "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."
200
211
  },
201
212
  "resultsChecksum": {
202
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
213
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
203
214
  "description": "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."
204
215
  },
205
216
  "statusMessage": {
@@ -217,14 +228,14 @@
217
228
  "groups": {
218
229
  "type": "array",
219
230
  "items": {
220
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Requirement_Group"
231
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Requirement_Group"
221
232
  },
222
233
  "description": "A set of descriptions for the requirement groups."
223
234
  },
224
235
  "inputs": {
225
236
  "type": "array",
226
237
  "items": {
227
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.5.0#/$defs/Input"
238
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.7.0#/$defs/Input"
228
239
  },
229
240
  "description": "Typed inputs used to parameterize this baseline at execution time. See the Input primitive for the full schema."
230
241
  },
@@ -249,7 +260,7 @@
249
260
  ],
250
261
  "allOf": [
251
262
  {
252
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Requirement_Core"
263
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Requirement_Core"
253
264
  }
254
265
  ],
255
266
  "properties": {
@@ -257,7 +268,7 @@
257
268
  "type": "array",
258
269
  "minItems": 1,
259
270
  "items": {
260
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Requirement_Description"
271
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Requirement_Description"
261
272
  },
262
273
  "contains": {
263
274
  "type": "object",
@@ -273,37 +284,37 @@
273
284
  "description": "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'."
274
285
  },
275
286
  "severity": {
276
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Severity",
287
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Severity",
277
288
  "description": "Explicit severity rating. Typically derived from impact score but provided explicitly for clarity."
278
289
  },
279
290
  "sourceLocation": {
280
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Source_Location",
291
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Source_Location",
281
292
  "description": "The explicit location of the requirement within the source code."
282
293
  },
283
294
  "results": {
284
295
  "type": "array",
285
296
  "minItems": 1,
286
297
  "items": {
287
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Requirement_Result"
298
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Requirement_Result"
288
299
  },
289
300
  "description": "The set of all tests within the requirement and their results."
290
301
  },
291
302
  "statusOverrides": {
292
303
  "type": "array",
293
304
  "items": {
294
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Status_Override"
305
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Status_Override"
295
306
  },
296
307
  "description": "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."
297
308
  },
298
309
  "poams": {
299
310
  "type": "array",
300
311
  "items": {
301
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/POAM"
312
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/POAM"
302
313
  },
303
314
  "description": "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."
304
315
  },
305
316
  "effectiveStatus": {
306
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
317
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
307
318
  "description": "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."
308
319
  },
309
320
  "effectiveImpact": {
@@ -313,33 +324,33 @@
313
324
  "description": "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."
314
325
  },
315
326
  "disposition": {
316
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Override_Type",
327
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Override_Type",
317
328
  "description": "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."
318
329
  },
319
330
  "effectiveChecksum": {
320
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
331
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
321
332
  "description": "Checksum of this requirement's resolved effective posture, for per-control change detection in continuous monitoring.\n\nsha256 over the canonical JSON object with keys status, impact, disposition (in that order), holding the resolved effective status, resolved effective impact, and governing override type (null when nothing governs), with override expiry anchored to the document timestamp.\n\nFlips exactly when the operative status, impact, or disposition changes; stable under all other churn (result details, timestamps, tags).\n\nOptional; stamped by tooling (hdf convert, hdf amend apply)."
322
333
  },
323
334
  "evidence": {
324
335
  "type": "array",
325
336
  "items": {
326
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
337
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
327
338
  },
328
339
  "description": "Supporting evidence for this requirement's findings, such as screenshots, code samples, or log excerpts."
329
340
  },
330
341
  "cvss": {
331
342
  "type": "array",
332
343
  "items": {
333
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0#/$defs/Cvss"
344
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0#/$defs/Cvss"
334
345
  },
335
346
  "description": "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."
336
347
  },
337
348
  "epss": {
338
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.5.0#/$defs/Epss",
349
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.7.0#/$defs/Epss",
339
350
  "description": "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."
340
351
  },
341
352
  "kev": {
342
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.5.0#/$defs/Kev",
353
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.7.0#/$defs/Kev",
343
354
  "description": "CISA Known Exploited Vulnerabilities (KEV) catalog status. When inKev=true, dateAdded and dueDate carry the federal patching deadline."
344
355
  },
345
356
  "cwe": {
@@ -353,14 +364,14 @@
353
364
  "affectedPackages": {
354
365
  "type": "array",
355
366
  "items": {
356
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0#/$defs/Affected_Package"
367
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0#/$defs/Affected_Package"
357
368
  },
358
369
  "description": "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)."
359
370
  }
360
371
  },
372
+ "$comment": "Examples, in order: 1) Passing requirement — no overrides, no disposition; 2) Waiver — AO accepted risk, status overridden to passed; 3) False positive (compliance scan) — STIG check was wrong, requirement actually passes; 4) False positive (CVE scan) — vulnerability does not apply to this build; 5) Risk adjustment — impact lowered, pass/fail unchanged; 6) Operational requirement — cannot remediate, remains open risk; 7) POAM — remediation tracked, status unchanged.",
361
373
  "examples": [
362
374
  {
363
- "$comment": "Passing requirement — no overrides, no disposition",
364
375
  "id": "SV-230222",
365
376
  "title": "RHEL 9 must use SSH protocol version 2",
366
377
  "impact": 0.7,
@@ -385,7 +396,6 @@
385
396
  "effectiveStatus": "passed"
386
397
  },
387
398
  {
388
- "$comment": "Waiver — AO accepted risk, status overridden to passed",
389
399
  "id": "SV-230300",
390
400
  "title": "RHEL 9 must enforce password complexity",
391
401
  "impact": 0.5,
@@ -429,7 +439,6 @@
429
439
  }
430
440
  },
431
441
  {
432
- "$comment": "False positive (compliance scan) — STIG check was wrong, requirement actually passes",
433
442
  "id": "SV-230410",
434
443
  "title": "RHEL 9 must have sshd PermitRootLogin disabled",
435
444
  "impact": 0.7,
@@ -469,7 +478,6 @@
469
478
  "disposition": "falsePositive"
470
479
  },
471
480
  {
472
- "$comment": "False positive (CVE scan) — vulnerability does not apply to this build",
473
481
  "id": "CVE-2026-12345",
474
482
  "title": "libxml2 buffer overflow in xmlParseEntityDecl",
475
483
  "impact": 0.9,
@@ -509,7 +517,6 @@
509
517
  "disposition": "falsePositive"
510
518
  },
511
519
  {
512
- "$comment": "Risk adjustment — impact lowered, pass/fail unchanged",
513
520
  "id": "CVE-2026-67890",
514
521
  "title": "OpenSSL timing side-channel in RSA decryption",
515
522
  "impact": 0.7,
@@ -552,7 +559,6 @@
552
559
  "disposition": "riskAdjustment"
553
560
  },
554
561
  {
555
- "$comment": "Operational requirement — cannot remediate, remains open risk",
556
562
  "id": "SV-230500",
557
563
  "title": "RHEL 9 must disable USB mass storage",
558
564
  "impact": 0.5,
@@ -592,7 +598,6 @@
592
598
  "disposition": "operationalRequirement"
593
599
  },
594
600
  {
595
- "$comment": "POAM — remediation tracked, status unchanged",
596
601
  "id": "SV-230350",
597
602
  "title": "RHEL 9 must be patched within 30 days of release",
598
603
  "impact": 0.7,
@@ -646,9 +651,9 @@
646
651
  "description": "A requirement that has been evaluated, including any findings.",
647
652
  "title": "Evaluated Requirement"
648
653
  },
649
- "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0": {
654
+ "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0": {
650
655
  "$schema": "https://json-schema.org/draft/2020-12/schema",
651
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0",
656
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0",
652
657
  "title": "HDF Common Primitives",
653
658
  "description": "Shared building blocks used by hdf-results and hdf-baseline schemas.",
654
659
  "$defs": {
@@ -728,22 +733,20 @@
728
733
  }
729
734
  },
730
735
  "unevaluatedProperties": false,
736
+ "$comment": "Examples, in order: 1) By-identity: cite a CVE by its id in the 'cve' system without a URL — equivalently urn:cve:CVE-2021-44228; 2) By-identity AND by-locator together (anyOf, not oneOf) — an ATT&CK technique cited by id with its canonical URL; 3) By-locator to a retrievable STIX bundle, with integrity hash, media type, and attribution; 4) Enrichment envelope: a STIX threat-intel object embedded losslessly in `document` and classified via `kind`, cited by id and pointed at by href — the pointer and the embedded copy compose. The payload rides verbatim; HDF does not normalize STIX fields.",
731
737
  "examples": [
732
738
  {
733
- "$comment": "By-identity: cite a CVE by its id in the 'cve' system without a URL — equivalently urn:cve:CVE-2021-44228.",
734
739
  "sourceName": "cve",
735
740
  "externalId": "CVE-2021-44228",
736
741
  "rel": "definition"
737
742
  },
738
743
  {
739
- "$comment": "By-identity AND by-locator together (anyOf, not oneOf) — an ATT&CK technique cited by id with its canonical URL.",
740
744
  "sourceName": "mitre-att&ck",
741
745
  "externalId": "T1059",
742
746
  "href": "https://attack.mitre.org/techniques/T1059/",
743
747
  "rel": "canonical"
744
748
  },
745
749
  {
746
- "$comment": "By-locator to a retrievable STIX bundle, with integrity hash, media type, and attribution.",
747
750
  "sourceName": "stix",
748
751
  "href": "https://cti.example.org/bundles/log4shell.json",
749
752
  "rel": "investigate",
@@ -759,7 +762,6 @@
759
762
  "addedAt": "2026-07-26T00:00:00Z"
760
763
  },
761
764
  {
762
- "$comment": "Enrichment envelope: a STIX threat-intel object embedded losslessly in `document` and classified via `kind`, cited by id and pointed at by href — the pointer and the embedded copy compose. The payload rides verbatim; HDF does not normalize STIX fields.",
763
765
  "sourceName": "stix",
764
766
  "externalId": "vulnerability--f7c1b8e0-1234-4a2b-9c3d-000000000001",
765
767
  "href": "https://cti.example.org/bundles/log4shell.json#vulnerability--f7c1b8e0-1234-4a2b-9c3d-000000000001",
@@ -1091,6 +1093,24 @@
1091
1093
  "type",
1092
1094
  "data"
1093
1095
  ],
1096
+ "if": {
1097
+ "properties": {
1098
+ "encoding": {
1099
+ "const": "base64"
1100
+ }
1101
+ },
1102
+ "required": [
1103
+ "encoding"
1104
+ ]
1105
+ },
1106
+ "then": {
1107
+ "properties": {
1108
+ "data": {
1109
+ "pattern": "^[0-9A-Za-z+/]+={0,2}$",
1110
+ "contentEncoding": "base64"
1111
+ }
1112
+ }
1113
+ },
1094
1114
  "properties": {
1095
1115
  "type": {
1096
1116
  "type": "string",
@@ -1107,7 +1127,8 @@
1107
1127
  },
1108
1128
  "data": {
1109
1129
  "type": "string",
1110
- "description": "The evidence content. For screenshots/files: base64-encoded data or URL. For code/logs: the raw text. For URLs: the URL string."
1130
+ "minLength": 1,
1131
+ "description": "The evidence content. For screenshots/files: base64-encoded data or URL. For code/logs: the raw text. For URLs: the URL string. Must not be empty. When encoding is 'base64', data must be bare base64 matching ^[0-9A-Za-z+/]+={0,2}$ (OSCAL's Base64Datatype): no data: URI prefix, URL, or line breaks."
1111
1132
  },
1112
1133
  "description": {
1113
1134
  "type": "string",
@@ -1119,7 +1140,7 @@
1119
1140
  },
1120
1141
  "encoding": {
1121
1142
  "type": "string",
1122
- "description": "Encoding used for the data. Example: 'base64', 'utf-8'."
1143
+ "description": "Encoding used for the data. Example: 'base64', 'utf-8'. The value 'base64' (exactly, lowercase) requires data to be bare base64."
1123
1144
  },
1124
1145
  "size": {
1125
1146
  "type": "number",
@@ -1183,6 +1204,7 @@
1183
1204
  }
1184
1205
  }
1185
1206
  ],
1207
+ "$comment": "Examples, in order: 1) base64-encoded PNG screenshot with full capture provenance; 2) raw configuration text; 3) log excerpt; 4) URL to an external ticket; 5) base64-encoded file captured by an automated system.",
1186
1208
  "description": "Supporting evidence for a finding or override, such as screenshots, code samples, log excerpts, or URLs.",
1187
1209
  "title": "Evidence"
1188
1210
  },
@@ -1260,6 +1282,13 @@
1260
1282
  "status"
1261
1283
  ],
1262
1284
  "properties": {
1285
+ "title": {
1286
+ "type": "string",
1287
+ "minLength": 1,
1288
+ "pattern": "^[^ \\t\\n\\r]([^\\n\\r]*[^ \\t\\n\\r])?$",
1289
+ "$comment": "The pattern is OSCAL's StringDatatype (\\S(.*\\S)?) as its XSD defines \\S and '.', spelled with explicit classes so ECMA-262 and Go regexp engines agree: \\S and '.' differ between them on CR and non-ASCII whitespace.",
1290
+ "description": "Short single-line label for this milestone, suitable where a consumer needs a title (for example an OSCAL POA&M remediation or task). No line breaks, and no leading or trailing whitespace. The description remains the full text of the milestone; the title does not replace it."
1291
+ },
1263
1292
  "description": {
1264
1293
  "type": "string",
1265
1294
  "description": "Description of this milestone or task."
@@ -1289,6 +1318,25 @@
1289
1318
  "description": "Identity of who completed this milestone."
1290
1319
  }
1291
1320
  },
1321
+ "examples": [
1322
+ {
1323
+ "title": "Deploy OpenSSH 9.8p1",
1324
+ "description": "Upgrade OpenSSH to 9.8p1 on every RHEL 9 host in the web tier to remediate CVE-2024-6387, then restart sshd during the Saturday maintenance window.",
1325
+ "estimatedCompletion": "2026-10-31T00:00:00Z",
1326
+ "status": "inProgress"
1327
+ },
1328
+ {
1329
+ "description": "Isolate the affected host on a restricted VLAN until the vendor patch is available.",
1330
+ "estimatedCompletion": "2026-09-05T00:00:00Z",
1331
+ "status": "completed",
1332
+ "completedAt": "2026-09-04T14:30:00Z",
1333
+ "completedBy": {
1334
+ "identifier": "network-admin@example.com",
1335
+ "type": "email"
1336
+ }
1337
+ }
1338
+ ],
1339
+ "$comment": "Examples, in order: 1) titled milestone in progress — the title is the short label, the description the full remediation text; 2) untitled completed milestone with completion provenance — title is optional, and a consumer needing one derives it.",
1292
1340
  "description": "A milestone or task within a POA&M remediation plan.",
1293
1341
  "title": "Milestone"
1294
1342
  },
@@ -1578,9 +1626,9 @@
1578
1626
  "description": "Whether the requirement is mandatory within its baseline.\n\nDistinct from severity (risk weight) and status (lifecycle state).\n\nMaps 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{}).\n\nOptional: when omitted, consumers should treat the requirement as 'required' by convention."
1579
1627
  }
1580
1628
  },
1629
+ "$comment": "Examples, in order: 1) v3.1.x-style requirement: classification fields omitted. Consumers must continue to handle this shape for backward compatibility; 2) v3.2 example populating all three classification fields. controlType=technical because AC-3 is enforced via configuration, not policy text. verificationMethod=automated because a check exists. applicability=required because this is a CORE control in the source baseline; 3) v3.2 example for a manual-by-design requirement. FedRAMP 20x KSIs are statement-form: code is omitted (not null) and verificationMethod=manual-by-design distinguishes this from 'automation could exist but doesn't yet'. controlType=policy because this is an authored governance statement; 4) v3.2 example for a STIG rule lacking a <fix>. Differs from manual-by-design: automation should exist, just not yet. applicability=advisory used here because the source format flagged it as recommended-but-not-mandatory; CIS-style IG memberships and FedRAMP 'Optional:' markers map onto applicability=optional or advisory similarly.",
1581
1630
  "examples": [
1582
1631
  {
1583
- "$comment": "v3.1.x-style requirement: classification fields omitted. Consumers must continue to handle this shape under v3.5.0 (backward compatibility).",
1584
1632
  "id": "SV-238196",
1585
1633
  "title": "The Ubuntu operating system must enforce password complexity",
1586
1634
  "impact": 0.5,
@@ -1610,7 +1658,6 @@
1610
1658
  ]
1611
1659
  },
1612
1660
  {
1613
- "$comment": "v3.2 example populating all three classification fields. controlType=technical because AC-3 is enforced via configuration, not policy text. verificationMethod=automated because a check exists. applicability=required because this is a CORE control in the source baseline.",
1614
1661
  "id": "AC-3",
1615
1662
  "title": "Access Enforcement",
1616
1663
  "impact": 0.7,
@@ -1632,7 +1679,6 @@
1632
1679
  "applicability": "required"
1633
1680
  },
1634
1681
  {
1635
- "$comment": "v3.2 example for a manual-by-design requirement. FedRAMP 20x KSIs are statement-form: code is omitted (not null) and verificationMethod=manual-by-design distinguishes this from 'automation could exist but doesn't yet'. controlType=policy because this is an authored governance statement.",
1636
1682
  "id": "KSI-CNA-01",
1637
1683
  "title": "Cyber Security Plan documents the system",
1638
1684
  "impact": 0.5,
@@ -1652,7 +1698,6 @@
1652
1698
  "applicability": "required"
1653
1699
  },
1654
1700
  {
1655
- "$comment": "v3.2 example for a STIG rule lacking a <fix>. Differs from manual-by-design: automation should exist, just not yet. applicability=advisory used here because the source format flagged it as recommended-but-not-mandatory; CIS-style IG memberships and FedRAMP 'Optional:' markers map onto applicability=optional or advisory similarly.",
1656
1701
  "id": "SV-999999",
1657
1702
  "title": "Example STIG rule pending automation",
1658
1703
  "impact": 0.3,
@@ -1717,9 +1762,9 @@
1717
1762
  }
1718
1763
  }
1719
1764
  },
1720
- "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0": {
1765
+ "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0": {
1721
1766
  "$schema": "https://json-schema.org/draft/2020-12/schema",
1722
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0",
1767
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0",
1723
1768
  "title": "HDF Component Primitives",
1724
1769
  "description": "First-class system component with identity, polymorphic type, generalized BOM attachment (boms[]), and system-binding properties. Components are the successor to Targets, adding stable identity (componentId), external system cross-references, and manifest inventory (SBOM, AI model/dataset, and reserved future BOM kinds).",
1725
1770
  "$defs": {
@@ -1765,7 +1810,7 @@
1765
1810
  "description": "Description of this component's role or purpose."
1766
1811
  },
1767
1812
  "owner": {
1768
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
1813
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
1769
1814
  "description": "Team or individual responsible for this component. Enables per-component ownership when different teams manage different parts of a system."
1770
1815
  },
1771
1816
  "externalIds": {
@@ -1785,14 +1830,14 @@
1785
1830
  "boms": {
1786
1831
  "type": "array",
1787
1832
  "items": {
1788
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.5.0#/$defs/Bom"
1833
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.7.0#/$defs/Bom"
1789
1834
  },
1790
1835
  "description": "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."
1791
1836
  },
1792
1837
  "integrity": {
1793
1838
  "type": "array",
1794
1839
  "items": {
1795
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum"
1840
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum"
1796
1841
  },
1797
1842
  "description": "Cryptographic integrity of this component's underlying artifact — model weights or shards, dataset archive, container image, or package bytes.\n\nAn array supports multi-file/sharded artifacts.\n\nThis 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).\n\nDistinct from BOM-document integrity (Bom.hashes[]) and from the document tamper-evidence Integrity type."
1798
1843
  },
@@ -1806,12 +1851,12 @@
1806
1851
  "inputOverrides": {
1807
1852
  "type": "array",
1808
1853
  "items": {
1809
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0#/$defs/Input_Override"
1854
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0#/$defs/Input_Override"
1810
1855
  },
1811
1856
  "description": "System-specific overrides for baseline input values."
1812
1857
  },
1813
1858
  "targetSelector": {
1814
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0#/$defs/Target_Selector",
1859
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0#/$defs/Target_Selector",
1815
1860
  "description": "Label selector to match targets belonging to this component during migration. Targets with matching labels are automatically included."
1816
1861
  }
1817
1862
  },
@@ -1942,9 +1987,9 @@
1942
1987
  }
1943
1988
  }
1944
1989
  ],
1990
+ "$comment": "Examples, in order: 1) 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; 2) Standalone/workgroup host: has a short hostname but no directory domain — 'domain' is omitted rather than fabricated from the FQDN suffix.",
1945
1991
  "examples": [
1946
1992
  {
1947
- "$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.",
1948
1993
  "type": "host",
1949
1994
  "name": "web-server-prod-01",
1950
1995
  "componentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
@@ -1960,7 +2005,6 @@
1960
2005
  }
1961
2006
  },
1962
2007
  {
1963
- "$comment": "Standalone/workgroup host: has a short hostname but no directory domain — 'domain' is omitted rather than fabricated from the FQDN suffix.",
1964
2008
  "type": "host",
1965
2009
  "name": "kiosk-lab-07",
1966
2010
  "hostname": "kiosk-lab-07",
@@ -2095,7 +2139,7 @@
2095
2139
  "const": "cloudAccount"
2096
2140
  },
2097
2141
  "provider": {
2098
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Cloud_Provider",
2142
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Cloud_Provider",
2099
2143
  "description": "Cloud provider."
2100
2144
  },
2101
2145
  "accountId": {
@@ -2134,7 +2178,7 @@
2134
2178
  "const": "cloudResource"
2135
2179
  },
2136
2180
  "provider": {
2137
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Cloud_Provider",
2181
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Cloud_Provider",
2138
2182
  "description": "Cloud provider."
2139
2183
  },
2140
2184
  "resourceType": {
@@ -2433,9 +2477,9 @@
2433
2477
  }
2434
2478
  }
2435
2479
  },
2436
- "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.5.0": {
2480
+ "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.7.0": {
2437
2481
  "$schema": "https://json-schema.org/draft/2020-12/schema",
2438
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.5.0",
2482
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.7.0",
2439
2483
  "title": "HDF BOM Primitives",
2440
2484
  "description": "Generalized Bill-of-Materials / manifest representation.\n\nOne extensible Bom shape, discriminated by bomType, carries any manifest kind (SBOM, AI model/dataset, and reserved future kinds) either by passthrough (opaque ref/embed of the native document) or normalized (converted into HDF's queryable shape).\n\nSubject identity (name, version, componentId) is inherited from the host component or system — the BOM never re-owns it.\n\nSee ADR-0001.",
2441
2485
  "$defs": {
@@ -2491,7 +2535,7 @@
2491
2535
  "hashes": {
2492
2536
  "type": "array",
2493
2537
  "items": {
2494
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum"
2538
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum"
2495
2539
  },
2496
2540
  "description": "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."
2497
2541
  },
@@ -2608,9 +2652,9 @@
2608
2652
  ]
2609
2653
  }
2610
2654
  ],
2655
+ "$comment": "Examples, in order: 1) Passthrough SBOM by external reference — the universal escape hatch, available to every bomType; 2) Passthrough for a reserved-but-not-yet-normalized type (cbom) — carried opaquely until a normalized extension ships; 3) Normalized ai-model BOM: CISA/G7-aligned fields live in the model extension, never at the component root or shared base; 4) Normalized dataset BOM with lineage — a filtered derivative of a base dataset, referenced by an ai-model via datasetRefs.",
2611
2656
  "examples": [
2612
2657
  {
2613
- "$comment": "Passthrough SBOM by external reference — the universal escape hatch, available to every bomType.",
2614
2658
  "bomType": "sbom",
2615
2659
  "format": "cyclonedx",
2616
2660
  "ref": "https://artifacts.agency.gov/sbom/webtier.cdx.json",
@@ -2622,7 +2666,6 @@
2622
2666
  ]
2623
2667
  },
2624
2668
  {
2625
- "$comment": "Passthrough for a reserved-but-not-yet-normalized type (cbom) — carried opaquely until a normalized extension ships.",
2626
2669
  "bomType": "cbom",
2627
2670
  "format": "cyclonedx",
2628
2671
  "document": {
@@ -2631,7 +2674,6 @@
2631
2674
  }
2632
2675
  },
2633
2676
  {
2634
- "$comment": "Normalized ai-model BOM: CISA/G7-aligned fields live in the model extension, never at the component root or shared base.",
2635
2677
  "bomType": "ai-model",
2636
2678
  "format": "cyclonedx-ml",
2637
2679
  "model": {
@@ -2671,7 +2713,6 @@
2671
2713
  }
2672
2714
  },
2673
2715
  {
2674
- "$comment": "Normalized dataset BOM with lineage — a filtered derivative of a base dataset, referenced by an ai-model via datasetRefs.",
2675
2716
  "bomType": "dataset",
2676
2717
  "format": "croissant",
2677
2718
  "dataset": {
@@ -2906,9 +2947,9 @@
2906
2947
  }
2907
2948
  }
2908
2949
  },
2909
- "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0": {
2950
+ "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0": {
2910
2951
  "$schema": "https://json-schema.org/draft/2020-12/schema",
2911
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0",
2952
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0",
2912
2953
  "title": "HDF System Primitives",
2913
2954
  "description": "Types for describing system architecture, authorization boundaries, and components.",
2914
2955
  "$defs": {
@@ -2959,7 +3000,7 @@
2959
3000
  "description": "Rationale for why this override is needed."
2960
3001
  },
2961
3002
  "approvedBy": {
2962
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
3003
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
2963
3004
  "description": "Identity of the person or system that approved this override."
2964
3005
  }
2965
3006
  },
@@ -3041,9 +3082,9 @@
3041
3082
  }
3042
3083
  }
3043
3084
  },
3044
- "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.5.0": {
3085
+ "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.7.0": {
3045
3086
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3046
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.5.0",
3087
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.7.0",
3047
3088
  "title": "HDF Statistics Primitives",
3048
3089
  "description": "Statistics types for tracking assessment run metrics.",
3049
3090
  "$defs": {
@@ -3112,9 +3153,9 @@
3112
3153
  }
3113
3154
  }
3114
3155
  },
3115
- "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0": {
3156
+ "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0": {
3116
3157
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3117
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0",
3158
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0",
3118
3159
  "title": "HDF Extension Primitives",
3119
3160
  "description": "Extension types for waivers, attestations, generators, and integrity.",
3120
3161
  "$defs": {
@@ -3144,20 +3185,20 @@
3144
3185
  "externalReferences": {
3145
3186
  "type": "array",
3146
3187
  "items": {
3147
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
3188
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
3148
3189
  },
3149
3190
  "description": "Optional references to the external artifacts behind this override (e.g. the STIX bundle/object or CTI feed motivating an E:A riskAdjustment). Inert context distinct from `evidence`; see External_Reference. Symmetric with Standalone_Override.externalReferences for the inline (results-embedded) override carrier."
3150
3191
  },
3151
3192
  "type": {
3152
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Override_Type",
3193
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Override_Type",
3153
3194
  "description": "The type of override applied to this requirement."
3154
3195
  },
3155
3196
  "status": {
3156
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
3197
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
3157
3198
  "description": "The new status this override sets for the requirement. Optional when only impact is being overridden."
3158
3199
  },
3159
3200
  "impact": {
3160
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Impact_Override",
3201
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Impact_Override",
3161
3202
  "description": "Override to the requirement's impact score. At least one of status or impact must be set."
3162
3203
  },
3163
3204
  "reason": {
@@ -3165,7 +3206,7 @@
3165
3206
  "description": "Explanation for why this override was applied."
3166
3207
  },
3167
3208
  "appliedBy": {
3168
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
3209
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
3169
3210
  "description": "Identity of who applied this override. For simple cases, use type 'simple' with just an identifier."
3170
3211
  },
3171
3212
  "appliedAt": {
@@ -3179,30 +3220,31 @@
3179
3220
  "description": "Timestamp when this override expires and must be reviewed/renewed. REQUIRED - no permanent overrides allowed. ISO 8601 format."
3180
3221
  },
3181
3222
  "signature": {
3182
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Signature",
3223
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Signature",
3183
3224
  "description": "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."
3184
3225
  },
3185
3226
  "evidence": {
3186
3227
  "type": "array",
3187
3228
  "items": {
3188
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
3229
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
3189
3230
  },
3190
3231
  "description": "Supporting evidence for this override, such as screenshots demonstrating manual verification for attestations."
3191
3232
  },
3192
3233
  "previousChecksum": {
3193
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
3234
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
3194
3235
  "description": "SHA-256 checksum of the previous amendment in chronological order. Each amendment's checksum is recorded by the NEXT one, so editing an amendment in place is detectable — provided a later amendment is chained to it. It is NOT tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a chain that has been stripped or recomputed wholesale are all outside what it can detect. Use signature for non-repudiation. Omitted on the first amendment on a requirement."
3195
3236
  },
3196
3237
  "cvss": {
3197
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0#/$defs/Cvss",
3238
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0#/$defs/Cvss",
3198
3239
  "$comment": "When present alongside impact.value on a riskAdjustment override, impact.value should be approximately cvss.computedScore / 10.0. Soft consistency rule — validators may warn but should not error. The cvss block makes Environmental/Threat enrichment auditable.",
3199
3240
  "description": "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."
3200
3241
  },
3201
3242
  "justification": {
3202
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Justification",
3243
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Justification",
3203
3244
  "description": "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."
3204
3245
  }
3205
3246
  },
3247
+ "$comment": "Example 3: Inline riskAdjustment carrying the STIX source that motivated it via externalReferences (the enrichment envelope, with the raw sighting embedded losslessly in document). This is the shape the enrich pass writes onto Evaluated_Requirement.overrides[] for the E:A recompute.",
3206
3248
  "examples": [
3207
3249
  {
3208
3250
  "type": "waiver",
@@ -3229,7 +3271,6 @@
3229
3271
  "expiresAt": "2026-10-14T00:00:00Z"
3230
3272
  },
3231
3273
  {
3232
- "$comment": "Inline riskAdjustment carrying the STIX source that motivated it via externalReferences (the enrichment envelope, with the raw sighting embedded losslessly in document). This is the shape the enrich pass writes onto Evaluated_Requirement.overrides[] for the E:A recompute.",
3233
3274
  "type": "riskAdjustment",
3234
3275
  "impact": {
3235
3276
  "value": 0.9
@@ -3292,7 +3333,7 @@
3292
3333
  "evidence": [
3293
3334
  {
3294
3335
  "type": "screenshot",
3295
- "data": "base64-encoded-screenshot-data-here",
3336
+ "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
3296
3337
  "description": "Screenshot showing firewall configuration",
3297
3338
  "mimeType": "image/png",
3298
3339
  "encoding": "base64",
@@ -3335,7 +3376,7 @@
3335
3376
  "description": "Detailed explanation of the plan, including what actions will be taken."
3336
3377
  },
3337
3378
  "appliedBy": {
3338
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
3379
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
3339
3380
  "description": "Identity of who created this POA&M. For simple cases, use type 'simple' with just an identifier."
3340
3381
  },
3341
3382
  "appliedAt": {
@@ -3351,23 +3392,23 @@
3351
3392
  "milestones": {
3352
3393
  "type": "array",
3353
3394
  "items": {
3354
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Milestone"
3395
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Milestone"
3355
3396
  },
3356
3397
  "description": "Optional array of milestones tracking progress toward completion."
3357
3398
  },
3358
3399
  "signature": {
3359
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Signature",
3400
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Signature",
3360
3401
  "description": "Optional digital signature for enhanced trust and non-repudiation."
3361
3402
  },
3362
3403
  "evidence": {
3363
3404
  "type": "array",
3364
3405
  "items": {
3365
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
3406
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
3366
3407
  },
3367
3408
  "description": "Supporting evidence for this POA&M, such as documentation of compensating controls or mitigation implementation."
3368
3409
  },
3369
3410
  "previousChecksum": {
3370
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
3411
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
3371
3412
  "description": "SHA-256 checksum of the previous amendment in chronological order. Each amendment's checksum is recorded by the NEXT one, so editing an amendment in place is detectable — provided a later amendment is chained to it. It is NOT tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a chain that has been stripped or recomputed wholesale are all outside what it can detect. Use signature for non-repudiation. Omitted on the first amendment on a requirement."
3372
3413
  }
3373
3414
  },
@@ -3520,7 +3561,7 @@
3520
3561
  },
3521
3562
  "properties": {
3522
3563
  "algorithm": {
3523
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Hash_Algorithm",
3564
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Hash_Algorithm",
3524
3565
  "description": "The hash algorithm used for the checksum."
3525
3566
  },
3526
3567
  "checksum": {
@@ -3553,9 +3594,9 @@
3553
3594
  }
3554
3595
  }
3555
3596
  },
3556
- "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0": {
3597
+ "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0": {
3557
3598
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3558
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0",
3599
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0",
3559
3600
  "title": "HDF Amendment Primitives",
3560
3601
  "description": "Types for waivers, attestations, and POA&Ms that modify requirement compliance status.",
3561
3602
  "$defs": {
@@ -3666,7 +3707,7 @@
3666
3707
  "externalReferences": {
3667
3708
  "type": "array",
3668
3709
  "items": {
3669
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
3710
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
3670
3711
  },
3671
3712
  "description": "Optional references to the external artifacts behind this override (e.g. the STIX bundle/object, advisory, or CTI feed that motivated it). Inert context distinct from `evidence`; see External_Reference."
3672
3713
  },
@@ -3676,6 +3717,7 @@
3676
3717
  },
3677
3718
  "requirementId": {
3678
3719
  "type": "string",
3720
+ "minLength": 1,
3679
3721
  "description": "The ID of the requirement being amended. Must match a requirement ID in the referenced baseline."
3680
3722
  },
3681
3723
  "baselineRef": {
@@ -3683,7 +3725,7 @@
3683
3725
  "description": "Name of the baseline containing the requirement. Required when the system has multiple baselines with potentially overlapping requirement IDs."
3684
3726
  },
3685
3727
  "status": {
3686
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
3728
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
3687
3729
  "description": "The new status this amendment sets. Optional when only impact is being overridden."
3688
3730
  },
3689
3731
  "impact": {
@@ -3695,7 +3737,7 @@
3695
3737
  "description": "Justification for this amendment."
3696
3738
  },
3697
3739
  "appliedBy": {
3698
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
3740
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
3699
3741
  "description": "Identity of who applied this amendment."
3700
3742
  },
3701
3743
  "appliedAt": {
@@ -3711,20 +3753,20 @@
3711
3753
  "evidence": {
3712
3754
  "type": "array",
3713
3755
  "items": {
3714
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
3756
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
3715
3757
  },
3716
3758
  "description": "Supporting evidence (screenshots, logs, URLs, documents)."
3717
3759
  },
3718
3760
  "signature": {
3719
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Signature",
3761
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Signature",
3720
3762
  "description": "Digital signature for non-repudiation."
3721
3763
  },
3722
3764
  "previousChecksum": {
3723
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
3765
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
3724
3766
  "description": "SHA-256 checksum of the prior amendment in chronological order. Each amendment's checksum is recorded by the NEXT one, so editing an amendment in place is detectable — provided a later amendment is chained to it. It is NOT tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a chain that has been stripped or recomputed wholesale are all outside what it can detect. Use signature for non-repudiation. Omitted on the first amendment."
3725
3767
  },
3726
3768
  "cvss": {
3727
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0#/$defs/Cvss",
3769
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0#/$defs/Cvss",
3728
3770
  "$comment": "When present alongside impact.value on a riskAdjustment override, impact.value should be approximately cvss.computedScore / 10.0. Soft consistency rule — validators may warn but should not error. The cvss block makes Environmental/Threat enrichment auditable.",
3729
3771
  "description": "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."
3730
3772
  },
@@ -3735,7 +3777,7 @@
3735
3777
  "milestones": {
3736
3778
  "type": "array",
3737
3779
  "items": {
3738
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Milestone"
3780
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Milestone"
3739
3781
  },
3740
3782
  "description": "Remediation milestones (primarily for POA&M type amendments)."
3741
3783
  },
@@ -3752,11 +3794,12 @@
3752
3794
  "affectedPackages": {
3753
3795
  "type": "array",
3754
3796
  "items": {
3755
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0#/$defs/Affected_Package"
3797
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0#/$defs/Affected_Package"
3756
3798
  },
3757
3799
  "description": "Software packages this amendment is scoped to, distinct from componentRef (which scopes to an HDF-internal Component by UUID).\n\nUse 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.\n\nSymmetric with Evaluated_Requirement.affectedPackages, which scopes findings to the same package vocabulary.\n\nWhen omitted, the amendment applies system-wide (or only to componentRef when that is set)."
3758
3800
  }
3759
3801
  },
3802
+ "$comment": "Example 7: VEX-style import — falsePositive scoped to specific packages by purl. The affectedPackages array carries structured product identity instead of squeezing 'Products: …' into the reason free-text field.",
3760
3803
  "examples": [
3761
3804
  {
3762
3805
  "type": "waiver",
@@ -3858,7 +3901,6 @@
3858
3901
  "expiresAt": "2026-09-26T00:00:00Z"
3859
3902
  },
3860
3903
  {
3861
- "$comment": "VEX-style import — falsePositive scoped to specific packages by purl. The affectedPackages array carries structured product identity instead of squeezing 'Products: …' into the reason free-text field.",
3862
3904
  "type": "falsePositive",
3863
3905
  "requirementId": "CVE-2026-12345",
3864
3906
  "status": "notApplicable",
@@ -3885,9 +3927,9 @@
3885
3927
  }
3886
3928
  }
3887
3929
  },
3888
- "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0": {
3930
+ "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0": {
3889
3931
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3890
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0",
3932
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0",
3891
3933
  "title": "HDF Result Primitives",
3892
3934
  "description": "Types for representing assessment results and statuses.",
3893
3935
  "$defs": {
@@ -4018,9 +4060,9 @@
4018
4060
  }
4019
4061
  }
4020
4062
  },
4021
- "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0": {
4063
+ "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0": {
4022
4064
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4023
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0",
4065
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0",
4024
4066
  "title": "HDF CVSS Primitives",
4025
4067
  "description": "Types for representing CVSS (Common Vulnerability Scoring System) data attached to assessment findings. Supports CVSS v2.0, v3.0, v3.1, and v4.0 metric groups (Base, Threat, Environmental, Supplemental).",
4026
4068
  "$defs": {
@@ -4084,7 +4126,7 @@
4084
4126
  ]
4085
4127
  }
4086
4128
  ],
4087
- "$comment": "Only `version` is required; every metric/score field is optional because a single Cvss instance may represent vendor-supplied Base data (on a finding's cvss[]), consumer-supplied enrichment (on a riskAdjustment override — Environmental/Threat/Supplemental deltas with NO base, since base is the finding's scan-specific vendor data), or a fully-resolved effectiveCvss. The Base/Threat/Environmental/Supplemental groups do not partition cleanly into vendor-vs-consumer (Threat straddles: vendor temporal data and consumer exploit-maturity both live here), so a single permissive type is more honest than separate vendor/consumer types. The anyOf guardrail rejects a content-free object (e.g. {version} alone) by requiring at least one substantive metric or score. baseVector remains optional even when baseScore is present: some vendor tools (Twistlock/Prisma Cloud) emit a final score without the vector that derived it — that score is captured structurally rather than lost.",
4129
+ "$comment": "Only `version` is required; every metric/score field is optional because a single Cvss instance may represent vendor-supplied Base data (on a finding's cvss[]), consumer-supplied enrichment (on a riskAdjustment override — Environmental/Threat/Supplemental deltas with NO base, since base is the finding's scan-specific vendor data), or a fully-resolved effectiveCvss. The Base/Threat/Environmental/Supplemental groups do not partition cleanly into vendor-vs-consumer (Threat straddles: vendor temporal data and consumer exploit-maturity both live here), so a single permissive type is more honest than separate vendor/consumer types. The anyOf guardrail rejects a content-free object (e.g. {version} alone) by requiring at least one substantive metric or score. baseVector remains optional even when baseScore is present: some vendor tools (Twistlock/Prisma Cloud) emit a final score without the vector that derived it — that score is captured structurally rather than lost. Examples, in order: 1) Base-only: vendor-supplied CVSS 3.1 data exactly as a scanner (e.g., Nessus, Grype) would emit it. No consumer enrichment yet; 2) Base + Threat: consumer added Exploit Maturity ('E:U' = Unproven) and Remediation Level ('RL:O' = Official Fix) to a HTTP/2 'Rapid Reset' DoS finding. Threat score drops from base 7.5 to 5.5; 3) Base + Environmental: consumer asserts the affected system is high-criticality (CR:H, IR:H, AR:H) AND network-reachable in their environment (MAV:N). Environmental score reflects deployment risk for the xz-utils backdoor; 4) Full CVSS 4.0: vendor base + consumer threat (E:A = Attacked, exploits seen in the wild) + environmental (high CIA requirements) + supplemental context (S:P = present safety impact, AU:N = no autonomous spread, RE:M = moderate response effort) for the Fortinet FortiOS pre-auth RCE. computedScore reflects post-mitigation final risk; 5) CVSS 2.0 legacy: Heartbleed (CVE-2014-0160) as still reported by older scanner output and legacy NVD data. CVSS 2.0 vectors have no 'CVSS:2.0/' prefix.",
4088
4130
  "properties": {
4089
4131
  "version": {
4090
4132
  "type": "string",
@@ -4164,7 +4206,6 @@
4164
4206
  },
4165
4207
  "examples": [
4166
4208
  {
4167
- "$comment": "Base-only: vendor-supplied CVSS 3.1 data exactly as a scanner (e.g., Nessus, Grype) would emit it. No consumer enrichment yet.",
4168
4209
  "version": "3.1",
4169
4210
  "source": "CVE-2024-12345",
4170
4211
  "baseVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
@@ -4172,7 +4213,6 @@
4172
4213
  "baseSeverity": "critical"
4173
4214
  },
4174
4215
  {
4175
- "$comment": "Base + Threat: consumer added Exploit Maturity ('E:U' = Unproven) and Remediation Level ('RL:O' = Official Fix) to a HTTP/2 'Rapid Reset' DoS finding. Threat score drops from base 7.5 to 5.5.",
4176
4216
  "version": "3.1",
4177
4217
  "source": "CVE-2023-44487",
4178
4218
  "baseVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
@@ -4182,7 +4222,6 @@
4182
4222
  "threatScore": 5.5
4183
4223
  },
4184
4224
  {
4185
- "$comment": "Base + Environmental: consumer asserts the affected system is high-criticality (CR:H, IR:H, AR:H) AND network-reachable in their environment (MAV:N). Environmental score reflects deployment risk for the xz-utils backdoor.",
4186
4225
  "version": "3.1",
4187
4226
  "source": "CVE-2024-3094",
4188
4227
  "baseVector": "CVSS:3.1/AV:L/AC:H/PR:H/UI:N/S:U/C:H/I:H/A:H",
@@ -4194,7 +4233,6 @@
4194
4233
  "computedSeverity": "critical"
4195
4234
  },
4196
4235
  {
4197
- "$comment": "Full CVSS 4.0: vendor base + consumer threat (E:A = Attacked, exploits seen in the wild) + environmental (high CIA requirements) + supplemental context (S:P = present safety impact, AU:N = no autonomous spread, RE:M = moderate response effort) for the Fortinet FortiOS pre-auth RCE. computedScore reflects post-mitigation final risk.",
4198
4236
  "version": "4.0",
4199
4237
  "source": "CVE-2024-21762",
4200
4238
  "baseVector": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N",
@@ -4209,7 +4247,6 @@
4209
4247
  "computedSeverity": "medium"
4210
4248
  },
4211
4249
  {
4212
- "$comment": "CVSS 2.0 legacy: Heartbleed (CVE-2014-0160) as still reported by older scanner output and legacy NVD data. CVSS 2.0 vectors have no 'CVSS:2.0/' prefix.",
4213
4250
  "version": "2.0",
4214
4251
  "source": "CVE-2014-0160",
4215
4252
  "baseVector": "AV:N/AC:L/Au:N/C:P/I:N/A:N",
@@ -4222,9 +4259,9 @@
4222
4259
  }
4223
4260
  }
4224
4261
  },
4225
- "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0": {
4262
+ "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0": {
4226
4263
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4227
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0",
4264
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0",
4228
4265
  "title": "HDF Affected Package Primitives",
4229
4266
  "description": "Types for representing the software package(s) affected by a vulnerability finding.",
4230
4267
  "$defs": {
@@ -4290,9 +4327,9 @@
4290
4327
  "description": "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'."
4291
4328
  }
4292
4329
  },
4330
+ "$comment": "Examples, in order: 1) RPM ecosystem with full CPE + PURL — typical Grype/Trivy output for a RHEL host scan; 2) NPM ecosystem with PURL only — the JavaScript world rarely emits CPEs; PURL is the canonical identifier; 3) Minimal valid AffectedPackage — only the three required fields. Use when the scanner reports a package by name+version without emitting CPE or PURL strings; 4) Maven ecosystem with full identifiers + fixedInVersion — log4j Log4Shell-style finding showing the patch path from vulnerable to fixed; 5) purl-only — VEX import path where the source format gives a purl and we choose not to decompose it. Valid because purl encodes name/version/ecosystem implicitly; 6) cpe-only — NIST-flavored scopes where the consumer carries a CPE 2.3 string and no purl. Valid because cpe encodes vendor/product/version.",
4293
4331
  "examples": [
4294
4332
  {
4295
- "$comment": "RPM ecosystem with full CPE + PURL — typical Grype/Trivy output for a RHEL host scan.",
4296
4333
  "name": "openssl",
4297
4334
  "version": "1.1.1k-7.el8_4",
4298
4335
  "ecosystem": "rpm",
@@ -4301,7 +4338,6 @@
4301
4338
  "fixedInVersion": "1.1.1l"
4302
4339
  },
4303
4340
  {
4304
- "$comment": "NPM ecosystem with PURL only — the JavaScript world rarely emits CPEs; PURL is the canonical identifier.",
4305
4341
  "name": "lodash",
4306
4342
  "version": "4.17.20",
4307
4343
  "ecosystem": "npm",
@@ -4309,13 +4345,11 @@
4309
4345
  "fixedInVersion": "4.17.21"
4310
4346
  },
4311
4347
  {
4312
- "$comment": "Minimal valid AffectedPackage — only the three required fields. Use when the scanner reports a package by name+version without emitting CPE or PURL strings.",
4313
4348
  "name": "requests",
4314
4349
  "version": "2.28.1",
4315
4350
  "ecosystem": "pypi"
4316
4351
  },
4317
4352
  {
4318
- "$comment": "Maven ecosystem with full identifiers + fixedInVersion — log4j Log4Shell-style finding showing the patch path from vulnerable to fixed.",
4319
4353
  "name": "org.apache.logging.log4j:log4j-core",
4320
4354
  "version": "2.14.1",
4321
4355
  "ecosystem": "maven",
@@ -4324,11 +4358,9 @@
4324
4358
  "fixedInVersion": "2.17.1"
4325
4359
  },
4326
4360
  {
4327
- "$comment": "purl-only — VEX import path where the source format gives a purl and we choose not to decompose it. Valid because purl encodes name/version/ecosystem implicitly.",
4328
4361
  "purl": "pkg:npm/lodash@4.17.20"
4329
4362
  },
4330
4363
  {
4331
- "$comment": "cpe-only — NIST-flavored scopes where the consumer carries a CPE 2.3 string and no purl. Valid because cpe encodes vendor/product/version.",
4332
4364
  "cpe": "cpe:2.3:a:openssl:openssl:1.1.1k:*:*:*:*:*:*:*"
4333
4365
  }
4334
4366
  ],
@@ -4337,9 +4369,9 @@
4337
4369
  }
4338
4370
  }
4339
4371
  },
4340
- "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.5.0": {
4372
+ "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.7.0": {
4341
4373
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4342
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.5.0",
4374
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.7.0",
4343
4375
  "title": "HDF Runner Primitive",
4344
4376
  "description": "Information about the test execution environment where the security tool/scanner was executed.",
4345
4377
  "$defs": {
@@ -4383,7 +4415,7 @@
4383
4415
  "description": "The container instance identifier. Example: 'a1b2c3d4e5f6', 'security-scan-job-xyz123'. Can be a Docker container ID, Kubernetes pod name, or other container runtime identifier."
4384
4416
  },
4385
4417
  "operator": {
4386
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
4418
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
4387
4419
  "description": "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."
4388
4420
  }
4389
4421
  },
@@ -4432,9 +4464,9 @@
4432
4464
  }
4433
4465
  }
4434
4466
  },
4435
- "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.5.0": {
4467
+ "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.7.0": {
4436
4468
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4437
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.5.0",
4469
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.7.0",
4438
4470
  "title": "HDF Change Event Primitives",
4439
4471
  "description": "Shared building blocks for HDF change-event wire documents. The envelope is entity-agnostic: hdf-requirement-change-event composes it today, and any future sibling event type (e.g. component change events — hdf-comparison already models componentDiffs alongside requirementDiffs) reuses it verbatim.",
4440
4472
  "$defs": {
@@ -4488,7 +4520,7 @@
4488
4520
  "priorChecksum": {
4489
4521
  "oneOf": [
4490
4522
  {
4491
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum"
4523
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum"
4492
4524
  },
4493
4525
  {
4494
4526
  "type": "null"
@@ -4497,23 +4529,22 @@
4497
4529
  "description": "The effectiveChecksum of the entity state this event supersedes, forming a per-key hash chain: a mismatch or gap against stored state is detectable, letting a consumer mark the key unverified instead of serving stale posture.\n\nNull at chain start (no prior state, e.g. a new entity or the first event after a seed).\n\nThe chain provides tamper/gap evidence given a trusted head; completeness is anchored out-of-band by periodic re-centering rescans."
4498
4530
  }
4499
4531
  },
4532
+ "$comment": "Examples, in order: 1) Steady-state envelope: mid-chain event from an InSpec producer. priorChecksum links to the previous effectiveChecksum for this key; 2) Chain-start envelope: first event for a key after seeding — priorChecksum is null (the CloudTrail null-previous-digest convention), sequence starts low.",
4500
4533
  "examples": [
4501
4534
  {
4502
- "$comment": "Steady-state envelope: mid-chain event from an InSpec producer. priorChecksum links to the previous effectiveChecksum for this key.",
4503
4535
  "eventId": "0190f6f2-1c4e-7c3a-9f2a-3b1d5e7a9c01",
4504
4536
  "source": "inspec://web01/rhel9-stig",
4505
4537
  "sequence": 412,
4506
4538
  "systemRef": "apptier.hdf-system.json",
4507
4539
  "componentId": "6e0f2a3b-9c01-4d5e-8f7a-1b2c3d4e5f60",
4508
4540
  "timestamp": "2026-07-22T14:03:11Z",
4509
- "schemaRef": "https://mitre.github.io/hdf-libs/schemas/hdf-requirement-change-event/v3.5.0",
4541
+ "schemaRef": "https://mitre.github.io/hdf-libs/schemas/hdf-requirement-change-event/v3.7.0",
4510
4542
  "priorChecksum": {
4511
4543
  "algorithm": "sha256",
4512
4544
  "value": "704f62b2d0803438ad6b7b9bab45e2c4f350b7344135a2a7f8ef986d98669021"
4513
4545
  }
4514
4546
  },
4515
4547
  {
4516
- "$comment": "Chain-start envelope: first event for a key after seeding — priorChecksum is null (the CloudTrail null-previous-digest convention), sequence starts low.",
4517
4548
  "eventId": "0190f6f2-2a5b-7e4d-b1c8-4f2e6a8b0d12",
4518
4549
  "source": "inspec://web01/rhel9-stig",
4519
4550
  "sequence": 1,
@@ -4561,7 +4592,7 @@
4561
4592
  ],
4562
4593
  "properties": {
4563
4594
  "effectiveStatus": {
4564
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
4595
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
4565
4596
  "description": "The resolved effective compliance status at this point in the chain."
4566
4597
  },
4567
4598
  "effectiveImpact": {
@@ -4571,14 +4602,13 @@
4571
4602
  "description": "The resolved effective impact score (0.0–1.0) at this point in the chain."
4572
4603
  }
4573
4604
  },
4605
+ "$comment": "Examples, in order: 1) Prior posture of a failing SSH-cipher control before remediation; 2) Prior posture of a control passing under a waiver (the projection carries the resolved status; the governing override type travels in the requirement payload, not here).",
4574
4606
  "examples": [
4575
4607
  {
4576
- "$comment": "Prior posture of a failing SSH-cipher control before remediation.",
4577
4608
  "effectiveStatus": "failed",
4578
4609
  "effectiveImpact": 0.5
4579
4610
  },
4580
4611
  {
4581
- "$comment": "Prior posture of a control passing under a waiver (the projection carries the resolved status; the governing override type travels in the requirement payload, not here).",
4582
4612
  "effectiveStatus": "passed",
4583
4613
  "effectiveImpact": 0.5
4584
4614
  }
@@ -4611,7 +4641,7 @@
4611
4641
  "description": "URI to the seed snapshot document (relative path or absolute URL)."
4612
4642
  },
4613
4643
  "checksum": {
4614
- "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
4644
+ "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
4615
4645
  "description": "Checksum of the seed snapshot, REQUIRED: the derivation pins an immutable snapshot by content, not just location."
4616
4646
  }
4617
4647
  },
@@ -4639,9 +4669,9 @@
4639
4669
  "description": "The posture-as-of time of this reconciled view (RFC 3339, trimmed UTC) — the analog of PROV's generatedAtTime."
4640
4670
  }
4641
4671
  },
4672
+ "$comment": "Examples, in order: 1) A reconciled result set: reassembled from the pinned seed scan plus 3 change events through watermark 414. The document's generator names the reconciler, never the scanner.",
4642
4673
  "examples": [
4643
4674
  {
4644
- "$comment": "A reconciled result set: reassembled from the pinned seed scan plus 3 change events through watermark 414. The document's generator names the reconciler, never the scanner.",
4645
4675
  "seed": {
4646
4676
  "uri": "apptier-seed-scan.hdf.json",
4647
4677
  "checksum": {
@@ -4660,9 +4690,9 @@
4660
4690
  }
4661
4691
  }
4662
4692
  },
4663
- "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.5.0": {
4693
+ "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.7.0": {
4664
4694
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4665
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.5.0",
4695
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.7.0",
4666
4696
  "title": "HDF Parameter Primitives",
4667
4697
  "description": "Input/parameter type definitions for typed, traceable configuration values that bridge governance prose and scanner automation.",
4668
4698
  "$defs": {
@@ -4793,9 +4823,9 @@
4793
4823
  }
4794
4824
  }
4795
4825
  },
4796
- "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.5.0": {
4826
+ "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.7.0": {
4797
4827
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4798
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.5.0",
4828
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.7.0",
4799
4829
  "title": "HDF EPSS Primitive",
4800
4830
  "description": "Type for representing FIRST.org's Exploit Prediction Scoring System (EPSS) data for a vulnerability. EPSS estimates the probability that a CVE will be exploited in the wild in the next 30 days. See https://www.first.org/epss/ for the underlying model and methodology.",
4801
4831
  "$defs": {
@@ -4827,21 +4857,19 @@
4827
4857
  "description": "ISO 8601 date (YYYY-MM-DD) on which FIRST.org published this EPSS score."
4828
4858
  }
4829
4859
  },
4860
+ "$comment": "Examples, in order: 1) High exploit probability and high percentile, characteristic of a widely-exploited vulnerability like Log4Shell (CVE-2021-44228) shortly after disclosure; 2) Low score but moderate percentile, the common case for CVEs that have some observed exploitation evidence but are not under active mass exploitation; 3) Very low score, typical of a CVE with no known exploitation activity or proof-of-concept availability.",
4830
4861
  "examples": [
4831
4862
  {
4832
- "$comment": "High exploit probability and high percentile, characteristic of a widely-exploited vulnerability like Log4Shell (CVE-2021-44228) shortly after disclosure.",
4833
4863
  "score": 0.97532,
4834
4864
  "percentile": 0.99987,
4835
4865
  "date": "2026-05-26"
4836
4866
  },
4837
4867
  {
4838
- "$comment": "Low score but moderate percentile, the common case for CVEs that have some observed exploitation evidence but are not under active mass exploitation.",
4839
4868
  "score": 0.04521,
4840
4869
  "percentile": 0.78432,
4841
4870
  "date": "2026-05-26"
4842
4871
  },
4843
4872
  {
4844
- "$comment": "Very low score, typical of a CVE with no known exploitation activity or proof-of-concept availability.",
4845
4873
  "score": 0.00042,
4846
4874
  "percentile": 0.10215,
4847
4875
  "date": "2026-05-26"
@@ -4852,9 +4880,9 @@
4852
4880
  }
4853
4881
  }
4854
4882
  },
4855
- "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.5.0": {
4883
+ "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.7.0": {
4856
4884
  "$schema": "https://json-schema.org/draft/2020-12/schema",
4857
- "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.5.0",
4885
+ "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.7.0",
4858
4886
  "title": "HDF Kev Primitives",
4859
4887
  "description": "Types for representing CISA Known Exploited Vulnerabilities (KEV) catalog membership. The KEV catalog (https://www.cisa.gov/known-exploited-vulnerabilities-catalog) flags CVEs that are confirmed actively exploited in the wild and drives federal patching urgency under CISA Binding Operational Directive 22-01.",
4860
4888
  "$defs": {
@@ -4900,23 +4928,21 @@
4900
4928
  "description": "CISA's notes describing the vulnerability, observed exploitation, or remediation guidance."
4901
4929
  }
4902
4930
  },
4931
+ "$comment": "Examples, in order: 1) High-urgency case: recently added KEV entry with a short federal patching deadline; 2) Older KEV entry whose due date has already passed — useful for reporting overdue remediation; 3) Vulnerability evaluated against the KEV catalog and confirmed not present — dateAdded/dueDate are not required when inKev is false.",
4903
4932
  "examples": [
4904
4933
  {
4905
- "$comment": "High-urgency case: recently added KEV entry with a short federal patching deadline.",
4906
4934
  "inKev": true,
4907
4935
  "dateAdded": "2026-03-15",
4908
4936
  "dueDate": "2026-04-05",
4909
4937
  "notes": "Active ransomware exploitation observed; apply vendor patch immediately."
4910
4938
  },
4911
4939
  {
4912
- "$comment": "Older KEV entry whose due date has already passed — useful for reporting overdue remediation.",
4913
4940
  "inKev": true,
4914
4941
  "dateAdded": "2023-11-07",
4915
4942
  "dueDate": "2023-11-28",
4916
4943
  "notes": "Apply mitigations per vendor instructions or discontinue use of the product if mitigations are unavailable."
4917
4944
  },
4918
4945
  {
4919
- "$comment": "Vulnerability evaluated against the KEV catalog and confirmed not present — dateAdded/dueDate are not required when inKev is false.",
4920
4946
  "inKev": false
4921
4947
  }
4922
4948
  ],