NIS2 Effectiveness Report Contract v1

Contract ID: CONTRACT-NIS2-EFFECTIVENESS-REPORT-V1-062 Status: Published (sprint 062 monthly export work) Owner: Export Center Guild Schema version: nis2-effectiveness-report-v1 Bundle schema version: nis2-effectiveness-report-bundle-v1 Input contract: nis2-effectiveness-dashboard-v1 DSSE payload type: application/vnd.stellaops.nis2.effectiveness-report.v1+json

Part of the Stella Ops Contracts index. Audience: Export Center and CLI implementers building the monthly NIS2 effectiveness export, and auditors/reviewers who verify the resulting offline bundle. The input dashboard is produced by the KPI Telemetry Schema read projection; the linked control register is the NIS2 Control Register.

Implementation references (ground truth):

• Adapter: src/ExportCenter/StellaOps.ExportCenter.Adapters.Nis2/Nis2EffectivenessExporter.cs, Nis2EffectivenessModels.cs, Nis2EffectivenessBundleVerifier.cs.
• Schema/payload constants: Nis2EffectivenessConstants (ReportSchemaVersion, BundleSchemaVersion, SourceReportSchemaVersion, PayloadType, SignatureAlgorithm).
• CLI: src/Cli/StellaOps.Cli/Commands/Nis2EffectivenessCommandGroup.cs (registered as stella export nis2-effectiveness and stella verify nis2-effectiveness).
• Assurance profile registration: AssuranceExportProfileRegistry profile id nis2.effectiveness-report.

Purpose

The NIS2 effectiveness report export pins the monthly 13-area effectiveness dashboard shape into a deterministic bundle for offline auditor review. The report is evidence-pointer-first: it preserves the dashboard metrics, linked controls, target/control snapshot references, hashes, and blockers that were present at export time.

This contract does not claim production qualified signing. The current CLI path uses a local HMAC DSSE-shaped envelope so the bundle can be reproduced and tamper-checked offline. Production CAdES/KMS signing remains a separate platform integration and must not be inferred from the DSSE signature alg = "HS256".

HMAC operations are not raw System.Security.Cryptography calls: they route through StellaOps.Cryptography.DefaultHmacAlgorithm.Instance.ComputeMac(..., HmacAlgorithmName.HmacSha256) (Sprint 20260430_000 HMAC-CLEANUP-EXPORT-NIS2) so that regional crypto plugins (FIPS/GOST/SM/eIDAS) can substitute the implementation. The DSSE signature alg is always recorded as HS256 regardless of the substituted provider.

Bundle Envelope

{
  "schemaVersion": "nis2-effectiveness-report-bundle-v1",
  "sourceReportSchemaVersion": "nis2-effectiveness-dashboard-v1",
  "sourceReport": {},
  "monthlyReport": {},
  "manifest": {},
  "signature": {}
}

Field notes (from Nis2EffectivenessReportBundle):

The DSSE envelope embedded in signature is:

{
  "payloadType": "application/vnd.stellaops.nis2.effectiveness-report.v1+json",
  "payload": "<base64 of canonical monthlyReport bytes>",
  "signatures": [
    { "keyid": "<key id>", "alg": "HS256", "sig": "<base64 HMAC-SHA256>" }
  ]
}

Monthly Report

{
  "schemaVersion": "nis2-effectiveness-report-v1",
  "tenantId": "tenant-a",
  "reportMonth": "2026-04",
  "generatedAt": "2026-04-30T12:00:00Z",
  "period": {
    "start": "2026-04-01",
    "endExclusive": "2026-05-01"
  },
  "source": "live",
  "rollingWindow": "rolling-30d",
  "sourceReportHash": "sha256:...",
  "sourceReferences": {
    "sourceReportRef": "nis2-effectiveness-dashboard://tenant-a/2026-04#sha256:...",
    "targetDocumentHash": "sha256:...",
    "targetDocumentRef": "policy://target-documents/nis2/2026-04",
    "controlRegisterSnapshotHash": "sha256:...",
    "controlRegisterSnapshotRef": "policy://control-registers/nis2/2026-04",
    "policySnapshotRef": "policy://snapshots/nis2/2026-04"
  },
  "areaCount": 13,
  "areas": [],
  "blockers": [],
  "reportHash": "sha256:..."
}

Required Fields

Area Shape

Each areas[] item (Nis2EffectivenessReportArea) preserves the source dashboard values:

• areaNumber, areaSlug, areaLabel
• evidenceMode, responsibleRole, state
• latestObservedAt, nextReview (nullable timestamps, UTC-normalized)
• override (Nis2EffectivenessSourceOverride: active, optional owner, reason, effectiveFrom, nextReview, previousValueHash, newValueHash, approvedBy)
• metrics[] (Nis2EffectivenessSourceMetric: kpiKey, metricName, label, description, unit, thresholdDirection, target, latest, trend)
• linkedControls[] (Nis2EffectivenessSourceLinkedControl: controlId, label, route, responsibleRole, evidenceMode, evidenceRefs[], nextReview)

Note: the source dashboard area carries a per-area rollingWindow, but the report area drops it (ToReportArea does not copy it). The report-level rollingWindow is the authoritative window for the monthly report.

The adapter sorts areas by areaNumber, metrics by metricName then kpiKey, linked controls by controlId then label, and evidence refs lexicographically. Validation requires each area to carry at least one metric, and the source report to contain exactly 13 areas numbered 1 through 13 exactly once (ValidateSourceReport).

Blockers

The exporter records blockers instead of fabricating upstream evidence. Each blockers[] item (Nis2EffectivenessReportBlocker) has four fields: code, summary, detail, and source (provenance of the blocker). Blockers are sorted by code, then summary, then detail, then source.

Manifest Entries

manifest carries top-level generatedAt and reportMonth plus an entries[] array. Each entry (Nis2EffectivenessBundleEntry) is { "path", "mediaType", "sha256" }, where sha256 is the sha256:-prefixed SHA-256 of the canonical bytes of the referenced object. The manifest must contain exactly these three logical paths and media types:

The reports/... entry media type is the same value as the DSSE payloadType (Nis2EffectivenessConstants.PayloadType).

Determinism Rules

• The source dashboard report must contain exactly 13 areas numbered 1 through 13.
• Canonical JSON is used for the source report, monthly report, DSSE envelope, and outer bundle.
• sourceReportHash is computed after source normalization and before bundle assembly.
• reportHash is computed over { schemaVersion, tenantId, reportMonth, generatedAt, period, source, rollingWindow, sourceReportHash, sourceReferences, areaCount, areas, blockers }.
• The bundle hash is the sha256:-prefixed SHA-256 of the canonical nis2-effectiveness-report-bundle-v1 bytes (CanonJson.Sha256Prefixed).
• Re-running export with identical source report, month, source refs, and signing key must produce byte-identical bundle output.

Signing and Verification

• CLI/offline signing uses DSSE PAE (DSSEv1 <len> <payloadType> <len> <payload>) with payload type application/vnd.stellaops.nis2.effectiveness-report.v1+json and local HMAC-SHA256 signatures recorded with alg = "HS256". The signed payload is the canonical bytes of monthlyReport, base64-encoded into the DSSE payload field.
• HMAC computation and verification both route through StellaOps.Cryptography.DefaultHmacAlgorithm.Instance.ComputeMac(..., HmacAlgorithmName.HmacSha256); verification uses CryptographicOperations.FixedTimeEquals for the constant-time comparison.
• Offline verification (Nis2EffectivenessBundleVerifier.Verify) validates bundle schema versions, source-report schema, the 13-area count, manifest entry hashes, source report hash, report hash, DSSE payload bytes, DSSE payload type, the key id (the signature whose keyid matches the supplied signing key id), and the HMAC signature.
• A tampered source report, monthly report, manifest, or signature must fail verification with a non-zero CLI exit code (CliExitCodes.VerificationFailed).
• Production ExportCenter signing must use the platform Signer/KMS/CAdES path when that integration is available. Until then, local HMAC output is an offline reproducibility/tamper-evidence mechanism only.

Verification error codes

Verify returns IsValid plus a list of machine-readable error codes. The codes include:

CLI Surface

The registered CLI preserves a deterministic local/offline path and can also delegate production to the shipped ExportCenter Assurance run endpoint. The local path resolves signing material from operator-controlled CLI inputs; --via-export-center posts the same source dashboard to ExportCenter, where signing material is resolved server-side, and downloads the produced bundle.

• stella export nis2-effectiveness (Nis2EffectivenessCommandGroup.BuildNis2EffectivenessExportCommand). Options: --month (required, yyyy-MM), --report (required local nis2-effectiveness-dashboard-v1 JSON for both local and ExportCenter production), --via-export-center, --output/-o, --overwrite, --signing-key-file, --signing-key-id, --source-report-ref, --target-document-ref, --target-document-hash, --control-register-snapshot-ref, --control-register-snapshot-hash, --policy-snapshot-ref, --json. Without --via-export-center, the command produces and self-verifies the bundle locally and returns VerificationFailed if verification fails. With --via-export-center, it starts the Assurance run, downloads the server-produced bundle, and still supports offline verification of the downloaded artifact. When --output is omitted the bundle is written to nis2-effectiveness-<tenantId>-<yyyyMM>.bundle.json.
• stella verify nis2-effectiveness (BuildNis2EffectivenessVerifyCommand). Options: --bundle (required), --signing-key-file, --signing-key-id, --json.
• Signing key resolution (ResolveSigningKeyAsync): --signing-key-file if supplied, otherwise the STELLAOPS_NIS2_EFFECTIVENESS_HMAC_KEY environment variable; the key bytes are UTF-8 trimmed before HMAC use, and the key id defaults to hmac-sha256:<first16hex> when --signing-key-id is omitted.

The Assurance profile registry advertises the registered compatibility command exactly as stella export nis2-effectiveness.

Assurance Profile Discovery And Run Execution (HTTP)

The nis2.effectiveness-report profile is discoverable and executable through the framework-aware Assurance export API (AssuranceExportEndpoints):

• GET /v1/exports/assurance/profiles (optionally ?frameworkId=nis2; scope export.viewer)
• GET /v1/exports/assurance/profiles/{profileId} (nis2.effectiveness-report; scope export.viewer)
• GET /v1/exports/assurance/profiles/{profileId}/readiness (scope export.viewer)
• POST /v1/exports/assurance/profiles/nis2.effectiveness-report/runs (scope export.operator) starts deterministic signed production from the supplied nis2Effectiveness source inputs.
• GET /v1/exports/assurance/profiles/nis2.effectiveness-report/runs/{runId} (scope export.viewer) reads the run.
• GET /v1/exports/assurance/runs/{runId}/bundle (scope export.viewer) downloads the produced bundle.

When operator-owned signing and storage configuration is ready, profile readiness reports the non-blocking source-dashboard-required reason because the monthly NIS2 effectiveness dashboard remains a produce-time input. Missing signing material fails closed instead of falling back to request-supplied secrets.