@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/dist/grc.d.ts
ADDED
|
@@ -0,0 +1,356 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Governance, risk and compliance as code: catalogs, controls, verdicts, findings and waivers (commons 0001-grc FR-001 to FR-005), with
|
|
3
|
+
* the time values they all share (an `Instant`, an ISO 8601 `Duration`; FR-011 uses them) and the globs that waivers and change-impact
|
|
4
|
+
* declarations match with (FR-005, FR-013). Pure: the kernel reads no clock, so every "now" is a value the caller gives.
|
|
5
|
+
*
|
|
6
|
+
* - A **catalog** is a framework's controls as a constant tuple (`defineCatalog`), so `catalog.control("XX-99")` does not compile where the
|
|
7
|
+
* catalog has no `XX-99` (FR-001). Two catalogs are related by a **crosswalk** of Set Theory Relationship Mappings (NIST IR 8477), each
|
|
8
|
+
* end typed by its catalog.
|
|
9
|
+
* - A **control** (`defineControl`) checks one type of subject `S` and implements catalog controls; a **pack** (`definePack`) groups the
|
|
10
|
+
* controls of one subject type, and `runPack` runs each over each subject, a check that throws giving `error` for that subject (FR-002).
|
|
11
|
+
* - A **status** is `pass | fail | warn | error | not-applicable | gap`; an **outcome** adds `accepted` (a waived `fail` or `warn`).
|
|
12
|
+
* `join` is the least upper bound in `not-applicable < pass < accepted < warn < gap < fail < error`, a join-semilattice, so a roll-up
|
|
13
|
+
* does not depend on its order (FR-003).
|
|
14
|
+
* - A **finding** is one type for every harness, grouped into sections by `sections` (FR-004).
|
|
15
|
+
* - A **waiver** names a control, the subjects it covers (exact ids or globs), a reason, the role that approved it, when it was granted and
|
|
16
|
+
* when it expires; `defineWaiver` refuses one without an expiry or expiring before its grant, and `applyWaivers` turns an applying
|
|
17
|
+
* waiver's `fail` or `warn` into `accepted`, never an `error` or a `gap` (FR-005).
|
|
18
|
+
*
|
|
19
|
+
* @example
|
|
20
|
+
* ```ts
|
|
21
|
+
* import { defineCatalog, defineControl, definePack, duration, instantOf, runPack, verdict } from "./grc.js";
|
|
22
|
+
* const catalog = defineCatalog("example", "1.0", [{ id: "EX-1", title: "Disks are encrypted" }] as const);
|
|
23
|
+
* type Host = { readonly name: string; readonly encrypted: boolean };
|
|
24
|
+
* const encrypted = defineControl({
|
|
25
|
+
* id: "disk-encryption", title: "Disk encryption", implements: [catalog.control("EX-1")], severity: "high", cadence: duration("P1D"),
|
|
26
|
+
* check: (h: Host) => verdict(h.encrypted ? "pass" : "fail"),
|
|
27
|
+
* });
|
|
28
|
+
* const pack = definePack({ id: "hosts", title: "Hosts", subjectKind: "host", subjectId: (h: Host) => h.name, controls: [encrypted] });
|
|
29
|
+
* const at = instantOf("2026-03-01T00:00:00Z");
|
|
30
|
+
* if (at !== undefined) await runPack(pack, [{ name: "a", encrypted: false }], { at }); // one finding, status "fail"
|
|
31
|
+
* ```
|
|
32
|
+
*
|
|
33
|
+
* @module
|
|
34
|
+
*/
|
|
35
|
+
import { type Decoder, type Result } from "@intellectual-frontiers/core";
|
|
36
|
+
import type { Brand } from "@intellectual-frontiers/core";
|
|
37
|
+
import type { Sha256 } from "@intellectual-frontiers/crypto/sha256";
|
|
38
|
+
/** An instant in UTC as ISO 8601 text with milliseconds, `2026-03-01T00:00:00.000Z`: comparable as text, made only by `instantOf`. */
|
|
39
|
+
export type Instant = Brand<string, "Instant">;
|
|
40
|
+
/**
|
|
41
|
+
* ISO 8601 date-time text with a `Z` or a `±HH:MM` offset as an `Instant` in UTC (fractions past milliseconds dropped), or undefined where
|
|
42
|
+
* it is not one: a day the month does not have, an hour past 23, a leap second, or a year outside 0000 to 9999 once in UTC.
|
|
43
|
+
*/
|
|
44
|
+
export declare function instantOf(text: string): Instant | undefined;
|
|
45
|
+
/** Milliseconds since 1970-01-01T00:00:00Z as an `Instant`, or undefined where it is not finite or falls outside the years 0000 to 9999. */
|
|
46
|
+
export declare function instantFromEpochMs(ms: number): Instant | undefined;
|
|
47
|
+
/** An instant as milliseconds since 1970-01-01T00:00:00Z. */
|
|
48
|
+
export declare function epochMs(instant: Instant): number;
|
|
49
|
+
/** Negative where `a` is before `b`, zero where they are the same instant, positive where `a` is after. */
|
|
50
|
+
export declare function compareInstants(a: Instant, b: Instant): number;
|
|
51
|
+
/** The latest of some instants, or undefined where there are none. */
|
|
52
|
+
export declare function latestInstant(instants: Iterable<Instant>): Instant | undefined;
|
|
53
|
+
/** An ISO 8601 duration (`P1D`, `P30D`, `P1Y`, `PT15M`, `P1Y2M3W4DT5H6M7.5S`), its text kept for what renders it. */
|
|
54
|
+
export type Duration = {
|
|
55
|
+
readonly text: string;
|
|
56
|
+
readonly years: number;
|
|
57
|
+
readonly months: number;
|
|
58
|
+
readonly weeks: number;
|
|
59
|
+
readonly days: number;
|
|
60
|
+
readonly hours: number;
|
|
61
|
+
readonly minutes: number;
|
|
62
|
+
readonly seconds: number;
|
|
63
|
+
};
|
|
64
|
+
/** Why text is not an ISO 8601 duration. */
|
|
65
|
+
export type DurationError = {
|
|
66
|
+
readonly kind: "duration";
|
|
67
|
+
readonly text: string;
|
|
68
|
+
};
|
|
69
|
+
/** ISO 8601 duration text as a `Duration`: whole years, months, weeks, days, hours and minutes, and seconds with an optional fraction. */
|
|
70
|
+
export declare function parseDuration(text: string): Result<Duration, DurationError>;
|
|
71
|
+
/** A duration from a literal in code, such as a control's cadence; it throws where the literal is not one (a mistake in the code, not in data). */
|
|
72
|
+
export declare function duration(text: string): Duration;
|
|
73
|
+
/**
|
|
74
|
+
* The instant a duration after another, in UTC: years and months first (a day the month lacks becomes its last, so 31 January plus `P1M`
|
|
75
|
+
* is 28 or 29 February), then weeks, days, hours, minutes and seconds; undefined past the year 9999.
|
|
76
|
+
*/
|
|
77
|
+
export declare function addDuration(start: Instant, d: Duration): Instant | undefined;
|
|
78
|
+
/** A role (`security-lead`, `platform/owner`), never a person: who approves a waiver, owns a risk or gives a review. */
|
|
79
|
+
export type Role = Brand<string, "Role">;
|
|
80
|
+
/** Text as a `Role` where it is one (lower-case words joined by `-`, `_`, `.` or `/`), else undefined. An e-mail address is not a role. */
|
|
81
|
+
export declare function roleOf(text: string): Role | undefined;
|
|
82
|
+
/** A compiled glob: `**` any run of characters across `/` (`a/**` everything under `a`, `**\/b` any `b`), `*` any run within one part, `?` one character but `/`; every other character itself. */
|
|
83
|
+
export type Glob = {
|
|
84
|
+
readonly pattern: string;
|
|
85
|
+
readonly test: (text: string) => boolean;
|
|
86
|
+
};
|
|
87
|
+
/** A glob compiled once, to test many paths or ids. */
|
|
88
|
+
export declare function glob(pattern: string): Glob;
|
|
89
|
+
/** One control of a catalog: its id and title, and whatever else the catalog's own constant gives (kept in its type). */
|
|
90
|
+
export type CatalogControl<I extends string = string> = {
|
|
91
|
+
readonly id: I;
|
|
92
|
+
readonly title: string;
|
|
93
|
+
readonly description?: string;
|
|
94
|
+
readonly group?: string;
|
|
95
|
+
};
|
|
96
|
+
/** A reference to one control of one catalog, typed by both: `{ catalog: "example", id: "EX-1" }`. */
|
|
97
|
+
export type ControlRef<C extends string = string, I extends string = string> = {
|
|
98
|
+
readonly catalog: C;
|
|
99
|
+
readonly id: I;
|
|
100
|
+
};
|
|
101
|
+
/** A framework's controls, typed: `C` is its id and `E` the union of its controls, so an id it does not hold does not compile. */
|
|
102
|
+
export type Catalog<C extends string, E extends CatalogControl> = {
|
|
103
|
+
readonly id: C;
|
|
104
|
+
readonly version: string;
|
|
105
|
+
readonly controls: readonly E[];
|
|
106
|
+
readonly ids: readonly E["id"][];
|
|
107
|
+
/** The reference to one of the catalog's controls; an id the catalog does not hold does not compile. */
|
|
108
|
+
readonly control: <I extends E["id"]>(id: I) => ControlRef<C, I>;
|
|
109
|
+
/** One of the catalog's controls, with every field its constant gave. */
|
|
110
|
+
readonly get: <I extends E["id"]>(id: I) => Extract<E, {
|
|
111
|
+
readonly id: I;
|
|
112
|
+
}>;
|
|
113
|
+
/** Whether text read at run time is one of the catalog's ids (a type guard). */
|
|
114
|
+
readonly has: (id: string) => id is E["id"];
|
|
115
|
+
};
|
|
116
|
+
/** The ids of a catalog's controls. */
|
|
117
|
+
export type CatalogIds<K> = K extends Catalog<string, infer E> ? E["id"] : never;
|
|
118
|
+
/**
|
|
119
|
+
* A catalog from its id, its version and a constant tuple of its controls (`[...] as const`, or inline). Two controls with one id are a
|
|
120
|
+
* mistake in the code, and throw.
|
|
121
|
+
*/
|
|
122
|
+
export declare function defineCatalog<const C extends string, const T extends readonly CatalogControl[]>(id: C, version: string, controls: T): Catalog<C, T[number]>;
|
|
123
|
+
/** The relationships of NIST IR 8477's Set Theory Relationship Mapping. */
|
|
124
|
+
export declare const STRM_RELATIONSHIPS: readonly ["equal", "subset-of", "superset-of", "intersects-with", "no-relationship"];
|
|
125
|
+
/** How the first end of a mapping relates to the second: `subset-of` means the first's requirements lie within the second's. */
|
|
126
|
+
export type StrmRelationship = (typeof STRM_RELATIONSHIPS)[number];
|
|
127
|
+
/** How strongly two controls are related, from 1 (barely) to 10 (fully). */
|
|
128
|
+
export type StrmStrength = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
|
|
129
|
+
/** Whether a number is a strength (an integer from 1 to 10), for values read at run time. */
|
|
130
|
+
export declare function isStrmStrength(n: number): n is StrmStrength;
|
|
131
|
+
/** One mapping of a crosswalk, each end typed by its catalog. */
|
|
132
|
+
export type StrmMapping<A extends ControlRef, B extends ControlRef> = {
|
|
133
|
+
readonly from: A;
|
|
134
|
+
readonly to: B;
|
|
135
|
+
readonly relationship: StrmRelationship;
|
|
136
|
+
readonly strength: StrmStrength;
|
|
137
|
+
readonly rationale?: string;
|
|
138
|
+
};
|
|
139
|
+
/** A row of a crosswalk as written: two ids, each one of its catalog's. */
|
|
140
|
+
export type StrmRow<IA extends string, IB extends string> = {
|
|
141
|
+
readonly from: IA;
|
|
142
|
+
readonly to: IB;
|
|
143
|
+
readonly relationship: StrmRelationship;
|
|
144
|
+
readonly strength: StrmStrength;
|
|
145
|
+
readonly rationale?: string;
|
|
146
|
+
};
|
|
147
|
+
/** The mappings from one catalog (at its version) to another. */
|
|
148
|
+
export type Crosswalk<CA extends string, IA extends string, CB extends string, IB extends string> = {
|
|
149
|
+
readonly from: {
|
|
150
|
+
readonly catalog: CA;
|
|
151
|
+
readonly version: string;
|
|
152
|
+
};
|
|
153
|
+
readonly to: {
|
|
154
|
+
readonly catalog: CB;
|
|
155
|
+
readonly version: string;
|
|
156
|
+
};
|
|
157
|
+
readonly mappings: readonly StrmMapping<ControlRef<CA, IA>, ControlRef<CB, IB>>[];
|
|
158
|
+
};
|
|
159
|
+
/** A crosswalk between two catalogs; an id either catalog does not hold does not compile. */
|
|
160
|
+
export declare function defineCrosswalk<CA extends string, EA extends CatalogControl, CB extends string, EB extends CatalogControl>(from: Catalog<CA, EA>, to: Catalog<CB, EB>, rows: readonly StrmRow<NoInfer<EA["id"]>, NoInfer<EB["id"]>>[]): Crosswalk<CA, EA["id"], CB, EB["id"]>;
|
|
161
|
+
/** The relationship read the other way: `subset-of` becomes `superset-of` and back; the others are symmetric. */
|
|
162
|
+
export declare function inverseRelationship(r: StrmRelationship): StrmRelationship;
|
|
163
|
+
/** A crosswalk read from its other end. */
|
|
164
|
+
export declare function invertCrosswalk<CA extends string, IA extends string, CB extends string, IB extends string>(c: Crosswalk<CA, IA, CB, IB>): Crosswalk<CB, IB, CA, IA>;
|
|
165
|
+
/** Every outcome, from the least to the greatest in the order `join` takes. */
|
|
166
|
+
export declare const OUTCOMES: readonly ["not-applicable", "pass", "accepted", "warn", "gap", "fail", "error"];
|
|
167
|
+
/** What a check says, or what it says once waivers are applied: a status, or `accepted` (a `fail` or `warn` an applying waiver accepted). */
|
|
168
|
+
export type Outcome = (typeof OUTCOMES)[number];
|
|
169
|
+
/** What a check says of one subject: `gap` where the evidence it needs does not exist, `error` where it could not judge. */
|
|
170
|
+
export type Status = Exclude<Outcome, "accepted">;
|
|
171
|
+
/** Every status. */
|
|
172
|
+
export declare const STATUSES: readonly Status[];
|
|
173
|
+
/** An outcome's place in the order, from 0 (`not-applicable`) to 6 (`error`). */
|
|
174
|
+
export declare function outcomeRank(o: Outcome): number;
|
|
175
|
+
/**
|
|
176
|
+
* The least upper bound of two outcomes in `not-applicable < pass < accepted < warn < gap < fail < error`: associative, commutative and
|
|
177
|
+
* idempotent, with `not-applicable` its identity and `pass` the identity among the applicable. Two statuses join to a status.
|
|
178
|
+
*/
|
|
179
|
+
export declare function join<O extends Outcome>(a: O, b: O): O;
|
|
180
|
+
/** The join of every outcome, in any order; `not-applicable` where there are none. */
|
|
181
|
+
export declare function joinAll<O extends Outcome>(outcomes: Iterable<O>): O | "not-applicable";
|
|
182
|
+
/** Every severity, from the least to the greatest. */
|
|
183
|
+
export declare const SEVERITIES: readonly ["info", "low", "medium", "high", "critical"];
|
|
184
|
+
/** How much a finding matters. */
|
|
185
|
+
export type Severity = (typeof SEVERITIES)[number];
|
|
186
|
+
/** The greater of two severities. */
|
|
187
|
+
export declare function maxSeverity(a: Severity, b: Severity): Severity;
|
|
188
|
+
/** What a check is judged against: `kind` says what sort of thing it is (`host`, `repository`), `id` which one. */
|
|
189
|
+
export type SubjectRef = {
|
|
190
|
+
readonly kind: string;
|
|
191
|
+
readonly id: string;
|
|
192
|
+
};
|
|
193
|
+
/** What every check is given beside its subject: the instant the assessment is taken at. A pack may ask for more by extending it. */
|
|
194
|
+
export type CheckContext = {
|
|
195
|
+
readonly at: Instant;
|
|
196
|
+
};
|
|
197
|
+
/** What a check says of one subject. Fields left out come from the control (its severity, title and remediation). */
|
|
198
|
+
export type Verdict = {
|
|
199
|
+
readonly status: Status;
|
|
200
|
+
readonly severity?: Severity;
|
|
201
|
+
readonly title?: string;
|
|
202
|
+
readonly detail?: string;
|
|
203
|
+
readonly evidence?: readonly Sha256[];
|
|
204
|
+
readonly remediation?: string;
|
|
205
|
+
};
|
|
206
|
+
/** A verdict from its status and the fields to say beside it. */
|
|
207
|
+
export declare function verdict(status: Status, fields?: Omit<Verdict, "status">): Verdict;
|
|
208
|
+
/** What a check returns: one verdict, or several (none means the control does not apply to the subject). */
|
|
209
|
+
export type Checked = Verdict | readonly Verdict[];
|
|
210
|
+
/** A check of subjects of type `S`, implementing catalog controls. */
|
|
211
|
+
export type Control<S, C extends CheckContext = CheckContext> = {
|
|
212
|
+
readonly id: string;
|
|
213
|
+
readonly title: string;
|
|
214
|
+
readonly description?: string;
|
|
215
|
+
readonly implements: readonly ControlRef[];
|
|
216
|
+
readonly severity: Severity;
|
|
217
|
+
readonly cadence: Duration;
|
|
218
|
+
readonly remediation?: string;
|
|
219
|
+
readonly check: (subject: S, context: C) => Checked | Promise<Checked>;
|
|
220
|
+
};
|
|
221
|
+
/** A control as a finding or a rendering carries it: everything but its check, with its cadence as text. */
|
|
222
|
+
export type ControlSummary = {
|
|
223
|
+
readonly id: string;
|
|
224
|
+
readonly title: string;
|
|
225
|
+
readonly description?: string;
|
|
226
|
+
readonly implements: readonly ControlRef[];
|
|
227
|
+
readonly severity: Severity;
|
|
228
|
+
readonly cadence: string;
|
|
229
|
+
};
|
|
230
|
+
/** A control from its declaration; the subject type is what its check takes. */
|
|
231
|
+
export declare function defineControl<S, C extends CheckContext = CheckContext>(control: Control<S, C>): Control<S, C>;
|
|
232
|
+
/** A control without its check. */
|
|
233
|
+
export declare function controlSummary<S, C extends CheckContext>(c: Control<S, C>): ControlSummary;
|
|
234
|
+
/** The controls over one subject type, with how to name a subject. */
|
|
235
|
+
export type Pack<S, C extends CheckContext = CheckContext> = {
|
|
236
|
+
readonly id: string;
|
|
237
|
+
readonly title: string;
|
|
238
|
+
readonly subjectKind: string;
|
|
239
|
+
readonly subjectId: (subject: S) => string;
|
|
240
|
+
readonly controls: readonly Control<S, C>[];
|
|
241
|
+
};
|
|
242
|
+
/** A pack from its declaration. Two controls with one id are a mistake in the code, and throw. */
|
|
243
|
+
export declare function definePack<S, C extends CheckContext = CheckContext>(pack: Pack<S, C>): Pack<S, C>;
|
|
244
|
+
/** A verdict on one subject under one control, with its detail, evidence and the waiver that accepted it: one type for every harness. */
|
|
245
|
+
export type Finding = {
|
|
246
|
+
readonly control: ControlSummary;
|
|
247
|
+
readonly subject: SubjectRef;
|
|
248
|
+
readonly status: Status;
|
|
249
|
+
readonly outcome: Outcome;
|
|
250
|
+
readonly severity: Severity;
|
|
251
|
+
readonly title: string;
|
|
252
|
+
readonly detail: string;
|
|
253
|
+
readonly evidence: readonly Sha256[];
|
|
254
|
+
readonly remediation?: string;
|
|
255
|
+
/** The id of the waiver that turned `status` into `accepted`. */
|
|
256
|
+
readonly waiver?: string;
|
|
257
|
+
readonly at: Instant;
|
|
258
|
+
};
|
|
259
|
+
/** A stable key of a finding's control and subject, for maps and for names a rendering derives identifiers from. */
|
|
260
|
+
export declare function findingKey(f: Pick<Finding, "control" | "subject">): string;
|
|
261
|
+
/** The findings of a check's verdicts for one subject, each verdict filled in from its control. */
|
|
262
|
+
export declare function findingsOf<S, C extends CheckContext>(control: Control<S, C>, subject: SubjectRef, checked: Checked, at: Instant): readonly Finding[];
|
|
263
|
+
/** One control's check of one subject, as findings; a check that throws or rejects gives one `error` finding and never a rejection. */
|
|
264
|
+
export declare function runCheck<S, C extends CheckContext>(control: Control<S, C>, subject: S, ref: SubjectRef, context: C): Promise<readonly Finding[]>;
|
|
265
|
+
/** A pack run: what was assessed, when, and every finding in the order of the pack's controls and then of the subjects given. */
|
|
266
|
+
export type Assessment = {
|
|
267
|
+
readonly pack: {
|
|
268
|
+
readonly id: string;
|
|
269
|
+
readonly title: string;
|
|
270
|
+
};
|
|
271
|
+
readonly at: Instant;
|
|
272
|
+
readonly controls: readonly ControlSummary[];
|
|
273
|
+
readonly subjects: readonly SubjectRef[];
|
|
274
|
+
readonly findings: readonly Finding[];
|
|
275
|
+
};
|
|
276
|
+
/** The reference of a subject in a pack; a `subjectId` that throws names it by its place, `#0`, `#1`... */
|
|
277
|
+
export declare function subjectRef<S, C extends CheckContext>(pack: Pack<S, C>, subject: S, index: number): SubjectRef;
|
|
278
|
+
/** Every control of a pack over every subject (a check that throws is `error` for that subject alone), then the waivers given applied. */
|
|
279
|
+
export declare function runPack<S, C extends CheckContext>(pack: Pack<S, C>, subjects: readonly S[], context: C, options?: {
|
|
280
|
+
readonly waivers?: readonly Waiver[];
|
|
281
|
+
}): Promise<Assessment>;
|
|
282
|
+
/** A group of findings under one key, with the join of their outcomes and how many have each outcome. */
|
|
283
|
+
export type Section = {
|
|
284
|
+
readonly key: string;
|
|
285
|
+
readonly outcome: Outcome;
|
|
286
|
+
readonly counts: Readonly<Record<Outcome, number>>;
|
|
287
|
+
readonly findings: readonly Finding[];
|
|
288
|
+
};
|
|
289
|
+
/** Findings grouped by the key or keys each one has (a finding with two keys is in both sections), in the order `compare` gives the keys (text order by default). */
|
|
290
|
+
export declare function sections(findings: readonly Finding[], keyOf: (f: Finding) => string | readonly string[], compare?: (a: string, b: string) => number): readonly Section[];
|
|
291
|
+
/** How many findings have each outcome. */
|
|
292
|
+
export declare function countOutcomes(findings: readonly Finding[]): Readonly<Record<Outcome, number>>;
|
|
293
|
+
/** A section key: the finding's control id. */
|
|
294
|
+
export declare const byControl: (f: Finding) => string;
|
|
295
|
+
/** A section key: the finding's subject, `kind:id`. */
|
|
296
|
+
export declare const bySubject: (f: Finding) => string;
|
|
297
|
+
/** A section key: the finding's outcome (sort with `compareOutcomeKeys` for the semilattice's order). */
|
|
298
|
+
export declare const byOutcome: (f: Finding) => string;
|
|
299
|
+
/** A section key: the finding's severity. */
|
|
300
|
+
export declare const bySeverity: (f: Finding) => string;
|
|
301
|
+
/** Section keys: each catalog control the finding's control implements, `catalog:id`. */
|
|
302
|
+
export declare const byRequirement: (f: Finding) => readonly string[];
|
|
303
|
+
/** Outcome keys from the greatest to the least, for `sections(findings, byOutcome, compareOutcomeKeys)`. */
|
|
304
|
+
export declare function compareOutcomeKeys(a: string, b: string): number;
|
|
305
|
+
/** An approved, expiring acceptance of a control's `fail` or `warn` for some subjects. */
|
|
306
|
+
export type Waiver = {
|
|
307
|
+
readonly id: string;
|
|
308
|
+
readonly control: string;
|
|
309
|
+
/** Subject ids, each exact or a glob (`web-*`). */
|
|
310
|
+
readonly subjects: readonly string[];
|
|
311
|
+
readonly reason: string;
|
|
312
|
+
readonly approvedBy: Role;
|
|
313
|
+
readonly grantedAt: Instant;
|
|
314
|
+
readonly expiresAt: Instant;
|
|
315
|
+
};
|
|
316
|
+
/** A waiver as written, before `defineWaiver` checks it: its expiry may be missing. */
|
|
317
|
+
export type WaiverInput = Omit<Waiver, "expiresAt"> & {
|
|
318
|
+
readonly expiresAt?: Instant;
|
|
319
|
+
};
|
|
320
|
+
/** Why a waiver is refused. */
|
|
321
|
+
export type WaiverError = {
|
|
322
|
+
readonly kind: "no-expiry";
|
|
323
|
+
readonly waiver: string;
|
|
324
|
+
} | {
|
|
325
|
+
readonly kind: "expires-before-grant";
|
|
326
|
+
readonly waiver: string;
|
|
327
|
+
} | {
|
|
328
|
+
readonly kind: "no-subjects";
|
|
329
|
+
readonly waiver: string;
|
|
330
|
+
} | {
|
|
331
|
+
readonly kind: "no-reason";
|
|
332
|
+
readonly waiver: string;
|
|
333
|
+
};
|
|
334
|
+
/** A waiver error as one sentence. */
|
|
335
|
+
export declare function formatWaiverError(e: WaiverError): string;
|
|
336
|
+
/** A waiver, or why it is refused: it has no expiry, expires before (or when) it is granted, covers no subject or gives no reason. */
|
|
337
|
+
export declare function defineWaiver(w: WaiverInput): Result<Waiver, WaiverError>;
|
|
338
|
+
/** Where a waiver stands at an instant: not yet granted, in force (from its grant, up to but not including its expiry), or expired. */
|
|
339
|
+
export declare function waiverState(w: Waiver, at: Instant): "pending" | "active" | "expired";
|
|
340
|
+
/** Whether a waiver covers a finding's control and subject and is in force at the instant (whatever the finding's status). */
|
|
341
|
+
export declare function waiverCovers(w: Waiver, f: Pick<Finding, "control" | "subject">, at: Instant): boolean;
|
|
342
|
+
/**
|
|
343
|
+
* The findings with the waivers applied at an instant: a `fail` or `warn` that an active waiver covers becomes `accepted` and carries the
|
|
344
|
+
* waiver's id (the first in id order where several apply); every other finding has its status as its outcome and no waiver.
|
|
345
|
+
*/
|
|
346
|
+
export declare function applyWaivers(findings: readonly Finding[], waivers: readonly Waiver[], at: Instant): readonly Finding[];
|
|
347
|
+
/** An ISO 8601 date-time with a zone, as an `Instant`. */
|
|
348
|
+
export declare const instantDecoder: Decoder<Instant>;
|
|
349
|
+
/** A role. */
|
|
350
|
+
export declare const roleDecoder: Decoder<Role>;
|
|
351
|
+
/** An ISO 8601 duration. */
|
|
352
|
+
export declare const durationDecoder: Decoder<Duration>;
|
|
353
|
+
/** A severity. */
|
|
354
|
+
export declare const severityDecoder: Decoder<Severity>;
|
|
355
|
+
/** A waiver as a file holds it, refused as `defineWaiver` refuses (the error at its path names why). */
|
|
356
|
+
export declare const waiverDecoder: Decoder<Waiver>;
|