@mitre/hdf-schema 3.7.2 → 3.8.0-next.42532249979.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.
- package/README.md +9 -0
- package/dist/go/hdf.go +348 -181
- package/dist/helpers.d.ts +7 -5
- package/dist/helpers.js +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +28 -28
- package/dist/schemas/hdf-amendments.schema.json +414 -62
- package/dist/schemas/hdf-baseline.schema.json +419 -67
- package/dist/schemas/hdf-comparison.schema.json +730 -153
- package/dist/schemas/hdf-evidence-package.schema.json +418 -65
- package/dist/schemas/hdf-plan.schema.json +420 -68
- package/dist/schemas/hdf-requirement-change-event.schema.json +486 -140
- package/dist/schemas/hdf-results.schema.json +472 -126
- package/dist/schemas/hdf-system.schema.json +435 -83
- package/dist/ts/hdf.d.ts +218 -26
- package/dist/ts/hdf.js +18 -2
- package/dist/ts/hdf.ts +219 -20
- package/package.json +3 -3
package/dist/go/hdf.go
CHANGED
|
@@ -115,57 +115,57 @@ func (r *HDFRequirementChangeEvent) Marshal() ([]byte, error) {
|
|
|
115
115
|
|
|
116
116
|
// The top level value containing all assessment results.
|
|
117
117
|
type HDFResults struct {
|
|
118
|
-
// Information on the baselines that were evaluated, including findings.
|
|
119
|
-
Baselines []EvaluatedBaseline
|
|
120
|
-
// The components that were assessed. Each component describes a system element (host,
|
|
121
|
-
// container, cloud resource, application, etc.) with optional identity, SBOM, and external
|
|
122
|
-
// references.
|
|
123
|
-
Components []Component
|
|
124
|
-
// Present ONLY on reconciled result sets: lineage recording the seed snapshot and event
|
|
125
|
-
// watermark this document was reassembled from (ADR-0005). Documents produced directly by a
|
|
126
|
-
// scan omit this field. When present, generator names the reconciling tool.
|
|
127
|
-
Derivation *Derivation
|
|
128
|
-
//
|
|
129
|
-
//
|
|
130
|
-
Extensions
|
|
131
|
-
// Optional references to external artifacts (CTI/STIX, BOMs, advisories, runbooks, or any
|
|
132
|
-
// URI-addressable artifact) relevant to this assessment as a whole. Inert context; see
|
|
133
|
-
// External_Reference.
|
|
134
|
-
ExternalReferences []ExternalReference
|
|
135
|
-
// Information about the tool that generated this file.
|
|
136
|
-
Generator *Generator
|
|
137
|
-
// Unique identifier for this assessment run.
|
|
138
|
-
ID *string
|
|
139
|
-
// Cryptographic integrity information for verifying this file.
|
|
140
|
-
Integrity *Integrity
|
|
141
|
-
// Reference to an hdf-plan document describing the assessment plan that produced these
|
|
142
|
-
// results. May be a relative path, absolute URI, or fragment identifier.
|
|
143
|
-
PlanRef *string
|
|
144
|
-
// Hash of this results document as it stood immediately before the most recent amendment
|
|
145
|
-
// application. Written by `hdf amend apply` when it applies at least one override; an apply
|
|
146
|
-
// that matches nothing leaves the document untouched. The hash covers the results file's
|
|
147
|
-
// RAW BYTES as read, not a canonical form, so reproducing it requires the byte-identical
|
|
148
|
-
// original — reformatting or re-serializing the source changes the value. Only the most
|
|
149
|
-
// recent pre-application state is recorded: applying amendments to an already-amended
|
|
150
|
-
// document REPLACES this value, so it is a single link back one step, not a growing chain.
|
|
151
|
-
// Distinct from the `previousChecksum` inside an override, which chains amendments to each
|
|
152
|
-
// other and is computed over a canonical JSON form.
|
|
153
|
-
PreAmendmentChecksum *Checksum
|
|
154
|
-
// Optional reference to automated remediation resources (Ansible playbooks, Terraform
|
|
155
|
-
// scripts, etc.) for fixing failing requirements found in this assessment.
|
|
156
|
-
Remediation *Remediation
|
|
157
|
-
// Information about the test execution environment where the security tool was run.
|
|
158
|
-
// Distinct from targets (what is being tested).
|
|
159
|
-
Runner *Runner
|
|
160
|
-
// Statistics for the assessment run, including duration and result counts.
|
|
161
|
-
Statistics *Statistics
|
|
162
|
-
// Reference to an hdf-system document describing the system under assessment. May be a
|
|
163
|
-
// relative path, absolute URI, or fragment identifier.
|
|
164
|
-
SystemRef *string
|
|
165
|
-
// When this assessment was executed.
|
|
166
|
-
Timestamp *time.Time
|
|
167
|
-
// The security tool that produced the assessment data in this file.
|
|
168
|
-
Tool *Tool
|
|
118
|
+
// Information on the baselines that were evaluated, including findings.
|
|
119
|
+
Baselines []EvaluatedBaseline `json:"baselines"`
|
|
120
|
+
// The components that were assessed. Each component describes a system element (host,
|
|
121
|
+
// container, cloud resource, application, etc.) with optional identity, SBOM, and external
|
|
122
|
+
// references.
|
|
123
|
+
Components []Component `json:"components,omitempty"`
|
|
124
|
+
// Present ONLY on reconciled result sets: lineage recording the seed snapshot and event
|
|
125
|
+
// watermark this document was reassembled from (ADR-0005). Documents produced directly by a
|
|
126
|
+
// scan omit this field. When present, generator names the reconciling tool.
|
|
127
|
+
Derivation *Derivation `json:"derivation,omitempty"`
|
|
128
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) these
|
|
129
|
+
// results were converted from.
|
|
130
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
131
|
+
// Optional references to external artifacts (CTI/STIX, BOMs, advisories, runbooks, or any
|
|
132
|
+
// URI-addressable artifact) relevant to this assessment as a whole. Inert context; see
|
|
133
|
+
// External_Reference.
|
|
134
|
+
ExternalReferences []ExternalReference `json:"externalReferences,omitempty"`
|
|
135
|
+
// Information about the tool that generated this file.
|
|
136
|
+
Generator *Generator `json:"generator,omitempty"`
|
|
137
|
+
// Unique identifier for this assessment run.
|
|
138
|
+
ID *string `json:"id,omitempty"`
|
|
139
|
+
// Cryptographic integrity information for verifying this file.
|
|
140
|
+
Integrity *Integrity `json:"integrity,omitempty"`
|
|
141
|
+
// Reference to an hdf-plan document describing the assessment plan that produced these
|
|
142
|
+
// results. May be a relative path, absolute URI, or fragment identifier.
|
|
143
|
+
PlanRef *string `json:"planRef,omitempty"`
|
|
144
|
+
// Hash of this results document as it stood immediately before the most recent amendment
|
|
145
|
+
// application. Written by `hdf amend apply` when it applies at least one override; an apply
|
|
146
|
+
// that matches nothing leaves the document untouched. The hash covers the results file's
|
|
147
|
+
// RAW BYTES as read, not a canonical form, so reproducing it requires the byte-identical
|
|
148
|
+
// original — reformatting or re-serializing the source changes the value. Only the most
|
|
149
|
+
// recent pre-application state is recorded: applying amendments to an already-amended
|
|
150
|
+
// document REPLACES this value, so it is a single link back one step, not a growing chain.
|
|
151
|
+
// Distinct from the `previousChecksum` inside an override, which chains amendments to each
|
|
152
|
+
// other and is computed over a canonical JSON form.
|
|
153
|
+
PreAmendmentChecksum *Checksum `json:"preAmendmentChecksum,omitempty"`
|
|
154
|
+
// Optional reference to automated remediation resources (Ansible playbooks, Terraform
|
|
155
|
+
// scripts, etc.) for fixing failing requirements found in this assessment.
|
|
156
|
+
Remediation *Remediation `json:"remediation,omitempty"`
|
|
157
|
+
// Information about the test execution environment where the security tool was run.
|
|
158
|
+
// Distinct from targets (what is being tested).
|
|
159
|
+
Runner *Runner `json:"runner,omitempty"`
|
|
160
|
+
// Statistics for the assessment run, including duration and result counts.
|
|
161
|
+
Statistics *Statistics `json:"statistics,omitempty"`
|
|
162
|
+
// Reference to an hdf-system document describing the system under assessment. May be a
|
|
163
|
+
// relative path, absolute URI, or fragment identifier.
|
|
164
|
+
SystemRef *string `json:"systemRef,omitempty"`
|
|
165
|
+
// When this assessment was executed.
|
|
166
|
+
Timestamp *time.Time `json:"timestamp,omitempty"`
|
|
167
|
+
// The security tool that produced the assessment data in this file.
|
|
168
|
+
Tool *Tool `json:"tool,omitempty"`
|
|
169
169
|
}
|
|
170
170
|
|
|
171
171
|
// Information on a baseline that was evaluated, including any findings.
|
|
@@ -174,8 +174,9 @@ type EvaluatedBaseline struct {
|
|
|
174
174
|
Depends []Dependency `json:"depends,omitempty"`
|
|
175
175
|
// The description - should be more detailed than the summary.
|
|
176
176
|
Description *string `json:"description,omitempty"`
|
|
177
|
-
//
|
|
178
|
-
|
|
177
|
+
// Producer data outside the HDF model that belongs to this baseline rather than to the
|
|
178
|
+
// document, and the pre-converted source artifact(s) this baseline was built from.
|
|
179
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
179
180
|
// A set of descriptions for the requirement groups.
|
|
180
181
|
Groups []RequirementGroup `json:"groups,omitempty"`
|
|
181
182
|
// Typed inputs used to parameterize this baseline at execution time. See the Input
|
|
@@ -252,67 +253,134 @@ type Dependency struct {
|
|
|
252
253
|
URL *string `json:"url,omitempty"`
|
|
253
254
|
}
|
|
254
255
|
|
|
256
|
+
// Carrier for data outside the HDF model: `passthrough` for producer data HDF does not model,
|
|
257
|
+
// `rawSourceArtifacts` for the pre-converted input(s). CLOSED: these two members are the whole of
|
|
258
|
+
// it. A key HDF does not define goes inside `passthrough` — that is what `passthrough` is for — so
|
|
259
|
+
// `extensions` never becomes a second, unnamed schema that consumers must reverse-engineer from the
|
|
260
|
+
// producers that happen to write it. Closed with `additionalProperties` rather than the house
|
|
261
|
+
// `unevaluatedProperties` because this definition composes nothing, and the shipped Go validator is
|
|
262
|
+
// a draft-07 engine that does not implement `unevaluatedProperties` — a closure only one of the two
|
|
263
|
+
// validators enforces is not a closure. Declared on every HDF document type that carries a producer
|
|
264
|
+
// envelope (`generator` / `integrity`), and on `Evaluated_Baseline`, so one rule governs both
|
|
265
|
+
// sites.
|
|
266
|
+
type Extensions struct {
|
|
267
|
+
// Catch-all for producer data that HDF does not model — the role heimdall2's
|
|
268
|
+
// `passthrough.auxiliary_data` played: fields a converter deliberately carried but had no
|
|
269
|
+
// home for.
|
|
270
|
+
//
|
|
271
|
+
// Deliberately permissive: unenumerated properties are accepted by design, with no shape
|
|
272
|
+
// imposed on them. HDF neither reads nor interprets what is here. It is the ONLY permissive
|
|
273
|
+
// surface in `extensions` — everything HDF does not define belongs here rather than beside
|
|
274
|
+
// it.
|
|
275
|
+
//
|
|
276
|
+
// This is NOT where the pre-converted source artifact goes. v2 put it here only because
|
|
277
|
+
// nothing else had room; `rawSourceArtifacts` is its home now, and it gives the bytes a
|
|
278
|
+
// checksum, a media type and a reference contract that an untyped object cannot.
|
|
279
|
+
//
|
|
280
|
+
// For data that belongs to one requirement rather than to the document, use that object's
|
|
281
|
+
// own fields — a document-level bag cannot say which requirement it describes.
|
|
282
|
+
Passthrough map[string]interface{} `json:"passthrough,omitempty"`
|
|
283
|
+
// The input(s) this document was converted from, verbatim.
|
|
284
|
+
//
|
|
285
|
+
// An array because a conversion can consume more than one artifact — the OSCAL profile path
|
|
286
|
+
// takes a profile and a catalog. Every other converter takes one input, and an array of one
|
|
287
|
+
// costs nothing.
|
|
288
|
+
//
|
|
289
|
+
// Populating this is required of ingest converters by policy, enforced by the converter
|
|
290
|
+
// contract and test harness rather than by a schema `required`: a tool that emits HDF
|
|
291
|
+
// natively has no source artifact, and requiring the field would make valid native HDF
|
|
292
|
+
// invalid.
|
|
293
|
+
RawSourceArtifacts []ExternalReference `json:"rawSourceArtifacts,omitempty"`
|
|
294
|
+
}
|
|
295
|
+
|
|
255
296
|
// A generalized reference to any external artifact by identity and/or location, modeled on the STIX
|
|
256
297
|
// 2.1 `external_references` common property. Purpose-agnostic: cite a CVE, an ATT&CK technique, a
|
|
257
298
|
// STIX bundle/object, a BOM, a runbook, or any vendor artifact — including kinds with no dedicated
|
|
258
299
|
// HDF reference category. `sourceName` names the system; `externalId` cites by id within that
|
|
259
300
|
// system; `href` locates it. `sourceName` + `externalId` is equivalently a URN
|
|
260
301
|
// (`urn:<sourceName>:<externalId>`, RFC 8141), so the by-identity and by-location forms stay
|
|
261
|
-
// interconvertible.
|
|
262
|
-
//
|
|
302
|
+
// interconvertible. An entry may also carry the artifact itself rather than point at it: `document`
|
|
303
|
+
// for a JSON object, `content` + `encoding` for anything else. Embedding satisfies the at-least-one
|
|
304
|
+
// rule on its own, so an artifact with no meaningful public location needs no synthetic `href`. A
|
|
305
|
+
// reference is inert context: it overrides nothing, so it carries only lightweight optional
|
|
306
|
+
// `addedBy`/`addedAt` attribution, never override machinery.
|
|
263
307
|
type ExternalReference struct {
|
|
264
|
-
// When this reference was attached (RFC 3339 / trimmed-UTC per HDF timestamp convention).
|
|
265
|
-
AddedAt *time.Time
|
|
266
|
-
// Who attached this reference. Lightweight, flat attribution — a reference overrides
|
|
267
|
-
// nothing, so it has no chaining/superseding/disposition.
|
|
268
|
-
AddedBy *Identity
|
|
269
|
-
// Integrity hash of the
|
|
270
|
-
// `
|
|
271
|
-
|
|
272
|
-
//
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
//
|
|
276
|
-
//
|
|
277
|
-
//
|
|
278
|
-
//
|
|
279
|
-
//
|
|
280
|
-
//
|
|
281
|
-
//
|
|
282
|
-
//
|
|
283
|
-
|
|
284
|
-
//
|
|
285
|
-
//
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
//
|
|
289
|
-
//
|
|
290
|
-
//
|
|
291
|
-
|
|
292
|
-
//
|
|
293
|
-
//
|
|
294
|
-
//
|
|
295
|
-
//
|
|
296
|
-
//
|
|
297
|
-
//
|
|
298
|
-
//
|
|
299
|
-
|
|
300
|
-
//
|
|
301
|
-
//
|
|
302
|
-
|
|
303
|
-
//
|
|
304
|
-
//
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
//
|
|
308
|
-
//
|
|
309
|
-
//
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
//
|
|
313
|
-
//
|
|
314
|
-
|
|
315
|
-
|
|
308
|
+
// When this reference was attached (RFC 3339 / trimmed-UTC per HDF timestamp convention).
|
|
309
|
+
AddedAt *time.Time `json:"addedAt,omitempty"`
|
|
310
|
+
// Who attached this reference. Lightweight, flat attribution — a reference overrides
|
|
311
|
+
// nothing, so it has no chaining/superseding/disposition.
|
|
312
|
+
AddedBy *Identity `json:"addedBy,omitempty"`
|
|
313
|
+
// Integrity hash of the artifact. Reuses the HDF `Checksum` primitive (not STIX `hashes`).
|
|
314
|
+
// Applies both to an artifact retrievable at `href` and to one embedded here in `content`
|
|
315
|
+
// or `document` — beside embedded bytes it is what makes the copy verifiable rather than
|
|
316
|
+
// merely present.
|
|
317
|
+
Checksum *Checksum `json:"checksum,omitempty"`
|
|
318
|
+
// Optional lossless embedded copy of the artifact's bytes as a string, for artifacts
|
|
319
|
+
// `document` cannot hold: XML, CSV, NDJSON, plain text, a JSON array, or bytes that are not
|
|
320
|
+
// valid UTF-8 text at all.
|
|
321
|
+
//
|
|
322
|
+
// `encoding` states how to read it back and is required alongside it. Set `mediaType` so a
|
|
323
|
+
// consumer knows what the bytes are, and `checksum` so the copy can be verified against the
|
|
324
|
+
// source.
|
|
325
|
+
//
|
|
326
|
+
// Carried verbatim — never reformatted, re-indented, or re-serialized.
|
|
327
|
+
Content *string `json:"content,omitempty"`
|
|
328
|
+
// Human-readable description of what is referenced. Satisfies the at-least-one rule on its
|
|
329
|
+
// own when neither id nor href is available.
|
|
330
|
+
Description *string `json:"description,omitempty"`
|
|
331
|
+
// Optional lossless embedded copy of the referenced artifact as a JSON object — the raw
|
|
332
|
+
// STIX object, EPSS record, advisory, or annotation payload — preserved verbatim.
|
|
333
|
+
//
|
|
334
|
+
// JSON objects only. An artifact that is not a JSON object (XML, CSV, NDJSON, plain text, a
|
|
335
|
+
// JSON array, or bytes that are not text at all) embeds through `content` + `encoding`
|
|
336
|
+
// instead.
|
|
337
|
+
//
|
|
338
|
+
// Composes with `href`/`externalId` (which point at the artifact) and `checksum` (which
|
|
339
|
+
// ties the copy to the source): a single entry can both point and embed.
|
|
340
|
+
//
|
|
341
|
+
// HDF stays payload-agnostic — the content is carried untouched, never normalized into HDF
|
|
342
|
+
// fields — so this does not duplicate the source ontology (e.g. STIX rides here unchanged).
|
|
343
|
+
Document map[string]interface{} `json:"document,omitempty"`
|
|
344
|
+
// How to read `content` back into the artifact's bytes. 'utf-8' for text (XML, CSV, NDJSON,
|
|
345
|
+
// plain text, JavaScript-wrapped JSON); 'base64' for anything that is not valid UTF-8
|
|
346
|
+
// text.
|
|
347
|
+
//
|
|
348
|
+
// Required whenever `content` is present, and meaningless without it — an embedded copy
|
|
349
|
+
// whose encoding a consumer has to guess is not lossless.
|
|
350
|
+
Encoding *ExternalReferenceEncoding `json:"encoding,omitempty"`
|
|
351
|
+
// Identifier of the artifact within `sourceName` (e.g., 'CVE-2021-44228' for source 'cve',
|
|
352
|
+
// 'T1059' for 'mitre-att&ck'). Cite by id without needing a URL. Together with `sourceName`
|
|
353
|
+
// this is a URN.
|
|
354
|
+
ExternalID *string `json:"externalId,omitempty"`
|
|
355
|
+
// Location of the artifact. `uri-reference` (not `uri`) so a bare internal
|
|
356
|
+
// `#fragment`/`#uuid` reference is expressible alongside absolute URLs. Set it only when
|
|
357
|
+
// the location is meaningful to a reader — never a producer's local filesystem path.
|
|
358
|
+
Href *string `json:"href,omitempty"`
|
|
359
|
+
// Open token classifying the referenced/embedded payload, turning a bare reference into an
|
|
360
|
+
// enrichment envelope.
|
|
361
|
+
//
|
|
362
|
+
// Deliberately open (like `sourceName`/`rel`), not a closed enum.
|
|
363
|
+
//
|
|
364
|
+
// Documented starter vocabulary: 'threat-intel' (STIX/CTI object), 'annotation' (human
|
|
365
|
+
// triage note), 'exploitation' (EPSS/KEV signal carried as context), 'advisory'
|
|
366
|
+
// (vendor/security advisory).
|
|
367
|
+
//
|
|
368
|
+
// Use the `x-` prefix for custom kinds.
|
|
369
|
+
Kind *string `json:"kind,omitempty"`
|
|
370
|
+
// IANA media type of the artifact (RFC 6838), e.g., 'application/json', 'application/xml',
|
|
371
|
+
// 'text/csv'. Applies both to an artifact retrievable at `href` and to one embedded here in
|
|
372
|
+
// `content` or `document`.
|
|
373
|
+
MediaType *string `json:"mediaType,omitempty"`
|
|
374
|
+
// Open relationship token describing how this reference relates to the referencing object.
|
|
375
|
+
// Deliberately open (cf. OSCAL `rel` allow-other, RFC 8288 extension relations). Documented
|
|
376
|
+
// starter vocabulary: 'reference' (generic), 'definition' (defines the concept), 'evidence'
|
|
377
|
+
// (supporting evidence), 'investigate' (a live pivot to investigate), 'canonical' (the
|
|
378
|
+
// authoritative source).
|
|
379
|
+
Rel *string `json:"rel,omitempty"`
|
|
380
|
+
// Name of the external system/source being referenced (e.g., 'cve', 'mitre-att&ck', 'stix',
|
|
381
|
+
// 'taxii', or any vendor label). Open string — not a closed enum. Use the `x-` prefix
|
|
382
|
+
// convention for custom/experimental sources, mirroring `bomType`.
|
|
383
|
+
SourceName string `json:"sourceName"`
|
|
316
384
|
}
|
|
317
385
|
|
|
318
386
|
// Represents an identity that performed an action, such as capturing evidence or applying an
|
|
@@ -801,26 +869,82 @@ type Reference struct {
|
|
|
801
869
|
|
|
802
870
|
// A test within a requirement and its results and findings such as how long it took to run.
|
|
803
871
|
type RequirementResult struct {
|
|
804
|
-
// The stacktrace/backtrace of the exception if one occurred.
|
|
805
|
-
Backtrace
|
|
806
|
-
// A description of this test. Example: 'limits.conf * is expected to include ["hard",
|
|
807
|
-
// "maxlogins", "10"]'.
|
|
808
|
-
CodeDesc
|
|
809
|
-
// The type of exception if an exception was thrown.
|
|
810
|
-
Exception
|
|
811
|
-
// An explanation of the test result. Typically provided for failed tests, errors, or to
|
|
812
|
-
// explain why a test was not applicable or not reviewed.
|
|
813
|
-
Message
|
|
814
|
-
// The
|
|
815
|
-
|
|
816
|
-
//
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
872
|
+
// The stacktrace/backtrace of the exception if one occurred.
|
|
873
|
+
Backtrace []string `json:"backtrace,omitempty"`
|
|
874
|
+
// A description of this test. Example: 'limits.conf * is expected to include ["hard",
|
|
875
|
+
// "maxlogins", "10"]'.
|
|
876
|
+
CodeDesc string `json:"codeDesc"`
|
|
877
|
+
// The type of exception if an exception was thrown.
|
|
878
|
+
Exception *string `json:"exception,omitempty"`
|
|
879
|
+
// An explanation of the test result. Typically provided for failed tests, errors, or to
|
|
880
|
+
// explain why a test was not applicable or not reviewed.
|
|
881
|
+
Message *string `json:"message,omitempty"`
|
|
882
|
+
// The source tool's own record for this result, carrying every field the record had.
|
|
883
|
+
// Complete, not necessarily byte-exact: see Raw_Source_Record.content for the producer and
|
|
884
|
+
// consumer obligations, and extensions.rawSourceArtifacts[] when byte-exact carriage is
|
|
885
|
+
// required.
|
|
886
|
+
RawSourceRecord *RawSourceRecord `json:"rawSourceRecord,omitempty"`
|
|
887
|
+
// The resource used in the test. Example: 'file', 'command', 'service'.
|
|
888
|
+
Resource *string `json:"resource,omitempty"`
|
|
889
|
+
// The unique identifier of the resource. Example: '/etc/passwd'.
|
|
890
|
+
ResourceID *string `json:"resourceId,omitempty"`
|
|
891
|
+
// The execution time in seconds for the test.
|
|
892
|
+
RunTime *float64 `json:"runTime,omitempty"`
|
|
893
|
+
// The time at which the test started.
|
|
894
|
+
StartTime time.Time `json:"startTime"`
|
|
895
|
+
// The status of this test within the requirement. Example: 'failed'.
|
|
896
|
+
Status ResultStatus `json:"status"`
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
// The source tool's own record for this result — the one entry in the converter's input that
|
|
900
|
+
// produced it, complete though not necessarily byte-for-byte (see `content`). SCOPED TO THE RESULT
|
|
901
|
+
// DELIBERATELY. For a vulnerability scanner the native record is one (vulnerability, package) pair,
|
|
902
|
+
// which is exactly one result: a CVE reported against two packages yields two entries whose records
|
|
903
|
+
// differ only in the package they matched. Held on the requirement instead, those two records would
|
|
904
|
+
// collide, and merging entries that share an id would have to discard one — so the result is not
|
|
905
|
+
// merely an available home but the correct one. Distinct from `extensions.rawSourceArtifacts[]`,
|
|
906
|
+
// which carries whole input artifacts: this carries the one record inside one of them, and
|
|
907
|
+
// `pointer` ties the two together. A consumer that wants the whole input reads the artifact; one
|
|
908
|
+
// that wants provenance for a single finding reads this. Distinct from `code`, which means the code
|
|
909
|
+
// that ran to evaluate the requirement — an InSpec control's source, or a check reference. A
|
|
910
|
+
// serialized finding is not code, and putting one there overloaded a field whose meaning came from
|
|
911
|
+
// InSpec. CLOSED, and deliberately not a passthrough bag: three required members and an optional
|
|
912
|
+
// pointer are the whole of it. Producer data that HDF does not model belongs in
|
|
913
|
+
// `extensions.passthrough`, which is document-scoped and permissive by design; this field is
|
|
914
|
+
// neither. Closed with `additionalProperties` rather than the house `unevaluatedProperties` because
|
|
915
|
+
// this definition composes nothing, and the shipped Go validator is a draft-07 engine that does not
|
|
916
|
+
// implement `unevaluatedProperties` — a closure only one of the two validators enforces is not a
|
|
917
|
+
// closure.
|
|
918
|
+
type RawSourceRecord struct {
|
|
919
|
+
// The source tool's own record for this result, carrying every field the record had.
|
|
920
|
+
//
|
|
921
|
+
// COMPLETE, NOT NECESSARILY BYTE-EXACT. A producer SHOULD write the record's bytes
|
|
922
|
+
// unchanged where it can. A producer that cannot — notably one implemented in two languages
|
|
923
|
+
// whose JSON serializers disagree on key order, HTML escaping and number rendering, and
|
|
924
|
+
// which therefore MUST canonicalize to stay byte-identical with its twin — MAY write a
|
|
925
|
+
// canonically serialized form instead. Such a form preserves every field and value but not
|
|
926
|
+
// the original key order, insignificant whitespace, or duplicate keys. A consumer MUST
|
|
927
|
+
// therefore compare records by parsing them, not by comparing bytes, and MUST NOT checksum
|
|
928
|
+
// this field and expect the result to match a checksum of the input.
|
|
929
|
+
//
|
|
930
|
+
// For carriage that IS byte-exact, use `extensions.rawSourceArtifacts[]`, which forbids a
|
|
931
|
+
// parsed `document` precisely so the bytes and their checksum survive; `pointer` ties this
|
|
932
|
+
// record to its position within that artifact.
|
|
933
|
+
Content string `json:"content"`
|
|
934
|
+
// How to read `content`: 'utf-8' for text, 'base64' for bytes that are not valid UTF-8 text.
|
|
935
|
+
Encoding ExternalReferenceEncoding `json:"encoding"`
|
|
936
|
+
// The record's IANA media type — the type of this record, which for a fragment of a larger
|
|
937
|
+
// artifact may be narrower than the artifact's own. Example: 'application/json' for one
|
|
938
|
+
// match object out of a JSON report.
|
|
939
|
+
MediaType string `json:"mediaType"`
|
|
940
|
+
// Where this record sits inside the artifact it came from, as a JSON Pointer (RFC 6901) for
|
|
941
|
+
// JSON sources or an XPath for XML ones. Example: '/matches/3'.
|
|
942
|
+
//
|
|
943
|
+
// Optional, and the link that makes carriage verifiable rather than merely present: with it
|
|
944
|
+
// a consumer can confirm the record really is the subtree of
|
|
945
|
+
// `extensions.rawSourceArtifacts[]` it claims to be. Omit it when the source's shape gives
|
|
946
|
+
// a record no addressable location.
|
|
947
|
+
Pointer *string `json:"pointer,omitempty"`
|
|
824
948
|
}
|
|
825
949
|
|
|
826
950
|
// The explicit location of a requirement within source code.
|
|
@@ -1380,6 +1504,9 @@ type Tool struct {
|
|
|
1380
1504
|
type HDFBaseline struct {
|
|
1381
1505
|
// The set of dependencies this baseline depends on.
|
|
1382
1506
|
Depends []Dependency `json:"depends,omitempty"`
|
|
1507
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) this
|
|
1508
|
+
// baseline was converted from.
|
|
1509
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
1383
1510
|
// The tool that generated this file.
|
|
1384
1511
|
Generator *Generator `json:"generator,omitempty"`
|
|
1385
1512
|
// A set of descriptions for the requirement groups.
|
|
@@ -1493,47 +1620,48 @@ type BaselineRequirement struct {
|
|
|
1493
1620
|
// Structured comparison between two or more HDF security assessment documents. Supports temporal,
|
|
1494
1621
|
// baseline, fleet, and multi-source comparison modes.
|
|
1495
1622
|
type HDFComparison struct {
|
|
1496
|
-
// Map of annotation IDs to annotation objects, providing context or action items for
|
|
1497
|
-
// requirement diffs.
|
|
1498
|
-
Annotations map[string]Annotation
|
|
1499
|
-
// Comparison of baselines between sources.
|
|
1500
|
-
BaselineDiffs []BaselineDiff
|
|
1501
|
-
// The mode of comparison being performed.
|
|
1502
|
-
ComparisonMode ComparisonMode
|
|
1503
|
-
// Comparison of components between two system documents. Used in systemDrift mode. A
|
|
1504
|
-
// component's BOM changes surface as a field change on its boms[] here.
|
|
1505
|
-
ComponentDiffs []ComponentDiff
|
|
1506
|
-
// External/metadata changes separate from status changes (Terraform pattern).
|
|
1507
|
-
Drift []RequirementDiff
|
|
1508
|
-
//
|
|
1509
|
-
|
|
1510
|
-
|
|
1511
|
-
//
|
|
1512
|
-
|
|
1513
|
-
|
|
1514
|
-
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
//
|
|
1523
|
-
//
|
|
1524
|
-
//
|
|
1525
|
-
//
|
|
1526
|
-
|
|
1527
|
-
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
Summary
|
|
1533
|
-
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
|
-
|
|
1623
|
+
// Map of annotation IDs to annotation objects, providing context or action items for
|
|
1624
|
+
// requirement diffs.
|
|
1625
|
+
Annotations map[string]Annotation `json:"annotations,omitempty"`
|
|
1626
|
+
// Comparison of baselines between sources.
|
|
1627
|
+
BaselineDiffs []BaselineDiff `json:"baselineDiffs,omitempty"`
|
|
1628
|
+
// The mode of comparison being performed.
|
|
1629
|
+
ComparisonMode ComparisonMode `json:"comparisonMode"`
|
|
1630
|
+
// Comparison of components between two system documents. Used in systemDrift mode. A
|
|
1631
|
+
// component's BOM changes surface as a field change on its boms[] here.
|
|
1632
|
+
ComponentDiffs []ComponentDiff `json:"componentDiffs,omitempty"`
|
|
1633
|
+
// External/metadata changes separate from status changes (Terraform pattern).
|
|
1634
|
+
Drift []RequirementDiff `json:"drift,omitempty"`
|
|
1635
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) this
|
|
1636
|
+
// comparison was derived from.
|
|
1637
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
1638
|
+
// Optional references to external artifacts relevant to this comparison (CTI/STIX,
|
|
1639
|
+
// advisories, or any URI-addressable artifact). Inert context; see External_Reference.
|
|
1640
|
+
ExternalReferences []ExternalReference `json:"externalReferences,omitempty"`
|
|
1641
|
+
// Schema version for this comparison format.
|
|
1642
|
+
FormatVersion FormatVersion `json:"formatVersion"`
|
|
1643
|
+
// Information about the tool that generated this comparison.
|
|
1644
|
+
Generator *Generator `json:"generator,omitempty"`
|
|
1645
|
+
// Cryptographic integrity information for verifying this comparison document.
|
|
1646
|
+
Integrity *Integrity `json:"integrity,omitempty"`
|
|
1647
|
+
// Configuration for how requirements were matched across sources.
|
|
1648
|
+
Matching *MatchingConfig `json:"matching,omitempty"`
|
|
1649
|
+
// RESERVED — not emitted by the current systemDrift comparison. systemDrift now reports a
|
|
1650
|
+
// component's BOM changes as a field change on its boms[] (see componentDiffs), and
|
|
1651
|
+
// standalone SBOM package diffing is a separate `hdf diff <sbom> <sbom>` output shape. This
|
|
1652
|
+
// field is retained for a future normalized package-level diff; consumers must not expect
|
|
1653
|
+
// it from today's systemDrift output.
|
|
1654
|
+
PackageDiffs []PackageDiff `json:"packageDiffs,omitempty"`
|
|
1655
|
+
// Detailed comparison of individual requirements between sources.
|
|
1656
|
+
RequirementDiffs []RequirementDiff `json:"requirementDiffs"`
|
|
1657
|
+
// The source documents being compared. At least two sources are required.
|
|
1658
|
+
Sources []Source `json:"sources"`
|
|
1659
|
+
// Summary statistics for the overall comparison.
|
|
1660
|
+
Summary ComparisonSummary `json:"summary"`
|
|
1661
|
+
// URI identifying the system being compared in systemDrift mode.
|
|
1662
|
+
SystemRef *string `json:"systemRef,omitempty"`
|
|
1663
|
+
// When this comparison was performed.
|
|
1664
|
+
Timestamp *time.Time `json:"timestamp,omitempty"`
|
|
1537
1665
|
}
|
|
1538
1666
|
|
|
1539
1667
|
// An annotation attached to a comparison, providing context or action items.
|
|
@@ -1845,6 +1973,9 @@ type HDFSystem struct {
|
|
|
1845
1973
|
DataFlows []DataFlow `json:"dataFlows,omitempty"`
|
|
1846
1974
|
// Description of the system's purpose and mission.
|
|
1847
1975
|
Description *string `json:"description,omitempty"`
|
|
1976
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) this system
|
|
1977
|
+
// document was converted from.
|
|
1978
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
1848
1979
|
// Optional references to external artifacts describing this system's threat environment or
|
|
1849
1980
|
// context (CTI/STIX, BOMs, advisories, or any URI-addressable artifact). Inert context; see
|
|
1850
1981
|
// External_Reference.
|
|
@@ -1933,6 +2064,9 @@ type HDFPlan struct {
|
|
|
1933
2064
|
Assessments []Assessment `json:"assessments"`
|
|
1934
2065
|
// Description of the plan's purpose and scope.
|
|
1935
2066
|
Description *string `json:"description,omitempty"`
|
|
2067
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) this plan
|
|
2068
|
+
// was converted from.
|
|
2069
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
1936
2070
|
// Optional references to external artifacts relevant to this assessment plan (CTI/STIX,
|
|
1937
2071
|
// advisories, methodology docs, or any URI-addressable artifact). Inert context; see
|
|
1938
2072
|
// External_Reference.
|
|
@@ -2017,6 +2151,10 @@ type HDFAmendments struct {
|
|
|
2017
2151
|
ApprovedBy *Identity `json:"approvedBy,omitempty"`
|
|
2018
2152
|
// Description of the amendments' purpose and scope.
|
|
2019
2153
|
Description *string `json:"description,omitempty"`
|
|
2154
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) these
|
|
2155
|
+
// amendments were converted from — the VEX family and oscal-poam-to-hdf all emit this
|
|
2156
|
+
// document type.
|
|
2157
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
2020
2158
|
// Information about the tool that generated this document.
|
|
2021
2159
|
Generator *Generator `json:"generator,omitempty"`
|
|
2022
2160
|
// Cryptographic integrity information for verifying this amendments document has not been
|
|
@@ -2128,6 +2266,9 @@ type HDFEvidencePackage struct {
|
|
|
2128
2266
|
Contents []ContentReference `json:"contents"`
|
|
2129
2267
|
// Description of the evidence package's purpose and scope.
|
|
2130
2268
|
Description *string `json:"description,omitempty"`
|
|
2269
|
+
// Producer data outside the HDF model, and the pre-converted source artifact(s) this
|
|
2270
|
+
// package was assembled from.
|
|
2271
|
+
Extensions *Extensions `json:"extensions,omitempty"`
|
|
2131
2272
|
// References to external native-format evidence (log/telemetry corpora and other artifacts)
|
|
2132
2273
|
// carried by URI + integrity hash + format discriminator, without recreating the data
|
|
2133
2274
|
// inside HDF. Logs in ECS/OCSF/etc. are legitimate accreditation evidence; HDF indexes them
|
|
@@ -2193,17 +2334,27 @@ type SBOMCoverage struct {
|
|
|
2193
2334
|
|
|
2194
2335
|
// A reference to an HDF document or BOM/manifest included in the evidence package.
|
|
2195
2336
|
type ContentReference struct {
|
|
2196
|
-
// Cryptographic checksum for verifying the referenced document's integrity.
|
|
2197
|
-
Checksum
|
|
2198
|
-
// componentId of the component this content entry relates to. Use to link SBOMs, results,
|
|
2199
|
-
// or other documents to a specific system component.
|
|
2200
|
-
ComponentRef
|
|
2201
|
-
// Optional description of this content entry.
|
|
2202
|
-
Description
|
|
2203
|
-
// The type of HDF document being referenced.
|
|
2204
|
-
Type
|
|
2205
|
-
//
|
|
2206
|
-
|
|
2337
|
+
// Cryptographic checksum for verifying the referenced document's integrity.
|
|
2338
|
+
Checksum *Checksum `json:"checksum,omitempty"`
|
|
2339
|
+
// componentId of the component this content entry relates to. Use to link SBOMs, results,
|
|
2340
|
+
// or other documents to a specific system component.
|
|
2341
|
+
ComponentRef *string `json:"componentRef,omitempty"`
|
|
2342
|
+
// Optional description of this content entry.
|
|
2343
|
+
Description *string `json:"description,omitempty"`
|
|
2344
|
+
// The type of HDF document being referenced.
|
|
2345
|
+
Type ContentType `json:"type"`
|
|
2346
|
+
// A uri-reference whose DECODED form is a path relative to the package document's own
|
|
2347
|
+
// directory — that is what the reference MEANS, independently of any one consumer.
|
|
2348
|
+
// Percent-escapes are part of the encoding, not the name: `my%20scans/q4.json` and `my
|
|
2349
|
+
// scans/q4.json` name the same file, and the escaped spelling is the one this field's
|
|
2350
|
+
// format admits. A consumer decodes before it resolves, never after, because decoding can
|
|
2351
|
+
// produce a parent traversal that containment must then see. It is never fetched: there is
|
|
2352
|
+
// no network retrieval anywhere in evidence handling. `uri-reference` admits shapes other
|
|
2353
|
+
// than a relative path and they stay schema-valid; how a consumer resolves one, and what it
|
|
2354
|
+
// does when it cannot, is that consumer's own contract. An artifact deliberately held
|
|
2355
|
+
// elsewhere belongs in externalEvidence[], which references it by URI and checksum without
|
|
2356
|
+
// retrieving it.
|
|
2357
|
+
URI string `json:"uri"`
|
|
2207
2358
|
}
|
|
2208
2359
|
|
|
2209
2360
|
// A reference to external native-format evidence (log/telemetry corpus or other artifact) carried
|
|
@@ -2336,8 +2487,9 @@ const (
|
|
|
2336
2487
|
Username IdentityType = "username"
|
|
2337
2488
|
)
|
|
2338
2489
|
|
|
2339
|
-
//
|
|
2340
|
-
// container-image and other artifact digests that use it.
|
|
2490
|
+
// Cryptographic hash algorithms a checksum or integrity record may name. blake3 covers
|
|
2491
|
+
// container-image and other artifact digests that use it. HDF tooling verifies every algorithm in
|
|
2492
|
+
// this enum, so any of them may be recorded where the checksum needs to be verifiable.
|
|
2341
2493
|
type HashAlgorithm string
|
|
2342
2494
|
|
|
2343
2495
|
const (
|
|
@@ -2347,6 +2499,21 @@ const (
|
|
|
2347
2499
|
Sha512 HashAlgorithm = "sha512"
|
|
2348
2500
|
)
|
|
2349
2501
|
|
|
2502
|
+
// How to read `content` back into the artifact's bytes. 'utf-8' for text (XML, CSV, NDJSON,
|
|
2503
|
+
// plain text, JavaScript-wrapped JSON); 'base64' for anything that is not valid UTF-8
|
|
2504
|
+
// text.
|
|
2505
|
+
//
|
|
2506
|
+
// Required whenever `content` is present, and meaningless without it — an embedded copy
|
|
2507
|
+
// whose encoding a consumer has to guess is not lossless.
|
|
2508
|
+
//
|
|
2509
|
+
// How to read `content`: 'utf-8' for text, 'base64' for bytes that are not valid UTF-8 text.
|
|
2510
|
+
type ExternalReferenceEncoding string
|
|
2511
|
+
|
|
2512
|
+
const (
|
|
2513
|
+
Base64 ExternalReferenceEncoding = "base64"
|
|
2514
|
+
UTF8 ExternalReferenceEncoding = "utf-8"
|
|
2515
|
+
)
|
|
2516
|
+
|
|
2350
2517
|
// Comparison operator for evaluating the input value against observed values. Numeric:
|
|
2351
2518
|
// eq/ne/lt/le/gt/ge. String: eq/ne/contains/matches. Collection: in/notIn.
|
|
2352
2519
|
type ComparisonOperator string
|