@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/oscal.ts
ADDED
|
@@ -0,0 +1,850 @@
|
|
|
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, type Risk } from "./assess.ts";
|
|
35
|
+
import { canonicalize } from "./evidence.ts";
|
|
36
|
+
import {
|
|
37
|
+
type Assessment,
|
|
38
|
+
type ControlRef,
|
|
39
|
+
type ControlSummary,
|
|
40
|
+
type Finding,
|
|
41
|
+
type Instant,
|
|
42
|
+
type Outcome,
|
|
43
|
+
type SubjectRef,
|
|
44
|
+
findingKey,
|
|
45
|
+
joinAll,
|
|
46
|
+
} from "./grc.ts";
|
|
47
|
+
import { type Uuid, uuidV5Of } from "@intellectual-frontiers/crypto/uuid";
|
|
48
|
+
|
|
49
|
+
/** The OSCAL version written. */
|
|
50
|
+
export const OSCAL_VERSION = "1.2.3";
|
|
51
|
+
|
|
52
|
+
/** NIST SP 800-30 Rev. 1, the system a risk's likelihood, impact and level facets are named in. */
|
|
53
|
+
export const SP800_30 = "https://doi.org/10.6028/NIST.SP.800-30r1";
|
|
54
|
+
|
|
55
|
+
/** The `identifier-type` of a system id that is a UUID. */
|
|
56
|
+
export const RFC4122 = "https://ietf.org/rfc/rfc4122";
|
|
57
|
+
|
|
58
|
+
// ---------------------------------------------------------------------------------------------------------------------------- types
|
|
59
|
+
|
|
60
|
+
/** An OSCAL property: a name, a value, and the namespace the name is defined in where it is not OSCAL's. */
|
|
61
|
+
export type OscalProp = { readonly name: string; readonly value: string; readonly ns?: string };
|
|
62
|
+
|
|
63
|
+
/** An OSCAL party: the organization a document is by. */
|
|
64
|
+
export type OscalParty = { readonly uuid: Uuid; readonly type: "organization" | "person"; readonly name: string };
|
|
65
|
+
|
|
66
|
+
/** An OSCAL document's metadata. */
|
|
67
|
+
export type OscalMetadata = {
|
|
68
|
+
readonly title: string;
|
|
69
|
+
readonly "last-modified": Instant;
|
|
70
|
+
readonly version: string;
|
|
71
|
+
readonly "oscal-version": typeof OSCAL_VERSION;
|
|
72
|
+
readonly parties?: readonly OscalParty[];
|
|
73
|
+
};
|
|
74
|
+
|
|
75
|
+
/** A back-matter resource. */
|
|
76
|
+
export type OscalResource = {
|
|
77
|
+
readonly uuid: Uuid;
|
|
78
|
+
readonly title: string;
|
|
79
|
+
readonly description?: string;
|
|
80
|
+
readonly props?: readonly OscalProp[];
|
|
81
|
+
readonly rlinks?: readonly { readonly href: string }[];
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
/** A document's back matter. */
|
|
85
|
+
export type OscalBackMatter = { readonly resources: readonly OscalResource[] };
|
|
86
|
+
|
|
87
|
+
/** An inventory item: a subject of an assessment. */
|
|
88
|
+
export type OscalInventoryItem = { readonly uuid: Uuid; readonly description: string; readonly props: readonly OscalProp[] };
|
|
89
|
+
|
|
90
|
+
/** A reference from an observation to the subject it observed. */
|
|
91
|
+
export type OscalSubjectReference = { readonly "subject-uuid": Uuid; readonly type: "inventory-item"; readonly title: string };
|
|
92
|
+
|
|
93
|
+
/** Evidence an observation relied on, here the SHA-256 of a piece of evidence. */
|
|
94
|
+
export type OscalRelevantEvidence = { readonly description: string; readonly props: readonly OscalProp[] };
|
|
95
|
+
|
|
96
|
+
/** An observation: one finding of one control on one subject. */
|
|
97
|
+
export type OscalObservation = {
|
|
98
|
+
readonly uuid: Uuid;
|
|
99
|
+
readonly title: string;
|
|
100
|
+
readonly description: string;
|
|
101
|
+
readonly props: readonly OscalProp[];
|
|
102
|
+
readonly methods: readonly ("EXAMINE" | "INTERVIEW" | "TEST" | "UNKNOWN")[];
|
|
103
|
+
readonly types: readonly string[];
|
|
104
|
+
readonly subjects: readonly OscalSubjectReference[];
|
|
105
|
+
readonly "relevant-evidence"?: readonly OscalRelevantEvidence[];
|
|
106
|
+
readonly collected: Instant;
|
|
107
|
+
readonly remarks?: string;
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
/** The status of an OSCAL finding's target. */
|
|
111
|
+
export type OscalTargetStatus = { readonly state: "satisfied" | "not-satisfied"; readonly reason?: "pass" | "fail" | "other" };
|
|
112
|
+
|
|
113
|
+
/** An OSCAL finding: what the observations say of one control. */
|
|
114
|
+
export type OscalFinding = {
|
|
115
|
+
readonly uuid: Uuid;
|
|
116
|
+
readonly title: string;
|
|
117
|
+
readonly description: string;
|
|
118
|
+
readonly props: readonly OscalProp[];
|
|
119
|
+
readonly target: { readonly type: "objective-id"; readonly "target-id": string; readonly status: OscalTargetStatus };
|
|
120
|
+
readonly "related-observations"?: readonly { readonly "observation-uuid": Uuid }[];
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
/** The controls a result reviewed. */
|
|
124
|
+
export type OscalReviewedControls = {
|
|
125
|
+
readonly "control-selections": readonly (
|
|
126
|
+
| { readonly "include-controls": readonly { readonly "control-id": string }[] }
|
|
127
|
+
| { readonly "include-all": Readonly<Record<string, never>> }
|
|
128
|
+
)[];
|
|
129
|
+
};
|
|
130
|
+
|
|
131
|
+
/** One result of an assessment. */
|
|
132
|
+
export type OscalResult = {
|
|
133
|
+
readonly uuid: Uuid;
|
|
134
|
+
readonly title: string;
|
|
135
|
+
readonly description: string;
|
|
136
|
+
readonly start: Instant;
|
|
137
|
+
readonly "local-definitions"?: { readonly "inventory-items": readonly OscalInventoryItem[] };
|
|
138
|
+
readonly "reviewed-controls": OscalReviewedControls;
|
|
139
|
+
readonly observations?: readonly OscalObservation[];
|
|
140
|
+
readonly findings?: readonly OscalFinding[];
|
|
141
|
+
};
|
|
142
|
+
|
|
143
|
+
/** An OSCAL assessment-results document. */
|
|
144
|
+
export type OscalAssessmentResults = {
|
|
145
|
+
readonly "assessment-results": {
|
|
146
|
+
readonly uuid: Uuid;
|
|
147
|
+
readonly metadata: OscalMetadata;
|
|
148
|
+
readonly "import-ap": { readonly href: string };
|
|
149
|
+
readonly results: readonly OscalResult[];
|
|
150
|
+
readonly "back-matter"?: OscalBackMatter;
|
|
151
|
+
};
|
|
152
|
+
};
|
|
153
|
+
|
|
154
|
+
/** The status of an OSCAL risk. */
|
|
155
|
+
export type OscalRiskStatus = "open" | "investigating" | "remediating" | "deviation-requested" | "deviation-approved" | "closed";
|
|
156
|
+
|
|
157
|
+
/** A characterization of a risk: who made it, and its facets. */
|
|
158
|
+
export type OscalCharacterization = {
|
|
159
|
+
readonly origin: { readonly actors: readonly { readonly type: "party"; readonly "actor-uuid": Uuid }[] };
|
|
160
|
+
readonly facets: readonly { readonly name: string; readonly system: string; readonly value: string }[];
|
|
161
|
+
};
|
|
162
|
+
|
|
163
|
+
/** An OSCAL risk. */
|
|
164
|
+
export type OscalRisk = {
|
|
165
|
+
readonly uuid: Uuid;
|
|
166
|
+
readonly title: string;
|
|
167
|
+
readonly description: string;
|
|
168
|
+
readonly statement: string;
|
|
169
|
+
readonly props?: readonly OscalProp[];
|
|
170
|
+
readonly status: OscalRiskStatus;
|
|
171
|
+
readonly characterizations?: readonly OscalCharacterization[];
|
|
172
|
+
readonly "related-observations"?: readonly { readonly "observation-uuid": Uuid }[];
|
|
173
|
+
};
|
|
174
|
+
|
|
175
|
+
/** An item of a plan of action and milestones. */
|
|
176
|
+
export type OscalPoamItem = {
|
|
177
|
+
readonly uuid: Uuid;
|
|
178
|
+
readonly title: string;
|
|
179
|
+
readonly description: string;
|
|
180
|
+
readonly props?: readonly OscalProp[];
|
|
181
|
+
readonly "related-observations"?: readonly { readonly "observation-uuid": Uuid }[];
|
|
182
|
+
readonly "related-risks": readonly { readonly "risk-uuid": Uuid }[];
|
|
183
|
+
};
|
|
184
|
+
|
|
185
|
+
/** An OSCAL plan-of-action-and-milestones document. */
|
|
186
|
+
export type OscalPoam = {
|
|
187
|
+
readonly "plan-of-action-and-milestones": {
|
|
188
|
+
readonly uuid: Uuid;
|
|
189
|
+
readonly metadata: OscalMetadata;
|
|
190
|
+
readonly "local-definitions"?: { readonly "inventory-items": readonly OscalInventoryItem[] };
|
|
191
|
+
readonly observations?: readonly OscalObservation[];
|
|
192
|
+
readonly risks?: readonly OscalRisk[];
|
|
193
|
+
readonly "poam-items": readonly OscalPoamItem[];
|
|
194
|
+
};
|
|
195
|
+
};
|
|
196
|
+
|
|
197
|
+
/** A catalog control a component implements, and how. */
|
|
198
|
+
export type OscalImplementedRequirement = {
|
|
199
|
+
readonly uuid: Uuid;
|
|
200
|
+
readonly "control-id": string;
|
|
201
|
+
readonly description: string;
|
|
202
|
+
readonly props: readonly OscalProp[];
|
|
203
|
+
};
|
|
204
|
+
|
|
205
|
+
/** A component's implementation of the controls of one catalog. */
|
|
206
|
+
export type OscalControlImplementation = {
|
|
207
|
+
readonly uuid: Uuid;
|
|
208
|
+
readonly source: string;
|
|
209
|
+
readonly description: string;
|
|
210
|
+
readonly "implemented-requirements": readonly OscalImplementedRequirement[];
|
|
211
|
+
};
|
|
212
|
+
|
|
213
|
+
/** The types of a defined component (OSCAL 1.2.3 `defined-component/type`; 1.2 added `region`, `zone`, `resource-container` and `network`). */
|
|
214
|
+
export const OSCAL_COMPONENT_TYPES = [
|
|
215
|
+
"interconnection",
|
|
216
|
+
"software",
|
|
217
|
+
"hardware",
|
|
218
|
+
"service",
|
|
219
|
+
"policy",
|
|
220
|
+
"physical",
|
|
221
|
+
"process-procedure",
|
|
222
|
+
"plan",
|
|
223
|
+
"guidance",
|
|
224
|
+
"standard",
|
|
225
|
+
"validation",
|
|
226
|
+
"region",
|
|
227
|
+
"zone",
|
|
228
|
+
"resource-container",
|
|
229
|
+
"network",
|
|
230
|
+
] as const;
|
|
231
|
+
|
|
232
|
+
/** The type of a component. */
|
|
233
|
+
export type OscalComponentType = (typeof OSCAL_COMPONENT_TYPES)[number];
|
|
234
|
+
|
|
235
|
+
/** A component of a component definition. */
|
|
236
|
+
export type OscalDefinedComponent = {
|
|
237
|
+
readonly uuid: Uuid;
|
|
238
|
+
readonly type: OscalComponentType;
|
|
239
|
+
readonly title: string;
|
|
240
|
+
readonly description: string;
|
|
241
|
+
readonly props?: readonly OscalProp[];
|
|
242
|
+
readonly "control-implementations"?: readonly OscalControlImplementation[];
|
|
243
|
+
};
|
|
244
|
+
|
|
245
|
+
/** An OSCAL component-definition document. */
|
|
246
|
+
export type OscalComponentDefinition = {
|
|
247
|
+
readonly "component-definition": {
|
|
248
|
+
readonly uuid: Uuid;
|
|
249
|
+
readonly metadata: OscalMetadata;
|
|
250
|
+
readonly components: readonly OscalDefinedComponent[];
|
|
251
|
+
readonly "back-matter"?: OscalBackMatter;
|
|
252
|
+
};
|
|
253
|
+
};
|
|
254
|
+
|
|
255
|
+
/** How far a control is implemented. */
|
|
256
|
+
export type OscalImplementationState = "implemented" | "partial" | "planned" | "alternative" | "not-applicable";
|
|
257
|
+
|
|
258
|
+
/** An SSP's statement of one catalog control. */
|
|
259
|
+
export type OscalSspRequirement = {
|
|
260
|
+
readonly uuid: Uuid;
|
|
261
|
+
readonly "control-id": string;
|
|
262
|
+
readonly props: readonly OscalProp[];
|
|
263
|
+
readonly "by-components": readonly {
|
|
264
|
+
readonly "component-uuid": Uuid;
|
|
265
|
+
readonly uuid: Uuid;
|
|
266
|
+
readonly description: string;
|
|
267
|
+
readonly "implementation-status": { readonly state: OscalImplementationState };
|
|
268
|
+
}[];
|
|
269
|
+
};
|
|
270
|
+
|
|
271
|
+
/** An OSCAL system-security-plan document, minimal: the system, its users and components, and how far each control is implemented. */
|
|
272
|
+
export type OscalSsp = {
|
|
273
|
+
readonly "system-security-plan": {
|
|
274
|
+
readonly uuid: Uuid;
|
|
275
|
+
readonly metadata: OscalMetadata;
|
|
276
|
+
readonly "import-profile": { readonly href: string };
|
|
277
|
+
readonly "system-characteristics": {
|
|
278
|
+
readonly "system-ids": readonly { readonly "identifier-type": string; readonly id: string }[];
|
|
279
|
+
readonly "system-name": string;
|
|
280
|
+
readonly description: string;
|
|
281
|
+
readonly "system-information": {
|
|
282
|
+
readonly "information-types": readonly { readonly uuid: Uuid; readonly title: string; readonly description: string }[];
|
|
283
|
+
};
|
|
284
|
+
readonly status: { readonly state: "operational" | "under-development" | "under-major-modification" | "disposition" | "other" };
|
|
285
|
+
readonly "authorization-boundary": { readonly description: string };
|
|
286
|
+
};
|
|
287
|
+
readonly "system-implementation": {
|
|
288
|
+
readonly users: readonly { readonly uuid: Uuid; readonly title: string }[];
|
|
289
|
+
readonly components: readonly {
|
|
290
|
+
readonly uuid: Uuid;
|
|
291
|
+
readonly type: "this-system";
|
|
292
|
+
readonly title: string;
|
|
293
|
+
readonly description: string;
|
|
294
|
+
readonly status: { readonly state: "operational" };
|
|
295
|
+
}[];
|
|
296
|
+
readonly "inventory-items"?: readonly OscalInventoryItem[];
|
|
297
|
+
};
|
|
298
|
+
readonly "control-implementation": {
|
|
299
|
+
readonly description: string;
|
|
300
|
+
readonly "implemented-requirements": readonly OscalSspRequirement[];
|
|
301
|
+
};
|
|
302
|
+
};
|
|
303
|
+
};
|
|
304
|
+
|
|
305
|
+
/** Any document this module writes. */
|
|
306
|
+
export type OscalDocument = OscalAssessmentResults | OscalPoam | OscalComponentDefinition | OscalSsp;
|
|
307
|
+
|
|
308
|
+
/** What every document needs: the namespace of its UUIDs, its metadata, and the namespace of the properties this module names. */
|
|
309
|
+
export type OscalOptions = {
|
|
310
|
+
/** The namespace every `uuid` is a version 5 UUID in. */
|
|
311
|
+
readonly namespace: Uuid;
|
|
312
|
+
readonly lastModified: Instant;
|
|
313
|
+
readonly version: string;
|
|
314
|
+
/** The namespace (a URI) of the properties this module defines: `outcome`, `status`, `severity`, `control`, `sha256`, ... */
|
|
315
|
+
readonly propNamespace: string;
|
|
316
|
+
/** The document's title; each function has a default. */
|
|
317
|
+
readonly title?: string;
|
|
318
|
+
/** The organization the document is by, as a party. */
|
|
319
|
+
readonly organization?: string;
|
|
320
|
+
/** The OSCAL `control-id` of a catalog control; by default its id as the catalog has it. */
|
|
321
|
+
readonly controlId?: (ref: ControlRef) => string;
|
|
322
|
+
/** The `href` of a catalog (a control implementation's `source`); by default a back-matter resource of the document. */
|
|
323
|
+
readonly catalogHref?: (catalog: string) => string;
|
|
324
|
+
};
|
|
325
|
+
|
|
326
|
+
// ---------------------------------------------------------------------------------------------------------------------------- helpers
|
|
327
|
+
|
|
328
|
+
const byText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
|
|
329
|
+
|
|
330
|
+
function text(s: string | undefined, fallback: string): string {
|
|
331
|
+
const t = (s ?? "").trim();
|
|
332
|
+
return t === "" ? fallback : t;
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
function stableText(value: unknown): string {
|
|
336
|
+
const c = canonicalize(value);
|
|
337
|
+
return c.kind === "ok" ? c.value : String(value);
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
const subjectKey = (s: SubjectRef): string => JSON.stringify([s.kind, s.id]);
|
|
341
|
+
|
|
342
|
+
/** 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. */
|
|
343
|
+
function ordered(findings: readonly Finding[]): readonly { readonly finding: Finding; readonly key: string; readonly n: number }[] {
|
|
344
|
+
const keyed = findings.map((f) => ({ finding: f, key: findingKey(f), text: stableText(f) }));
|
|
345
|
+
keyed.sort((a, b) => byText(a.key, b.key) || byText(a.text, b.text));
|
|
346
|
+
const count = new Map<string, number>();
|
|
347
|
+
return keyed.map(({ finding, key }) => {
|
|
348
|
+
const n = count.get(key) ?? 0;
|
|
349
|
+
count.set(key, n + 1);
|
|
350
|
+
return { finding, key, n };
|
|
351
|
+
});
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
function uniqueControls(controls: readonly ControlSummary[]): readonly ControlSummary[] {
|
|
355
|
+
const seen = new Map<string, ControlSummary>();
|
|
356
|
+
for (const c of controls) if (!seen.has(c.id)) seen.set(c.id, c);
|
|
357
|
+
return [...seen.values()].sort((a, b) => byText(a.id, b.id));
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
function uniqueSubjects(subjects: readonly SubjectRef[]): readonly SubjectRef[] {
|
|
361
|
+
const seen = new Map<string, SubjectRef>();
|
|
362
|
+
for (const s of subjects) if (!seen.has(subjectKey(s))) seen.set(subjectKey(s), s);
|
|
363
|
+
return [...seen.entries()].sort(([a], [b]) => byText(a, b)).map(([, s]) => s);
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
async function metadataOf(o: OscalOptions, title: string): Promise<OscalMetadata> {
|
|
367
|
+
return {
|
|
368
|
+
title: text(o.title, title),
|
|
369
|
+
"last-modified": o.lastModified,
|
|
370
|
+
version: text(o.version, "1"),
|
|
371
|
+
"oscal-version": OSCAL_VERSION,
|
|
372
|
+
...(o.organization === undefined
|
|
373
|
+
? {}
|
|
374
|
+
: {
|
|
375
|
+
parties: [
|
|
376
|
+
{
|
|
377
|
+
uuid: await uuidV5Of(o.namespace, ["party", o.organization]),
|
|
378
|
+
type: "organization",
|
|
379
|
+
name: text(o.organization, "organization"),
|
|
380
|
+
},
|
|
381
|
+
],
|
|
382
|
+
}),
|
|
383
|
+
};
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
/** A target of a control: a catalog control it implements (by catalog and OSCAL id), or the control itself where it implements none. */
|
|
387
|
+
type Target = { readonly key: string; readonly controlId: string; readonly controls: readonly string[] };
|
|
388
|
+
|
|
389
|
+
function targetsOf(controls: readonly ControlSummary[], o: OscalOptions): readonly Target[] {
|
|
390
|
+
const idOf = o.controlId ?? ((r: ControlRef): string => r.id);
|
|
391
|
+
const targets = new Map<string, { controlId: string; controls: Set<string> }>();
|
|
392
|
+
const add = (key: string, controlId: string, control: string): void => {
|
|
393
|
+
const t = targets.get(key) ?? { controlId, controls: new Set<string>() };
|
|
394
|
+
t.controls.add(control);
|
|
395
|
+
targets.set(key, t);
|
|
396
|
+
};
|
|
397
|
+
for (const c of uniqueControls(controls)) {
|
|
398
|
+
if (c.implements.length === 0) add(JSON.stringify(["", c.id]), c.id, c.id);
|
|
399
|
+
for (const r of c.implements) add(JSON.stringify([r.catalog, r.id]), idOf(r), c.id);
|
|
400
|
+
}
|
|
401
|
+
return [...targets.entries()]
|
|
402
|
+
.sort(([a], [b]) => byText(a, b))
|
|
403
|
+
.map(([key, t]) => ({ key, controlId: t.controlId, controls: [...t.controls].sort(byText) }));
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
function targetStatus(outcome: Outcome): OscalTargetStatus {
|
|
407
|
+
switch (outcome) {
|
|
408
|
+
case "pass":
|
|
409
|
+
case "accepted":
|
|
410
|
+
case "not-applicable":
|
|
411
|
+
return { state: "satisfied" };
|
|
412
|
+
case "warn":
|
|
413
|
+
case "gap":
|
|
414
|
+
case "fail":
|
|
415
|
+
return { state: "not-satisfied", reason: "fail" };
|
|
416
|
+
case "error":
|
|
417
|
+
return { state: "not-satisfied", reason: "other" };
|
|
418
|
+
default:
|
|
419
|
+
return absurd(outcome);
|
|
420
|
+
}
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
async function inventoryItems(subjects: readonly SubjectRef[], o: OscalOptions): Promise<readonly OscalInventoryItem[]> {
|
|
424
|
+
return Promise.all(
|
|
425
|
+
uniqueSubjects(subjects).map(async (s) => ({
|
|
426
|
+
uuid: await subjectUuid(s, o),
|
|
427
|
+
description: text(`${s.kind} ${s.id}`, "a subject"),
|
|
428
|
+
props: [
|
|
429
|
+
{ name: "asset-id", value: text(s.id, "unnamed") },
|
|
430
|
+
{ name: "subject-kind", ns: o.propNamespace, value: text(s.kind, "unknown") },
|
|
431
|
+
],
|
|
432
|
+
})),
|
|
433
|
+
);
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
function subjectUuid(s: SubjectRef, o: OscalOptions): Promise<Uuid> {
|
|
437
|
+
return uuidV5Of(o.namespace, ["subject", s.kind, s.id]);
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
async function observation(f: Finding, key: string, n: number, scope: readonly string[], o: OscalOptions): Promise<OscalObservation> {
|
|
441
|
+
const p = (name: string, value: string): OscalProp => ({ name, ns: o.propNamespace, value: text(value, "none") });
|
|
442
|
+
return {
|
|
443
|
+
uuid: await uuidV5Of(o.namespace, ["observation", ...scope, key, String(n)]),
|
|
444
|
+
title: text(`${f.control.id} on ${f.subject.kind} ${f.subject.id}: ${f.title}`, f.control.id),
|
|
445
|
+
description: text(f.detail, `${f.control.id}: ${f.outcome}`),
|
|
446
|
+
props: [
|
|
447
|
+
p("control", f.control.id),
|
|
448
|
+
p("outcome", f.outcome),
|
|
449
|
+
p("status", f.status),
|
|
450
|
+
p("severity", f.severity),
|
|
451
|
+
...(f.waiver === undefined ? [] : [p("waiver", f.waiver)]),
|
|
452
|
+
],
|
|
453
|
+
methods: ["TEST"],
|
|
454
|
+
types: ["finding"],
|
|
455
|
+
subjects: [
|
|
456
|
+
{
|
|
457
|
+
"subject-uuid": await subjectUuid(f.subject, o),
|
|
458
|
+
type: "inventory-item",
|
|
459
|
+
title: text(`${f.subject.kind} ${f.subject.id}`, "a subject"),
|
|
460
|
+
},
|
|
461
|
+
],
|
|
462
|
+
...(f.evidence.length === 0
|
|
463
|
+
? {}
|
|
464
|
+
: {
|
|
465
|
+
"relevant-evidence": [...new Set(f.evidence)]
|
|
466
|
+
.sort(byText)
|
|
467
|
+
.map((d) => ({ description: `evidence of SHA-256 ${d}`, props: [{ name: "sha256", ns: o.propNamespace, value: d }] })),
|
|
468
|
+
}),
|
|
469
|
+
collected: f.at,
|
|
470
|
+
...(f.remediation === undefined || f.outcome === "pass" || text(f.remediation, "") === "" ? {} : { remarks: text(f.remediation, "") }),
|
|
471
|
+
};
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
// ---------------------------------------------------------------------------------------------------------------------------- assessment results
|
|
475
|
+
|
|
476
|
+
/**
|
|
477
|
+
* An assessment as OSCAL assessment results: one result, its subjects as inventory items, each finding an observation, and each control
|
|
478
|
+
* reviewed (each catalog control the assessment's controls implement, or a control that implements none) an OSCAL finding whose target is
|
|
479
|
+
* satisfied or not by the join of the outcomes of the newest findings of its controls. `assessmentPlan` is the `import-ap` href; by default
|
|
480
|
+
* a back-matter resource that stands for the plan.
|
|
481
|
+
*/
|
|
482
|
+
export async function assessmentResults(
|
|
483
|
+
a: Assessment,
|
|
484
|
+
o: OscalOptions & { readonly assessmentPlan?: string },
|
|
485
|
+
): Promise<OscalAssessmentResults> {
|
|
486
|
+
const scope = [a.pack.id, a.at];
|
|
487
|
+
const list = ordered(a.findings);
|
|
488
|
+
const observations = await Promise.all(list.map(({ finding, key, n }) => observation(finding, key, n, scope, o)));
|
|
489
|
+
const newest = new Set(newestFindings(a.findings));
|
|
490
|
+
const controls = uniqueControls([...a.controls, ...a.findings.map((f) => f.control)]);
|
|
491
|
+
const targets = targetsOf(controls, o);
|
|
492
|
+
const findings = await Promise.all(
|
|
493
|
+
targets.map(async (t): Promise<OscalFinding> => {
|
|
494
|
+
const related = list.flatMap(({ finding }, i) => (t.controls.includes(finding.control.id) ? [{ finding, i }] : []));
|
|
495
|
+
const outcome = joinAll(related.filter((r) => newest.has(r.finding)).map((r) => r.finding.outcome));
|
|
496
|
+
const observed = related.flatMap(({ i }) => {
|
|
497
|
+
const obs = observations[i];
|
|
498
|
+
return obs === undefined ? [] : [{ "observation-uuid": obs.uuid }];
|
|
499
|
+
});
|
|
500
|
+
return {
|
|
501
|
+
uuid: await uuidV5Of(o.namespace, ["finding", ...scope, t.key]),
|
|
502
|
+
title: text(t.controlId, "control"),
|
|
503
|
+
description: `${t.controlId}: ${related.length === 0 ? "not assessed" : outcome}, by ${t.controls.join(", ")}.`,
|
|
504
|
+
props: [
|
|
505
|
+
{ name: "outcome", ns: o.propNamespace, value: related.length === 0 ? "not-applicable" : outcome },
|
|
506
|
+
...t.controls.map((c) => ({ name: "control", ns: o.propNamespace, value: text(c, "control") })),
|
|
507
|
+
],
|
|
508
|
+
target: { type: "objective-id", "target-id": t.controlId, status: targetStatus(outcome) },
|
|
509
|
+
...(observed.length === 0 ? {} : { "related-observations": observed }),
|
|
510
|
+
};
|
|
511
|
+
}),
|
|
512
|
+
);
|
|
513
|
+
const plan = await uuidV5Of(o.namespace, ["assessment-plan", a.pack.id]);
|
|
514
|
+
const subjects = await inventoryItems([...a.subjects, ...a.findings.map((f) => f.subject)], o);
|
|
515
|
+
const ids = [...new Set(targets.map((t) => t.controlId))].sort(byText);
|
|
516
|
+
const result: OscalResult = {
|
|
517
|
+
uuid: await uuidV5Of(o.namespace, ["result", ...scope]),
|
|
518
|
+
title: text(`${a.pack.title} as of ${a.at}`, a.pack.id),
|
|
519
|
+
description: text(`The findings of ${a.pack.title} (${a.pack.id}), assessed at ${a.at}.`, "The findings of an assessment."),
|
|
520
|
+
start: a.at,
|
|
521
|
+
...(subjects.length === 0 ? {} : { "local-definitions": { "inventory-items": subjects } }),
|
|
522
|
+
"reviewed-controls": {
|
|
523
|
+
"control-selections": [ids.length === 0 ? { "include-all": {} } : { "include-controls": ids.map((id) => ({ "control-id": id })) }],
|
|
524
|
+
},
|
|
525
|
+
...(observations.length === 0 ? {} : { observations }),
|
|
526
|
+
...(findings.length === 0 ? {} : { findings }),
|
|
527
|
+
};
|
|
528
|
+
return {
|
|
529
|
+
"assessment-results": {
|
|
530
|
+
uuid: await uuidV5Of(o.namespace, ["assessment-results", ...scope]),
|
|
531
|
+
metadata: await metadataOf(o, `${text(a.pack.title, a.pack.id)}: assessment results`),
|
|
532
|
+
"import-ap": { href: o.assessmentPlan ?? `#${plan}` },
|
|
533
|
+
results: [result],
|
|
534
|
+
...(o.assessmentPlan === undefined
|
|
535
|
+
? { "back-matter": { resources: [{ uuid: plan, title: text(`The assessment plan of ${a.pack.title}`, "The assessment plan") }] } }
|
|
536
|
+
: {}),
|
|
537
|
+
},
|
|
538
|
+
};
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
// ---------------------------------------------------------------------------------------------------------------------------- POA&M
|
|
542
|
+
|
|
543
|
+
const OPEN_OUTCOMES: ReadonlySet<Outcome> = new Set<Outcome>(["fail", "warn", "gap", "error", "accepted"]);
|
|
544
|
+
|
|
545
|
+
function riskStatus(r: Risk): OscalRiskStatus {
|
|
546
|
+
switch (r.treatment) {
|
|
547
|
+
case "accept":
|
|
548
|
+
case "transfer":
|
|
549
|
+
return "deviation-approved";
|
|
550
|
+
case "mitigate":
|
|
551
|
+
case "avoid":
|
|
552
|
+
return "remediating";
|
|
553
|
+
default:
|
|
554
|
+
return absurd(r.treatment);
|
|
555
|
+
}
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
/**
|
|
559
|
+
* A plan of action and milestones: for each finding whose outcome is `fail`, `warn`, `gap`, `error` or `accepted`, an observation, a risk
|
|
560
|
+
* (`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
|
|
561
|
+
* 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
|
|
562
|
+
* (not its time), so the same open finding keeps its UUIDs from one assessment to the next.
|
|
563
|
+
*/
|
|
564
|
+
export async function poam(a: Assessment, risks: readonly Risk[], o: OscalOptions): Promise<OscalPoam> {
|
|
565
|
+
const list = ordered(a.findings.filter((f) => OPEN_OUTCOMES.has(f.outcome)));
|
|
566
|
+
const scope = [a.pack.id, a.at];
|
|
567
|
+
const party = o.organization === undefined ? undefined : await uuidV5Of(o.namespace, ["party", o.organization]);
|
|
568
|
+
const observations = await Promise.all(list.map(({ finding, key, n }) => observation(finding, key, n, scope, o)));
|
|
569
|
+
const findingRisks = await Promise.all(
|
|
570
|
+
list.map(async ({ finding: f, key, n }, i): Promise<OscalRisk> => {
|
|
571
|
+
const obs = observations[i];
|
|
572
|
+
return {
|
|
573
|
+
uuid: await uuidV5Of(o.namespace, ["risk", "finding", a.pack.id, key, String(n)]),
|
|
574
|
+
title: text(`${f.control.id} on ${f.subject.kind} ${f.subject.id}: ${f.title}`, f.control.id),
|
|
575
|
+
description: text(f.detail, `${f.control.id}: ${f.outcome}`),
|
|
576
|
+
statement: text(
|
|
577
|
+
f.outcome === "accepted"
|
|
578
|
+
? `Accepted under waiver ${f.waiver ?? "(unnamed)"}: ${f.status}.`
|
|
579
|
+
: `${f.outcome} (severity ${f.severity}).${f.remediation === undefined ? "" : ` Remediation: ${f.remediation}`}`,
|
|
580
|
+
f.outcome,
|
|
581
|
+
),
|
|
582
|
+
props: [
|
|
583
|
+
{ name: "control", ns: o.propNamespace, value: text(f.control.id, "control") },
|
|
584
|
+
{ name: "severity", ns: o.propNamespace, value: f.severity },
|
|
585
|
+
],
|
|
586
|
+
status: f.outcome === "accepted" ? "deviation-approved" : "open",
|
|
587
|
+
...(obs === undefined ? {} : { "related-observations": [{ "observation-uuid": obs.uuid }] }),
|
|
588
|
+
};
|
|
589
|
+
}),
|
|
590
|
+
);
|
|
591
|
+
const register = [...risks].sort((x, y) => byText(x.id, y.id));
|
|
592
|
+
const registerRisks = await Promise.all(
|
|
593
|
+
register.map(async (r): Promise<OscalRisk> => ({
|
|
594
|
+
uuid: await uuidV5Of(o.namespace, ["risk", "register", r.id]),
|
|
595
|
+
title: text(r.title, r.id),
|
|
596
|
+
description: text(r.description, text(r.title, r.id)),
|
|
597
|
+
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}.`,
|
|
598
|
+
props: [
|
|
599
|
+
{ name: "risk-id", ns: o.propNamespace, value: text(r.id, "risk") },
|
|
600
|
+
{ name: "treatment", ns: o.propNamespace, value: r.treatment },
|
|
601
|
+
{ name: "owner", ns: o.propNamespace, value: text(r.owner, "owner") },
|
|
602
|
+
{ name: "review-by", ns: o.propNamespace, value: r.reviewBy },
|
|
603
|
+
...[...new Set(r.controls ?? [])].sort(byText).map((c) => ({ name: "control", ns: o.propNamespace, value: text(c, "control") })),
|
|
604
|
+
],
|
|
605
|
+
status: riskStatus(r),
|
|
606
|
+
...(party === undefined
|
|
607
|
+
? {}
|
|
608
|
+
: {
|
|
609
|
+
characterizations: [
|
|
610
|
+
{
|
|
611
|
+
origin: { actors: [{ type: "party", "actor-uuid": party }] },
|
|
612
|
+
facets: [
|
|
613
|
+
{ name: "likelihood", system: SP800_30, value: r.likelihood },
|
|
614
|
+
{ name: "impact", system: SP800_30, value: r.impact },
|
|
615
|
+
{ name: "risk", system: SP800_30, value: r.level },
|
|
616
|
+
],
|
|
617
|
+
},
|
|
618
|
+
],
|
|
619
|
+
}),
|
|
620
|
+
})),
|
|
621
|
+
);
|
|
622
|
+
const items: OscalPoamItem[] = [];
|
|
623
|
+
for (const [i, { finding: f, key, n }] of list.entries()) {
|
|
624
|
+
const obs = observations[i];
|
|
625
|
+
const risk = findingRisks[i];
|
|
626
|
+
if (obs === undefined || risk === undefined) continue;
|
|
627
|
+
items.push({
|
|
628
|
+
uuid: await uuidV5Of(o.namespace, ["poam-item", "finding", a.pack.id, key, String(n)]),
|
|
629
|
+
title: risk.title,
|
|
630
|
+
description: risk.statement,
|
|
631
|
+
props: [{ name: "outcome", ns: o.propNamespace, value: f.outcome }],
|
|
632
|
+
"related-observations": [{ "observation-uuid": obs.uuid }],
|
|
633
|
+
"related-risks": [{ "risk-uuid": risk.uuid }],
|
|
634
|
+
});
|
|
635
|
+
}
|
|
636
|
+
for (const r of registerRisks) {
|
|
637
|
+
const id = r.props?.[0]?.value ?? r.title;
|
|
638
|
+
items.push({
|
|
639
|
+
uuid: await uuidV5Of(o.namespace, ["poam-item", "register", id]),
|
|
640
|
+
title: text(`Risk register: ${r.title}`, "Risk register"),
|
|
641
|
+
description: r.statement,
|
|
642
|
+
"related-risks": [{ "risk-uuid": r.uuid }],
|
|
643
|
+
});
|
|
644
|
+
}
|
|
645
|
+
const subjects = await inventoryItems(
|
|
646
|
+
list.map(({ finding }) => finding.subject),
|
|
647
|
+
o,
|
|
648
|
+
);
|
|
649
|
+
const allRisks = [...findingRisks, ...registerRisks];
|
|
650
|
+
return {
|
|
651
|
+
"plan-of-action-and-milestones": {
|
|
652
|
+
uuid: await uuidV5Of(o.namespace, ["plan-of-action-and-milestones", ...scope]),
|
|
653
|
+
metadata: await metadataOf(o, `${text(a.pack.title, a.pack.id)}: plan of action and milestones`),
|
|
654
|
+
...(subjects.length === 0 ? {} : { "local-definitions": { "inventory-items": subjects } }),
|
|
655
|
+
...(observations.length === 0 ? {} : { observations }),
|
|
656
|
+
...(allRisks.length === 0 ? {} : { risks: allRisks }),
|
|
657
|
+
"poam-items": items,
|
|
658
|
+
},
|
|
659
|
+
};
|
|
660
|
+
}
|
|
661
|
+
|
|
662
|
+
// ---------------------------------------------------------------------------------------------------------------------------- component definition
|
|
663
|
+
|
|
664
|
+
/** The component a component definition describes. */
|
|
665
|
+
export type ComponentInput = {
|
|
666
|
+
readonly id: string;
|
|
667
|
+
readonly title: string;
|
|
668
|
+
readonly description: string;
|
|
669
|
+
readonly type?: OscalComponentType;
|
|
670
|
+
readonly version?: string;
|
|
671
|
+
};
|
|
672
|
+
|
|
673
|
+
async function catalogResources(catalogs: readonly string[], o: OscalOptions): Promise<readonly OscalResource[]> {
|
|
674
|
+
return Promise.all(catalogs.map(async (c) => ({ uuid: await uuidV5Of(o.namespace, ["catalog", c]), title: text(c, "catalog") })));
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
/**
|
|
678
|
+
* A component definition of one component: for each catalog its controls implement (in the catalogs' order), a control implementation
|
|
679
|
+
* whose implemented requirements are those catalog controls, each saying which controls implement it. A catalog's `source` is
|
|
680
|
+
* `catalogHref`'s, or a back-matter resource that stands for it.
|
|
681
|
+
*/
|
|
682
|
+
export async function componentDefinition(
|
|
683
|
+
controls: readonly ControlSummary[],
|
|
684
|
+
component: ComponentInput,
|
|
685
|
+
o: OscalOptions,
|
|
686
|
+
): Promise<OscalComponentDefinition> {
|
|
687
|
+
const unique = uniqueControls(controls);
|
|
688
|
+
const idOf = o.controlId ?? ((r: ControlRef): string => r.id);
|
|
689
|
+
const catalogs = [...new Set(unique.flatMap((c) => c.implements.map((r) => r.catalog)))].sort(byText);
|
|
690
|
+
const resources = await catalogResources(catalogs, o);
|
|
691
|
+
const implementations = await Promise.all(
|
|
692
|
+
catalogs.map(async (catalog, i): Promise<OscalControlImplementation> => {
|
|
693
|
+
const byId = new Map<string, ControlSummary[]>();
|
|
694
|
+
for (const c of unique) {
|
|
695
|
+
for (const r of c.implements) {
|
|
696
|
+
if (r.catalog !== catalog) continue;
|
|
697
|
+
const id = idOf(r);
|
|
698
|
+
const list = byId.get(id) ?? [];
|
|
699
|
+
if (!list.includes(c)) list.push(c);
|
|
700
|
+
byId.set(id, list);
|
|
701
|
+
}
|
|
702
|
+
}
|
|
703
|
+
const resource = resources[i];
|
|
704
|
+
return {
|
|
705
|
+
uuid: await uuidV5Of(o.namespace, ["control-implementation", component.id, catalog]),
|
|
706
|
+
source: o.catalogHref?.(catalog) ?? `#${resource?.uuid ?? ""}`,
|
|
707
|
+
description: text(`The controls of ${catalog} that ${component.title} implements.`, "Controls implemented."),
|
|
708
|
+
"implemented-requirements": await Promise.all(
|
|
709
|
+
[...byId.entries()]
|
|
710
|
+
.sort(([x], [y]) => byText(x, y))
|
|
711
|
+
.map(async ([id, cs]) => ({
|
|
712
|
+
uuid: await uuidV5Of(o.namespace, ["implemented-requirement", component.id, catalog, id]),
|
|
713
|
+
"control-id": id,
|
|
714
|
+
description: text(cs.map((c) => `${c.id} (${c.title})`).join("; "), id),
|
|
715
|
+
props: cs.map((c) => ({ name: "control", ns: o.propNamespace, value: text(c.id, "control") })),
|
|
716
|
+
})),
|
|
717
|
+
),
|
|
718
|
+
};
|
|
719
|
+
}),
|
|
720
|
+
);
|
|
721
|
+
return {
|
|
722
|
+
"component-definition": {
|
|
723
|
+
uuid: await uuidV5Of(o.namespace, ["component-definition", component.id]),
|
|
724
|
+
metadata: await metadataOf(o, `${text(component.title, component.id)}: component definition`),
|
|
725
|
+
components: [
|
|
726
|
+
{
|
|
727
|
+
uuid: await uuidV5Of(o.namespace, ["component", component.id]),
|
|
728
|
+
type: component.type ?? "software",
|
|
729
|
+
title: text(component.title, component.id),
|
|
730
|
+
description: text(component.description, text(component.title, component.id)),
|
|
731
|
+
...(component.version === undefined ? {} : { props: [{ name: "version", value: text(component.version, "unversioned") }] }),
|
|
732
|
+
...(implementations.length === 0 ? {} : { "control-implementations": implementations }),
|
|
733
|
+
},
|
|
734
|
+
],
|
|
735
|
+
...(resources.length === 0 || o.catalogHref !== undefined ? {} : { "back-matter": { resources } }),
|
|
736
|
+
},
|
|
737
|
+
};
|
|
738
|
+
}
|
|
739
|
+
|
|
740
|
+
// ---------------------------------------------------------------------------------------------------------------------------- system security plan
|
|
741
|
+
|
|
742
|
+
/** The system a security plan describes, and the profile (baseline) it imports. */
|
|
743
|
+
export type SystemInput = {
|
|
744
|
+
readonly id: string;
|
|
745
|
+
readonly name: string;
|
|
746
|
+
readonly description: string;
|
|
747
|
+
readonly profile: string;
|
|
748
|
+
readonly boundary?: string;
|
|
749
|
+
readonly informationType?: { readonly title: string; readonly description: string };
|
|
750
|
+
readonly user?: string;
|
|
751
|
+
};
|
|
752
|
+
|
|
753
|
+
function implementationState(outcomes: readonly Outcome[]): OscalImplementationState {
|
|
754
|
+
const c = coverageOf(outcomes);
|
|
755
|
+
switch (c) {
|
|
756
|
+
case "covered":
|
|
757
|
+
case "addressed":
|
|
758
|
+
return "implemented";
|
|
759
|
+
case "partial":
|
|
760
|
+
return "partial";
|
|
761
|
+
case "untested":
|
|
762
|
+
return "planned";
|
|
763
|
+
default:
|
|
764
|
+
return absurd(c);
|
|
765
|
+
}
|
|
766
|
+
}
|
|
767
|
+
|
|
768
|
+
/**
|
|
769
|
+
* A minimal system security plan of what is implemented: the system as one `this-system` component, the assessment's subjects as its
|
|
770
|
+
* inventory, and each catalog control its controls implement (or control that implements none) with its implementation status from the
|
|
771
|
+
* coverage of the newest findings of its controls.
|
|
772
|
+
*/
|
|
773
|
+
export async function systemSecurityPlan(a: Assessment, system: SystemInput, o: OscalOptions): Promise<OscalSsp> {
|
|
774
|
+
const newest = newestFindings(a.findings);
|
|
775
|
+
const thisSystem = await uuidV5Of(o.namespace, ["component", "this-system", system.id]);
|
|
776
|
+
const targets = targetsOf([...a.controls, ...a.findings.map((f) => f.control)], o);
|
|
777
|
+
const requirements = await Promise.all(
|
|
778
|
+
targets.map(async (t): Promise<OscalSspRequirement> => {
|
|
779
|
+
const outcomes = newest.filter((f) => t.controls.includes(f.control.id)).map((f) => f.outcome);
|
|
780
|
+
const state = implementationState(outcomes);
|
|
781
|
+
return {
|
|
782
|
+
uuid: await uuidV5Of(o.namespace, ["ssp-requirement", system.id, t.key]),
|
|
783
|
+
"control-id": t.controlId,
|
|
784
|
+
props: t.controls.map((c) => ({ name: "control", ns: o.propNamespace, value: text(c, "control") })),
|
|
785
|
+
"by-components": [
|
|
786
|
+
{
|
|
787
|
+
"component-uuid": thisSystem,
|
|
788
|
+
uuid: await uuidV5Of(o.namespace, ["ssp-by-component", system.id, t.key]),
|
|
789
|
+
description: text(`${t.controlId} is met by ${t.controls.join(", ")}: ${state}.`, t.controlId),
|
|
790
|
+
"implementation-status": { state },
|
|
791
|
+
},
|
|
792
|
+
],
|
|
793
|
+
};
|
|
794
|
+
}),
|
|
795
|
+
);
|
|
796
|
+
const items = await inventoryItems([...a.subjects, ...a.findings.map((f) => f.subject)], o);
|
|
797
|
+
const info = system.informationType ?? { title: "System information", description: "The information the system stores and processes." };
|
|
798
|
+
return {
|
|
799
|
+
"system-security-plan": {
|
|
800
|
+
uuid: await uuidV5Of(o.namespace, ["system-security-plan", system.id]),
|
|
801
|
+
metadata: await metadataOf(o, `${text(system.name, system.id)}: system security plan`),
|
|
802
|
+
"import-profile": { href: text(system.profile, "#") },
|
|
803
|
+
"system-characteristics": {
|
|
804
|
+
"system-ids": [{ "identifier-type": RFC4122, id: thisSystem }],
|
|
805
|
+
"system-name": text(system.name, system.id),
|
|
806
|
+
description: text(system.description, text(system.name, system.id)),
|
|
807
|
+
"system-information": {
|
|
808
|
+
"information-types": [
|
|
809
|
+
{
|
|
810
|
+
uuid: await uuidV5Of(o.namespace, ["information-type", system.id]),
|
|
811
|
+
title: text(info.title, "System information"),
|
|
812
|
+
description: text(info.description, "System information."),
|
|
813
|
+
},
|
|
814
|
+
],
|
|
815
|
+
},
|
|
816
|
+
status: { state: "operational" },
|
|
817
|
+
"authorization-boundary": {
|
|
818
|
+
description: text(system.boundary, `Every subject of ${text(system.name, system.id)} listed in its inventory.`),
|
|
819
|
+
},
|
|
820
|
+
},
|
|
821
|
+
"system-implementation": {
|
|
822
|
+
users: [{ uuid: await uuidV5Of(o.namespace, ["user", system.id]), title: text(system.user, "Operator") }],
|
|
823
|
+
components: [
|
|
824
|
+
{
|
|
825
|
+
uuid: thisSystem,
|
|
826
|
+
type: "this-system",
|
|
827
|
+
title: text(system.name, system.id),
|
|
828
|
+
description: text(system.description, text(system.name, system.id)),
|
|
829
|
+
status: { state: "operational" },
|
|
830
|
+
},
|
|
831
|
+
],
|
|
832
|
+
...(items.length === 0 ? {} : { "inventory-items": items }),
|
|
833
|
+
},
|
|
834
|
+
"control-implementation": {
|
|
835
|
+
description: text(
|
|
836
|
+
`How ${system.name} meets each control its checks implement, from the assessment at ${a.at}.`,
|
|
837
|
+
"How each control is met.",
|
|
838
|
+
),
|
|
839
|
+
"implemented-requirements": requirements,
|
|
840
|
+
},
|
|
841
|
+
},
|
|
842
|
+
};
|
|
843
|
+
}
|
|
844
|
+
|
|
845
|
+
// ---------------------------------------------------------------------------------------------------------------------------- rendering
|
|
846
|
+
|
|
847
|
+
/** A document as OSCAL JSON text: two-space indents and a final newline, its members in the order this module writes them. */
|
|
848
|
+
export function renderOscal(doc: OscalDocument): string {
|
|
849
|
+
return `${JSON.stringify(doc, null, 2)}\n`;
|
|
850
|
+
}
|