IF Commons GitHub

GRC documents and serializers

0004Active

0004-grc-documents · owner if · domain grc

The envelope

FR-001checkpassing

A document MUST be { kind, schema, id, createdAt, provenance, ...body }, where schema is a version string, createdAt an ISO 8601 instant and provenance says the producer (a name and a version), the ids or digests of the documents it was made from, and optionally who or what acted; defineKind MUST make the decoder of one kind from the decoders of its body, and a kind MUST be registered once in the registry of kinds under its kind as the stable id.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/governance/document.ts, grc/src/logical/standard-kinds.ts

Tests: passed: suite/documents.test.ts a kind is defined from the decoders of its body and an assessment round-trips through the

FR-002checkpassing

readDocument MUST decode any text or value through the registry of kinds, and MUST return an error value that names the unknown kind, or the schema that was found and the one expected, and MUST NOT read any other schema than the one the kind holds in this release (no dual reader, no migration).

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/governance/document.ts, grc/src/logical/standard-kinds.ts

Tests: passed: suite/documents.test.ts a document of another schema or an unknown kind is an error value that names what was foun

FR-003checkpassing

canonicalize MUST write RFC 8785's JSON Canonicalization Scheme (members sorted by the UTF-16 code units of their names, no white space), digestOf MUST be the SHA-256 of it, and the same document MUST have the same digest on every runtime whatever the order of its members.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/logical/canonical.ts

Tests: passed: suite/documents.test.ts the canonical form sorts members and the digest is the same for any order

FR-004checkpassing

Ids that are derived MUST be derived the same way every time: idOf MUST give a version 5 UUID URN of a namespace and the parts of a name, so that the same input gives the same document.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/logical/canonical.ts

Tests: passed: suite/documents.test.ts a derived id is a version 5 UUID of a namespace and a name: the same parts give the same i

Serializers

FR-005checkpassing

A serializer MUST be a port { id, format, version, media, serialize(assessment, context) } returning the text of a document of that format or an error value, registered in a registry of serializers by its stable id; it MUST be deterministic (the same assessment, the same bytes) and MUST NOT read the clock.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/logical/serializer.ts, grc/src/serializers/cyclonedx/mod.ts, grc/src/serializers/intoto/mod.ts, grc/src/serializers/ocsf/mod.ts, grc/src/serializers/oscal/mod.ts, grc/src/serializers/sarif/mod.ts

Tests: passed: suite/documents.test.ts serializers are registered by stable id, give the same bytes for the same assessment and r

Cited by: GRC, logical/serializer

FR-006checkpassing

The oscal serializer MUST write OSCAL assessment-results (results with observations, findings and the control each is about) for the assessment, every uuid a version 5 UUID of the document's id and a stable name.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/serializers/oscal/mod.ts

Tests: passed: suite/documents.test.ts oscal writes assessment-results with observations and a finding for each control, and stab

Cited by: GRC, serializers/oscal/mod

FR-007checkpartly run

The oscal serializer MUST also write a system-security-plan (each control the checks speak of, implemented where every result shows it and partial where one does not, by the checks that show it; and what the caller says of the system, by the option system: its description, sensitivity level, boundary, import profile, information types, components, users and whose each control is, provider, inherited or customer, none of which is made up where it is not said) and a plan-of-action-and-milestones (the findings that are open and the risks that are not closed, each with its milestones and the exception or accepted risk that holds it until a date) from the same assessment, and all three documents MUST be valid against the schema NIST publishes for OSCAL; a serializer MAY be given a mapping through a crosswalk (0002 FR-002) so that a control of one framework is written under another's identifier.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/serializers/oscal/mod.ts

Tests: passed: suite/documents.test.ts oscal writes a system security plan of what is implemented and a plan of action of what is; passed: suite/documents.test.ts the system security plan says what the caller says of the system and invents nothing else:; skipped: suite/documents.test.ts the three OSCAL documents are valid against NIST's published schema, where the schema (OSC

Cited by: GRC, serializers/oscal/mod

FR-008checkpassing

The ocsf serializer MUST write each finding as an OCSF Compliance Finding (class 2003) with type_uid, status_id and severity_id mapped from the status and the severity, the control in compliance, and metadata.product and metadata.version.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/serializers/ocsf/mod.ts

Tests: passed: suite/documents.test.ts ocsf writes each finding as a compliance finding of class 2003 with the mapped ids

Cited by: GRC, serializers/ocsf/mod

FR-009checkpassing

The sarif serializer MUST write SARIF 2.1.0: a run with the rules (one for each check), and a result for each finding with its level, its message and the subject as a logical location.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/serializers/sarif/mod.ts

Tests: passed: suite/documents.test.ts sarif writes one run with a rule for each check and a result for each finding

Cited by: GRC, serializers/sarif/mod

FR-010checkpassing

The cyclonedx serializer MUST write a CycloneDX BOM whose declarations hold the assessor, the claims (one for each control), the evidence and the attestations, and the intoto serializer MUST write an in-toto Statement v1 whose subjects are the digests of the evidence and whose predicate type is the one the caller names.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Written in: grc/src/serializers/cyclonedx/mod.ts, grc/src/serializers/intoto/mod.ts

Tests: passed: suite/documents.test.ts cyclonedx writes declarations and intoto a statement of the evidence digests with the pred

Cited by: GRC, serializers/cyclonedx/mod, serializers/intoto/mod

FR-011checkpassing

A conformance suite for serializers MUST check that each registered serializer is deterministic, names its format and version, gives an error value and not an exception for an assessment with no results, and produces what a decoder of its format accepts; the suite MUST return each failure as data.

Enforced (check): .github: cd commons/grc && bun run verify — suite/documents.test.ts

Proved by: grc/suite/documents.test.ts

Tests: passed: suite/documents.test.ts the conformance suite passes every serializer of the library and fails one that is not det

Cited by: conformance/mod, GRC

Scenarios

  • Given {"kind":"grc.result","schema":"0.2"} when the registry holds grc.result at 1, When it is written or read, Then the error names 0.2 and 1, per FR-002.
  • Given {"b":1,"a":2.0} and {"a":2,"b":1}, When it is written or read, Then one digest, per FR-003.
  • Given an assessment with a failing and a passing result, When it is written as sarif, Then one result with level error, per FR-009.

Out of scope

Edge cases

  • An assessment with no results: each serializer gives a valid, empty document, per FR-011.
  • A control URN in an OSCAL control-id: its control segment only, per FR-006.

Assumptions

  • The versions of the standards are constants of each serializer and change only by changing the serializer and its fixtures: OSCAL 1.2.x, OCSF 1.x, SARIF 2.1.0, CycloneDX 1.6 and in-toto Statement v1, as they stood at the time of writing; the release verifies them.

Open questions

OQ-1open question

Whether the SBOM of the artifacts under assessment (not the declarations about them) belongs to this library or to a supply-chain one.

Key entities

  • Document, Kind, Serializer.

Success criteria

SC-001success criterion

A document of another schema is refused with both versions named.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

conformance/mod, governance/document, governance/kinds, GRC, logical/serializer, serializers/cyclonedx/mod, serializers/intoto/mod, serializers/ocsf/mod, serializers/oscal/mod, serializers/sarif/mod, GRC logical model

Titles, headings, exports, tables, columns and requirements. Esc closes.