@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/oscal.js
ADDED
|
@@ -0,0 +1,513 @@
|
|
|
1
|
+
// Spec: 0001-grc FR-017
|
|
2
|
+
/**
|
|
3
|
+
* Assessments as OSCAL 1.2.3 JSON (commons 0001-grc FR-017): `assessment-results` (one result of every finding as an observation and of
|
|
4
|
+
* every reviewed control as an OSCAL finding), a `plan-of-action-and-milestones` (a POA&M item and a risk for each finding not passing, and
|
|
5
|
+
* for each risk of a register), a `component-definition` (a component whose control implementations are the catalog controls its controls
|
|
6
|
+
* implement), and a minimal `system-security-plan` of what is implemented and how far, from an assessment.
|
|
7
|
+
*
|
|
8
|
+
* Every `uuid` is a version 5 UUID (RFC 9562) of a namespace the caller gives and a stable name of what it identifies, and every list is in
|
|
9
|
+
* an order of its own (controls by id, subjects by kind and id, findings by their key), so the same input gives the same document byte for
|
|
10
|
+
* byte, whatever order its findings, controls or risks came in. The document's `metadata` takes its title, `last-modified` (an `Instant`)
|
|
11
|
+
* and version from the caller; the kernel reads no clock. OSCAL's strings are never empty nor start or end with white space, so each is
|
|
12
|
+
* trimmed and an empty one given a stated default.
|
|
13
|
+
*
|
|
14
|
+
* Statuses: an OSCAL finding's target is `satisfied` where the join of its findings' outcomes is `pass`, `accepted` or `not-applicable`,
|
|
15
|
+
* else `not-satisfied` with the reason `fail` (`warn`, `gap`, `fail`) or `other` (`error`). A POA&M risk is `deviation-approved` for an
|
|
16
|
+
* `accepted` finding or a risk treated by `accept` or `transfer`, `remediating` for one treated by `mitigate` or `avoid`, else `open`. An
|
|
17
|
+
* SSP requirement is `implemented` where its coverage is `covered` or `addressed`, `partial` where `partial`, and `planned` where untested.
|
|
18
|
+
*
|
|
19
|
+
* From OSCAL 1.1.2 to 1.2.3 the members these four documents use did not change; 1.2 widened enumerations (component types `region`,
|
|
20
|
+
* `zone`, `resource-container` and `network`, the observation type `discovery`, CVSS v4 as a facet system, a further UUID identifier type),
|
|
21
|
+
* made an SSP's `users` optional (written still) and added the mapping model, which this module does not write.
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* import { assessmentResults, renderOscal } from "./oscal.ts";
|
|
26
|
+
* import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
|
|
27
|
+
* // const namespace = await uuidV5(NAMESPACE_URL, "https://example.com/assessments");
|
|
28
|
+
* // renderOscal(await assessmentResults(assessment, { namespace, lastModified: assessment.at, version: "1", propNamespace: "https://example.com/ns" }));
|
|
29
|
+
* ```
|
|
30
|
+
*
|
|
31
|
+
* @module
|
|
32
|
+
*/
|
|
33
|
+
import { absurd } from "@intellectual-frontiers/core";
|
|
34
|
+
import { coverageOf, newestFindings } from "./assess.js";
|
|
35
|
+
import { canonicalize } from "./evidence.js";
|
|
36
|
+
import { findingKey, joinAll, } from "./grc.js";
|
|
37
|
+
import { uuidV5Of } from "@intellectual-frontiers/crypto/uuid";
|
|
38
|
+
/** The OSCAL version written. */
|
|
39
|
+
export const OSCAL_VERSION = "1.2.3";
|
|
40
|
+
/** NIST SP 800-30 Rev. 1, the system a risk's likelihood, impact and level facets are named in. */
|
|
41
|
+
export const SP800_30 = "https://doi.org/10.6028/NIST.SP.800-30r1";
|
|
42
|
+
/** The `identifier-type` of a system id that is a UUID. */
|
|
43
|
+
export const RFC4122 = "https://ietf.org/rfc/rfc4122";
|
|
44
|
+
/** The types of a defined component (OSCAL 1.2.3 `defined-component/type`; 1.2 added `region`, `zone`, `resource-container` and `network`). */
|
|
45
|
+
export const OSCAL_COMPONENT_TYPES = [
|
|
46
|
+
"interconnection",
|
|
47
|
+
"software",
|
|
48
|
+
"hardware",
|
|
49
|
+
"service",
|
|
50
|
+
"policy",
|
|
51
|
+
"physical",
|
|
52
|
+
"process-procedure",
|
|
53
|
+
"plan",
|
|
54
|
+
"guidance",
|
|
55
|
+
"standard",
|
|
56
|
+
"validation",
|
|
57
|
+
"region",
|
|
58
|
+
"zone",
|
|
59
|
+
"resource-container",
|
|
60
|
+
"network",
|
|
61
|
+
];
|
|
62
|
+
// ---------------------------------------------------------------------------------------------------------------------------- helpers
|
|
63
|
+
const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
64
|
+
function text(s, fallback) {
|
|
65
|
+
const t = (s ?? "").trim();
|
|
66
|
+
return t === "" ? fallback : t;
|
|
67
|
+
}
|
|
68
|
+
function stableText(value) {
|
|
69
|
+
const c = canonicalize(value);
|
|
70
|
+
return c.kind === "ok" ? c.value : String(value);
|
|
71
|
+
}
|
|
72
|
+
const subjectKey = (s) => JSON.stringify([s.kind, s.id]);
|
|
73
|
+
/** Findings in a total order of their own (key, then the canonical form of the whole), each with its place among those of its key. */
|
|
74
|
+
function ordered(findings) {
|
|
75
|
+
const keyed = findings.map((f) => ({ finding: f, key: findingKey(f), text: stableText(f) }));
|
|
76
|
+
keyed.sort((a, b) => byText(a.key, b.key) || byText(a.text, b.text));
|
|
77
|
+
const count = new Map();
|
|
78
|
+
return keyed.map(({ finding, key }) => {
|
|
79
|
+
const n = count.get(key) ?? 0;
|
|
80
|
+
count.set(key, n + 1);
|
|
81
|
+
return { finding, key, n };
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
function uniqueControls(controls) {
|
|
85
|
+
const seen = new Map();
|
|
86
|
+
for (const c of controls)
|
|
87
|
+
if (!seen.has(c.id))
|
|
88
|
+
seen.set(c.id, c);
|
|
89
|
+
return [...seen.values()].sort((a, b) => byText(a.id, b.id));
|
|
90
|
+
}
|
|
91
|
+
function uniqueSubjects(subjects) {
|
|
92
|
+
const seen = new Map();
|
|
93
|
+
for (const s of subjects)
|
|
94
|
+
if (!seen.has(subjectKey(s)))
|
|
95
|
+
seen.set(subjectKey(s), s);
|
|
96
|
+
return [...seen.entries()].sort(([a], [b]) => byText(a, b)).map(([, s]) => s);
|
|
97
|
+
}
|
|
98
|
+
async function metadataOf(o, title) {
|
|
99
|
+
return {
|
|
100
|
+
title: text(o.title, title),
|
|
101
|
+
"last-modified": o.lastModified,
|
|
102
|
+
version: text(o.version, "1"),
|
|
103
|
+
"oscal-version": OSCAL_VERSION,
|
|
104
|
+
...(o.organization === undefined
|
|
105
|
+
? {}
|
|
106
|
+
: {
|
|
107
|
+
parties: [
|
|
108
|
+
{
|
|
109
|
+
uuid: await uuidV5Of(o.namespace, ["party", o.organization]),
|
|
110
|
+
type: "organization",
|
|
111
|
+
name: text(o.organization, "organization"),
|
|
112
|
+
},
|
|
113
|
+
],
|
|
114
|
+
}),
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
function targetsOf(controls, o) {
|
|
118
|
+
const idOf = o.controlId ?? ((r) => r.id);
|
|
119
|
+
const targets = new Map();
|
|
120
|
+
const add = (key, controlId, control) => {
|
|
121
|
+
const t = targets.get(key) ?? { controlId, controls: new Set() };
|
|
122
|
+
t.controls.add(control);
|
|
123
|
+
targets.set(key, t);
|
|
124
|
+
};
|
|
125
|
+
for (const c of uniqueControls(controls)) {
|
|
126
|
+
if (c.implements.length === 0)
|
|
127
|
+
add(JSON.stringify(["", c.id]), c.id, c.id);
|
|
128
|
+
for (const r of c.implements)
|
|
129
|
+
add(JSON.stringify([r.catalog, r.id]), idOf(r), c.id);
|
|
130
|
+
}
|
|
131
|
+
return [...targets.entries()]
|
|
132
|
+
.sort(([a], [b]) => byText(a, b))
|
|
133
|
+
.map(([key, t]) => ({ key, controlId: t.controlId, controls: [...t.controls].sort(byText) }));
|
|
134
|
+
}
|
|
135
|
+
function targetStatus(outcome) {
|
|
136
|
+
switch (outcome) {
|
|
137
|
+
case "pass":
|
|
138
|
+
case "accepted":
|
|
139
|
+
case "not-applicable":
|
|
140
|
+
return { state: "satisfied" };
|
|
141
|
+
case "warn":
|
|
142
|
+
case "gap":
|
|
143
|
+
case "fail":
|
|
144
|
+
return { state: "not-satisfied", reason: "fail" };
|
|
145
|
+
case "error":
|
|
146
|
+
return { state: "not-satisfied", reason: "other" };
|
|
147
|
+
default:
|
|
148
|
+
return absurd(outcome);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
async function inventoryItems(subjects, o) {
|
|
152
|
+
return Promise.all(uniqueSubjects(subjects).map(async (s) => ({
|
|
153
|
+
uuid: await subjectUuid(s, o),
|
|
154
|
+
description: text(`${s.kind} ${s.id}`, "a subject"),
|
|
155
|
+
props: [
|
|
156
|
+
{ name: "asset-id", value: text(s.id, "unnamed") },
|
|
157
|
+
{ name: "subject-kind", ns: o.propNamespace, value: text(s.kind, "unknown") },
|
|
158
|
+
],
|
|
159
|
+
})));
|
|
160
|
+
}
|
|
161
|
+
function subjectUuid(s, o) {
|
|
162
|
+
return uuidV5Of(o.namespace, ["subject", s.kind, s.id]);
|
|
163
|
+
}
|
|
164
|
+
async function observation(f, key, n, scope, o) {
|
|
165
|
+
const p = (name, value) => ({ name, ns: o.propNamespace, value: text(value, "none") });
|
|
166
|
+
return {
|
|
167
|
+
uuid: await uuidV5Of(o.namespace, ["observation", ...scope, key, String(n)]),
|
|
168
|
+
title: text(`${f.control.id} on ${f.subject.kind} ${f.subject.id}: ${f.title}`, f.control.id),
|
|
169
|
+
description: text(f.detail, `${f.control.id}: ${f.outcome}`),
|
|
170
|
+
props: [
|
|
171
|
+
p("control", f.control.id),
|
|
172
|
+
p("outcome", f.outcome),
|
|
173
|
+
p("status", f.status),
|
|
174
|
+
p("severity", f.severity),
|
|
175
|
+
...(f.waiver === undefined ? [] : [p("waiver", f.waiver)]),
|
|
176
|
+
],
|
|
177
|
+
methods: ["TEST"],
|
|
178
|
+
types: ["finding"],
|
|
179
|
+
subjects: [
|
|
180
|
+
{
|
|
181
|
+
"subject-uuid": await subjectUuid(f.subject, o),
|
|
182
|
+
type: "inventory-item",
|
|
183
|
+
title: text(`${f.subject.kind} ${f.subject.id}`, "a subject"),
|
|
184
|
+
},
|
|
185
|
+
],
|
|
186
|
+
...(f.evidence.length === 0
|
|
187
|
+
? {}
|
|
188
|
+
: {
|
|
189
|
+
"relevant-evidence": [...new Set(f.evidence)]
|
|
190
|
+
.sort(byText)
|
|
191
|
+
.map((d) => ({ description: `evidence of SHA-256 ${d}`, props: [{ name: "sha256", ns: o.propNamespace, value: d }] })),
|
|
192
|
+
}),
|
|
193
|
+
collected: f.at,
|
|
194
|
+
...(f.remediation === undefined || f.outcome === "pass" || text(f.remediation, "") === "" ? {} : { remarks: text(f.remediation, "") }),
|
|
195
|
+
};
|
|
196
|
+
}
|
|
197
|
+
// ---------------------------------------------------------------------------------------------------------------------------- assessment results
|
|
198
|
+
/**
|
|
199
|
+
* An assessment as OSCAL assessment results: one result, its subjects as inventory items, each finding an observation, and each control
|
|
200
|
+
* reviewed (each catalog control the assessment's controls implement, or a control that implements none) an OSCAL finding whose target is
|
|
201
|
+
* satisfied or not by the join of the outcomes of the newest findings of its controls. `assessmentPlan` is the `import-ap` href; by default
|
|
202
|
+
* a back-matter resource that stands for the plan.
|
|
203
|
+
*/
|
|
204
|
+
export async function assessmentResults(a, o) {
|
|
205
|
+
const scope = [a.pack.id, a.at];
|
|
206
|
+
const list = ordered(a.findings);
|
|
207
|
+
const observations = await Promise.all(list.map(({ finding, key, n }) => observation(finding, key, n, scope, o)));
|
|
208
|
+
const newest = new Set(newestFindings(a.findings));
|
|
209
|
+
const controls = uniqueControls([...a.controls, ...a.findings.map((f) => f.control)]);
|
|
210
|
+
const targets = targetsOf(controls, o);
|
|
211
|
+
const findings = await Promise.all(targets.map(async (t) => {
|
|
212
|
+
const related = list.flatMap(({ finding }, i) => (t.controls.includes(finding.control.id) ? [{ finding, i }] : []));
|
|
213
|
+
const outcome = joinAll(related.filter((r) => newest.has(r.finding)).map((r) => r.finding.outcome));
|
|
214
|
+
const observed = related.flatMap(({ i }) => {
|
|
215
|
+
const obs = observations[i];
|
|
216
|
+
return obs === undefined ? [] : [{ "observation-uuid": obs.uuid }];
|
|
217
|
+
});
|
|
218
|
+
return {
|
|
219
|
+
uuid: await uuidV5Of(o.namespace, ["finding", ...scope, t.key]),
|
|
220
|
+
title: text(t.controlId, "control"),
|
|
221
|
+
description: `${t.controlId}: ${related.length === 0 ? "not assessed" : outcome}, by ${t.controls.join(", ")}.`,
|
|
222
|
+
props: [
|
|
223
|
+
{ name: "outcome", ns: o.propNamespace, value: related.length === 0 ? "not-applicable" : outcome },
|
|
224
|
+
...t.controls.map((c) => ({ name: "control", ns: o.propNamespace, value: text(c, "control") })),
|
|
225
|
+
],
|
|
226
|
+
target: { type: "objective-id", "target-id": t.controlId, status: targetStatus(outcome) },
|
|
227
|
+
...(observed.length === 0 ? {} : { "related-observations": observed }),
|
|
228
|
+
};
|
|
229
|
+
}));
|
|
230
|
+
const plan = await uuidV5Of(o.namespace, ["assessment-plan", a.pack.id]);
|
|
231
|
+
const subjects = await inventoryItems([...a.subjects, ...a.findings.map((f) => f.subject)], o);
|
|
232
|
+
const ids = [...new Set(targets.map((t) => t.controlId))].sort(byText);
|
|
233
|
+
const result = {
|
|
234
|
+
uuid: await uuidV5Of(o.namespace, ["result", ...scope]),
|
|
235
|
+
title: text(`${a.pack.title} as of ${a.at}`, a.pack.id),
|
|
236
|
+
description: text(`The findings of ${a.pack.title} (${a.pack.id}), assessed at ${a.at}.`, "The findings of an assessment."),
|
|
237
|
+
start: a.at,
|
|
238
|
+
...(subjects.length === 0 ? {} : { "local-definitions": { "inventory-items": subjects } }),
|
|
239
|
+
"reviewed-controls": {
|
|
240
|
+
"control-selections": [ids.length === 0 ? { "include-all": {} } : { "include-controls": ids.map((id) => ({ "control-id": id })) }],
|
|
241
|
+
},
|
|
242
|
+
...(observations.length === 0 ? {} : { observations }),
|
|
243
|
+
...(findings.length === 0 ? {} : { findings }),
|
|
244
|
+
};
|
|
245
|
+
return {
|
|
246
|
+
"assessment-results": {
|
|
247
|
+
uuid: await uuidV5Of(o.namespace, ["assessment-results", ...scope]),
|
|
248
|
+
metadata: await metadataOf(o, `${text(a.pack.title, a.pack.id)}: assessment results`),
|
|
249
|
+
"import-ap": { href: o.assessmentPlan ?? `#${plan}` },
|
|
250
|
+
results: [result],
|
|
251
|
+
...(o.assessmentPlan === undefined
|
|
252
|
+
? { "back-matter": { resources: [{ uuid: plan, title: text(`The assessment plan of ${a.pack.title}`, "The assessment plan") }] } }
|
|
253
|
+
: {}),
|
|
254
|
+
},
|
|
255
|
+
};
|
|
256
|
+
}
|
|
257
|
+
// ---------------------------------------------------------------------------------------------------------------------------- POA&M
|
|
258
|
+
const OPEN_OUTCOMES = new Set(["fail", "warn", "gap", "error", "accepted"]);
|
|
259
|
+
function riskStatus(r) {
|
|
260
|
+
switch (r.treatment) {
|
|
261
|
+
case "accept":
|
|
262
|
+
case "transfer":
|
|
263
|
+
return "deviation-approved";
|
|
264
|
+
case "mitigate":
|
|
265
|
+
case "avoid":
|
|
266
|
+
return "remediating";
|
|
267
|
+
default:
|
|
268
|
+
return absurd(r.treatment);
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* A plan of action and milestones: for each finding whose outcome is `fail`, `warn`, `gap`, `error` or `accepted`, an observation, a risk
|
|
273
|
+
* (`open`, or `deviation-approved` where a waiver accepted it) and a POA&M item; and for each risk of a register given, a risk with its
|
|
274
|
+
* NIST SP 800-30 likelihood, impact and level as facets and a POA&M item. A finding's risk and item are named by its control and subject
|
|
275
|
+
* (not its time), so the same open finding keeps its UUIDs from one assessment to the next.
|
|
276
|
+
*/
|
|
277
|
+
export async function poam(a, risks, o) {
|
|
278
|
+
const list = ordered(a.findings.filter((f) => OPEN_OUTCOMES.has(f.outcome)));
|
|
279
|
+
const scope = [a.pack.id, a.at];
|
|
280
|
+
const party = o.organization === undefined ? undefined : await uuidV5Of(o.namespace, ["party", o.organization]);
|
|
281
|
+
const observations = await Promise.all(list.map(({ finding, key, n }) => observation(finding, key, n, scope, o)));
|
|
282
|
+
const findingRisks = await Promise.all(list.map(async ({ finding: f, key, n }, i) => {
|
|
283
|
+
const obs = observations[i];
|
|
284
|
+
return {
|
|
285
|
+
uuid: await uuidV5Of(o.namespace, ["risk", "finding", a.pack.id, key, String(n)]),
|
|
286
|
+
title: text(`${f.control.id} on ${f.subject.kind} ${f.subject.id}: ${f.title}`, f.control.id),
|
|
287
|
+
description: text(f.detail, `${f.control.id}: ${f.outcome}`),
|
|
288
|
+
statement: text(f.outcome === "accepted"
|
|
289
|
+
? `Accepted under waiver ${f.waiver ?? "(unnamed)"}: ${f.status}.`
|
|
290
|
+
: `${f.outcome} (severity ${f.severity}).${f.remediation === undefined ? "" : ` Remediation: ${f.remediation}`}`, f.outcome),
|
|
291
|
+
props: [
|
|
292
|
+
{ name: "control", ns: o.propNamespace, value: text(f.control.id, "control") },
|
|
293
|
+
{ name: "severity", ns: o.propNamespace, value: f.severity },
|
|
294
|
+
],
|
|
295
|
+
status: f.outcome === "accepted" ? "deviation-approved" : "open",
|
|
296
|
+
...(obs === undefined ? {} : { "related-observations": [{ "observation-uuid": obs.uuid }] }),
|
|
297
|
+
};
|
|
298
|
+
}));
|
|
299
|
+
const register = [...risks].sort((x, y) => byText(x.id, y.id));
|
|
300
|
+
const registerRisks = await Promise.all(register.map(async (r) => ({
|
|
301
|
+
uuid: await uuidV5Of(o.namespace, ["risk", "register", r.id]),
|
|
302
|
+
title: text(r.title, r.id),
|
|
303
|
+
description: text(r.description, text(r.title, r.id)),
|
|
304
|
+
statement: `Level of risk ${r.level} (likelihood ${r.likelihood}, impact ${r.impact}; NIST SP 800-30 Rev. 1). Treatment: ${r.treatment}. Owner: ${r.owner}. Review by ${r.reviewBy}.`,
|
|
305
|
+
props: [
|
|
306
|
+
{ name: "risk-id", ns: o.propNamespace, value: text(r.id, "risk") },
|
|
307
|
+
{ name: "treatment", ns: o.propNamespace, value: r.treatment },
|
|
308
|
+
{ name: "owner", ns: o.propNamespace, value: text(r.owner, "owner") },
|
|
309
|
+
{ name: "review-by", ns: o.propNamespace, value: r.reviewBy },
|
|
310
|
+
...[...new Set(r.controls ?? [])].sort(byText).map((c) => ({ name: "control", ns: o.propNamespace, value: text(c, "control") })),
|
|
311
|
+
],
|
|
312
|
+
status: riskStatus(r),
|
|
313
|
+
...(party === undefined
|
|
314
|
+
? {}
|
|
315
|
+
: {
|
|
316
|
+
characterizations: [
|
|
317
|
+
{
|
|
318
|
+
origin: { actors: [{ type: "party", "actor-uuid": party }] },
|
|
319
|
+
facets: [
|
|
320
|
+
{ name: "likelihood", system: SP800_30, value: r.likelihood },
|
|
321
|
+
{ name: "impact", system: SP800_30, value: r.impact },
|
|
322
|
+
{ name: "risk", system: SP800_30, value: r.level },
|
|
323
|
+
],
|
|
324
|
+
},
|
|
325
|
+
],
|
|
326
|
+
}),
|
|
327
|
+
})));
|
|
328
|
+
const items = [];
|
|
329
|
+
for (const [i, { finding: f, key, n }] of list.entries()) {
|
|
330
|
+
const obs = observations[i];
|
|
331
|
+
const risk = findingRisks[i];
|
|
332
|
+
if (obs === undefined || risk === undefined)
|
|
333
|
+
continue;
|
|
334
|
+
items.push({
|
|
335
|
+
uuid: await uuidV5Of(o.namespace, ["poam-item", "finding", a.pack.id, key, String(n)]),
|
|
336
|
+
title: risk.title,
|
|
337
|
+
description: risk.statement,
|
|
338
|
+
props: [{ name: "outcome", ns: o.propNamespace, value: f.outcome }],
|
|
339
|
+
"related-observations": [{ "observation-uuid": obs.uuid }],
|
|
340
|
+
"related-risks": [{ "risk-uuid": risk.uuid }],
|
|
341
|
+
});
|
|
342
|
+
}
|
|
343
|
+
for (const r of registerRisks) {
|
|
344
|
+
const id = r.props?.[0]?.value ?? r.title;
|
|
345
|
+
items.push({
|
|
346
|
+
uuid: await uuidV5Of(o.namespace, ["poam-item", "register", id]),
|
|
347
|
+
title: text(`Risk register: ${r.title}`, "Risk register"),
|
|
348
|
+
description: r.statement,
|
|
349
|
+
"related-risks": [{ "risk-uuid": r.uuid }],
|
|
350
|
+
});
|
|
351
|
+
}
|
|
352
|
+
const subjects = await inventoryItems(list.map(({ finding }) => finding.subject), o);
|
|
353
|
+
const allRisks = [...findingRisks, ...registerRisks];
|
|
354
|
+
return {
|
|
355
|
+
"plan-of-action-and-milestones": {
|
|
356
|
+
uuid: await uuidV5Of(o.namespace, ["plan-of-action-and-milestones", ...scope]),
|
|
357
|
+
metadata: await metadataOf(o, `${text(a.pack.title, a.pack.id)}: plan of action and milestones`),
|
|
358
|
+
...(subjects.length === 0 ? {} : { "local-definitions": { "inventory-items": subjects } }),
|
|
359
|
+
...(observations.length === 0 ? {} : { observations }),
|
|
360
|
+
...(allRisks.length === 0 ? {} : { risks: allRisks }),
|
|
361
|
+
"poam-items": items,
|
|
362
|
+
},
|
|
363
|
+
};
|
|
364
|
+
}
|
|
365
|
+
async function catalogResources(catalogs, o) {
|
|
366
|
+
return Promise.all(catalogs.map(async (c) => ({ uuid: await uuidV5Of(o.namespace, ["catalog", c]), title: text(c, "catalog") })));
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* A component definition of one component: for each catalog its controls implement (in the catalogs' order), a control implementation
|
|
370
|
+
* whose implemented requirements are those catalog controls, each saying which controls implement it. A catalog's `source` is
|
|
371
|
+
* `catalogHref`'s, or a back-matter resource that stands for it.
|
|
372
|
+
*/
|
|
373
|
+
export async function componentDefinition(controls, component, o) {
|
|
374
|
+
const unique = uniqueControls(controls);
|
|
375
|
+
const idOf = o.controlId ?? ((r) => r.id);
|
|
376
|
+
const catalogs = [...new Set(unique.flatMap((c) => c.implements.map((r) => r.catalog)))].sort(byText);
|
|
377
|
+
const resources = await catalogResources(catalogs, o);
|
|
378
|
+
const implementations = await Promise.all(catalogs.map(async (catalog, i) => {
|
|
379
|
+
const byId = new Map();
|
|
380
|
+
for (const c of unique) {
|
|
381
|
+
for (const r of c.implements) {
|
|
382
|
+
if (r.catalog !== catalog)
|
|
383
|
+
continue;
|
|
384
|
+
const id = idOf(r);
|
|
385
|
+
const list = byId.get(id) ?? [];
|
|
386
|
+
if (!list.includes(c))
|
|
387
|
+
list.push(c);
|
|
388
|
+
byId.set(id, list);
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
const resource = resources[i];
|
|
392
|
+
return {
|
|
393
|
+
uuid: await uuidV5Of(o.namespace, ["control-implementation", component.id, catalog]),
|
|
394
|
+
source: o.catalogHref?.(catalog) ?? `#${resource?.uuid ?? ""}`,
|
|
395
|
+
description: text(`The controls of ${catalog} that ${component.title} implements.`, "Controls implemented."),
|
|
396
|
+
"implemented-requirements": await Promise.all([...byId.entries()]
|
|
397
|
+
.sort(([x], [y]) => byText(x, y))
|
|
398
|
+
.map(async ([id, cs]) => ({
|
|
399
|
+
uuid: await uuidV5Of(o.namespace, ["implemented-requirement", component.id, catalog, id]),
|
|
400
|
+
"control-id": id,
|
|
401
|
+
description: text(cs.map((c) => `${c.id} (${c.title})`).join("; "), id),
|
|
402
|
+
props: cs.map((c) => ({ name: "control", ns: o.propNamespace, value: text(c.id, "control") })),
|
|
403
|
+
}))),
|
|
404
|
+
};
|
|
405
|
+
}));
|
|
406
|
+
return {
|
|
407
|
+
"component-definition": {
|
|
408
|
+
uuid: await uuidV5Of(o.namespace, ["component-definition", component.id]),
|
|
409
|
+
metadata: await metadataOf(o, `${text(component.title, component.id)}: component definition`),
|
|
410
|
+
components: [
|
|
411
|
+
{
|
|
412
|
+
uuid: await uuidV5Of(o.namespace, ["component", component.id]),
|
|
413
|
+
type: component.type ?? "software",
|
|
414
|
+
title: text(component.title, component.id),
|
|
415
|
+
description: text(component.description, text(component.title, component.id)),
|
|
416
|
+
...(component.version === undefined ? {} : { props: [{ name: "version", value: text(component.version, "unversioned") }] }),
|
|
417
|
+
...(implementations.length === 0 ? {} : { "control-implementations": implementations }),
|
|
418
|
+
},
|
|
419
|
+
],
|
|
420
|
+
...(resources.length === 0 || o.catalogHref !== undefined ? {} : { "back-matter": { resources } }),
|
|
421
|
+
},
|
|
422
|
+
};
|
|
423
|
+
}
|
|
424
|
+
function implementationState(outcomes) {
|
|
425
|
+
const c = coverageOf(outcomes);
|
|
426
|
+
switch (c) {
|
|
427
|
+
case "covered":
|
|
428
|
+
case "addressed":
|
|
429
|
+
return "implemented";
|
|
430
|
+
case "partial":
|
|
431
|
+
return "partial";
|
|
432
|
+
case "untested":
|
|
433
|
+
return "planned";
|
|
434
|
+
default:
|
|
435
|
+
return absurd(c);
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
/**
|
|
439
|
+
* A minimal system security plan of what is implemented: the system as one `this-system` component, the assessment's subjects as its
|
|
440
|
+
* inventory, and each catalog control its controls implement (or control that implements none) with its implementation status from the
|
|
441
|
+
* coverage of the newest findings of its controls.
|
|
442
|
+
*/
|
|
443
|
+
export async function systemSecurityPlan(a, system, o) {
|
|
444
|
+
const newest = newestFindings(a.findings);
|
|
445
|
+
const thisSystem = await uuidV5Of(o.namespace, ["component", "this-system", system.id]);
|
|
446
|
+
const targets = targetsOf([...a.controls, ...a.findings.map((f) => f.control)], o);
|
|
447
|
+
const requirements = await Promise.all(targets.map(async (t) => {
|
|
448
|
+
const outcomes = newest.filter((f) => t.controls.includes(f.control.id)).map((f) => f.outcome);
|
|
449
|
+
const state = implementationState(outcomes);
|
|
450
|
+
return {
|
|
451
|
+
uuid: await uuidV5Of(o.namespace, ["ssp-requirement", system.id, t.key]),
|
|
452
|
+
"control-id": t.controlId,
|
|
453
|
+
props: t.controls.map((c) => ({ name: "control", ns: o.propNamespace, value: text(c, "control") })),
|
|
454
|
+
"by-components": [
|
|
455
|
+
{
|
|
456
|
+
"component-uuid": thisSystem,
|
|
457
|
+
uuid: await uuidV5Of(o.namespace, ["ssp-by-component", system.id, t.key]),
|
|
458
|
+
description: text(`${t.controlId} is met by ${t.controls.join(", ")}: ${state}.`, t.controlId),
|
|
459
|
+
"implementation-status": { state },
|
|
460
|
+
},
|
|
461
|
+
],
|
|
462
|
+
};
|
|
463
|
+
}));
|
|
464
|
+
const items = await inventoryItems([...a.subjects, ...a.findings.map((f) => f.subject)], o);
|
|
465
|
+
const info = system.informationType ?? { title: "System information", description: "The information the system stores and processes." };
|
|
466
|
+
return {
|
|
467
|
+
"system-security-plan": {
|
|
468
|
+
uuid: await uuidV5Of(o.namespace, ["system-security-plan", system.id]),
|
|
469
|
+
metadata: await metadataOf(o, `${text(system.name, system.id)}: system security plan`),
|
|
470
|
+
"import-profile": { href: text(system.profile, "#") },
|
|
471
|
+
"system-characteristics": {
|
|
472
|
+
"system-ids": [{ "identifier-type": RFC4122, id: thisSystem }],
|
|
473
|
+
"system-name": text(system.name, system.id),
|
|
474
|
+
description: text(system.description, text(system.name, system.id)),
|
|
475
|
+
"system-information": {
|
|
476
|
+
"information-types": [
|
|
477
|
+
{
|
|
478
|
+
uuid: await uuidV5Of(o.namespace, ["information-type", system.id]),
|
|
479
|
+
title: text(info.title, "System information"),
|
|
480
|
+
description: text(info.description, "System information."),
|
|
481
|
+
},
|
|
482
|
+
],
|
|
483
|
+
},
|
|
484
|
+
status: { state: "operational" },
|
|
485
|
+
"authorization-boundary": {
|
|
486
|
+
description: text(system.boundary, `Every subject of ${text(system.name, system.id)} listed in its inventory.`),
|
|
487
|
+
},
|
|
488
|
+
},
|
|
489
|
+
"system-implementation": {
|
|
490
|
+
users: [{ uuid: await uuidV5Of(o.namespace, ["user", system.id]), title: text(system.user, "Operator") }],
|
|
491
|
+
components: [
|
|
492
|
+
{
|
|
493
|
+
uuid: thisSystem,
|
|
494
|
+
type: "this-system",
|
|
495
|
+
title: text(system.name, system.id),
|
|
496
|
+
description: text(system.description, text(system.name, system.id)),
|
|
497
|
+
status: { state: "operational" },
|
|
498
|
+
},
|
|
499
|
+
],
|
|
500
|
+
...(items.length === 0 ? {} : { "inventory-items": items }),
|
|
501
|
+
},
|
|
502
|
+
"control-implementation": {
|
|
503
|
+
description: text(`How ${system.name} meets each control its checks implement, from the assessment at ${a.at}.`, "How each control is met."),
|
|
504
|
+
"implemented-requirements": requirements,
|
|
505
|
+
},
|
|
506
|
+
},
|
|
507
|
+
};
|
|
508
|
+
}
|
|
509
|
+
// ---------------------------------------------------------------------------------------------------------------------------- rendering
|
|
510
|
+
/** A document as OSCAL JSON text: two-space indents and a final newline, its members in the order this module writes them. */
|
|
511
|
+
export function renderOscal(doc) {
|
|
512
|
+
return `${JSON.stringify(doc, null, 2)}\n`;
|
|
513
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,89 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/grc",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Governance, risk and compliance as code: typed catalogs, controls, verdicts, findings and waivers, the hash-chained evidence ledger, coverage, freshness, drift and the risk register, and the findings, assessments and attestations written as OCSF, OSCAL, CycloneDX and in-toto; with a host that loads the settings of packs, runs them as signals and signs; the same code on Bun and Node 26.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=26"
|
|
9
|
+
},
|
|
10
|
+
"sideEffects": false,
|
|
11
|
+
"types": "./dist/mod.d.ts",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./dist/mod.d.ts",
|
|
15
|
+
"bun": "./src/mod.ts",
|
|
16
|
+
"default": "./dist/mod.js"
|
|
17
|
+
},
|
|
18
|
+
"./grc": {
|
|
19
|
+
"types": "./dist/grc.d.ts",
|
|
20
|
+
"bun": "./src/grc.ts",
|
|
21
|
+
"default": "./dist/grc.js"
|
|
22
|
+
},
|
|
23
|
+
"./assess": {
|
|
24
|
+
"types": "./dist/assess.d.ts",
|
|
25
|
+
"bun": "./src/assess.ts",
|
|
26
|
+
"default": "./dist/assess.js"
|
|
27
|
+
},
|
|
28
|
+
"./evidence": {
|
|
29
|
+
"types": "./dist/evidence.d.ts",
|
|
30
|
+
"bun": "./src/evidence.ts",
|
|
31
|
+
"default": "./dist/evidence.js"
|
|
32
|
+
},
|
|
33
|
+
"./oscal": {
|
|
34
|
+
"types": "./dist/oscal.d.ts",
|
|
35
|
+
"bun": "./src/oscal.ts",
|
|
36
|
+
"default": "./dist/oscal.js"
|
|
37
|
+
},
|
|
38
|
+
"./ocsf": {
|
|
39
|
+
"types": "./dist/ocsf.d.ts",
|
|
40
|
+
"bun": "./src/ocsf.ts",
|
|
41
|
+
"default": "./dist/ocsf.js"
|
|
42
|
+
},
|
|
43
|
+
"./attest": {
|
|
44
|
+
"types": "./dist/attest.d.ts",
|
|
45
|
+
"bun": "./src/attest.ts",
|
|
46
|
+
"default": "./dist/attest.js"
|
|
47
|
+
},
|
|
48
|
+
"./host": {
|
|
49
|
+
"types": "./dist/host/mod.d.ts",
|
|
50
|
+
"bun": "./src/host/mod.ts",
|
|
51
|
+
"default": "./dist/host/mod.js"
|
|
52
|
+
},
|
|
53
|
+
"./host/grc": {
|
|
54
|
+
"types": "./dist/host/grc.d.ts",
|
|
55
|
+
"bun": "./src/host/grc.ts",
|
|
56
|
+
"default": "./dist/host/grc.js"
|
|
57
|
+
},
|
|
58
|
+
"./host/sign": {
|
|
59
|
+
"types": "./dist/host/sign.d.ts",
|
|
60
|
+
"bun": "./src/host/sign.ts",
|
|
61
|
+
"default": "./dist/host/sign.js"
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
"dependencies": {
|
|
65
|
+
"@intellectual-frontiers/core": "0.1.2",
|
|
66
|
+
"@intellectual-frontiers/crypto": "0.1.2",
|
|
67
|
+
"@intellectual-frontiers/formats": "0.1.2",
|
|
68
|
+
"@intellectual-frontiers/system": "0.1.2",
|
|
69
|
+
"@intellectual-frontiers/telemetry": "0.1.2"
|
|
70
|
+
},
|
|
71
|
+
"files": [
|
|
72
|
+
"dist",
|
|
73
|
+
"src",
|
|
74
|
+
"README.md",
|
|
75
|
+
"LICENSE"
|
|
76
|
+
],
|
|
77
|
+
"repository": {
|
|
78
|
+
"type": "git",
|
|
79
|
+
"url": "git+https://github.com/intellectual-frontiers/.github.git",
|
|
80
|
+
"directory": "commons/grc"
|
|
81
|
+
},
|
|
82
|
+
"homepage": "https://github.com/intellectual-frontiers/.github/tree/main/commons/grc",
|
|
83
|
+
"bugs": {
|
|
84
|
+
"url": "https://github.com/intellectual-frontiers/.github/issues"
|
|
85
|
+
},
|
|
86
|
+
"publishConfig": {
|
|
87
|
+
"access": "public"
|
|
88
|
+
}
|
|
89
|
+
}
|