Standards Mapping v1

Contract ID: CONTRACT-STANDARDS-MAPPING-V1-032 Status: Draft Owner: ExportCenter Last Updated: 2026-05-30

Purpose

standards-mapping-v1 defines the local YAML mapping files and the deterministic ExportCenter bundle used to link external security standards to StellaOps control-register controls and offline evidence refs.

Audience: ExportCenter adapter implementers, EU-standards reviewers who author and approve the mapping YAML, and operators producing offline standards-coverage bundles.

The adapter is evidence-pointer-first: it copies the reviewed local mapping YAML, emits a normalized summary, signs the bundle index, and records blockers for draft or incomplete mappings instead of inferring standard coverage at export time.

The export adapter id is standards:mapping (StandardsMappingConstants.AdapterId). The source mapping schema version is the literal standards-mapping-v1 (StandardsMappingConstants.SourceSchemaVersion); the emitted bundle index and summary carry their own schema versions (standards-mapping-bundle-v1, standards-mapping-summary-v1).

Source Mapping Schema

Mapping sources MUST be local files using:

schemaVersion: standards-mapping-v1
mappingVersion: 0.1.0
status: draft
targetStandard:
  id: iso27001-2022
  name: ISO/IEC 27001:2022 Annex A
  controlSet:
    unit: control
    totalControls: 93
    requirementLevelCoverageStatus: null
coverage:
  mappedControls: 93
  coveragePercent: 100.0
  thresholdPercent: 80.0
  coverageBasis: annex-a-control-count
  stellaApplicableControls: 93
  nonApplicableControls: 0
review:
  reviewStatus: pending-eu-standards-reviewer
sourceBasis: []
evidenceSets: {}
controlMappings:
  - externalControlId: A.5.1
    externalControlName: Policies for information security
    stellaControlId: NIS2-01-NIS-POLICY
    maturity: mixed
    applicability: null
    mappingNote: null
    applicabilityReason: null
    evidenceRefs:
      - ref: evidence://policy/packs/security-policy/approved
        sourceType: stella-native

The line-oriented YAML reader (StandardsMappingYamlReader.Parse) recognizes a fixed set of keys at fixed indents. Keys outside this set (for example targetStandard.sourceVersion, controlSet.families, or the richer review.* block carried in the current EU pack files) are tolerated but ignored. evidenceRefs may be inline list items or a YAML alias (*anchor) that resolves against a top-level evidenceSets anchor (&anchor); anchors are the convention used by the live mapping files.

Required source fields (validated by the reader; a missing required field throws InvalidOperationException):

Note: coverage.coveragePercent, coverage.thresholdPercent, and the maturity set are NOT cross-validated by the adapter. The reader trusts the reviewed source values verbatim; only coverage.mappedControls vs the controlMappings count and targetStandard.id vs the resolved target are enforced.

Evidence refs MUST use immutable or replayable local evidence schemes such as evidence://.... Live SaaS, regulator, or public web endpoints are not valid source refs for deterministic bundles.

Supported Targets

StandardsMappingTargets.SupportedTargets is the canonical alias list: iso27001, iec62443-4-1, iec62443-4-2, en303645, jrc-cra. The resolver (StandardsMappingTargets.Resolve) also accepts the canonical target ids iso27001-2022 and etsi-en303645 as input aliases; both normalize to the same bundle target (iso27001 / en303645).

The bundle target (third column) is the slug used in bundle entry paths (mappings/<bundle-target>.yaml) and in the output file name. The reviewed mapping files live in docs/europe/standards-mapping/, which is also the CLI default for --mapping-dir.

jrc-cra is publishable only when docs/europe/standards-mapping/jrc-cra.yaml has reviewed non-zero mapping rows, no blocked/pending/draft publication state, and no bundle blockers. This gate is enforced for the CLI path only (StandardsMappingCommandGroup.EnsureTargetPublishable); the core StandardsMappingAdapter.Build/BuildFromDirectory API will materialize a jrc-cra bundle that still carries blockers without throwing. Adapters MUST preserve local blocker states rather than fetching remote content.

CLI Surface

The bundle is produced by the stella standards-mapping command (StandardsMappingCommandGroup):

When run inside ExportCenter (server-side export runs), authorization is the generic ExportCenter scope set from StellaOpsScopes: export.viewer (ExportViewer), export.operator (ExportOperator), export.admin (ExportAdmin). There is no standards-mapping-specific scope.

Bundle Schema

• schemaVersion MUST be exactly standards-mapping-bundle-v1.
• Bundle media type is application/vnd.stellaops.standards-mapping.v1+tar+gzip.
• JSON payloads MUST be canonicalized with ordinal-sorted object keys and UTF-8 without a BOM (CanonJson.Canonicalize).
• Hashes in bundle JSON MUST be lowercase SHA-256 with the sha256: prefix (CanonJson.Sha256Prefixed); checksums.txt lines use bare lowercase hex (CanonJson.Sha256Hex).
• Tar entries are PAX format (TarEntryFormat.Pax) with deterministic metadata: fixed mtime 2025-01-01T00:00:00Z, uid/gid 0, empty user/group names, and mode 0644 (user rw, group/other r).
• Gzip uses CompressionLevel.SmallestSize and the mtime field in the gzip header is overwritten with the fixed timestamp so identical inputs produce byte-identical archives.

Per-entry media types embedded in index.json.entries:

Bundle layout:

index.json
checksums.txt
mappings/<bundle-target>.yaml
mappings/<bundle-target>.summary.json
signatures/index.dsse.json

index.json is authoritative. index.json.entries lists only the two mappings/<bundle-target>.* files and the DSSE signature; index.json and checksums.txt are bundle members but are not self-listed in entries. checksums.txt is a deterministic convenience file for offline operators and is excluded from its own listing.

Required index.json Fields

The summary.json payload carries the same targetStandard/source/coverage shape plus the full sourceBasis[] and controlMappings[] arrays, which are NOT inlined into index.json.

Signing And Verification

index.json is signed as the DSSE payload:

{
  "payloadType": "application/vnd.stellaops.standards-mapping.index.v1+json",
  "payload": "<base64 canonical index.json>",
  "signatures": [
    {
      "keyid": "hmac-sha256:<key-ref>",
      "alg": "HMAC-SHA256",
      "sig": "<base64 HMAC over DSSE PAE>"
    }
  ]
}

The HMAC DSSE envelope is the local deterministic ExportCenter signing pattern for this adapter. The MAC and the persisted alg / signing.algorithm tag are NOT hard-coded to HS256. They are resolved at sign time from the central crypto abstraction (ICryptoHmac.GetAlgorithmForPurpose(HmacPurpose.Signing), upper-cased) per the active regional compliance profile (CoC §7.4): typically HMAC-SHA256 on the world / fips / kcmvp / eidas profiles, HMAC-GOST3411 on the gost profile, and HMAC-SM3 on the sm profile. (A SignatureAlgorithm = "HS256" constant exists on StandardsMappingConstants but is unused.) Sender and verifier MUST run the same regional profile, since the verifier recomputes the expected algorithm string and the MAC bytes with the same abstraction.

keyid is the signing key id. When no key id is supplied, the adapter derives hmac-sha256:<first-16-hex-chars-of-the-key's-sha256> (CreateHmacSigningKey); an explicit --signing-key-id / KeyId is recorded verbatim and is not required to start with hmac-sha256:.

Production key sourcing remains deployment-specific; the adapter MUST fail if no signing key is configured (the ProcessAsync path returns a failed result, the Build path throws on an empty key). Offline verification (StandardsMappingBundleVerifier.Verify) re-reads the tar.gz entries, requires index.json, checks the bundle schema version, validates every entries[] row against the archive (size + sha256: hash), then verifies the DSSE envelope: payload type, base64 payload equals index.json bytes, a signature whose keyid and alg match the configured key and resolved algorithm, and a fixed-time HMAC comparison over the DSSE PAE (DSSEv1 <typelen> <type> <payloadlen> <payload>). checksums.txt is a convenience listing and is not re-validated by Verify.

Determinism Rules

• Exporters MUST consume local mapping files only.
• Exporters MUST reject any source ref that is an absolute URI whose scheme is not file: (so http://, https://, and any other scheme are rejected with “is not a local file”); relative/absolute filesystem paths are resolved with Path.GetFullPath.
• Exporters MUST NOT infer mappings from standard prose at bundle time.
• Exporters normalize source YAML line endings to LF (both \r\n and bare \r become \n) and append a trailing \n if absent before hashing; the bundled mappings/<bundle-target>.yaml and the source.sha256 are computed over these normalized bytes, not the raw file.
• Identical source YAML, target, generated timestamp, and signing key MUST produce byte-identical bundles and identical bundle hashes (proven by the adjacent tests).
• Draft, pending, or blocked review states MUST remain visible as bundle blockers. The blocker heuristic raises a blocker when status, review.reviewStatus, or requirementLevelCoverageStatus contains the substring draft, pending, or blocked (case-insensitive). Each blocker carries a sprintRef resolved from the target standard id.

Offline And Replay Expectations

• Adapter implementation: src/ExportCenter/StellaOps.ExportCenter.Adapters.StandardsMapping/ (StandardsMappingAdapter, StandardsMappingYamlReader, StandardsMappingDeterministicArchive, StandardsMappingBundleVerifier, StandardsMappingTargets, StandardsMappingModels).
• CLI command: src/Cli/StellaOps.Cli/Commands/StandardsMappingCommandGroup.cs (stella standards-mapping).
• Reviewed mapping YAML: docs/europe/standards-mapping/{iso27001-2022,iec62443-4-1,iec62443-4-2,etsi-en303645,jrc-cra}.yaml.
• Adjacent tests: src/ExportCenter/StellaOps.ExportCenter.Adapters.StandardsMapping.Tests/StandardsMappingAdapterTests.cs (and CLI tests in src/Cli/__Tests/StellaOps.Cli.Tests/Commands/StandardsMappingCommandTests.cs).
• The adapter tests prove: byte-identical output from identical inputs (Build_SameInputs_...), DSSE signature verification (Verification.IsValid), local-file-only processing / remote-ref rejection (ProcessAsync_RejectsRemoteSourceRefs), all supported target aliases against the live files (BuildFromDirectory_CurrentLocalMappings_...), the precise missing-file blocker for jrc-cra, and adapter registration / config validation.

Known v1 Blockers

• Current review state of the live mapping files (as exercised by BuildFromDirectory_CurrentLocalMappings_ProducesSignedBundles):
  • iso27001-2022.yaml — status: draft, reviewStatus: pending-eu-standards-reviewer: still produces mapping-status / mapping-review blockers.
  • etsi-en303645.yaml — draft: produces blockers.
  • iec62443-4-1.yaml / iec62443-4-2.yaml — approved at the family level (reviewStatus: approved-family-level-by-eu-standards-reviewer, requirementLevelCoverageStatus: not-claimed-family-level-approved); none of these strings match the draft/pending/blocked heuristic, so the bundles are currently blocker-free.
  • jrc-cra.yaml — reviewStatus: reviewed-by-eu-standards-reviewer: blocker-free and publishable through the CLI gate.
• The adapter preserves draft/pending/blocked states in bundle blockers until eu-standards-reviewer completes the remaining reviews; it never clears a source-declared blocked state at export time.