@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/host/grc.js
ADDED
|
@@ -0,0 +1,358 @@
|
|
|
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 { absurd, array, describe, formatDecodeError, err, ok, } from "@intellectual-frontiers/core";
|
|
36
|
+
import { impactDeclarationDecoder, riskDecoder } from "../assess.js";
|
|
37
|
+
import { applyWaivers, controlSummary, joinAll, countOutcomes, runCheck, runPack, subjectRef, waiverDecoder, } from "../grc.js";
|
|
38
|
+
import { parseJson5 } from "@intellectual-frontiers/formats/json5";
|
|
39
|
+
import { complianceFinding } from "../ocsf.js";
|
|
40
|
+
import { SEVERITY } from "@intellectual-frontiers/telemetry/otel";
|
|
41
|
+
import { defineSignals } from "@intellectual-frontiers/telemetry/signals";
|
|
42
|
+
import { isTomlDateTime, parseToml } from "@intellectual-frontiers/formats/toml";
|
|
43
|
+
import { parseYaml } from "@intellectual-frontiers/formats/yaml";
|
|
44
|
+
import { readTextFile } from "@intellectual-frontiers/system/fs";
|
|
45
|
+
import { installed } from "@intellectual-frontiers/telemetry/host/otel";
|
|
46
|
+
const EXTENSIONS = new Map([
|
|
47
|
+
["toml", "toml"],
|
|
48
|
+
["yaml", "yaml"],
|
|
49
|
+
["yml", "yaml"],
|
|
50
|
+
["json", "json"],
|
|
51
|
+
["json5", "json5"],
|
|
52
|
+
]);
|
|
53
|
+
/** The format of a file by its extension (`.toml`, `.yaml` or `.yml`, `.json`, `.json5`, in any case), or undefined for any other. */
|
|
54
|
+
export function formatOf(path) {
|
|
55
|
+
const ext = /\.([A-Za-z0-9]+)$/.exec(path)?.[1]?.toLowerCase();
|
|
56
|
+
return ext === undefined ? undefined : EXTENSIONS.get(ext);
|
|
57
|
+
}
|
|
58
|
+
/** A load error as one line: `grc/waivers.toml: $.waivers[0].expiresAt: expected ...`. */
|
|
59
|
+
export function formatLoadError(e) {
|
|
60
|
+
switch (e.kind) {
|
|
61
|
+
case "read":
|
|
62
|
+
return `${e.file}: cannot read: ${e.reason}`;
|
|
63
|
+
case "format":
|
|
64
|
+
return `${e.file}: not a .toml, .yaml, .yml, .json or .json5 file`;
|
|
65
|
+
case "parse":
|
|
66
|
+
return `${e.file}:${e.line}:${e.column}: not ${e.format.toUpperCase()}: ${e.message}`;
|
|
67
|
+
case "decode":
|
|
68
|
+
return `${e.file}: ${formatDecodeError(e.error)}`;
|
|
69
|
+
default:
|
|
70
|
+
return absurd(e);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
/** A TOML value as plain data: each date or time its ISO 8601 text. */
|
|
74
|
+
function plainToml(v) {
|
|
75
|
+
if (Array.isArray(v))
|
|
76
|
+
return v.map(plainToml);
|
|
77
|
+
if (typeof v !== "object")
|
|
78
|
+
return v;
|
|
79
|
+
if (isTomlDateTime(v))
|
|
80
|
+
return v.text;
|
|
81
|
+
const out = {};
|
|
82
|
+
for (const [k, x] of Object.entries(v))
|
|
83
|
+
out[k] = plainToml(x);
|
|
84
|
+
return out;
|
|
85
|
+
}
|
|
86
|
+
/** The line and column (from 1) of a character offset in a text. */
|
|
87
|
+
function position(text, offset) {
|
|
88
|
+
const before = text.slice(0, offset).split("\n");
|
|
89
|
+
return { line: before.length, column: (before[before.length - 1] ?? "").length + 1 };
|
|
90
|
+
}
|
|
91
|
+
/** A text of a format as plain data, or where it stops being that format; `file` names it in the error. */
|
|
92
|
+
export function parseData(text, format, file) {
|
|
93
|
+
switch (format) {
|
|
94
|
+
case "toml": {
|
|
95
|
+
const r = parseToml(text);
|
|
96
|
+
return r.kind === "ok"
|
|
97
|
+
? ok(plainToml(r.value))
|
|
98
|
+
: err({ kind: "parse", file, format, line: r.error.line, column: r.error.column, message: r.error.message });
|
|
99
|
+
}
|
|
100
|
+
case "yaml": {
|
|
101
|
+
const r = parseYaml(text);
|
|
102
|
+
return r.kind === "ok"
|
|
103
|
+
? r
|
|
104
|
+
: err({ kind: "parse", file, format, line: r.error.line, column: r.error.column, message: r.error.message });
|
|
105
|
+
}
|
|
106
|
+
case "json5": {
|
|
107
|
+
const r = parseJson5(text);
|
|
108
|
+
return r.kind === "ok"
|
|
109
|
+
? r
|
|
110
|
+
: err({ kind: "parse", file, format, line: r.error.line, column: r.error.column, message: r.error.message });
|
|
111
|
+
}
|
|
112
|
+
case "json": {
|
|
113
|
+
try {
|
|
114
|
+
const value = JSON.parse(text);
|
|
115
|
+
return ok(value);
|
|
116
|
+
}
|
|
117
|
+
catch (e) {
|
|
118
|
+
const message = e instanceof Error ? e.message : String(e);
|
|
119
|
+
const at = /position (\d+)/.exec(message);
|
|
120
|
+
const { line, column } = at === null ? { line: 1, column: 1 } : position(text, Number(at[1]));
|
|
121
|
+
return err({ kind: "parse", file, format, line, column, message });
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
default:
|
|
125
|
+
return absurd(format);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
/** A text of a format decoded, or the error naming `file` and where the text or the value goes wrong. */
|
|
129
|
+
export function decodeData(text, format, file, decoder) {
|
|
130
|
+
const parsed = parseData(text, format, file);
|
|
131
|
+
if (parsed.kind === "err")
|
|
132
|
+
return parsed;
|
|
133
|
+
const r = decoder(parsed.value, "$");
|
|
134
|
+
return r.kind === "ok" ? r : err({ kind: "decode", file, error: r.error });
|
|
135
|
+
}
|
|
136
|
+
/** A file read, parsed by its extension's format and decoded; or the error naming the file and what went wrong where. */
|
|
137
|
+
export async function loadData(path, decoder) {
|
|
138
|
+
const format = formatOf(path);
|
|
139
|
+
if (format === undefined)
|
|
140
|
+
return err({ kind: "format", file: path });
|
|
141
|
+
let text;
|
|
142
|
+
try {
|
|
143
|
+
text = await readTextFile(path);
|
|
144
|
+
}
|
|
145
|
+
catch (e) {
|
|
146
|
+
return err({ kind: "read", file: path, reason: e instanceof Error ? e.message : String(e) });
|
|
147
|
+
}
|
|
148
|
+
return decodeData(text.replace(/^\ufeff/, ""), format, path, decoder);
|
|
149
|
+
}
|
|
150
|
+
/** A list of items decoded from either a top-level array or the array under `key` of a top-level table (`[[key]]` in TOML). */
|
|
151
|
+
export function listOf(key, item) {
|
|
152
|
+
const items = array(item);
|
|
153
|
+
return (input, path = "$") => {
|
|
154
|
+
if (Array.isArray(input))
|
|
155
|
+
return items(input, path);
|
|
156
|
+
if (typeof input === "object" && input !== null && key in input) {
|
|
157
|
+
const inner = Reflect.get(input, key);
|
|
158
|
+
return items(inner, `${path}.${key}`);
|
|
159
|
+
}
|
|
160
|
+
return err({ kind: "decode", path, expected: `an array, or a table with an array \`${key}\``, found: describe(input) });
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
/** The waivers a file holds (a list, or under `waivers`), each refused as `defineWaiver` refuses (no expiry, an expiry before its grant, ...). */
|
|
164
|
+
export function loadWaivers(path) {
|
|
165
|
+
return loadData(path, listOf("waivers", waiverDecoder));
|
|
166
|
+
}
|
|
167
|
+
/** The risks a file holds (a list, or under `risks`), for `riskRegister`. */
|
|
168
|
+
export function loadRisks(path) {
|
|
169
|
+
return loadData(path, listOf("risks", riskDecoder));
|
|
170
|
+
}
|
|
171
|
+
/** The impact declarations a file holds (a list, or under `declarations`), for `gate`. */
|
|
172
|
+
export function loadImpactDeclarations(path) {
|
|
173
|
+
return loadData(path, listOf("declarations", impactDeclarationDecoder));
|
|
174
|
+
}
|
|
175
|
+
// ---------------------------------------------------------------------------------------------------------------------------- signals (FR-019)
|
|
176
|
+
/** 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. */
|
|
177
|
+
export const GRC_SIGNALS = defineSignals({
|
|
178
|
+
"grc.pack": {
|
|
179
|
+
signal: "span",
|
|
180
|
+
role: "step",
|
|
181
|
+
description: "A pack run: its id, how many controls and subjects, and how many findings of each outcome.",
|
|
182
|
+
attributes: {
|
|
183
|
+
"grc.pack.id": "string",
|
|
184
|
+
"grc.pack.controls": "int",
|
|
185
|
+
"grc.pack.subjects": "int",
|
|
186
|
+
"grc.pack.findings?": "int",
|
|
187
|
+
"grc.outcome?": "string",
|
|
188
|
+
"grc.findings.not-applicable?": "int",
|
|
189
|
+
"grc.findings.pass?": "int",
|
|
190
|
+
"grc.findings.accepted?": "int",
|
|
191
|
+
"grc.findings.warn?": "int",
|
|
192
|
+
"grc.findings.gap?": "int",
|
|
193
|
+
"grc.findings.fail?": "int",
|
|
194
|
+
"grc.findings.error?": "int",
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
"grc.control": {
|
|
198
|
+
signal: "span",
|
|
199
|
+
role: "detail",
|
|
200
|
+
description: "One control's check of one subject: the join of its findings' statuses and of their outcomes, waivers applied.",
|
|
201
|
+
attributes: {
|
|
202
|
+
"grc.pack.id": "string",
|
|
203
|
+
"grc.control.id": "string",
|
|
204
|
+
"grc.subject.kind": "string",
|
|
205
|
+
"grc.subject.id": "string",
|
|
206
|
+
"grc.status?": "string",
|
|
207
|
+
"grc.outcome?": "string",
|
|
208
|
+
"grc.findings?": "int",
|
|
209
|
+
},
|
|
210
|
+
},
|
|
211
|
+
"grc.finding": {
|
|
212
|
+
signal: "log",
|
|
213
|
+
// Declared INFO; each record is emitted with its finding's severity (FINDING_SEVERITY).
|
|
214
|
+
severity: SEVERITY.INFO,
|
|
215
|
+
role: "none",
|
|
216
|
+
description: "A finding; its body is the finding's OCSF Compliance Finding (class 2003), its severity the finding's.",
|
|
217
|
+
attributes: {
|
|
218
|
+
"grc.pack.id": "string",
|
|
219
|
+
"grc.control.id": "string",
|
|
220
|
+
"grc.subject.kind": "string",
|
|
221
|
+
"grc.subject.id": "string",
|
|
222
|
+
"grc.status": "string",
|
|
223
|
+
"grc.outcome": "string",
|
|
224
|
+
"grc.severity": "string",
|
|
225
|
+
"grc.waiver.id?": "string",
|
|
226
|
+
},
|
|
227
|
+
},
|
|
228
|
+
});
|
|
229
|
+
/** The scope of the GRC signals. */
|
|
230
|
+
export const GRC_SCOPE = { name: "ifc-ts/grc" };
|
|
231
|
+
/** The log record severity of a finding of each severity (the table in the module's documentation). */
|
|
232
|
+
export const FINDING_SEVERITY = {
|
|
233
|
+
info: SEVERITY.INFO,
|
|
234
|
+
low: SEVERITY.INFO,
|
|
235
|
+
medium: SEVERITY.WARN,
|
|
236
|
+
high: SEVERITY.ERROR,
|
|
237
|
+
critical: SEVERITY.FATAL,
|
|
238
|
+
};
|
|
239
|
+
/** A JSON value as an OTLP `AnyValue`: an integer as an `intValue` (a `bigint`), any other number a `doubleValue`, `null` left out. */
|
|
240
|
+
export function toAnyValue(json) {
|
|
241
|
+
if (typeof json === "string" || typeof json === "boolean")
|
|
242
|
+
return json;
|
|
243
|
+
if (typeof json === "number")
|
|
244
|
+
return Number.isSafeInteger(json) ? BigInt(json) : json;
|
|
245
|
+
if (Array.isArray(json))
|
|
246
|
+
return json.flatMap((v) => toAnyValue(v) ?? []);
|
|
247
|
+
return typeof json === "object" && json !== null ? toAnyMap(json) : undefined;
|
|
248
|
+
}
|
|
249
|
+
function toAnyMap(json) {
|
|
250
|
+
const out = {};
|
|
251
|
+
for (const [k, v] of Object.entries(json)) {
|
|
252
|
+
const a = toAnyValue(v);
|
|
253
|
+
if (a !== undefined)
|
|
254
|
+
Object.defineProperty(out, k, { value: a, enumerable: true, writable: true, configurable: true });
|
|
255
|
+
}
|
|
256
|
+
return out;
|
|
257
|
+
}
|
|
258
|
+
/** An OTLP `AnyValue` as JSON, undoing `toAnyValue`: an integer a `number`, bytes a list of numbers (an OCSF body holds none). */
|
|
259
|
+
export function fromAnyValue(value) {
|
|
260
|
+
if (typeof value === "bigint")
|
|
261
|
+
return Number(value);
|
|
262
|
+
if (value instanceof Uint8Array)
|
|
263
|
+
return [...value];
|
|
264
|
+
if (typeof value !== "object")
|
|
265
|
+
return value;
|
|
266
|
+
if (Array.isArray(value))
|
|
267
|
+
return value.map((v) => fromAnyValue(v));
|
|
268
|
+
const out = {};
|
|
269
|
+
for (const [k, v] of Object.entries(value)) {
|
|
270
|
+
Object.defineProperty(out, k, { value: fromAnyValue(v), enumerable: true, writable: true, configurable: true });
|
|
271
|
+
}
|
|
272
|
+
return out;
|
|
273
|
+
}
|
|
274
|
+
/** An OCSF Compliance Finding as a log record's body: an OTLP map, each integer an `intValue`. */
|
|
275
|
+
export function ocsfBody(doc) {
|
|
276
|
+
return toAnyMap(doc);
|
|
277
|
+
}
|
|
278
|
+
const telemetries = new WeakMap();
|
|
279
|
+
/** The GRC telemetry of the installed pipeline (one for each pipeline), or undefined where none is installed. */
|
|
280
|
+
export function installedGrcTelemetry() {
|
|
281
|
+
const pipeline = installed();
|
|
282
|
+
if (pipeline === undefined)
|
|
283
|
+
return undefined;
|
|
284
|
+
let t = telemetries.get(pipeline);
|
|
285
|
+
if (t === undefined) {
|
|
286
|
+
t = pipeline.telemetry(GRC_SIGNALS, GRC_SCOPE);
|
|
287
|
+
telemetries.set(pipeline, t);
|
|
288
|
+
}
|
|
289
|
+
return t;
|
|
290
|
+
}
|
|
291
|
+
const failing = (o) => o === "fail" || o === "error";
|
|
292
|
+
const countAttributes = (findings) => {
|
|
293
|
+
const c = countOutcomes(findings);
|
|
294
|
+
return {
|
|
295
|
+
"grc.findings.not-applicable": c["not-applicable"],
|
|
296
|
+
"grc.findings.pass": c.pass,
|
|
297
|
+
"grc.findings.accepted": c.accepted,
|
|
298
|
+
"grc.findings.warn": c.warn,
|
|
299
|
+
"grc.findings.gap": c.gap,
|
|
300
|
+
"grc.findings.fail": c.fail,
|
|
301
|
+
"grc.findings.error": c.error,
|
|
302
|
+
};
|
|
303
|
+
};
|
|
304
|
+
/**
|
|
305
|
+
* 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
|
|
306
|
+
* control and subject in the order `runPack` checks them (`error` where its outcome is `fail` or `error`, else `ok`), and a log record of
|
|
307
|
+
* each finding, waivers applied, whose body is its OCSF Compliance Finding. With no telemetry given or installed, it is `runPack`.
|
|
308
|
+
*/
|
|
309
|
+
export async function runPackObserved(pack, subjects, context, options) {
|
|
310
|
+
const waivers = options.waivers ?? [];
|
|
311
|
+
const telemetry = options.telemetry ?? installedGrcTelemetry();
|
|
312
|
+
if (telemetry === undefined)
|
|
313
|
+
return runPack(pack, subjects, context, { waivers });
|
|
314
|
+
const refs = subjects.map((s, i) => subjectRef(pack, s, i));
|
|
315
|
+
const start = { "grc.pack.id": pack.id, "grc.pack.controls": pack.controls.length, "grc.pack.subjects": subjects.length };
|
|
316
|
+
const run = await telemetry.span("grc.pack", start, async (packSpan) => {
|
|
317
|
+
const findings = [];
|
|
318
|
+
for (const control of pack.controls) {
|
|
319
|
+
for (const [i, subject] of subjects.entries()) {
|
|
320
|
+
const ref = refs[i] ?? { kind: pack.subjectKind, id: `#${i}` };
|
|
321
|
+
const at = { "grc.pack.id": pack.id, "grc.control.id": control.id, "grc.subject.kind": ref.kind, "grc.subject.id": ref.id };
|
|
322
|
+
const checked = await packSpan.span("grc.control", at, async (span) => {
|
|
323
|
+
// Waivers apply to each finding alone, so applying them to one check's findings is applying them to the run's.
|
|
324
|
+
const found = applyWaivers(await runCheck(control, subject, ref, context), waivers, context.at);
|
|
325
|
+
const status = joinAll(found.map((f) => f.status));
|
|
326
|
+
const outcome = joinAll(found.map((f) => f.outcome));
|
|
327
|
+
span.set({ "grc.status": status, "grc.outcome": outcome, "grc.findings": found.length });
|
|
328
|
+
for (const f of found) {
|
|
329
|
+
span.log("grc.finding", {
|
|
330
|
+
...at,
|
|
331
|
+
"grc.status": f.status,
|
|
332
|
+
"grc.outcome": f.outcome,
|
|
333
|
+
"grc.severity": f.severity,
|
|
334
|
+
...(f.waiver === undefined ? {} : { "grc.waiver.id": f.waiver }),
|
|
335
|
+
}, ocsfBody(complianceFinding(f, { product: options.product })), { severity: FINDING_SEVERITY[f.severity] });
|
|
336
|
+
}
|
|
337
|
+
return failing(outcome) ? err({ message: `${control.id} ${outcome} for ${ref.kind} ${ref.id}`, value: found }) : ok(found);
|
|
338
|
+
});
|
|
339
|
+
// A failing check's span ends `error`; its findings are the assessment's all the same.
|
|
340
|
+
findings.push(...(checked.kind === "ok" ? checked.value : checked.error.value));
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
const outcome = joinAll(findings.map((f) => f.outcome));
|
|
344
|
+
packSpan.set({ "grc.pack.findings": findings.length, "grc.outcome": outcome, ...countAttributes(findings) });
|
|
345
|
+
const assessment = {
|
|
346
|
+
pack: { id: pack.id, title: pack.title },
|
|
347
|
+
at: context.at,
|
|
348
|
+
controls: pack.controls.map(controlSummary),
|
|
349
|
+
subjects: refs,
|
|
350
|
+
findings,
|
|
351
|
+
};
|
|
352
|
+
if (!failing(outcome))
|
|
353
|
+
return ok(assessment);
|
|
354
|
+
const n = findings.filter((f) => failing(f.outcome)).length;
|
|
355
|
+
return err({ message: `${pack.id}: ${n} of ${findings.length} findings fail or error`, value: assessment });
|
|
356
|
+
});
|
|
357
|
+
return run.kind === "ok" ? run.value : run.error.value;
|
|
358
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 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`
|
|
3
|
+
* 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.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { sign } from "@intellectual-frontiers/grc/host";
|
|
8
|
+
* typeof sign; // "object"
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
export * as grc from "./grc.js";
|
|
14
|
+
export * as sign from "./sign.js";
|
package/dist/host/mod.js
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.js";
|
|
15
|
+
export * as sign from "./sign.js";
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Signing and verifying behind one interface (commons 0001-grc FR-020): a `Signer` turns bytes into a signature and the id of the key that
|
|
3
|
+
* made it, a `Verifier` says whether a signature over bytes holds. Two kinds stand behind it. `sshSigner` and `sshVerifier` run OpenSSH's
|
|
4
|
+
* `ssh-keygen -Y sign` and `ssh-keygen -Y verify` by their argument vector (the message on standard input, the signature an armored
|
|
5
|
+
* SSHSIG), with the namespace given, the private key a file the caller names and the allowed signers a file the caller names; nothing else
|
|
6
|
+
* is read, and the signature's temporary file is removed after use. `webCryptoSigner` and `webCryptoVerifier` sign with Web Crypto keys
|
|
7
|
+
* (Ed25519, ECDSA with DER signatures, RSA-PSS, RSASSA-PKCS1-v1_5) in the same form as `crypto/dsse`, so an envelope signed here
|
|
8
|
+
* verifies there and the other way round. `signEnvelopeWith` and `verifyEnvelopeWith` make and check DSSE envelopes with any of them, and
|
|
9
|
+
* `toSign` and `toVerifySignature` give the shapes `evidence.ts` takes for manifests and bundles.
|
|
10
|
+
*
|
|
11
|
+
* Failures expected in use (no `ssh-keygen`, a key that cannot sign) are `Result`s; a signature that does not hold is `ok(false)`.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```ts
|
|
15
|
+
* import { sshSigner, sshVerifier } from "./sign.js";
|
|
16
|
+
* const message = new TextEncoder().encode("release 1.2.3");
|
|
17
|
+
* const signed = await sshSigner({ keyFile: "ci_ed25519", namespace: "file" }).sign(message);
|
|
18
|
+
* if (signed.kind === "ok") {
|
|
19
|
+
* const v = sshVerifier({ allowedSignersFile: "allowed_signers", identity: "ci@example.com", namespace: "file" });
|
|
20
|
+
* await v.verify(message, signed.value.sig); // { kind: "ok", value: true }
|
|
21
|
+
* }
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* @module
|
|
25
|
+
*/
|
|
26
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
27
|
+
import { type DsseEnvelope } from "@intellectual-frontiers/crypto/dsse";
|
|
28
|
+
import type { Sign, VerifySignature } from "../evidence.js";
|
|
29
|
+
/** Why signing or verifying could not be done (as opposed to a signature that does not hold). */
|
|
30
|
+
export type SignError = {
|
|
31
|
+
readonly kind: "missing-program";
|
|
32
|
+
readonly program: string;
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: "key";
|
|
35
|
+
readonly reason: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly kind: "failed";
|
|
38
|
+
readonly reason: string;
|
|
39
|
+
};
|
|
40
|
+
/** A signature, and the id of the key that made it. */
|
|
41
|
+
export type Signature = {
|
|
42
|
+
readonly keyid: string;
|
|
43
|
+
readonly sig: Uint8Array;
|
|
44
|
+
};
|
|
45
|
+
/** A signer: bytes to a signature with the id of its key. */
|
|
46
|
+
export type Signer = {
|
|
47
|
+
/** How it signs. */
|
|
48
|
+
readonly kind: "ssh" | "web-crypto";
|
|
49
|
+
/** The signature over `message`, or why there is none. */
|
|
50
|
+
readonly sign: (message: Uint8Array) => Promise<Result<Signature, SignError>>;
|
|
51
|
+
};
|
|
52
|
+
/** A verifier: whether a signature over bytes holds (`ok(false)` where it does not), or why it could not be checked. */
|
|
53
|
+
export type Verifier = {
|
|
54
|
+
/** How it verifies. */
|
|
55
|
+
readonly kind: "ssh" | "web-crypto";
|
|
56
|
+
/** The id of the key it verifies with, where it has one: an envelope's signature naming another id is not tried with it. */
|
|
57
|
+
readonly keyid?: string;
|
|
58
|
+
/** Whether `sig` is a signature over `message`. */
|
|
59
|
+
readonly verify: (message: Uint8Array, sig: Uint8Array) => Promise<Result<boolean, SignError>>;
|
|
60
|
+
};
|
|
61
|
+
/** A sign error as one sentence. */
|
|
62
|
+
export declare function formatSignError(e: SignError): string;
|
|
63
|
+
/** A signer as the `Sign` that `evidence.ts` takes; that shape has no error, so a failure rejects with an `Error` naming it. */
|
|
64
|
+
export declare function toSign(signer: Signer): Sign;
|
|
65
|
+
/** A verifier as the `VerifySignature` that `evidence.ts` takes; a check that cannot be done rejects, which it reports as a bad signature with the reason. */
|
|
66
|
+
export declare function toVerifySignature(verifier: Verifier): VerifySignature;
|
|
67
|
+
/** Why an envelope could not be signed: the place of the signer in the list given, and its error. */
|
|
68
|
+
export type EnvelopeSignError = {
|
|
69
|
+
readonly kind: "signer";
|
|
70
|
+
readonly index: number;
|
|
71
|
+
readonly error: SignError;
|
|
72
|
+
};
|
|
73
|
+
/** The payload of the type signed by every signer given, over DSSE's pre-authentication encoding, in an envelope with each key's id. */
|
|
74
|
+
export declare function signEnvelopeWith(payloadType: string, payload: Uint8Array, signers: readonly Signer[]): Promise<Result<DsseEnvelope, EnvelopeSignError>>;
|
|
75
|
+
/** Why an envelope was refused. */
|
|
76
|
+
export type EnvelopeVerifyError = {
|
|
77
|
+
readonly kind: "malformed";
|
|
78
|
+
readonly reason: string;
|
|
79
|
+
} | {
|
|
80
|
+
readonly kind: "payload-type";
|
|
81
|
+
readonly expected: string;
|
|
82
|
+
readonly found: string;
|
|
83
|
+
} | {
|
|
84
|
+
readonly kind: "verifier";
|
|
85
|
+
readonly index: number;
|
|
86
|
+
readonly error: SignError;
|
|
87
|
+
} | {
|
|
88
|
+
readonly kind: "no-valid-signature";
|
|
89
|
+
readonly signatures: number;
|
|
90
|
+
readonly verified: number;
|
|
91
|
+
readonly threshold: number;
|
|
92
|
+
};
|
|
93
|
+
/** What a verified envelope carries: its payload type, its payload, and the places of the verifiers that held a signature. */
|
|
94
|
+
export type VerifiedEnvelope = {
|
|
95
|
+
readonly payloadType: string;
|
|
96
|
+
readonly payload: Uint8Array;
|
|
97
|
+
readonly verifiers: readonly number[];
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* The payload of an envelope of type `payloadType` of which at least `threshold` (1 by default) of the verifiers given each hold a
|
|
101
|
+
* signature. A signature naming a key id is tried only with verifiers of that id or of none.
|
|
102
|
+
*/
|
|
103
|
+
export declare function verifyEnvelopeWith(envelope: DsseEnvelope, payloadType: string, verifiers: readonly Verifier[], threshold?: number): Promise<Result<VerifiedEnvelope, EnvelopeVerifyError>>;
|
|
104
|
+
/** How `sshSigner` signs: the private key's file, the namespace (`file`, `git`, or one of the caller's own), and optionally the key id and the program. */
|
|
105
|
+
export type SshSignerOptions = {
|
|
106
|
+
/** The private key's file (unencrypted, or held by an agent for its public key); the only key file read. */
|
|
107
|
+
readonly keyFile: string;
|
|
108
|
+
/** The namespace the signature is bound to; a verifier must name the same one. */
|
|
109
|
+
readonly namespace: string;
|
|
110
|
+
/** The id a signature carries; by default the key's SHA-256 fingerprint (`SHA256:...`) as `ssh-keygen -l` shows it, read from the signature. */
|
|
111
|
+
readonly keyid?: string;
|
|
112
|
+
/** The program to run (`ssh-keygen` on PATH by default). */
|
|
113
|
+
readonly program?: string;
|
|
114
|
+
};
|
|
115
|
+
/** How `sshVerifier` verifies: the allowed signers file, the identity expected in it, the namespace, and optionally the program. */
|
|
116
|
+
export type SshVerifierOptions = {
|
|
117
|
+
/** The allowed signers file (`ssh-keygen(1)`'s ALLOWED SIGNERS format); the only key file read. */
|
|
118
|
+
readonly allowedSignersFile: string;
|
|
119
|
+
/** The principal the signature must be by, as the allowed signers file names it. */
|
|
120
|
+
readonly identity: string;
|
|
121
|
+
/** The namespace the signature must be bound to. */
|
|
122
|
+
readonly namespace: string;
|
|
123
|
+
/** The id of the key, where the caller knows it, to match an envelope's signatures by. */
|
|
124
|
+
readonly keyid?: string;
|
|
125
|
+
/** The program to run (`ssh-keygen` on PATH by default). */
|
|
126
|
+
readonly program?: string;
|
|
127
|
+
};
|
|
128
|
+
/** The SHA-256 fingerprint of an SSH public key blob, as `ssh-keygen -l` writes it: `SHA256:` and unpadded base64. */
|
|
129
|
+
export declare function sshFingerprint(publicKeyBlob: Uint8Array): Promise<string>;
|
|
130
|
+
/** A signer by `ssh-keygen -Y sign -f KEY -n NAMESPACE`, the message on standard input; its signatures are armored SSHSIG text as bytes. */
|
|
131
|
+
export declare function sshSigner(options: SshSignerOptions): Signer;
|
|
132
|
+
/**
|
|
133
|
+
* A verifier by `ssh-keygen -Y verify -f ALLOWED -I IDENTITY -n NAMESPACE -s SIGFILE`, the message on standard input; the signature is
|
|
134
|
+
* written to a private temporary folder removed afterwards. A signature that does not hold (or is not by that identity, or not in that
|
|
135
|
+
* namespace) is `ok(false)`; an allowed signers file that is not there is a `key` error.
|
|
136
|
+
*/
|
|
137
|
+
export declare function sshVerifier(options: SshVerifierOptions): Verifier;
|
|
138
|
+
/** A signer with a Web Crypto private key, its signatures in the form `crypto/dsse` writes (ECDSA as DER), each named by `keyid`. */
|
|
139
|
+
export declare function webCryptoSigner(privateKey: CryptoKey, keyid: string): Signer;
|
|
140
|
+
/** A verifier with a Web Crypto public key, of signatures in the form `crypto/dsse` writes; with `keyid`, matched by it in envelopes. */
|
|
141
|
+
export declare function webCryptoVerifier(publicKey: CryptoKey, keyid?: string): Verifier;
|