@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/host/grc.ts
ADDED
|
@@ -0,0 +1,435 @@
|
|
|
1
|
+
// Spec: 0001-grc FR-021
|
|
2
|
+
/**
|
|
3
|
+
* The GRC host (commons 0001-grc FR-021): waivers, risk registers, impact declarations and any other data the caller has a decoder for,
|
|
4
|
+
* loaded from TOML, YAML, JSON or JSON5 files (chosen by the file's extension) with the kernel's parsers and decoders. An error names the
|
|
5
|
+
* file and either where its text stops parsing (line and column) or the path of the value that does not decode (`$.waivers[1].expiresAt`).
|
|
6
|
+
* A list file holds its items either as its top-level array or under one key (`waivers`, `risks`, `declarations`), so TOML, whose top
|
|
7
|
+
* level is a table, writes them as `[[waivers]]`. TOML dates and times are read as their ISO 8601 text, so a TOML offset date-time
|
|
8
|
+
* decodes as an `Instant`. Packs are code (their checks are functions), so a harness defines them in TypeScript and loads a pack's
|
|
9
|
+
* settings with `loadData` and a decoder of its own.
|
|
10
|
+
*
|
|
11
|
+
* Its signals (FR-019): `runPackObserved` runs a pack as `runPack` does, to the same assessment, and says so in the signals of
|
|
12
|
+
* `GRC_SIGNALS` (0006-signals): a `grc.pack` span for the run, ending `error` where any finding's outcome is `fail` or `error` (its
|
|
13
|
+
* message how many) and `ok` otherwise; a `grc.control` span under it for each control and subject checked, ending `error` where the check's
|
|
14
|
+
* outcome is `fail` or `error` and `ok` otherwise; and each finding a `grc.finding` log record in its check's span whose body is its OCSF
|
|
15
|
+
* Compliance Finding (`ocsfBody`; an integer is an OTLP `intValue`). The record's severity is the finding's (`FINDING_SEVERITY`):
|
|
16
|
+
*
|
|
17
|
+
* | finding severity | log record severity |
|
|
18
|
+
* | --- | --- |
|
|
19
|
+
* | `info`, `low` | 9 `INFO` |
|
|
20
|
+
* | `medium` | 13 `WARN` |
|
|
21
|
+
* | `high` | 17 `ERROR` |
|
|
22
|
+
* | `critical` | 21 `FATAL` |
|
|
23
|
+
*
|
|
24
|
+
* The finding's own severity is the record's `grc.severity` attribute, which tells `info` from `low`.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```ts
|
|
28
|
+
* import { formatLoadError, loadWaivers } from "./grc.ts";
|
|
29
|
+
* const w = await loadWaivers("grc/waivers.toml");
|
|
30
|
+
* if (w.kind === "err") console.error(formatLoadError(w.error));
|
|
31
|
+
* ```
|
|
32
|
+
*
|
|
33
|
+
* @module
|
|
34
|
+
*/
|
|
35
|
+
import {
|
|
36
|
+
absurd,
|
|
37
|
+
array,
|
|
38
|
+
type DecodeError,
|
|
39
|
+
type Decoder,
|
|
40
|
+
describe,
|
|
41
|
+
formatDecodeError,
|
|
42
|
+
err,
|
|
43
|
+
ok,
|
|
44
|
+
type Result,
|
|
45
|
+
} from "@intellectual-frontiers/core";
|
|
46
|
+
import { type ImpactDeclaration, impactDeclarationDecoder, type RiskInput, riskDecoder } from "../assess.ts";
|
|
47
|
+
import {
|
|
48
|
+
type Assessment,
|
|
49
|
+
applyWaivers,
|
|
50
|
+
type CheckContext,
|
|
51
|
+
controlSummary,
|
|
52
|
+
type Finding,
|
|
53
|
+
joinAll,
|
|
54
|
+
countOutcomes,
|
|
55
|
+
type Outcome,
|
|
56
|
+
type Pack,
|
|
57
|
+
runCheck,
|
|
58
|
+
runPack,
|
|
59
|
+
type Severity,
|
|
60
|
+
subjectRef,
|
|
61
|
+
type Waiver,
|
|
62
|
+
waiverDecoder,
|
|
63
|
+
} from "../grc.ts";
|
|
64
|
+
import { parseJson5 } from "@intellectual-frontiers/formats/json5";
|
|
65
|
+
import { complianceFinding, type OcsfComplianceFinding, type OcsfProduct } from "../ocsf.ts";
|
|
66
|
+
import { type AnyMap, type AnyValue, SEVERITY, type Scope, type SeverityNumber } from "@intellectual-frontiers/telemetry/otel";
|
|
67
|
+
import { defineSignals, type Telemetry } from "@intellectual-frontiers/telemetry/signals";
|
|
68
|
+
import { isTomlDateTime, parseToml, type TomlValue } from "@intellectual-frontiers/formats/toml";
|
|
69
|
+
import { parseYaml } from "@intellectual-frontiers/formats/yaml";
|
|
70
|
+
import { readTextFile } from "@intellectual-frontiers/system/fs";
|
|
71
|
+
import { installed, type Pipeline } from "@intellectual-frontiers/telemetry/host/otel";
|
|
72
|
+
|
|
73
|
+
/** A data file's format. */
|
|
74
|
+
export type DataFormat = "toml" | "yaml" | "json" | "json5";
|
|
75
|
+
|
|
76
|
+
const EXTENSIONS: ReadonlyMap<string, DataFormat> = new Map([
|
|
77
|
+
["toml", "toml"],
|
|
78
|
+
["yaml", "yaml"],
|
|
79
|
+
["yml", "yaml"],
|
|
80
|
+
["json", "json"],
|
|
81
|
+
["json5", "json5"],
|
|
82
|
+
]);
|
|
83
|
+
|
|
84
|
+
/** The format of a file by its extension (`.toml`, `.yaml` or `.yml`, `.json`, `.json5`, in any case), or undefined for any other. */
|
|
85
|
+
export function formatOf(path: string): DataFormat | undefined {
|
|
86
|
+
const ext = /\.([A-Za-z0-9]+)$/.exec(path)?.[1]?.toLowerCase();
|
|
87
|
+
return ext === undefined ? undefined : EXTENSIONS.get(ext);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Why a data file could not be loaded, each naming the file. */
|
|
91
|
+
export type LoadError =
|
|
92
|
+
| { readonly kind: "read"; readonly file: string; readonly reason: string }
|
|
93
|
+
| { readonly kind: "format"; readonly file: string }
|
|
94
|
+
| {
|
|
95
|
+
readonly kind: "parse";
|
|
96
|
+
readonly file: string;
|
|
97
|
+
readonly format: DataFormat;
|
|
98
|
+
readonly line: number;
|
|
99
|
+
readonly column: number;
|
|
100
|
+
readonly message: string;
|
|
101
|
+
}
|
|
102
|
+
| { readonly kind: "decode"; readonly file: string; readonly error: DecodeError };
|
|
103
|
+
|
|
104
|
+
/** A load error as one line: `grc/waivers.toml: $.waivers[0].expiresAt: expected ...`. */
|
|
105
|
+
export function formatLoadError(e: LoadError): string {
|
|
106
|
+
switch (e.kind) {
|
|
107
|
+
case "read":
|
|
108
|
+
return `${e.file}: cannot read: ${e.reason}`;
|
|
109
|
+
case "format":
|
|
110
|
+
return `${e.file}: not a .toml, .yaml, .yml, .json or .json5 file`;
|
|
111
|
+
case "parse":
|
|
112
|
+
return `${e.file}:${e.line}:${e.column}: not ${e.format.toUpperCase()}: ${e.message}`;
|
|
113
|
+
case "decode":
|
|
114
|
+
return `${e.file}: ${formatDecodeError(e.error)}`;
|
|
115
|
+
default:
|
|
116
|
+
return absurd(e);
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** A TOML value as plain data: each date or time its ISO 8601 text. */
|
|
121
|
+
function plainToml(v: TomlValue): unknown {
|
|
122
|
+
if (Array.isArray(v)) return v.map(plainToml);
|
|
123
|
+
if (typeof v !== "object") return v;
|
|
124
|
+
if (isTomlDateTime(v)) return v.text;
|
|
125
|
+
const out: Record<string, unknown> = {};
|
|
126
|
+
for (const [k, x] of Object.entries(v)) out[k] = plainToml(x);
|
|
127
|
+
return out;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** The line and column (from 1) of a character offset in a text. */
|
|
131
|
+
function position(text: string, offset: number): { readonly line: number; readonly column: number } {
|
|
132
|
+
const before = text.slice(0, offset).split("\n");
|
|
133
|
+
return { line: before.length, column: (before[before.length - 1] ?? "").length + 1 };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** A text of a format as plain data, or where it stops being that format; `file` names it in the error. */
|
|
137
|
+
export function parseData(text: string, format: DataFormat, file: string): Result<unknown, LoadError> {
|
|
138
|
+
switch (format) {
|
|
139
|
+
case "toml": {
|
|
140
|
+
const r = parseToml(text);
|
|
141
|
+
return r.kind === "ok"
|
|
142
|
+
? ok(plainToml(r.value))
|
|
143
|
+
: err({ kind: "parse", file, format, line: r.error.line, column: r.error.column, message: r.error.message });
|
|
144
|
+
}
|
|
145
|
+
case "yaml": {
|
|
146
|
+
const r = parseYaml(text);
|
|
147
|
+
return r.kind === "ok"
|
|
148
|
+
? r
|
|
149
|
+
: err({ kind: "parse", file, format, line: r.error.line, column: r.error.column, message: r.error.message });
|
|
150
|
+
}
|
|
151
|
+
case "json5": {
|
|
152
|
+
const r = parseJson5(text);
|
|
153
|
+
return r.kind === "ok"
|
|
154
|
+
? r
|
|
155
|
+
: err({ kind: "parse", file, format, line: r.error.line, column: r.error.column, message: r.error.message });
|
|
156
|
+
}
|
|
157
|
+
case "json": {
|
|
158
|
+
try {
|
|
159
|
+
const value: unknown = JSON.parse(text);
|
|
160
|
+
return ok(value);
|
|
161
|
+
} catch (e) {
|
|
162
|
+
const message = e instanceof Error ? e.message : String(e);
|
|
163
|
+
const at = /position (\d+)/.exec(message);
|
|
164
|
+
const { line, column } = at === null ? { line: 1, column: 1 } : position(text, Number(at[1]));
|
|
165
|
+
return err({ kind: "parse", file, format, line, column, message });
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
default:
|
|
169
|
+
return absurd(format);
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** A text of a format decoded, or the error naming `file` and where the text or the value goes wrong. */
|
|
174
|
+
export function decodeData<T>(text: string, format: DataFormat, file: string, decoder: Decoder<T>): Result<T, LoadError> {
|
|
175
|
+
const parsed = parseData(text, format, file);
|
|
176
|
+
if (parsed.kind === "err") return parsed;
|
|
177
|
+
const r = decoder(parsed.value, "$");
|
|
178
|
+
return r.kind === "ok" ? r : err({ kind: "decode", file, error: r.error });
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** A file read, parsed by its extension's format and decoded; or the error naming the file and what went wrong where. */
|
|
182
|
+
export async function loadData<T>(path: string, decoder: Decoder<T>): Promise<Result<T, LoadError>> {
|
|
183
|
+
const format = formatOf(path);
|
|
184
|
+
if (format === undefined) return err({ kind: "format", file: path });
|
|
185
|
+
let text: string;
|
|
186
|
+
try {
|
|
187
|
+
text = await readTextFile(path);
|
|
188
|
+
} catch (e) {
|
|
189
|
+
return err({ kind: "read", file: path, reason: e instanceof Error ? e.message : String(e) });
|
|
190
|
+
}
|
|
191
|
+
return decodeData(text.replace(/^\ufeff/, ""), format, path, decoder);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** A list of items decoded from either a top-level array or the array under `key` of a top-level table (`[[key]]` in TOML). */
|
|
195
|
+
export function listOf<T>(key: string, item: Decoder<T>): Decoder<readonly T[]> {
|
|
196
|
+
const items = array(item);
|
|
197
|
+
return (input, path = "$") => {
|
|
198
|
+
if (Array.isArray(input)) return items(input, path);
|
|
199
|
+
if (typeof input === "object" && input !== null && key in input) {
|
|
200
|
+
const inner: unknown = Reflect.get(input, key);
|
|
201
|
+
return items(inner, `${path}.${key}`);
|
|
202
|
+
}
|
|
203
|
+
return err({ kind: "decode", path, expected: `an array, or a table with an array \`${key}\``, found: describe(input) });
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** The waivers a file holds (a list, or under `waivers`), each refused as `defineWaiver` refuses (no expiry, an expiry before its grant, ...). */
|
|
208
|
+
export function loadWaivers(path: string): Promise<Result<readonly Waiver[], LoadError>> {
|
|
209
|
+
return loadData(path, listOf("waivers", waiverDecoder));
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** The risks a file holds (a list, or under `risks`), for `riskRegister`. */
|
|
213
|
+
export function loadRisks(path: string): Promise<Result<readonly RiskInput[], LoadError>> {
|
|
214
|
+
return loadData(path, listOf("risks", riskDecoder));
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** The impact declarations a file holds (a list, or under `declarations`), for `gate`. */
|
|
218
|
+
export function loadImpactDeclarations(path: string): Promise<Result<readonly ImpactDeclaration[], LoadError>> {
|
|
219
|
+
return loadData(path, listOf("declarations", impactDeclarationDecoder));
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
// ---------------------------------------------------------------------------------------------------------------------------- signals (FR-019)
|
|
223
|
+
|
|
224
|
+
/** The signals of a pack run (0006-signals FR-009): the run's span, a span for each check, and a log record for each finding. */
|
|
225
|
+
export const GRC_SIGNALS = defineSignals({
|
|
226
|
+
"grc.pack": {
|
|
227
|
+
signal: "span",
|
|
228
|
+
role: "step",
|
|
229
|
+
description: "A pack run: its id, how many controls and subjects, and how many findings of each outcome.",
|
|
230
|
+
attributes: {
|
|
231
|
+
"grc.pack.id": "string",
|
|
232
|
+
"grc.pack.controls": "int",
|
|
233
|
+
"grc.pack.subjects": "int",
|
|
234
|
+
"grc.pack.findings?": "int",
|
|
235
|
+
"grc.outcome?": "string",
|
|
236
|
+
"grc.findings.not-applicable?": "int",
|
|
237
|
+
"grc.findings.pass?": "int",
|
|
238
|
+
"grc.findings.accepted?": "int",
|
|
239
|
+
"grc.findings.warn?": "int",
|
|
240
|
+
"grc.findings.gap?": "int",
|
|
241
|
+
"grc.findings.fail?": "int",
|
|
242
|
+
"grc.findings.error?": "int",
|
|
243
|
+
},
|
|
244
|
+
},
|
|
245
|
+
"grc.control": {
|
|
246
|
+
signal: "span",
|
|
247
|
+
role: "detail",
|
|
248
|
+
description: "One control's check of one subject: the join of its findings' statuses and of their outcomes, waivers applied.",
|
|
249
|
+
attributes: {
|
|
250
|
+
"grc.pack.id": "string",
|
|
251
|
+
"grc.control.id": "string",
|
|
252
|
+
"grc.subject.kind": "string",
|
|
253
|
+
"grc.subject.id": "string",
|
|
254
|
+
"grc.status?": "string",
|
|
255
|
+
"grc.outcome?": "string",
|
|
256
|
+
"grc.findings?": "int",
|
|
257
|
+
},
|
|
258
|
+
},
|
|
259
|
+
"grc.finding": {
|
|
260
|
+
signal: "log",
|
|
261
|
+
// Declared INFO; each record is emitted with its finding's severity (FINDING_SEVERITY).
|
|
262
|
+
severity: SEVERITY.INFO,
|
|
263
|
+
role: "none",
|
|
264
|
+
description: "A finding; its body is the finding's OCSF Compliance Finding (class 2003), its severity the finding's.",
|
|
265
|
+
attributes: {
|
|
266
|
+
"grc.pack.id": "string",
|
|
267
|
+
"grc.control.id": "string",
|
|
268
|
+
"grc.subject.kind": "string",
|
|
269
|
+
"grc.subject.id": "string",
|
|
270
|
+
"grc.status": "string",
|
|
271
|
+
"grc.outcome": "string",
|
|
272
|
+
"grc.severity": "string",
|
|
273
|
+
"grc.waiver.id?": "string",
|
|
274
|
+
},
|
|
275
|
+
},
|
|
276
|
+
});
|
|
277
|
+
|
|
278
|
+
/** The kinds of the GRC registry. */
|
|
279
|
+
export type GrcKinds = (typeof GRC_SIGNALS)["kinds"];
|
|
280
|
+
|
|
281
|
+
/** The scope of the GRC signals. */
|
|
282
|
+
export const GRC_SCOPE: Scope = { name: "ifc-ts/grc" };
|
|
283
|
+
|
|
284
|
+
/** The log record severity of a finding of each severity (the table in the module's documentation). */
|
|
285
|
+
export const FINDING_SEVERITY: Readonly<Record<Severity, SeverityNumber>> = {
|
|
286
|
+
info: SEVERITY.INFO,
|
|
287
|
+
low: SEVERITY.INFO,
|
|
288
|
+
medium: SEVERITY.WARN,
|
|
289
|
+
high: SEVERITY.ERROR,
|
|
290
|
+
critical: SEVERITY.FATAL,
|
|
291
|
+
};
|
|
292
|
+
|
|
293
|
+
/** A JSON value as an OTLP `AnyValue`: an integer as an `intValue` (a `bigint`), any other number a `doubleValue`, `null` left out. */
|
|
294
|
+
export function toAnyValue(json: unknown): AnyValue | undefined {
|
|
295
|
+
if (typeof json === "string" || typeof json === "boolean") return json;
|
|
296
|
+
if (typeof json === "number") return Number.isSafeInteger(json) ? BigInt(json) : json;
|
|
297
|
+
if (Array.isArray(json)) return json.flatMap((v: unknown) => toAnyValue(v) ?? []);
|
|
298
|
+
return typeof json === "object" && json !== null ? toAnyMap(json) : undefined;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
function toAnyMap(json: object): AnyMap {
|
|
302
|
+
const out: Record<string, AnyValue> = {};
|
|
303
|
+
for (const [k, v] of Object.entries(json)) {
|
|
304
|
+
const a = toAnyValue(v);
|
|
305
|
+
if (a !== undefined) Object.defineProperty(out, k, { value: a, enumerable: true, writable: true, configurable: true });
|
|
306
|
+
}
|
|
307
|
+
return out;
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** An OTLP `AnyValue` as JSON, undoing `toAnyValue`: an integer a `number`, bytes a list of numbers (an OCSF body holds none). */
|
|
311
|
+
export function fromAnyValue(value: AnyValue): unknown {
|
|
312
|
+
if (typeof value === "bigint") return Number(value);
|
|
313
|
+
if (value instanceof Uint8Array) return [...value];
|
|
314
|
+
if (typeof value !== "object") return value;
|
|
315
|
+
if (Array.isArray(value)) return value.map((v: AnyValue) => fromAnyValue(v));
|
|
316
|
+
const out: Record<string, unknown> = {};
|
|
317
|
+
for (const [k, v] of Object.entries(value)) {
|
|
318
|
+
Object.defineProperty(out, k, { value: fromAnyValue(v), enumerable: true, writable: true, configurable: true });
|
|
319
|
+
}
|
|
320
|
+
return out;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/** An OCSF Compliance Finding as a log record's body: an OTLP map, each integer an `intValue`. */
|
|
324
|
+
export function ocsfBody(doc: OcsfComplianceFinding): AnyMap {
|
|
325
|
+
return toAnyMap(doc);
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** What `runPackObserved` takes beside the pack, its subjects and the context. */
|
|
329
|
+
export type ObservedOptions = {
|
|
330
|
+
readonly waivers?: readonly Waiver[];
|
|
331
|
+
/** The telemetry to say the run in; the installed pipeline's by default, and none (the run unobserved) where none is installed. */
|
|
332
|
+
readonly telemetry?: Telemetry<GrcKinds>;
|
|
333
|
+
/** The product the OCSF documents name as their writer. */
|
|
334
|
+
readonly product: OcsfProduct;
|
|
335
|
+
};
|
|
336
|
+
|
|
337
|
+
const telemetries = new WeakMap<Pipeline, Telemetry<GrcKinds>>();
|
|
338
|
+
|
|
339
|
+
/** The GRC telemetry of the installed pipeline (one for each pipeline), or undefined where none is installed. */
|
|
340
|
+
export function installedGrcTelemetry(): Telemetry<GrcKinds> | undefined {
|
|
341
|
+
const pipeline = installed();
|
|
342
|
+
if (pipeline === undefined) return undefined;
|
|
343
|
+
let t = telemetries.get(pipeline);
|
|
344
|
+
if (t === undefined) {
|
|
345
|
+
t = pipeline.telemetry(GRC_SIGNALS, GRC_SCOPE);
|
|
346
|
+
telemetries.set(pipeline, t);
|
|
347
|
+
}
|
|
348
|
+
return t;
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
const failing = (o: Outcome): boolean => o === "fail" || o === "error";
|
|
352
|
+
|
|
353
|
+
/** What a span that ends `error` returns: its status message (the span's `describeError` reads `message`) and the value all the same. */
|
|
354
|
+
type Failing<T> = { readonly message: string; readonly value: T };
|
|
355
|
+
|
|
356
|
+
const countAttributes = (findings: readonly Finding[]): Readonly<Record<`grc.findings.${Outcome}`, number>> => {
|
|
357
|
+
const c = countOutcomes(findings);
|
|
358
|
+
return {
|
|
359
|
+
"grc.findings.not-applicable": c["not-applicable"],
|
|
360
|
+
"grc.findings.pass": c.pass,
|
|
361
|
+
"grc.findings.accepted": c.accepted,
|
|
362
|
+
"grc.findings.warn": c.warn,
|
|
363
|
+
"grc.findings.gap": c.gap,
|
|
364
|
+
"grc.findings.fail": c.fail,
|
|
365
|
+
"grc.findings.error": c.error,
|
|
366
|
+
};
|
|
367
|
+
};
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* A pack run as `runPack` runs it, to the same assessment, said in signals (FR-019): a `grc.pack` span, a `grc.control` span for each
|
|
371
|
+
* control and subject in the order `runPack` checks them (`error` where its outcome is `fail` or `error`, else `ok`), and a log record of
|
|
372
|
+
* each finding, waivers applied, whose body is its OCSF Compliance Finding. With no telemetry given or installed, it is `runPack`.
|
|
373
|
+
*/
|
|
374
|
+
export async function runPackObserved<S, C extends CheckContext>(
|
|
375
|
+
pack: Pack<S, C>,
|
|
376
|
+
subjects: readonly S[],
|
|
377
|
+
context: C,
|
|
378
|
+
options: ObservedOptions,
|
|
379
|
+
): Promise<Assessment> {
|
|
380
|
+
const waivers = options.waivers ?? [];
|
|
381
|
+
const telemetry = options.telemetry ?? installedGrcTelemetry();
|
|
382
|
+
if (telemetry === undefined) return runPack(pack, subjects, context, { waivers });
|
|
383
|
+
const refs = subjects.map((s, i) => subjectRef(pack, s, i));
|
|
384
|
+
const start = { "grc.pack.id": pack.id, "grc.pack.controls": pack.controls.length, "grc.pack.subjects": subjects.length };
|
|
385
|
+
const run = await telemetry.span("grc.pack", start, async (packSpan): Promise<Result<Assessment, Failing<Assessment>>> => {
|
|
386
|
+
const findings: Finding[] = [];
|
|
387
|
+
for (const control of pack.controls) {
|
|
388
|
+
for (const [i, subject] of subjects.entries()) {
|
|
389
|
+
const ref = refs[i] ?? { kind: pack.subjectKind, id: `#${i}` };
|
|
390
|
+
const at = { "grc.pack.id": pack.id, "grc.control.id": control.id, "grc.subject.kind": ref.kind, "grc.subject.id": ref.id };
|
|
391
|
+
const checked = await packSpan.span(
|
|
392
|
+
"grc.control",
|
|
393
|
+
at,
|
|
394
|
+
async (span): Promise<Result<readonly Finding[], Failing<readonly Finding[]>>> => {
|
|
395
|
+
// Waivers apply to each finding alone, so applying them to one check's findings is applying them to the run's.
|
|
396
|
+
const found = applyWaivers(await runCheck(control, subject, ref, context), waivers, context.at);
|
|
397
|
+
const status = joinAll(found.map((f) => f.status));
|
|
398
|
+
const outcome = joinAll(found.map((f) => f.outcome));
|
|
399
|
+
span.set({ "grc.status": status, "grc.outcome": outcome, "grc.findings": found.length });
|
|
400
|
+
for (const f of found) {
|
|
401
|
+
span.log(
|
|
402
|
+
"grc.finding",
|
|
403
|
+
{
|
|
404
|
+
...at,
|
|
405
|
+
"grc.status": f.status,
|
|
406
|
+
"grc.outcome": f.outcome,
|
|
407
|
+
"grc.severity": f.severity,
|
|
408
|
+
...(f.waiver === undefined ? {} : { "grc.waiver.id": f.waiver }),
|
|
409
|
+
},
|
|
410
|
+
ocsfBody(complianceFinding(f, { product: options.product })),
|
|
411
|
+
{ severity: FINDING_SEVERITY[f.severity] },
|
|
412
|
+
);
|
|
413
|
+
}
|
|
414
|
+
return failing(outcome) ? err({ message: `${control.id} ${outcome} for ${ref.kind} ${ref.id}`, value: found }) : ok(found);
|
|
415
|
+
},
|
|
416
|
+
);
|
|
417
|
+
// A failing check's span ends `error`; its findings are the assessment's all the same.
|
|
418
|
+
findings.push(...(checked.kind === "ok" ? checked.value : checked.error.value));
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
const outcome = joinAll(findings.map((f) => f.outcome));
|
|
422
|
+
packSpan.set({ "grc.pack.findings": findings.length, "grc.outcome": outcome, ...countAttributes(findings) });
|
|
423
|
+
const assessment: Assessment = {
|
|
424
|
+
pack: { id: pack.id, title: pack.title },
|
|
425
|
+
at: context.at,
|
|
426
|
+
controls: pack.controls.map(controlSummary),
|
|
427
|
+
subjects: refs,
|
|
428
|
+
findings,
|
|
429
|
+
};
|
|
430
|
+
if (!failing(outcome)) return ok(assessment);
|
|
431
|
+
const n = findings.filter((f) => failing(f.outcome)).length;
|
|
432
|
+
return err({ message: `${pack.id}: ${n} of ${findings.length} findings fail or error`, value: assessment });
|
|
433
|
+
});
|
|
434
|
+
return run.kind === "ok" ? run.value : run.error.value;
|
|
435
|
+
}
|
package/src/host/mod.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// Spec: 0001-grc FR-019
|
|
2
|
+
/**
|
|
3
|
+
* The host of GRC engineering (commons 0007-grc): `grc` loads the settings of packs, waivers, risk registers and impact declarations from TOML, YAML, JSON and JSON5 files and runs a pack as signals, and `sign`
|
|
4
|
+
* signs and verifies with `ssh-keygen -Y` and with Web Crypto keys through DSSE, behind one signer interface. It touches the host (files, processes) and the pipeline of the telemetry that a process installs.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { sign } from "@intellectual-frontiers/grc/host";
|
|
9
|
+
* typeof sign; // "object"
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
export * as grc from "./grc.ts";
|
|
15
|
+
export * as sign from "./sign.ts";
|