@mitre/hdf-engine 3.7.1-rc.1 → 3.7.2-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.
- package/README.md +12 -7
- package/dist/index.d.ts +449 -92
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +854 -77
- package/dist/index.js.map +1 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -53,8 +53,8 @@ const matches = filter(results, {
|
|
|
53
53
|
|
|
54
54
|
```go
|
|
55
55
|
matches := hdfengine.Filter(ctx, results, hdfengine.Options{
|
|
56
|
-
Status:
|
|
57
|
-
Severity:
|
|
56
|
+
Status: hdfengine.In("failed"),
|
|
57
|
+
Severity: hdfengine.In("critical", "high"),
|
|
58
58
|
})
|
|
59
59
|
```
|
|
60
60
|
|
|
@@ -137,20 +137,25 @@ The `fetch` function is supplied by the caller, so this package never reads the
|
|
|
137
137
|
### Query
|
|
138
138
|
|
|
139
139
|
- `filter(results, options)` / `Filter(ctx, results, opts)` — matching requirements
|
|
140
|
-
- `FilterOptions` / `Options` — `status`, `severity`, `impact`, `cci`, `nist`, `id`, `tag`, `search`, `baseline`, `limit`, `count`, and a `statusOf` hook to override how status is resolved
|
|
140
|
+
- `FilterOptions` / `Options` — `status`, `severity`, `impact`, `rawImpact`, `cvss`, `epss`, `kev`, `cwe`, `cci`, `nist`, `id`, `tag`, `search`, `baseline`, `baselineLabel`, `disposition`, `poams`, `poamType`, `now`, `limit`, `count`, and a `statusOf` hook to override how status is resolved
|
|
141
141
|
- `Match` — one result row
|
|
142
142
|
|
|
143
143
|
### Compliance
|
|
144
144
|
|
|
145
145
|
- `countControlsByStatusSeverity` / `CountControlsByStatusSeverity` — counts by status and severity
|
|
146
|
-
- `countControlsByStatus` / `CountControlsByStatus` — counts with a caller-supplied status resolver
|
|
146
|
+
- `countControlsByStatus` / `CountControlsByStatus` — counts with a caller-supplied status resolver; an optional `now` (TypeScript) or `CountControlsByStatusAt` (Go) judges override expiry at a reference time instead of the clock
|
|
147
147
|
- `calculateCompliance` / `CalculateCompliance` — the percentage
|
|
148
148
|
- `deriveSeverity` / `DeriveSeverity` — a requirement's severity, explicit or derived from impact
|
|
149
|
+
- `filterValues`, `filterAliases`, `advertisedFilterValues` / `FilterValues`, `FilterAliases`, `AdvertisedFilterValues` — a field's closed vocabulary, the non-canonical forms accepted for it, and the subset a help string or tool schema should NAME. Each alias carries `advertise`: a separator variant of the canonical name is taught, a name a release retired is honoured and never taught. Callers build help text from these rather than keeping their own list
|
|
150
|
+
- `severityBucket` / `SeverityBucket` — the counting bucket a severity falls in; anything outside the schema enum lands in `informational`, so a caller assembling its own control map buckets the way the counts do
|
|
149
151
|
- `overallStatus` (TypeScript only) — the worst status across a requirement's results; the Go peer is internal to the package
|
|
150
|
-
- `mapControlIDs`, `mapControlIDsByStatus` / `MapControlIDs`, `MapControlIDsByStatus` — control id to status
|
|
152
|
+
- `mapControlIDs`, `mapControlIDsByStatus` / `MapControlIDs`, `MapControlIDsByStatus` — control id to status and severity bucket; `mapControlIDsByStatus` takes the same optional `now`, and Go has `MapControlIDsByStatusAt`
|
|
151
153
|
- `agentOverrideCount` / `AgentOverrideCount` — overrides attributed to an agent
|
|
152
|
-
- `validateThresholds` / `ValidateThresholds` — threshold verdicts
|
|
153
|
-
- `
|
|
154
|
+
- `validateThresholds` / `ValidateThresholds` — threshold verdicts over the grid bounds alone
|
|
155
|
+
- `evaluateRules` / `EvaluateRules`, `EvaluateRulesContext` — rule verdicts: each `rules:` entry is a filter predicate plus a bound. The Go context variant stops filtering on cancellation and returns what it had, so a caller checks `ctx.Err()` before treating the result as a verdict
|
|
156
|
+
- `evaluate` / `Evaluate`, `EvaluateContext` — the grid bounds and the rules in one verdict, as `hdf validate threshold` applies them
|
|
157
|
+
- `NewThresholdInput`, `NewThresholdInputAt` (Go only) — the counts, control map and status resolver a verdict needs; the `At` form judges override expiry at a reference time, which the rules half then shares
|
|
158
|
+
- `StatusCounts`, `SeverityCounts`, `ControlIDMapping`, `ThresholdConfig`, `ThresholdSeverity`, `ThresholdBound`, `ComplianceBound`, `ThresholdRule`, `RulePredicate`, `RuleOptions`, `ThresholdInput`, `Violation`
|
|
154
159
|
|
|
155
160
|
### Merge
|
|
156
161
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
+
import { StatusOverrideInput } from "@mitre/hdf-utilities";
|
|
1
2
|
import { EvaluatedRequirement, HDFBaseline, HDFResults, RequirementResult, Severity } from "@mitre/hdf-schema";
|
|
2
3
|
//#region src/version.d.ts
|
|
3
|
-
export declare const engineVersion = "3.7.
|
|
4
|
+
export declare const engineVersion = "3.7.2";
|
|
4
5
|
//#endregion
|
|
5
6
|
//#region src/merge.d.ts
|
|
6
7
|
/** One input to merge: a results document and the name it is recorded under. */
|
|
@@ -44,6 +45,92 @@ type HdfDocType = 'results' | 'baseline' | 'system' | 'plan' | 'amendments' | 'e
|
|
|
44
45
|
*/
|
|
45
46
|
export declare function detect(input: string): HdfDocType;
|
|
46
47
|
//#endregion
|
|
48
|
+
//#region src/values.d.ts
|
|
49
|
+
/**
|
|
50
|
+
* A predicate field's value set, and the normalizer that accepts the three
|
|
51
|
+
* spellings a policy may use for it: a bare scalar for the common single-value
|
|
52
|
+
* case, a list, and a `{not: [...]}` object for exclusion.
|
|
53
|
+
*
|
|
54
|
+
* Negation is PURE: `not` means "does not match any of these", and a requirement
|
|
55
|
+
* whose field is ABSENT satisfies it. The alternative — requiring the field to
|
|
56
|
+
* be present — silently weakens gates, because the requirement a gate most needs
|
|
57
|
+
* to catch is usually the one nobody has touched. `{status: [failed],
|
|
58
|
+
* disposition: {not: [waiver]}}` with `max: 0` must catch a failure nobody
|
|
59
|
+
* adjudicated; under a presence-requiring reading that requirement is excluded
|
|
60
|
+
* and the bound passes.
|
|
61
|
+
*
|
|
62
|
+
* Parity: Values in go/values.go.
|
|
63
|
+
*/
|
|
64
|
+
/**
|
|
65
|
+
* What a policy may write for a multi-value field: a scalar, a list, or a
|
|
66
|
+
* {not: [...]} object. Normalized to Values before it reaches a matcher.
|
|
67
|
+
*/
|
|
68
|
+
type PredicateValue = string | string[] | {
|
|
69
|
+
not: string | string[];
|
|
70
|
+
};
|
|
71
|
+
//#endregion
|
|
72
|
+
//#region src/vocabulary.d.ts
|
|
73
|
+
/**
|
|
74
|
+
* The closed vocabulary a status filter may name: the schema's Result_Status
|
|
75
|
+
* enum. It is the EFFECTIVE status that is compared — the resolver a caller
|
|
76
|
+
* injects runs the override ladder first — so these are the values a requirement
|
|
77
|
+
* can present after its amendments are applied.
|
|
78
|
+
*/
|
|
79
|
+
export declare const STATUS_VALUES: readonly ["passed", "failed", "notApplicable", "notReviewed", "error"];
|
|
80
|
+
/** The schema's Severity enum, which is also what deriveSeverity returns. */
|
|
81
|
+
export declare const SEVERITY_VALUES: readonly ["critical", "high", "medium", "low", "informational"];
|
|
82
|
+
/**
|
|
83
|
+
* The forms a value has legitimately arrived under, enumerated rather than
|
|
84
|
+
* derived. An earlier version stripped separators to fold them together, which
|
|
85
|
+
* also silently repaired typos: 'wai-ver' became 'waiver'. A closed vocabulary
|
|
86
|
+
* that quietly corrects a misspelling is not closed.
|
|
87
|
+
*
|
|
88
|
+
* The status and disposition entries are separator variants of one name. The
|
|
89
|
+
* severity entry is not: 3.7.0 renamed the bucket, and 'none' is the name it had
|
|
90
|
+
* before, kept so a command line or spec written against the old vocabulary
|
|
91
|
+
* selects what it always did.
|
|
92
|
+
*/
|
|
93
|
+
/**
|
|
94
|
+
* `advertise` records which forms help text should TEACH, so that is a property of
|
|
95
|
+
* the entry rather than of whichever string literal a command happens to hold. A
|
|
96
|
+
* separator variant is part of the CLI's display vocabulary and is taught; a
|
|
97
|
+
* retired name is honoured and never taught, because advertising it would hand a
|
|
98
|
+
* new user the name a release replaced. Parity: FilterAlias in go/vocabulary.go.
|
|
99
|
+
*/
|
|
100
|
+
interface FilterAlias {
|
|
101
|
+
form: string;
|
|
102
|
+
means: string;
|
|
103
|
+
advertise: boolean;
|
|
104
|
+
}
|
|
105
|
+
/** The accepted non-canonical forms for a field, or undefined when it has no closed vocabulary. */
|
|
106
|
+
export declare function filterAliases(field: string): FilterAlias[] | undefined;
|
|
107
|
+
/** The canonical vocabulary for a field, or undefined when it has no closed one. */
|
|
108
|
+
export declare function filterValues(field: string): readonly string[] | undefined;
|
|
109
|
+
/**
|
|
110
|
+
* The forms a help string or tool schema should name for a field: the canonical
|
|
111
|
+
* vocabulary, then the aliases marked for teaching. Every value here is accepted,
|
|
112
|
+
* but not everything accepted is here — a retired name is deliberately absent.
|
|
113
|
+
* Parity: AdvertisedFilterValues in go/vocabulary.go.
|
|
114
|
+
*/
|
|
115
|
+
export declare function advertisedFilterValues(field: string): string[] | undefined;
|
|
116
|
+
/**
|
|
117
|
+
* Folds a value to the form comparisons use. Case only: two spellings are the
|
|
118
|
+
* same value because this file says so, not because enough punctuation was
|
|
119
|
+
* removed to make them collide.
|
|
120
|
+
*/
|
|
121
|
+
export declare function normalizeKey(s: string): string;
|
|
122
|
+
/** Whether s names a status the filter understands, in any accepted form. */
|
|
123
|
+
export declare function validStatus(s: string): boolean;
|
|
124
|
+
/** Whether s names a severity the filter understands, in any accepted form. */
|
|
125
|
+
export declare function validSeverity(s: string): boolean;
|
|
126
|
+
/**
|
|
127
|
+
* The canonical form of a filter value for the named field, or the value
|
|
128
|
+
* unchanged when the field has no closed vocabulary or the value names no
|
|
129
|
+
* member. Normalizing here rather than in one caller is what makes a threshold
|
|
130
|
+
* rule and an `hdf query` invocation mean the same thing.
|
|
131
|
+
*/
|
|
132
|
+
export declare function normalizeFilterValue(field: string, value: string): string;
|
|
133
|
+
//#endregion
|
|
47
134
|
//#region src/query.d.ts
|
|
48
135
|
/**
|
|
49
136
|
* FilterOptions configures a requirements query. Every filter input arrives here;
|
|
@@ -52,15 +139,80 @@ export declare function detect(input: string): HdfDocType;
|
|
|
52
139
|
* agnostic to the caller's status-string convention (undefined → empty status).
|
|
53
140
|
*/
|
|
54
141
|
interface FilterOptions {
|
|
55
|
-
status?:
|
|
56
|
-
severity?:
|
|
142
|
+
status?: PredicateValue;
|
|
143
|
+
severity?: PredicateValue;
|
|
144
|
+
/**
|
|
145
|
+
* Compares the EFFECTIVE impact — the governing non-expired impact override's
|
|
146
|
+
* value, else the requirement's own.
|
|
147
|
+
*/
|
|
57
148
|
impact?: string;
|
|
58
|
-
|
|
59
|
-
|
|
149
|
+
/**
|
|
150
|
+
* Compares the requirement's own impact, ignoring overrides. It exists because
|
|
151
|
+
* impact resolves them: the governance policy "an override may not move a
|
|
152
|
+
* critical below 0.7" needs both scores, and no other key reaches the
|
|
153
|
+
* unadjusted one.
|
|
154
|
+
*/
|
|
155
|
+
rawImpact?: string;
|
|
156
|
+
/**
|
|
157
|
+
* Compares the requirement's authoritative CVSS score, using the same
|
|
158
|
+
* comparison grammar as impact. See cvssScoreOf for what "authoritative"
|
|
159
|
+
* resolves to and how several CVSS entries collapse to one number.
|
|
160
|
+
*/
|
|
161
|
+
cvss?: string;
|
|
162
|
+
/**
|
|
163
|
+
* Compares the EPSS exploit PROBABILITY (epss.score), not the percentile
|
|
164
|
+
* rank. They share a 0-1 scale and mean very different things.
|
|
165
|
+
*/
|
|
166
|
+
epss?: string;
|
|
167
|
+
/**
|
|
168
|
+
* CISA Known Exploited Vulnerabilities membership: 'true' for kev.inKev,
|
|
169
|
+
* 'false' for everything else — including a requirement carrying no kev block
|
|
170
|
+
* at all, which is not known-exploited either.
|
|
171
|
+
*/
|
|
172
|
+
kev?: string;
|
|
173
|
+
/**
|
|
174
|
+
* Selects by CWE identifier, OR across values, matched numerically so CWE-79,
|
|
175
|
+
* 'CWE 79' and cwe79 are one value. Reads the first-class cwe[] field ONLY and
|
|
176
|
+
* never falls back to tags.cwe.
|
|
177
|
+
*/
|
|
178
|
+
cwe?: PredicateValue;
|
|
179
|
+
cci?: PredicateValue;
|
|
180
|
+
nist?: PredicateValue;
|
|
60
181
|
id?: string;
|
|
61
|
-
tag?:
|
|
182
|
+
tag?: PredicateValue;
|
|
62
183
|
search?: string;
|
|
63
184
|
baseline?: string;
|
|
185
|
+
/**
|
|
186
|
+
* Selects requirements by the labels of the baseline they sit in, as
|
|
187
|
+
* `key:value`, OR across values, with the value globbable exactly as a tag
|
|
188
|
+
* value is. Named for the baseline rather than `label` alone because there is
|
|
189
|
+
* no requirement-level label, and because system documents carry component
|
|
190
|
+
* labels that may one day want their own key.
|
|
191
|
+
*
|
|
192
|
+
* A label is a property of the BASELINE, so this is applied once per baseline
|
|
193
|
+
* beside `baseline` rather than per requirement. A baseline carrying no labels
|
|
194
|
+
* therefore matches nothing: an absent label is not a wildcard.
|
|
195
|
+
* Parity: Options.BaselineLabel in go/filter.go.
|
|
196
|
+
*/
|
|
197
|
+
baselineLabel?: PredicateValue;
|
|
198
|
+
/**
|
|
199
|
+
* The TYPE of the override that governs the requirement (waiver,
|
|
200
|
+
* falsePositive, riskAdjustment, …), OR across values. The governing override
|
|
201
|
+
* is the most recent non-expired one of ANY kind, so it may differ from the one
|
|
202
|
+
* that set the status — see governingDisposition. Resolved rather than read
|
|
203
|
+
* from the stored disposition field, which is an output cache.
|
|
204
|
+
*/
|
|
205
|
+
disposition?: PredicateValue;
|
|
206
|
+
/**
|
|
207
|
+
* Remediation-plan validity: 'valid' for a requirement carrying a POA&M still
|
|
208
|
+
* in force, 'none-valid' for one carrying none, an empty list, or only lapsed
|
|
209
|
+
* ones. Absence and expiry are one concept on purpose.
|
|
210
|
+
*/
|
|
211
|
+
poams?: string;
|
|
212
|
+
/** Kind of the governing POA&M: remediation|mitigation|riskAcceptance|vendorDependency. */
|
|
213
|
+
poamType?: PredicateValue;
|
|
214
|
+
/** RFC3339 reference clock for expiry; undefined means now. */
|
|
215
|
+
now?: string;
|
|
64
216
|
limit?: number;
|
|
65
217
|
count?: boolean;
|
|
66
218
|
statusOf?: (control: EvaluatedRequirement) => string;
|
|
@@ -87,92 +239,21 @@ interface Match {
|
|
|
87
239
|
* options. Applies to requirement collections (results/baseline documents); the
|
|
88
240
|
* calling adapter rejects document types that carry no requirements.
|
|
89
241
|
*/
|
|
90
|
-
export declare function filter(results: HDFResults,
|
|
242
|
+
export declare function filter(results: HDFResults, rawOptions: FilterOptions): Match[];
|
|
91
243
|
//#endregion
|
|
92
|
-
//#region src/
|
|
93
|
-
/** Wire encoding of loader input (parity with Go InputFormat). */
|
|
94
|
-
type InputFormat = 'json' | 'ndjson';
|
|
95
|
-
interface LoadResult {
|
|
96
|
-
format: InputFormat;
|
|
97
|
-
docType: HdfDocType;
|
|
98
|
-
results?: HDFResults;
|
|
99
|
-
baseline?: HDFBaseline;
|
|
100
|
-
/** Non-empty when detected as results/baseline but the parse/validate failed. */
|
|
101
|
-
parseError?: string;
|
|
102
|
-
valid: boolean;
|
|
103
|
-
}
|
|
244
|
+
//#region src/effective.d.ts
|
|
104
245
|
/**
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
* (JSON vs NDJSON), document-type detection (detect), then the canonical
|
|
108
|
-
* hdf-parsers parse for the results and baseline types. Other types are
|
|
109
|
-
* detected but not parsed here.
|
|
246
|
+
* Maps a requirement's schema overrides onto the shared helper's neutral shape,
|
|
247
|
+
* whose timestamps are the RFC3339 strings the schema's Date fields came from.
|
|
110
248
|
*/
|
|
111
|
-
export declare function
|
|
249
|
+
export declare function overrideInputs(control: EvaluatedRequirement): StatusOverrideInput[];
|
|
112
250
|
/**
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
251
|
+
* The requirement's impact after its governing non-expired impact override, else
|
|
252
|
+
* its own. Computed rather than injected the way status is, because impact has
|
|
253
|
+
* no competing display conventions to reconcile — the ladder in hdf-utilities is
|
|
254
|
+
* canonical. An undefined reference means now.
|
|
117
255
|
*/
|
|
118
|
-
export declare function
|
|
119
|
-
//#endregion
|
|
120
|
-
//#region src/evidence.d.ts
|
|
121
|
-
/** Classifies a single content entry's checksum verification. */
|
|
122
|
-
type ChecksumStatus = 'match' | 'mismatch' | 'skipped' | 'error';
|
|
123
|
-
/** One content entry of an evidence package: a referenced document and its
|
|
124
|
-
* recorded checksum ('' when the entry carries none). */
|
|
125
|
-
interface EvidenceContent {
|
|
126
|
-
uri: string;
|
|
127
|
-
type: string;
|
|
128
|
-
checksum: string;
|
|
129
|
-
}
|
|
130
|
-
/** The verification outcome for one content entry. */
|
|
131
|
-
interface ChecksumResult {
|
|
132
|
-
uri: string;
|
|
133
|
-
type: string;
|
|
134
|
-
status: ChecksumStatus;
|
|
135
|
-
expected?: string;
|
|
136
|
-
actual?: string;
|
|
137
|
-
error?: string;
|
|
138
|
-
}
|
|
139
|
-
/** Reports which planned baselines are covered by results. */
|
|
140
|
-
interface CompletenessResult {
|
|
141
|
-
planned: string[];
|
|
142
|
-
covered: string[];
|
|
143
|
-
missing: string[];
|
|
144
|
-
complete: boolean;
|
|
145
|
-
}
|
|
146
|
-
/** Resolves a content URI to its bytes. The caller owns path confinement
|
|
147
|
-
* (HDF_MCP_ROOT for the MCP, the package directory for the CLI). Throws when the
|
|
148
|
-
* uri cannot be read. */
|
|
149
|
-
type FetchFn = (uri: string) => Uint8Array;
|
|
150
|
-
/** Extracts the planRef and content entries from an evidence-package document. */
|
|
151
|
-
export declare function parseEvidencePackage(pkg: string): {
|
|
152
|
-
planRef: string;
|
|
153
|
-
contents: EvidenceContent[];
|
|
154
|
-
};
|
|
155
|
-
/** Verifies each content entry's sha256 against fetch(uri), preserving entry
|
|
156
|
-
* order. No checksum → skipped; a fetch throw → error; hash mismatch → mismatch
|
|
157
|
-
* (carrying expected+actual). */
|
|
158
|
-
export declare function verifyChecksums(contents: EvidenceContent[], fetch: FetchFn): ChecksumResult[];
|
|
159
|
-
/** Extracts assessment baselineRefs from a plan document, deduped in first-seen
|
|
160
|
-
* order. */
|
|
161
|
-
export declare function plannedBaselineRefs(plan: string): string[];
|
|
162
|
-
/** Extracts baseline names from a results document, deduped in first-seen order. */
|
|
163
|
-
export declare function coveredBaselineNames(results: string): string[];
|
|
164
|
-
/** Concatenates the covered baseline names of every hdf-results document the
|
|
165
|
-
* package references, in entry order. An entry that cannot be fetched or parsed
|
|
166
|
-
* is skipped: checksum verification is what reports a read failure, and a
|
|
167
|
-
* partial coverage list is what the completeness diff needs. */
|
|
168
|
-
export declare function coveredBaselinesInPackage(contents: EvidenceContent[], fetch: FetchFn): string[];
|
|
169
|
-
/** Sums the agent-attributed override count across every hdf-results document
|
|
170
|
-
* the package references. Unreadable or unparseable entries are skipped. */
|
|
171
|
-
export declare function agentOverridesInPackage(contents: EvidenceContent[], fetch: FetchFn): number;
|
|
172
|
-
/** Diffs planned baseline refs against covered baseline names. A planned ref is
|
|
173
|
-
* covered when some results baseline shares its name. Missing is sorted so the
|
|
174
|
-
* outcome is deterministic across languages and runs. */
|
|
175
|
-
export declare function completeness(planned: string[], covered: string[]): CompletenessResult;
|
|
256
|
+
export declare function effectiveImpactOf(control: EvaluatedRequirement, now?: string): number;
|
|
176
257
|
//#endregion
|
|
177
258
|
//#region src/compliance.d.ts
|
|
178
259
|
interface SeverityCounts {
|
|
@@ -194,7 +275,21 @@ interface StatusCounts {
|
|
|
194
275
|
interface ControlIDMapping {
|
|
195
276
|
id: string;
|
|
196
277
|
status: string;
|
|
278
|
+
/**
|
|
279
|
+
* The counting BUCKET, not the requirement's raw severity string: always one
|
|
280
|
+
* of `critical`, `high`, `medium`, `low`, `informational`, having gone through
|
|
281
|
+
* severityBucket. Anything else would name a bucket the counts do not have,
|
|
282
|
+
* and a bound listing the control would report a mismatch against the bucket
|
|
283
|
+
* that control was counted in.
|
|
284
|
+
*/
|
|
197
285
|
severity: string;
|
|
286
|
+
/**
|
|
287
|
+
* The requirement's title when it has one, carried so a breached count bound
|
|
288
|
+
* can name its offenders the way a rule violation does. A reader should not
|
|
289
|
+
* have to know which kind of bound produced a line to know whether it will be
|
|
290
|
+
* readable. Parity: ControlIDMapping.Title in go/compliance.go.
|
|
291
|
+
*/
|
|
292
|
+
title?: string;
|
|
198
293
|
}
|
|
199
294
|
interface ThresholdBound {
|
|
200
295
|
min?: number;
|
|
@@ -207,7 +302,7 @@ interface ThresholdSeverity {
|
|
|
207
302
|
medium?: ThresholdBound;
|
|
208
303
|
low?: ThresholdBound;
|
|
209
304
|
informational?: ThresholdBound;
|
|
210
|
-
/**
|
|
305
|
+
/** The name `informational` replaced in 3.7.0; resolved on read, never written. */
|
|
211
306
|
none?: ThresholdBound;
|
|
212
307
|
total?: ThresholdBound;
|
|
213
308
|
}
|
|
@@ -222,6 +317,11 @@ interface ThresholdConfig {
|
|
|
222
317
|
skipped?: ThresholdSeverity;
|
|
223
318
|
error?: ThresholdSeverity;
|
|
224
319
|
noImpact?: ThresholdSeverity;
|
|
320
|
+
/**
|
|
321
|
+
* The additive half: a filter predicate plus a bound, for the policies the
|
|
322
|
+
* fixed grid above cannot express. See rules.ts.
|
|
323
|
+
*/
|
|
324
|
+
rules?: ThresholdRule[];
|
|
225
325
|
}
|
|
226
326
|
/**
|
|
227
327
|
* overallStatus is the canonical worst-wins roll-up of a requirement's result
|
|
@@ -237,7 +337,23 @@ export declare function overallStatus(results: RequirementResult[]): string;
|
|
|
237
337
|
* thing and must not land in different buckets.
|
|
238
338
|
*/
|
|
239
339
|
export declare function deriveSeverity(impact: number, severity?: Severity | null): string;
|
|
240
|
-
/**
|
|
340
|
+
/**
|
|
341
|
+
* severityBucket folds a severity string into the bucket the threshold grid
|
|
342
|
+
* counts it in. The schema's four named levels pass through; informational and
|
|
343
|
+
* anything outside the enum land in informational, so a malformed severity is
|
|
344
|
+
* counted rather than dropped and a document still gates.
|
|
345
|
+
*
|
|
346
|
+
* Exported because ControlIDMapping.severity is the bucket, not the raw string:
|
|
347
|
+
* a caller assembling its own control map has to apply the same rule or its
|
|
348
|
+
* listing and its counts will disagree. Parity: SeverityBucket in
|
|
349
|
+
* go/compliance.go.
|
|
350
|
+
*/
|
|
351
|
+
export declare function severityBucket(severity: string): string;
|
|
352
|
+
/**
|
|
353
|
+
* countControlsByStatusSeverity counts requirements by overall status and severity.
|
|
354
|
+
* Reads each requirement's OWN impact and raw result statuses by design: this is the
|
|
355
|
+
* no-override-awareness twin of countControlsByStatus, which is its purpose.
|
|
356
|
+
*/
|
|
241
357
|
export declare function countControlsByStatusSeverity(results: HDFResults): StatusCounts;
|
|
242
358
|
/**
|
|
243
359
|
* countControlsByStatus counts requirements by a caller-resolved status — the
|
|
@@ -249,7 +365,7 @@ export declare function countControlsByStatusSeverity(results: HDFResults): Stat
|
|
|
249
365
|
* (e.g. compliance with and without agent-attributed overrides) without the
|
|
250
366
|
* engine binding to any one status convention. Parity: go/compliance.go.
|
|
251
367
|
*/
|
|
252
|
-
export declare function countControlsByStatus(results: HDFResults, statusOf?: (req: EvaluatedRequirement) => string): StatusCounts;
|
|
368
|
+
export declare function countControlsByStatus(results: HDFResults, statusOf?: (req: EvaluatedRequirement) => string, now?: string): StatusCounts;
|
|
253
369
|
/**
|
|
254
370
|
* agentOverrideCount counts the status overrides across a result set whose
|
|
255
371
|
* applied-by identity type is "agent" — the detective count. Deterministic
|
|
@@ -268,17 +384,258 @@ export declare function mapControlIDs(results: HDFResults): ControlIDMapping[];
|
|
|
268
384
|
* listings (the same injection pattern as countControlsByStatus). Parity:
|
|
269
385
|
* go/compliance.go MapControlIDsByStatus.
|
|
270
386
|
*/
|
|
271
|
-
export declare function mapControlIDsByStatus(results: HDFResults, statusOf?: (req: EvaluatedRequirement) => string): ControlIDMapping[];
|
|
387
|
+
export declare function mapControlIDsByStatus(results: HDFResults, statusOf?: (req: EvaluatedRequirement) => string, now?: string): ControlIDMapping[];
|
|
388
|
+
/**
|
|
389
|
+
* normalizeThresholdConfig folds SAF's scalar count bound into the object form a
|
|
390
|
+
* bound is otherwise written in: a bare `total: 19` means EXACTLY 19, measured in
|
|
391
|
+
* SAF's own validate-threshold command, which guards the scalar path with
|
|
392
|
+
* `typeof !== 'object'` and then fails on inequality.
|
|
393
|
+
*
|
|
394
|
+
* Go reaches this rule through ThresholdBound's YAML decoding; TypeScript does no
|
|
395
|
+
* YAML decoding of its own, so a consumer that parsed a SAF file itself calls
|
|
396
|
+
* this before evaluating. Both are pinned by testdata/saf-bound-shorthand-cases.json.
|
|
397
|
+
* The input is not mutated.
|
|
398
|
+
*/
|
|
399
|
+
export declare function normalizeThresholdConfig(config: ThresholdConfig): ThresholdConfig;
|
|
400
|
+
/**
|
|
401
|
+
* addCounts sums count sets bucket by bucket and severity by severity, returning
|
|
402
|
+
* a new set and leaving its arguments untouched — a caller that reports the parts
|
|
403
|
+
* beside the whole is summing the very objects it still has to print. Each
|
|
404
|
+
* bucket's `total` is added, never recomputed from the severity fields.
|
|
405
|
+
*
|
|
406
|
+
* The counting functions above measure one document at a time, so a caller that
|
|
407
|
+
* composes documents — the HTML report rolling baselines into a source and
|
|
408
|
+
* sources into a whole, each evaluated as of its own assessment time — needs this
|
|
409
|
+
* rather than a second counting pass. Combining whole DOCUMENTS is merge's job,
|
|
410
|
+
* not this function's (ADR-0016 §1). Parity: AddCounts in go/compliance.go,
|
|
411
|
+
* pinned by testdata/status-counts-rollup-cases.json.
|
|
412
|
+
*/
|
|
413
|
+
export declare function addCounts(...counts: StatusCounts[]): StatusCounts;
|
|
414
|
+
/**
|
|
415
|
+
* severityTotals projects a count set onto severity alone, summing each severity
|
|
416
|
+
* across every status — so `total` is the whole set's requirement count. A
|
|
417
|
+
* severity breakdown answers "how much risk is in this document", which is a
|
|
418
|
+
* question about all of it, not about its failures. Parity: SeverityTotals in
|
|
419
|
+
* go/compliance.go.
|
|
420
|
+
*/
|
|
421
|
+
export declare function severityTotals(counts: StatusCounts): SeverityCounts;
|
|
272
422
|
/**
|
|
273
423
|
* calculateCompliance returns the compliance percentage rounded to two decimals:
|
|
274
424
|
* passed / (passed + failed + skipped + error) * 100; notApplicable excluded.
|
|
275
425
|
*/
|
|
276
426
|
export declare function calculateCompliance(counts: StatusCounts): number;
|
|
427
|
+
/**
|
|
428
|
+
* Violation is one breached bound together with the requirements that breached
|
|
429
|
+
* it. `findings` is empty in two cases, for two different reasons: a compliance
|
|
430
|
+
* percentage is a property of the whole document, so it has no offending
|
|
431
|
+
* requirement to name; and a controls list already names its requirement in the
|
|
432
|
+
* message, so repeating it would say the same thing twice.
|
|
433
|
+
*
|
|
434
|
+
* Findings from a RULE are the filter's own matches and carry every field. Those
|
|
435
|
+
* from a COUNT bound are rebuilt from the control map, which holds only id,
|
|
436
|
+
* title, status and severity — so `impact`, `baseline`, `baselineIndex` and
|
|
437
|
+
* `index` are zero there rather than the requirement's real values. The CLI
|
|
438
|
+
* prints none of them; a consumer serializing `findings` should not read them as
|
|
439
|
+
* data. Parity: Violation in go/rules.go.
|
|
440
|
+
*/
|
|
441
|
+
interface Violation {
|
|
442
|
+
message: string;
|
|
443
|
+
findings: Match[];
|
|
444
|
+
}
|
|
445
|
+
/** The messages of a violation list, for a caller that wants the verdict alone. */
|
|
446
|
+
export declare function violationMessages(violations: Violation[]): string[];
|
|
277
447
|
/**
|
|
278
448
|
* validateThresholds checks all threshold bounds against observed counts and
|
|
279
449
|
* compliance, returning human-readable violation messages (empty when all pass).
|
|
280
450
|
*/
|
|
281
451
|
export declare function validateThresholds(config: ThresholdConfig, counts: StatusCounts, compliance: number, controlMap: ControlIDMapping[]): string[];
|
|
452
|
+
/**
|
|
453
|
+
* ruleRefusal is what a caller is told when a policy carries rules the path it
|
|
454
|
+
* used cannot evaluate. It reaches end users, so it names the spec and what to do
|
|
455
|
+
* about it rather than an internal function. Parity: ruleRefusal in go/rules.go.
|
|
456
|
+
*/
|
|
457
|
+
export declare function ruleRefusal(count: number): string;
|
|
458
|
+
/**
|
|
459
|
+
* validateGrid is the status x severity half of a policy, shared by
|
|
460
|
+
* validateThresholds and evaluate. Parity: validateGrid in go/compliance.go.
|
|
461
|
+
*/
|
|
462
|
+
export declare function validateGrid(config: ThresholdConfig, counts: StatusCounts, compliance: number, controlMap: ControlIDMapping[]): Violation[];
|
|
463
|
+
//#endregion
|
|
464
|
+
//#region src/rules.d.ts
|
|
465
|
+
/**
|
|
466
|
+
* The vocabulary a rule may name. It is deliberately the filter engine's own
|
|
467
|
+
* vocabulary rather than a second one: a rule and an `hdf query` invocation then
|
|
468
|
+
* mean the same thing. Values within a field OR; fields AND.
|
|
469
|
+
*/
|
|
470
|
+
interface RulePredicate {
|
|
471
|
+
status?: PredicateValue;
|
|
472
|
+
severity?: PredicateValue;
|
|
473
|
+
impact?: string;
|
|
474
|
+
rawImpact?: string;
|
|
475
|
+
cvss?: string;
|
|
476
|
+
epss?: string;
|
|
477
|
+
kev?: string;
|
|
478
|
+
cwe?: PredicateValue;
|
|
479
|
+
cci?: PredicateValue;
|
|
480
|
+
nist?: PredicateValue;
|
|
481
|
+
id?: string;
|
|
482
|
+
tag?: PredicateValue;
|
|
483
|
+
search?: string;
|
|
484
|
+
baseline?: string;
|
|
485
|
+
/**
|
|
486
|
+
* Selects by the labels of the baseline a requirement sits in, which is what
|
|
487
|
+
* makes 'nothing fails in anything labelled environment=production'
|
|
488
|
+
* expressible as a policy rather than only as a query.
|
|
489
|
+
*/
|
|
490
|
+
baselineLabel?: PredicateValue;
|
|
491
|
+
disposition?: PredicateValue;
|
|
492
|
+
/**
|
|
493
|
+
* The KIND of the governing POA&M, which disposition collapses to the flat
|
|
494
|
+
* 'poam' because it is typed Override_Type and a plan's kind is not one.
|
|
495
|
+
*/
|
|
496
|
+
poamType?: PredicateValue;
|
|
497
|
+
poams?: string;
|
|
498
|
+
}
|
|
499
|
+
/**
|
|
500
|
+
* A policy the grid cannot express. Two decisions, recorded because a policy
|
|
501
|
+
* author will otherwise assume one of them: a rule bounds a COUNT and not a
|
|
502
|
+
* percentage — the grid's compliance min/max remains the only percentage bound,
|
|
503
|
+
* and extending rules to percentages is deferred rather than excluded — and a
|
|
504
|
+
* rule evaluates over the WHOLE document, not per baseline. A policy that wants
|
|
505
|
+
* one baseline says so with the baseline predicate.
|
|
506
|
+
*
|
|
507
|
+
* `name` is optional and exists for the
|
|
508
|
+
* violation message; a rule without one is identified by its predicate, which is
|
|
509
|
+
* the only other handle a reader has.
|
|
510
|
+
*/
|
|
511
|
+
interface ThresholdRule {
|
|
512
|
+
name?: string;
|
|
513
|
+
where: RulePredicate;
|
|
514
|
+
min?: number;
|
|
515
|
+
max?: number;
|
|
516
|
+
}
|
|
517
|
+
/**
|
|
518
|
+
* What rule evaluation needs beyond the document: the reference clock for
|
|
519
|
+
* expiry, and the status resolver. statusOf is injected rather than assumed so a
|
|
520
|
+
* rule and the grid's counts cannot disagree about what 'failed' means on the
|
|
521
|
+
* same document.
|
|
522
|
+
*/
|
|
523
|
+
interface RuleOptions {
|
|
524
|
+
now?: string;
|
|
525
|
+
statusOf?: (control: EvaluatedRequirement) => string;
|
|
526
|
+
}
|
|
527
|
+
/**
|
|
528
|
+
* Applies every rule to the document and returns one violation per breached
|
|
529
|
+
* bound. Evaluation is filter → count → compare, calling the engine's own filter
|
|
530
|
+
* rather than a second matcher.
|
|
531
|
+
*/
|
|
532
|
+
export declare function evaluateRules(config: ThresholdConfig, results: HDFResults, options?: RuleOptions): Violation[];
|
|
533
|
+
/**
|
|
534
|
+
* Everything an evaluation needs. A shape rather than a parameter list because
|
|
535
|
+
* rules made the list long enough that a caller could transpose two arguments of
|
|
536
|
+
* the same type without the compiler noticing. Parity: ThresholdInput in
|
|
537
|
+
* go/rules.go.
|
|
538
|
+
*/
|
|
539
|
+
interface ThresholdInput {
|
|
540
|
+
results: HDFResults;
|
|
541
|
+
counts: StatusCounts;
|
|
542
|
+
compliance: number;
|
|
543
|
+
controlMap: ControlIDMapping[];
|
|
544
|
+
now?: string;
|
|
545
|
+
statusOf?: (control: EvaluatedRequirement) => string;
|
|
546
|
+
}
|
|
547
|
+
/**
|
|
548
|
+
* Applies a whole policy — the grid and the rules — and returns every violation.
|
|
549
|
+
* This is the entry point a surface should call: validateThresholds evaluates the
|
|
550
|
+
* grid alone and refuses a config carrying rules, so a caller cannot
|
|
551
|
+
* half-implement a policy without being told. Parity: Evaluate in go/rules.go.
|
|
552
|
+
*/
|
|
553
|
+
export declare function evaluate(config: ThresholdConfig, input: ThresholdInput): Violation[];
|
|
554
|
+
//#endregion
|
|
555
|
+
//#region src/loader.d.ts
|
|
556
|
+
/** Wire encoding of loader input (parity with Go InputFormat). */
|
|
557
|
+
type InputFormat = 'json' | 'ndjson';
|
|
558
|
+
interface LoadResult {
|
|
559
|
+
format: InputFormat;
|
|
560
|
+
docType: HdfDocType;
|
|
561
|
+
results?: HDFResults;
|
|
562
|
+
baseline?: HDFBaseline;
|
|
563
|
+
/** Non-empty when detected as results/baseline but the parse/validate failed. */
|
|
564
|
+
parseError?: string;
|
|
565
|
+
valid: boolean;
|
|
566
|
+
}
|
|
567
|
+
/**
|
|
568
|
+
* load is the schema-typed loader core. In order: validateInputSize (FIRST,
|
|
569
|
+
* before any parse; maxSize <= 0 uses the default), wire-format detection
|
|
570
|
+
* (JSON vs NDJSON), document-type detection (detect), then the canonical
|
|
571
|
+
* hdf-parsers parse for the results and baseline types. Other types are
|
|
572
|
+
* detected but not parsed here.
|
|
573
|
+
*/
|
|
574
|
+
export declare function load(input: string | Uint8Array, maxSize?: number): LoadResult;
|
|
575
|
+
/**
|
|
576
|
+
* detectFormat classifies input as a single JSON document or newline-delimited
|
|
577
|
+
* JSON, consistent with the Go core: NDJSON is two or more non-blank lines that
|
|
578
|
+
* each independently parse as a complete JSON value. A pretty-printed single
|
|
579
|
+
* object stays 'json' (its first line is not itself a complete JSON value).
|
|
580
|
+
*/
|
|
581
|
+
export declare function detectFormat(text: string): InputFormat;
|
|
582
|
+
//#endregion
|
|
583
|
+
//#region src/evidence.d.ts
|
|
584
|
+
/** Classifies a single content entry's checksum verification. */
|
|
585
|
+
type ChecksumStatus = 'match' | 'mismatch' | 'skipped' | 'error';
|
|
586
|
+
/** One content entry of an evidence package: a referenced document and its
|
|
587
|
+
* recorded checksum ('' when the entry carries none). */
|
|
588
|
+
interface EvidenceContent {
|
|
589
|
+
uri: string;
|
|
590
|
+
type: string;
|
|
591
|
+
checksum: string;
|
|
592
|
+
}
|
|
593
|
+
/** The verification outcome for one content entry. */
|
|
594
|
+
interface ChecksumResult {
|
|
595
|
+
uri: string;
|
|
596
|
+
type: string;
|
|
597
|
+
status: ChecksumStatus;
|
|
598
|
+
expected?: string;
|
|
599
|
+
actual?: string;
|
|
600
|
+
error?: string;
|
|
601
|
+
}
|
|
602
|
+
/** Reports which planned baselines are covered by results. */
|
|
603
|
+
interface CompletenessResult {
|
|
604
|
+
planned: string[];
|
|
605
|
+
covered: string[];
|
|
606
|
+
missing: string[];
|
|
607
|
+
complete: boolean;
|
|
608
|
+
}
|
|
609
|
+
/** Resolves a content URI to its bytes. The caller owns path confinement
|
|
610
|
+
* (HDF_MCP_ROOT for the MCP, the package directory for the CLI). Throws when the
|
|
611
|
+
* uri cannot be read. */
|
|
612
|
+
type FetchFn = (uri: string) => Uint8Array;
|
|
613
|
+
/** Extracts the planRef and content entries from an evidence-package document. */
|
|
614
|
+
export declare function parseEvidencePackage(pkg: string): {
|
|
615
|
+
planRef: string;
|
|
616
|
+
contents: EvidenceContent[];
|
|
617
|
+
};
|
|
618
|
+
/** Verifies each content entry's sha256 against fetch(uri), preserving entry
|
|
619
|
+
* order. No checksum → skipped; a fetch throw → error; hash mismatch → mismatch
|
|
620
|
+
* (carrying expected+actual). */
|
|
621
|
+
export declare function verifyChecksums(contents: EvidenceContent[], fetch: FetchFn): ChecksumResult[];
|
|
622
|
+
/** Extracts assessment baselineRefs from a plan document, deduped in first-seen
|
|
623
|
+
* order. */
|
|
624
|
+
export declare function plannedBaselineRefs(plan: string): string[];
|
|
625
|
+
/** Extracts baseline names from a results document, deduped in first-seen order. */
|
|
626
|
+
export declare function coveredBaselineNames(results: string): string[];
|
|
627
|
+
/** Concatenates the covered baseline names of every hdf-results document the
|
|
628
|
+
* package references, in entry order. An entry that cannot be fetched or parsed
|
|
629
|
+
* is skipped: checksum verification is what reports a read failure, and a
|
|
630
|
+
* partial coverage list is what the completeness diff needs. */
|
|
631
|
+
export declare function coveredBaselinesInPackage(contents: EvidenceContent[], fetch: FetchFn): string[];
|
|
632
|
+
/** Sums the agent-attributed override count across every hdf-results document
|
|
633
|
+
* the package references. Unreadable or unparseable entries are skipped. */
|
|
634
|
+
export declare function agentOverridesInPackage(contents: EvidenceContent[], fetch: FetchFn): number;
|
|
635
|
+
/** Diffs planned baseline refs against covered baseline names. A planned ref is
|
|
636
|
+
* covered when some results baseline shares its name. Missing is sorted so the
|
|
637
|
+
* outcome is deterministic across languages and runs. */
|
|
638
|
+
export declare function completeness(planned: string[], covered: string[]): CompletenessResult;
|
|
282
639
|
//#endregion
|
|
283
|
-
export type { ChecksumResult, ChecksumStatus, CompletenessResult, ComplianceBound, ControlIDMapping, EvidenceContent, FetchFn, FilterOptions, HdfDocType, InputFormat, LoadResult, Match, MergeResult, MergeSource, MergeWarning, MergeWarningKind, SeverityCounts, StatusCounts, ThresholdBound, ThresholdConfig, ThresholdSeverity };
|
|
640
|
+
export type { ChecksumResult, ChecksumStatus, CompletenessResult, ComplianceBound, ControlIDMapping, EvidenceContent, FetchFn, FilterAlias, FilterOptions, HdfDocType, InputFormat, LoadResult, Match, MergeResult, MergeSource, MergeWarning, MergeWarningKind, RuleOptions, RulePredicate, SeverityCounts, StatusCounts, ThresholdBound, ThresholdConfig, ThresholdInput, ThresholdRule, ThresholdSeverity, Violation };
|
|
284
641
|
//# sourceMappingURL=index.d.ts.map
|