@intellectual-frontiers/grc 0.0.0-stage → 0.1.0
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/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/assess.d.ts +247 -0
- package/dist/assess.js +289 -0
- package/dist/attest.d.ts +164 -0
- package/dist/attest.js +213 -0
- package/dist/evidence.d.ts +212 -0
- package/dist/evidence.js +453 -0
- package/dist/grc.d.ts +356 -0
- package/dist/grc.js +487 -0
- package/dist/host/grc.d.ts +159 -0
- package/dist/host/grc.js +358 -0
- package/dist/host/mod.d.ts +14 -0
- package/dist/host/mod.js +15 -0
- package/dist/host/sign.d.ts +141 -0
- package/dist/host/sign.js +282 -0
- package/dist/mod.d.ts +19 -0
- package/dist/mod.js +20 -0
- package/dist/ocsf-types.auto.d.ts +4374 -0
- package/dist/ocsf-types.auto.js +24 -0
- package/dist/ocsf.d.ts +160 -0
- package/dist/ocsf.js +257 -0
- package/dist/oscal.d.ts +356 -0
- package/dist/oscal.js +513 -0
- package/package.json +87 -4
- package/src/assess.ts +472 -0
- package/src/attest.ts +354 -0
- package/src/evidence.ts +551 -0
- package/src/grc.ts +771 -0
- package/src/host/grc.ts +435 -0
- package/src/host/mod.ts +15 -0
- package/src/host/sign.ts +364 -0
- package/src/mod.ts +20 -0
- package/src/ocsf-types.auto.ts +4680 -0
- package/src/ocsf.ts +471 -0
- package/src/oscal.ts +850 -0
package/src/assess.ts
ADDED
|
@@ -0,0 +1,472 @@
|
|
|
1
|
+
// Spec: 0001-grc FR-010
|
|
2
|
+
/**
|
|
3
|
+
* Assessment: what findings, evidence and declarations add up to (commons 0001-grc FR-010 to FR-015). Every function is pure and takes the
|
|
4
|
+
* instant it judges at as a value.
|
|
5
|
+
*
|
|
6
|
+
* - **Coverage** rolls each catalog control (a requirement) or control up as `gap`, `untested`, `partial`, `addressed` or `covered` (FR-010).
|
|
7
|
+
* - **Freshness** holds the newest evidence to a cadence (an ISO 8601 duration): `fresh`, `due` within the last tenth of the cadence, or
|
|
8
|
+
* `stale`, with the instant it falls due (FR-011).
|
|
9
|
+
* - **Drift** compares a declared and an observed view of keyed records: added, removed and changed, each change with its field's path
|
|
10
|
+
* and both values, in key order (FR-012).
|
|
11
|
+
* - The **change-impact gate** reads declarations of paths (globs) to controls and judges a change `allowed` or `blocked`, with every
|
|
12
|
+
* reason (FR-013).
|
|
13
|
+
* - The **risk register** levels each risk by NIST SP 800-30 Rev. 1's Table I-2 and reports those past their review (FR-014).
|
|
14
|
+
* - The **trace** relates each requirement to the mechanisms that enforce it and the evidence they gave, and names those with none (FR-015).
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { riskLevel } from "./assess.ts";
|
|
19
|
+
* riskLevel("moderate", "very-high"); // "high"
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* @module
|
|
23
|
+
*/
|
|
24
|
+
import { absurd, type Decoder, array, literal, object, string } from "@intellectual-frontiers/core";
|
|
25
|
+
import {
|
|
26
|
+
type Catalog,
|
|
27
|
+
type CatalogControl,
|
|
28
|
+
type ControlRef,
|
|
29
|
+
type Duration,
|
|
30
|
+
type Finding,
|
|
31
|
+
type Instant,
|
|
32
|
+
type Outcome,
|
|
33
|
+
type Role,
|
|
34
|
+
addDuration,
|
|
35
|
+
compareInstants,
|
|
36
|
+
epochMs,
|
|
37
|
+
glob,
|
|
38
|
+
instantDecoder,
|
|
39
|
+
instantFromEpochMs,
|
|
40
|
+
joinAll,
|
|
41
|
+
latestInstant,
|
|
42
|
+
roleDecoder,
|
|
43
|
+
} from "./grc.ts";
|
|
44
|
+
import type { Json } from "@intellectual-frontiers/formats/json5";
|
|
45
|
+
import type { Sha256 } from "@intellectual-frontiers/crypto/sha256";
|
|
46
|
+
|
|
47
|
+
const byText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
|
|
48
|
+
|
|
49
|
+
/** The findings of the newest assessment of each control and subject: for each, those with the latest `at`. */
|
|
50
|
+
export function newestFindings(findings: readonly Finding[]): readonly Finding[] {
|
|
51
|
+
const latest = new Map<string, Instant>();
|
|
52
|
+
for (const f of findings) {
|
|
53
|
+
const k = JSON.stringify([f.control.id, f.subject.kind, f.subject.id]);
|
|
54
|
+
const seen = latest.get(k);
|
|
55
|
+
if (seen === undefined || compareInstants(f.at, seen) > 0) latest.set(k, f.at);
|
|
56
|
+
}
|
|
57
|
+
return findings.filter((f) => latest.get(JSON.stringify([f.control.id, f.subject.kind, f.subject.id])) === f.at);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ---------------------------------------------------------------------------------------------------------------------------- coverage (FR-010)
|
|
61
|
+
|
|
62
|
+
/** How well a requirement or control is met, from the worst to the best. */
|
|
63
|
+
export type CoverageStatus = "gap" | "untested" | "partial" | "addressed" | "covered";
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* The coverage that subjects' outcomes give, `not-applicable` ones left out: `untested` where none is left, `partial` where one is
|
|
67
|
+
* neither passing nor accepted, `addressed` where every one passes or is accepted and at least one is accepted, `covered` where every one
|
|
68
|
+
* passes.
|
|
69
|
+
*/
|
|
70
|
+
export function coverageOf(outcomes: readonly Outcome[]): Exclude<CoverageStatus, "gap"> {
|
|
71
|
+
const applicable = outcomes.filter((o) => o !== "not-applicable");
|
|
72
|
+
if (applicable.length === 0) return "untested";
|
|
73
|
+
if (applicable.some((o) => o !== "pass" && o !== "accepted")) return "partial";
|
|
74
|
+
return applicable.includes("accepted") ? "addressed" : "covered";
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** A control's coverage from the newest findings of it. */
|
|
78
|
+
export type ControlCoverage = { readonly control: string; readonly status: Exclude<CoverageStatus, "gap">; readonly outcome: Outcome };
|
|
79
|
+
|
|
80
|
+
/** Each control's coverage, in the order given, from the newest findings of each control and subject. */
|
|
81
|
+
export function controlCoverage(controls: readonly { readonly id: string }[], findings: readonly Finding[]): readonly ControlCoverage[] {
|
|
82
|
+
const newest = newestFindings(findings);
|
|
83
|
+
return controls.map((c) => {
|
|
84
|
+
const outcomes = newest.filter((f) => f.control.id === c.id).map((f) => f.outcome);
|
|
85
|
+
return { control: c.id, status: coverageOf(outcomes), outcome: joinAll(outcomes) };
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** A requirement's coverage: the catalog control, the controls that implement it, and how well they meet it. */
|
|
90
|
+
export type RequirementCoverage<C extends string = string, I extends string = string> = {
|
|
91
|
+
readonly requirement: ControlRef<C, I>;
|
|
92
|
+
readonly status: CoverageStatus;
|
|
93
|
+
readonly outcome: Outcome;
|
|
94
|
+
readonly controls: readonly string[];
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Every control of a catalog as a requirement, in the catalog's order: `gap` where no control implements it, else the coverage of the
|
|
99
|
+
* newest findings of every control that does (`untested` where there are none).
|
|
100
|
+
*/
|
|
101
|
+
export function requirementCoverage<C extends string, E extends CatalogControl>(
|
|
102
|
+
catalog: Catalog<C, E>,
|
|
103
|
+
controls: readonly { readonly id: string; readonly implements: readonly ControlRef[] }[],
|
|
104
|
+
findings: readonly Finding[],
|
|
105
|
+
): readonly RequirementCoverage<C, E["id"]>[] {
|
|
106
|
+
const newest = newestFindings(findings);
|
|
107
|
+
return catalog.ids.map((id) => {
|
|
108
|
+
const implementing = controls.filter((c) => c.implements.some((r) => r.catalog === catalog.id && r.id === id)).map((c) => c.id);
|
|
109
|
+
const outcomes = newest.filter((f) => implementing.includes(f.control.id)).map((f) => f.outcome);
|
|
110
|
+
return {
|
|
111
|
+
requirement: catalog.control(id),
|
|
112
|
+
status: implementing.length === 0 ? "gap" : coverageOf(outcomes),
|
|
113
|
+
outcome: joinAll(outcomes),
|
|
114
|
+
controls: implementing,
|
|
115
|
+
};
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// ---------------------------------------------------------------------------------------------------------------------------- freshness (FR-011)
|
|
120
|
+
|
|
121
|
+
/** Whether evidence is recent enough for its cadence. */
|
|
122
|
+
export type FreshnessStatus = "fresh" | "due" | "stale";
|
|
123
|
+
|
|
124
|
+
/** How fresh evidence is: its status, the newest evidence, when it falls due (`null` past the year 9999) and when the `due` window opens. */
|
|
125
|
+
export type Freshness = {
|
|
126
|
+
readonly status: FreshnessStatus;
|
|
127
|
+
readonly cadence: string;
|
|
128
|
+
readonly newest: Instant | null;
|
|
129
|
+
readonly dueAt: Instant | null;
|
|
130
|
+
readonly dueFrom: Instant | null;
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* The freshness at `at` of evidence observed at the given instants, held to a cadence: it falls due one cadence after the newest; it is
|
|
135
|
+
* `stale` after that instant, `due` in the last tenth of the cadence up to and at it, `fresh` before. No evidence at all is `stale`, due at `at`.
|
|
136
|
+
*/
|
|
137
|
+
export function freshness(cadence: Duration, evidence: readonly Instant[], at: Instant): Freshness {
|
|
138
|
+
const newest = latestInstant(evidence);
|
|
139
|
+
if (newest === undefined) return { status: "stale", cadence: cadence.text, newest: null, dueAt: at, dueFrom: at };
|
|
140
|
+
const dueAt = addDuration(newest, cadence);
|
|
141
|
+
if (dueAt === undefined) return { status: "fresh", cadence: cadence.text, newest, dueAt: null, dueFrom: null };
|
|
142
|
+
const length = epochMs(dueAt) - epochMs(newest);
|
|
143
|
+
const dueFrom = instantFromEpochMs(epochMs(dueAt) - length / 10) ?? newest;
|
|
144
|
+
const status: FreshnessStatus = compareInstants(at, dueAt) > 0 ? "stale" : compareInstants(at, dueFrom) >= 0 ? "due" : "fresh";
|
|
145
|
+
return { status, cadence: cadence.text, newest, dueAt, dueFrom };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** The freshness of each control's newest finding, held to the control's cadence, in the order given. */
|
|
149
|
+
export function controlFreshness(
|
|
150
|
+
controls: readonly { readonly id: string; readonly cadence: Duration }[],
|
|
151
|
+
findings: readonly Finding[],
|
|
152
|
+
at: Instant,
|
|
153
|
+
): readonly { readonly control: string; readonly freshness: Freshness }[] {
|
|
154
|
+
return controls.map((c) => ({
|
|
155
|
+
control: c.id,
|
|
156
|
+
freshness: freshness(
|
|
157
|
+
c.cadence,
|
|
158
|
+
findings.filter((f) => f.control.id === c.id).map((f) => f.at),
|
|
159
|
+
at,
|
|
160
|
+
),
|
|
161
|
+
}));
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// ---------------------------------------------------------------------------------------------------------------------------- drift (FR-012)
|
|
165
|
+
|
|
166
|
+
/** One step of a field's path: a member name or an array index. */
|
|
167
|
+
export type PathStep = string | number;
|
|
168
|
+
|
|
169
|
+
/** A field that differs: its path inside the record, and its value on each side (absent where that side does not have it). */
|
|
170
|
+
export type FieldChange = {
|
|
171
|
+
readonly path: readonly PathStep[];
|
|
172
|
+
readonly field: string;
|
|
173
|
+
readonly declared?: Json;
|
|
174
|
+
readonly observed?: Json;
|
|
175
|
+
};
|
|
176
|
+
|
|
177
|
+
/** What differs between a declared and an observed view of keyed records, each list in key order. */
|
|
178
|
+
export type Drift = {
|
|
179
|
+
readonly added: readonly { readonly key: string; readonly value: Json }[];
|
|
180
|
+
readonly removed: readonly { readonly key: string; readonly value: Json }[];
|
|
181
|
+
readonly changed: readonly { readonly key: string; readonly changes: readonly FieldChange[] }[];
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
/** Keyed records: a map, or an object whose members are the records. */
|
|
185
|
+
export type KeyedView = ReadonlyMap<string, Json> | { readonly [key: string]: Json };
|
|
186
|
+
|
|
187
|
+
/** A field's path as text, `$` for the record itself: `$.ports[0]`, `$["a b"]`. */
|
|
188
|
+
export function formatFieldPath(path: readonly PathStep[]): string {
|
|
189
|
+
return path.reduce<string>(
|
|
190
|
+
(s, p) => (typeof p === "number" ? `${s}[${p}]` : /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(p) ? `${s}.${p}` : `${s}[${JSON.stringify(p)}]`),
|
|
191
|
+
"$",
|
|
192
|
+
);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
function isObject(v: Json): v is { readonly [key: string]: Json } {
|
|
196
|
+
return typeof v === "object" && v !== null && !Array.isArray(v);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function isList(v: Json): v is readonly Json[] {
|
|
200
|
+
return Array.isArray(v);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
function sameJson(a: Json, b: Json): boolean {
|
|
204
|
+
if (isList(a) && isList(b)) return a.length === b.length && a.every((x, i) => b[i] !== undefined && sameJson(x, b[i]));
|
|
205
|
+
if (isObject(a) && isObject(b)) {
|
|
206
|
+
const ka = Object.keys(a).sort();
|
|
207
|
+
const kb = Object.keys(b).sort();
|
|
208
|
+
return (
|
|
209
|
+
ka.length === kb.length &&
|
|
210
|
+
ka.every((k, i) => {
|
|
211
|
+
const x = a[k];
|
|
212
|
+
const y = b[k];
|
|
213
|
+
return k === kb[i] && x !== undefined && y !== undefined && sameJson(x, y);
|
|
214
|
+
})
|
|
215
|
+
);
|
|
216
|
+
}
|
|
217
|
+
return a === b;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
function change(path: readonly PathStep[], declared: Json | undefined, observed: Json | undefined): FieldChange {
|
|
221
|
+
return {
|
|
222
|
+
path,
|
|
223
|
+
field: formatFieldPath(path),
|
|
224
|
+
...(declared === undefined ? {} : { declared }),
|
|
225
|
+
...(observed === undefined ? {} : { observed }),
|
|
226
|
+
};
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
function diff(path: readonly PathStep[], a: Json | undefined, b: Json | undefined, out: FieldChange[]): void {
|
|
230
|
+
if (a === undefined || b === undefined) {
|
|
231
|
+
if (a !== b) out.push(change(path, a, b));
|
|
232
|
+
return;
|
|
233
|
+
}
|
|
234
|
+
if (isObject(a) && isObject(b)) {
|
|
235
|
+
for (const k of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) diff([...path, k], a[k], b[k], out);
|
|
236
|
+
} else if (isList(a) && isList(b)) {
|
|
237
|
+
for (let i = 0; i < Math.max(a.length, b.length); i++) diff([...path, i], a[i], b[i], out);
|
|
238
|
+
} else if (!sameJson(a, b)) out.push(change(path, a, b));
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/** The field changes between two values: objects compared member by member in key order, arrays index by index, anything else whole. */
|
|
242
|
+
export function fieldChanges(declared: Json, observed: Json): readonly FieldChange[] {
|
|
243
|
+
const out: FieldChange[] = [];
|
|
244
|
+
diff([], declared, observed, out);
|
|
245
|
+
return out;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
function entriesOf(view: KeyedView): ReadonlyMap<string, Json> {
|
|
249
|
+
return view instanceof Map ? view : new Map(Object.entries(view));
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** The drift from what is declared to what is observed: records only observed are added, only declared removed, in both but different changed. */
|
|
253
|
+
export function drift(declared: KeyedView, observed: KeyedView): Drift {
|
|
254
|
+
const d = entriesOf(declared);
|
|
255
|
+
const o = entriesOf(observed);
|
|
256
|
+
const keys = [...new Set([...d.keys(), ...o.keys()])].sort(byText);
|
|
257
|
+
const added: { key: string; value: Json }[] = [];
|
|
258
|
+
const removed: { key: string; value: Json }[] = [];
|
|
259
|
+
const changed: { key: string; changes: readonly FieldChange[] }[] = [];
|
|
260
|
+
for (const key of keys) {
|
|
261
|
+
const a = d.get(key);
|
|
262
|
+
const b = o.get(key);
|
|
263
|
+
if (a === undefined && b !== undefined) added.push({ key, value: b });
|
|
264
|
+
else if (b === undefined && a !== undefined) removed.push({ key, value: a });
|
|
265
|
+
else if (a !== undefined && b !== undefined) {
|
|
266
|
+
const changes = fieldChanges(a, b);
|
|
267
|
+
if (changes.length > 0) changed.push({ key, changes });
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
return { added, removed, changed };
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
// ---------------------------------------------------------------------------------------------------------------------------- change impact (FR-013)
|
|
274
|
+
|
|
275
|
+
/** Paths (globs) and the controls a change to them bears on. */
|
|
276
|
+
export type ImpactDeclaration = { readonly paths: readonly string[]; readonly controls: readonly string[] };
|
|
277
|
+
|
|
278
|
+
/** A change: the paths it touches, the reviews it says it needs (by role) and the reviews given. */
|
|
279
|
+
export type Change = { readonly paths: readonly string[]; readonly needsReview?: readonly Role[]; readonly reviewedBy?: readonly Role[] };
|
|
280
|
+
|
|
281
|
+
/** The outcomes that block a change to the paths of a control. */
|
|
282
|
+
export type BlockingOutcome = "fail" | "error" | "gap";
|
|
283
|
+
|
|
284
|
+
/** Why a change is blocked. */
|
|
285
|
+
export type GateReason =
|
|
286
|
+
| { readonly kind: "control"; readonly control: string; readonly outcome: BlockingOutcome; readonly paths: readonly string[] }
|
|
287
|
+
| { readonly kind: "review"; readonly role: Role };
|
|
288
|
+
|
|
289
|
+
/** A control a change bears on, and the touched paths declared for it. */
|
|
290
|
+
export type Touched = { readonly control: string; readonly paths: readonly string[] };
|
|
291
|
+
|
|
292
|
+
/** The gate's judgement of a change, with every control it touches; where blocked, every reason. */
|
|
293
|
+
export type GateDecision =
|
|
294
|
+
| { readonly kind: "allowed"; readonly touched: readonly Touched[] }
|
|
295
|
+
| { readonly kind: "blocked"; readonly touched: readonly Touched[]; readonly reasons: readonly [GateReason, ...GateReason[]] };
|
|
296
|
+
|
|
297
|
+
/** A gate reason as one sentence. */
|
|
298
|
+
export function formatGateReason(r: GateReason): string {
|
|
299
|
+
switch (r.kind) {
|
|
300
|
+
case "control":
|
|
301
|
+
return `control ${r.control} is ${r.outcome} and the change touches ${r.paths.join(", ")}`;
|
|
302
|
+
case "review":
|
|
303
|
+
return `the change needs a review by ${r.role}, not given`;
|
|
304
|
+
default:
|
|
305
|
+
return absurd(r);
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/** Each control's newest outcome: the join of its newest findings' outcomes. */
|
|
310
|
+
export function newestOutcomes(findings: readonly Finding[]): ReadonlyMap<string, Outcome> {
|
|
311
|
+
const groups = new Map<string, Outcome[]>();
|
|
312
|
+
for (const f of newestFindings(findings)) groups.set(f.control.id, [...(groups.get(f.control.id) ?? []), f.outcome]);
|
|
313
|
+
return new Map([...groups].map(([k, v]) => [k, joinAll(v)]));
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* A change judged against the declarations and each control's newest outcome: `blocked` where a touched path is declared for a control
|
|
318
|
+
* whose outcome is `fail`, `error` or `gap` (a control with no outcome does not block), or where a review the change needs was not given;
|
|
319
|
+
* else `allowed`. Reasons: controls in id order, then reviews in role order.
|
|
320
|
+
*/
|
|
321
|
+
export function gate(declarations: readonly ImpactDeclaration[], change: Change, outcomes: ReadonlyMap<string, Outcome>): GateDecision {
|
|
322
|
+
const compiled = declarations.map((d) => ({ globs: d.paths.map(glob), controls: d.controls }));
|
|
323
|
+
const byControl = new Map<string, Set<string>>();
|
|
324
|
+
for (const path of change.paths)
|
|
325
|
+
for (const d of compiled)
|
|
326
|
+
if (d.globs.some((g) => g.test(path)))
|
|
327
|
+
for (const c of d.controls) byControl.set(c, (byControl.get(c) ?? new Set<string>()).add(path));
|
|
328
|
+
const touched: Touched[] = [...byControl.keys()]
|
|
329
|
+
.sort(byText)
|
|
330
|
+
.map((control) => ({ control, paths: [...(byControl.get(control) ?? [])].sort(byText) }));
|
|
331
|
+
const reasons: GateReason[] = [];
|
|
332
|
+
for (const t of touched) {
|
|
333
|
+
const outcome = outcomes.get(t.control);
|
|
334
|
+
if (outcome === "fail" || outcome === "error" || outcome === "gap")
|
|
335
|
+
reasons.push({ kind: "control", control: t.control, outcome, paths: t.paths });
|
|
336
|
+
}
|
|
337
|
+
const given = new Set<string>(change.reviewedBy ?? []);
|
|
338
|
+
for (const role of [...new Set(change.needsReview ?? [])].sort(byText)) if (!given.has(role)) reasons.push({ kind: "review", role });
|
|
339
|
+
const [first, ...rest] = reasons;
|
|
340
|
+
return first === undefined ? { kind: "allowed", touched } : { kind: "blocked", touched, reasons: [first, ...rest] };
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/** An impact declaration as a file holds it. */
|
|
344
|
+
export const impactDeclarationDecoder: Decoder<ImpactDeclaration> = object({ paths: array(string), controls: array(string) });
|
|
345
|
+
|
|
346
|
+
// ---------------------------------------------------------------------------------------------------------------------------- risk (FR-014)
|
|
347
|
+
|
|
348
|
+
/** NIST SP 800-30's five qualitative levels, from the least to the greatest. */
|
|
349
|
+
export const RISK_LEVELS = ["very-low", "low", "moderate", "high", "very-high"] as const;
|
|
350
|
+
|
|
351
|
+
/** A qualitative level of likelihood, impact or risk (NIST SP 800-30 Rev. 1, Appendices G to I). */
|
|
352
|
+
export type RiskLevel = (typeof RISK_LEVELS)[number];
|
|
353
|
+
|
|
354
|
+
/**
|
|
355
|
+
* NIST SP 800-30 Rev. 1, Table I-2, "Assessment scale – level of risk (combination of likelihood and impact)": the level of risk for a
|
|
356
|
+
* likelihood (the row) and an impact (the column).
|
|
357
|
+
*/
|
|
358
|
+
export const RISK_MATRIX: Readonly<Record<RiskLevel, Readonly<Record<RiskLevel, RiskLevel>>>> = {
|
|
359
|
+
"very-high": { "very-low": "very-low", low: "low", moderate: "moderate", high: "high", "very-high": "very-high" },
|
|
360
|
+
high: { "very-low": "very-low", low: "low", moderate: "moderate", high: "high", "very-high": "very-high" },
|
|
361
|
+
moderate: { "very-low": "very-low", low: "low", moderate: "moderate", high: "moderate", "very-high": "high" },
|
|
362
|
+
low: { "very-low": "very-low", low: "low", moderate: "low", high: "low", "very-high": "moderate" },
|
|
363
|
+
"very-low": { "very-low": "very-low", low: "very-low", moderate: "very-low", high: "low", "very-high": "low" },
|
|
364
|
+
};
|
|
365
|
+
|
|
366
|
+
/** The level of risk of a likelihood and an impact, by Table I-2. */
|
|
367
|
+
export function riskLevel(likelihood: RiskLevel, impact: RiskLevel): RiskLevel {
|
|
368
|
+
return RISK_MATRIX[likelihood][impact];
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** What is done about a risk. */
|
|
372
|
+
export type Treatment = "accept" | "mitigate" | "transfer" | "avoid";
|
|
373
|
+
|
|
374
|
+
/** A risk as it is written: the level is computed. */
|
|
375
|
+
export type RiskInput = {
|
|
376
|
+
readonly id: string;
|
|
377
|
+
readonly title: string;
|
|
378
|
+
readonly description?: string;
|
|
379
|
+
readonly likelihood: RiskLevel;
|
|
380
|
+
readonly impact: RiskLevel;
|
|
381
|
+
readonly treatment: Treatment;
|
|
382
|
+
readonly owner: Role;
|
|
383
|
+
readonly reviewBy: Instant;
|
|
384
|
+
readonly controls?: readonly string[];
|
|
385
|
+
};
|
|
386
|
+
|
|
387
|
+
/** A risk with its level. */
|
|
388
|
+
export type Risk = RiskInput & { readonly level: RiskLevel };
|
|
389
|
+
|
|
390
|
+
/** A risk past its review date at the instant the register was taken. */
|
|
391
|
+
export type OverdueReview = { readonly risk: string; readonly owner: Role; readonly reviewBy: Instant };
|
|
392
|
+
|
|
393
|
+
/** A register: its risks from the greatest level to the least (then by id), and those past their review. */
|
|
394
|
+
export type RiskRegister = { readonly at: Instant; readonly risks: readonly Risk[]; readonly overdue: readonly OverdueReview[] };
|
|
395
|
+
|
|
396
|
+
/** A risk with its level computed. */
|
|
397
|
+
export function defineRisk(r: RiskInput): Risk {
|
|
398
|
+
return { ...r, level: riskLevel(r.likelihood, r.impact) };
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/** The register of some risks at an instant: each levelled, and each whose review date is before the instant reported overdue. */
|
|
402
|
+
export function riskRegister(risks: readonly RiskInput[], at: Instant): RiskRegister {
|
|
403
|
+
const levelled = risks.map(defineRisk).sort((a, b) => RISK_LEVELS.indexOf(b.level) - RISK_LEVELS.indexOf(a.level) || byText(a.id, b.id));
|
|
404
|
+
const overdue = levelled
|
|
405
|
+
.filter((r) => compareInstants(r.reviewBy, at) < 0)
|
|
406
|
+
.map((r) => ({ risk: r.id, owner: r.owner, reviewBy: r.reviewBy }));
|
|
407
|
+
return { at, risks: levelled, overdue };
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
const levelDecoder: Decoder<RiskLevel> = literal(...RISK_LEVELS);
|
|
411
|
+
|
|
412
|
+
/** A risk as a file holds it. */
|
|
413
|
+
export const riskDecoder: Decoder<RiskInput> = object(
|
|
414
|
+
{
|
|
415
|
+
id: string,
|
|
416
|
+
title: string,
|
|
417
|
+
likelihood: levelDecoder,
|
|
418
|
+
impact: levelDecoder,
|
|
419
|
+
treatment: literal("accept", "mitigate", "transfer", "avoid"),
|
|
420
|
+
owner: roleDecoder,
|
|
421
|
+
reviewBy: instantDecoder,
|
|
422
|
+
},
|
|
423
|
+
{ description: string, controls: array(string) },
|
|
424
|
+
);
|
|
425
|
+
|
|
426
|
+
// ---------------------------------------------------------------------------------------------------------------------------- trace (FR-015)
|
|
427
|
+
|
|
428
|
+
/** What enforces requirements: a control, a policy, a process, named by its id. */
|
|
429
|
+
export type Mechanism<R extends string = string> = { readonly id: string; readonly enforces: readonly R[] };
|
|
430
|
+
|
|
431
|
+
/** A piece of evidence a mechanism gave. */
|
|
432
|
+
export type EvidenceLink = { readonly mechanism: string; readonly digest: Sha256 };
|
|
433
|
+
|
|
434
|
+
/** Why a requirement is unproven: no mechanism enforces it, or none that does gave evidence. */
|
|
435
|
+
export type Unproven = "unenforced" | "unevidenced";
|
|
436
|
+
|
|
437
|
+
/** One requirement's trace: each mechanism that enforces it with the evidence it gave (digests in order, once each). */
|
|
438
|
+
export type RequirementTrace<R extends string = string> = {
|
|
439
|
+
readonly requirement: R;
|
|
440
|
+
readonly status: "proven" | Unproven;
|
|
441
|
+
readonly mechanisms: readonly { readonly id: string; readonly evidence: readonly Sha256[] }[];
|
|
442
|
+
};
|
|
443
|
+
|
|
444
|
+
/** Every requirement's trace in the order given, and those unproven. */
|
|
445
|
+
export type Trace<R extends string = string> = {
|
|
446
|
+
readonly requirements: readonly RequirementTrace<R>[];
|
|
447
|
+
readonly unproven: readonly { readonly requirement: R; readonly reason: Unproven }[];
|
|
448
|
+
};
|
|
449
|
+
|
|
450
|
+
/** The trace of requirements to mechanisms to evidence; a requirement is proven where a mechanism that enforces it gave evidence. */
|
|
451
|
+
export function trace<const R extends string>(
|
|
452
|
+
requirements: readonly R[],
|
|
453
|
+
mechanisms: readonly Mechanism<NoInfer<R>>[],
|
|
454
|
+
evidence: readonly EvidenceLink[],
|
|
455
|
+
): Trace<R> {
|
|
456
|
+
const byMechanism = new Map<string, Set<Sha256>>();
|
|
457
|
+
for (const e of evidence) byMechanism.set(e.mechanism, (byMechanism.get(e.mechanism) ?? new Set<Sha256>()).add(e.digest));
|
|
458
|
+
const traces = requirements.map((requirement): RequirementTrace<R> => {
|
|
459
|
+
const ms = mechanisms
|
|
460
|
+
.filter((m) => m.enforces.includes(requirement))
|
|
461
|
+
.map((m) => ({ id: m.id, evidence: [...(byMechanism.get(m.id) ?? [])].sort(byText) }));
|
|
462
|
+
const status = ms.length === 0 ? "unenforced" : ms.some((m) => m.evidence.length > 0) ? "proven" : "unevidenced";
|
|
463
|
+
return { requirement, status, mechanisms: ms };
|
|
464
|
+
});
|
|
465
|
+
const unproven = traces.flatMap((t) => (t.status === "proven" ? [] : [{ requirement: t.requirement, reason: t.status }]));
|
|
466
|
+
return { requirements: traces, unproven };
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
/** The evidence that findings carry, as links from their controls (the mechanisms) to the digests. */
|
|
470
|
+
export function evidenceOfFindings(findings: readonly Finding[]): readonly EvidenceLink[] {
|
|
471
|
+
return findings.flatMap((f) => f.evidence.map((digest) => ({ mechanism: f.control.id, digest })));
|
|
472
|
+
}
|