Assurance Pack v1

Contract ID: CONTRACT-ASSURANCE-PACK-V1-001 Status: Draft Owner: Architecture Guild Schema version: assurance-pack-v1

This contract is the descriptor catalogue for Stella Ops Assurance packs — the metadata that registers a regulatory framework (NIS2, DORA, CRA, and future frameworks) as an optional, discoverable add-on over Stella Ops core primitives. It is the entry point for the Assurance contract family and is intended for integrators wiring compliance surfaces into Web, CLI, setup, and ExportCenter, and for reviewers checking what a pack claims and who owns each part.

Purpose

assurance-pack-v1 describes optional Assurance packs that register framework-specific mappings, exports, timelines, and setup prerequisites over Stella Ops core primitives. It keeps NIS2, DORA, CRA, and future frameworks out of core product identity while preserving discoverability in Web, CLI, setup, and ExportCenter.

This contract is descriptor metadata. It does not replace pack-specific payload contracts such as nis2-control-register-v1, nis2-soa-v1, dora-major-incident-report-v1, dora-roi-v1, dora-info-sharing-event-v1, tlpt-evidence-pack-v1, cra-tech-file-v1, or conformity-dossier-v1. The discovery, readiness, and timeline surfaces are defined in the companion assurance-evidence-export-v1, assurance-setup-prerequisites-v1, and assurance-reporting-timeline-v1contracts.

Implementation Status

The descriptor catalog is currently implemented and shipped by the CLI, not by ExportCenter. Four descriptors are embedded as JSON resources in the StellaOps.Cli assembly under src/Cli/StellaOps.Cli/Commands/Assurance/Descriptors/:

• cra.product-security.json
• cra.technical-documentation.json
• dora.json
• nis2.json

EmbeddedAssurancePackCatalog (in src/Cli/StellaOps.Cli/Commands/Assurance/AssurancePackCommandGroup.cs) loads these resources, sorts them ordinally by packId, and serves them through the stella assurance command tree. Tenant readiness is computed fail-closed by fanning out to Authority, ExportCenter, and Notify readiness APIs (see CLI Surface and Readiness APIs). Modules named in owners[] (Policy, ExportCenter, Notify, Telemetry, Findings, EvidenceLocker) own the underlying payload contracts, profiles, and readiness endpoints, but the generic descriptor catalog itself is a CLI-embedded resource set today.

Naming Rules

• packId MUST be a stable lowercase token using . for subpacks.
• frameworkId MUST be a stable lowercase token.
• Pack ids MUST NOT encode only geography unless the regulation or standard is geographically scoped by design.
• A jurisdiction may be represented in jurisdictions[], not by making the whole product surface Europe-specific.

Examples of well-formed pack ids (the first four ship as embedded descriptors today; iso27001 is an illustrative future id, not a shipped pack):

• nis2
• dora
• cra.product-security
• cra.technical-documentation
• iso27001

Required Fields

Claim Boundaries

Evidence Scopes

Evidence scopes describe whose facts are being used. They are separate from the claim boundary: a pack can be operator-support while still combining Stella-observed software evidence, operator-supplied legal/process evidence, and Stella supplier evidence.

NIS2 and DORA MUST include operator-observed-estate and operator-supplied. Missing evidence-scope metadata for those frameworks is a readiness blocker (evidence-scopes-missing, evidence-source-lanes-missing, or coverage-primary-scope-missing) because otherwise Stella could appear to claim broad compliance outside the software estate it can prove.

Evidence Source Lane Shape

{
  "scope": "operator-observed-estate",
  "label": "Stella-observed software estate",
  "description": "Container images, releases, services, integrations, plugins, and host agents that Stella deploys, scans, observes, or controls for the operator.",
  "requiredForConfiguredStatus": true
}

requiredForConfiguredStatus = true means a tenant cannot truthfully reach configured pack status without this lane being present or deliberately marked unavailable with stable reason codes.

Coverage Summary Shape

{
  "primaryScope": "operator-observed-estate",
  "coverageLabel": "Software-estate assurance for services Stella monitors or deploys for the operator.",
  "observedSoftwareKinds": ["container-images", "release-bundles", "services"],
  "operatorSuppliedGaps": ["legal-entity-and-sector-classification"],
  "supplierEvidenceProfile": "stella.supplier-evidence"
}

operatorSuppliedGaps[] MUST list important areas that Stella cannot infer from telemetry or release evidence. UI, CLI, and exports must preserve these labels rather than collapsing them into successful Stella-native evidence.

Owner Shape

{
  "module": "ExportCenter",
  "path": "src/ExportCenter/",
  "responsibility": "signed export profile"
}

module should match an existing module or role. path MUST point to an existing repository directory for implementation ownership.

Example: NIS2 Evidence Pack

{
  "schemaVersion": "assurance-pack-v1",
  "packId": "nis2",
  "frameworkId": "nis2",
  "packVersion": "1.0.0",
  "displayName": "NIS2 Evidence Pack",
  "claimBoundary": "operator-support",
  "evidenceScopes": ["operator-observed-estate", "operator-supplied", "stella-supplier"],
  "evidenceSourceLanes": [
    {
      "scope": "operator-observed-estate",
      "label": "Stella-observed software estate",
      "description": "Container images, releases, services, integrations, plugins, and host agents that Stella deploys, scans, observes, or controls for the operator.",
      "requiredForConfiguredStatus": true
    },
    {
      "scope": "operator-supplied",
      "label": "Operator-supplied NIS2 governance evidence",
      "description": "Legal entity, governance, physical security, HR, supplier contract, and process evidence that Stella cannot infer from software telemetry.",
      "requiredForConfiguredStatus": true
    },
    {
      "scope": "stella-supplier",
      "label": "Stella supplier evidence",
      "description": "Stella signed release, SBOM, VEX, CVD, support lifecycle, and incident notification evidence reusable as supplier evidence when Stella is part of the operator estate.",
      "requiredForConfiguredStatus": false
    }
  ],
  "coverageSummary": {
    "primaryScope": "operator-observed-estate",
    "coverageLabel": "Software-estate assurance for services Stella monitors or deploys for the operator.",
    "observedSoftwareKinds": ["container-images", "release-bundles", "services", "integrations", "plugins", "host-agents"],
    "operatorSuppliedGaps": [
      "legal-entity-and-sector-classification",
      "governance-policy-ownership",
      "business-continuity-processes",
      "physical-security-controls",
      "staff-training-and-awareness-records"
    ],
    "supplierEvidenceProfile": "stella.supplier-evidence"
  },
  "jurisdictions": ["EU"],
  "features": ["controls", "exports", "timelines", "dashboards", "standards-mapping"],
  "owners": [
    { "module": "Policy", "path": "src/Policy/", "responsibility": "control register" },
    { "module": "ExportCenter", "path": "src/ExportCenter/", "responsibility": "SoA export" },
    { "module": "Notify", "path": "src/Notify/", "responsibility": "incident timeline channels" }
  ],
  "setupPrerequisites": ["nis2.soa.live-export", "nis2.effectiveness.monthly-export"],
  "exports": ["nis2.statement-of-applicability", "nis2.effectiveness-report"],
  "reportingTimelines": ["nis2.article23.incident"],
  "controlMappings": ["nis2-control-register-v1"],
  "compatibilityRoutes": [
    "/compliance/nis2/control-register",
    "/api/policy/control-register/nis2",
    "stella export nis2-soa",
    "stella export nis2-effectiveness"
  ],
  "offlineMode": {
    "supported": true,
    "requiresLiveRegulatorEndpoint": false,
    "fixturePolicy": "local deterministic fixtures only"
  }
}

Example: CRA Product Security Pack

{
  "schemaVersion": "assurance-pack-v1",
  "packId": "cra.product-security",
  "frameworkId": "cra",
  "packVersion": "1.0.0",
  "displayName": "CRA Product Security Pack",
  "claimBoundary": "manufacturer-self",
  "evidenceScopes": ["stella-product", "stella-supplier"],
  "evidenceSourceLanes": [
    {
      "scope": "stella-product",
      "label": "Stella product manufacturer evidence",
      "description": "Stella-owned product security metadata, advisory publication, support lifecycle, signed release, SBOM, VEX, and incident reporting preflight evidence.",
      "requiredForConfiguredStatus": true
    },
    {
      "scope": "stella-supplier",
      "label": "Reusable Stella supplier evidence",
      "description": "The same signed product-security facts can be exported as supplier evidence for an operator that deploys Stella.",
      "requiredForConfiguredStatus": false
    }
  ],
  "coverageSummary": {
    "primaryScope": "stella-product",
    "coverageLabel": "Stella product-security and manufacturer-publication evidence.",
    "observedSoftwareKinds": ["stella-release-bundles", "product-advisory-feed", "sbom-vex", "support-lifecycle", "security-contact-publication"],
    "operatorSuppliedGaps": [],
    "supplierEvidenceProfile": "stella.supplier-evidence"
  },
  "jurisdictions": ["EU"],
  "features": ["publication-preflight", "product-advisory-feed", "support-lifecycle"],
  "owners": [
    { "module": "Router", "path": "src/Router/", "responsibility": "well-known public metadata routing" },
    { "module": "Notify", "path": "src/Notify/", "responsibility": "product advisory feed" }
  ],
  "setupPrerequisites": ["cra.product-security.publication"],
  "exports": ["cra.product-advisory-feed"],
  "reportingTimelines": ["cra.article14.incident"],
  "controlMappings": [],
  "compatibilityRoutes": ["/.well-known/security.txt", "/.well-known/stella-product-security.json"],
  "offlineMode": {
    "supported": true,
    "requiresLiveRegulatorEndpoint": false,
    "fixturePolicy": "local rendered metadata and advisory feed fixtures"
  }
}

Example: DORA Operational Resilience Pack

{
  "schemaVersion": "assurance-pack-v1",
  "packId": "dora",
  "frameworkId": "dora",
  "packVersion": "1.0.0",
  "displayName": "DORA Operational Resilience Pack",
  "claimBoundary": "operator-support",
  "evidenceScopes": ["operator-observed-estate", "operator-supplied", "stella-supplier"],
  "evidenceSourceLanes": [
    {
      "scope": "operator-observed-estate",
      "label": "Stella-observed ICT software estate",
      "description": "ICT services, container images, release bundles, integrations, plugins, runtime host agents, and direct software dependencies that Stella deploys, scans, observes, or controls for the financial-entity operator.",
      "requiredForConfiguredStatus": true
    },
    {
      "scope": "operator-supplied",
      "label": "Operator-supplied DORA entity and contract evidence",
      "description": "Financial-entity identity, competent-authority context, ICT risk policies, contracts, subcontracting beyond direct integrations, tolerance decisions, and filing approvals supplied by the operator.",
      "requiredForConfiguredStatus": true
    },
    {
      "scope": "stella-supplier",
      "label": "Stella supplier evidence",
      "description": "Stella signed releases, SBOM/VEX, support lifecycle, security contact, CVD, build attestations, and incident notification posture when Stella is an ICT third-party provider in the operator estate.",
      "requiredForConfiguredStatus": false
    }
  ],
  "coverageSummary": {
    "primaryScope": "operator-observed-estate",
    "coverageLabel": "Operational-resilience evidence for Stella-monitored or Stella-deployed ICT software.",
    "observedSoftwareKinds": ["ict-services", "container-images", "release-bundles", "integrations", "plugins", "runtime-host-agents", "direct-software-dependencies"],
    "operatorSuppliedGaps": [
      "financial-entity-legal-profile",
      "ict-risk-strategy-and-tolerance-decisions",
      "outsourcing-contract-terms",
      "subcontracting-beyond-direct-integrations",
      "competent-authority-filing-and-approval"
    ],
    "supplierEvidenceProfile": "stella.supplier-evidence"
  },
  "jurisdictions": ["EU"],
  "features": ["exports", "timelines", "asset-inventory", "retention", "info-sharing", "tlpt-evidence"],
  "owners": [
    { "module": "Telemetry", "path": "src/Telemetry/", "responsibility": "major ICT incident facts and classification evidence" },
    { "module": "Notify", "path": "src/Notify/", "responsibility": "incident handoff timelines and Article 45 information-sharing channels" },
    { "module": "Findings", "path": "src/Findings/", "responsibility": "Register of Information source records and local-contract export data" },
    { "module": "EvidenceLocker", "path": "src/EvidenceLocker/", "responsibility": "DORA retention metadata and signed evidence capsules" },
    { "module": "CLI", "path": "src/Cli/", "responsibility": "offline export, handoff, and verification commands" }
  ],
  "setupPrerequisites": [
    "dora.major-incident.handoff",
    "dora.roi.local-contract-export",
    "dora.info-sharing.channel",
    "dora.tlpt.evidence-pack"
  ],
  "exports": [
    "dora.major-incident-report",
    "dora.roi",
    "dora.info-sharing",
    "dora.tlpt-evidence-pack"
  ],
  "reportingTimelines": ["dora.article19.incident"],
  "controlMappings": [
    "dora-incident-classification-v1",
    "dora-major-incident-report-v1",
    "dora-roi-v1",
    "dora-info-sharing-event-v1",
    "tlpt-evidence-pack-v1"
  ],
  "compatibilityRoutes": [
    "stella incident classify",
    "stella export dora-incident-report",
    "stella verify dora-incident-report",
    "stella export dora-roi",
    "stella verify dora-roi",
    "stella export dora-info-sharing",
    "stella verify dora-info-sharing",
    "stella tlpt pack",
    "stella verify tlpt-pack"
  ],
  "offlineMode": {
    "supported": true,
    "requiresLiveRegulatorEndpoint": false,
    "fixturePolicy": "local deterministic DORA fixtures only; no live regulator schema or endpoint fetches"
  }
}

The DORA descriptor (dora.json) is embedded and discoverable today via stella assurance packs list and stella assurance pack inspect dora. DORA may also be exercised through pack-specific commands and runtime modules (stella incident classify, stella export dora-*, stella tlpt pack, etc., listed in compatibilityRoutes). When the generic readiness APIs are not wired for a tenant, stella assurance pack status dora reports the pack as unavailable, not configured (fail-closed). Missing descriptor or readiness APIs must be reported as unavailable, not configured.

Example: CRA Technical Documentation Pack

{
  "schemaVersion": "assurance-pack-v1",
  "packId": "cra.technical-documentation",
  "frameworkId": "cra",
  "packVersion": "1.0.0",
  "displayName": "CRA Technical Documentation Pack",
  "claimBoundary": "manufacturer-customer-support",
  "evidenceScopes": ["operator-supplied", "stella-supplier"],
  "evidenceSourceLanes": [
    {
      "scope": "operator-supplied",
      "label": "Manufacturer-supplied product evidence",
      "description": "The product manufacturer supplies product identity, intended purpose, conformity route decisions, and non-Stella evidence used in the dossier.",
      "requiredForConfiguredStatus": true
    },
    {
      "scope": "stella-supplier",
      "label": "Stella generated evidence services",
      "description": "Stella assembles signed technical-file and conformity-dossier artifacts from supplied product evidence and Stella-native release/evidence refs.",
      "requiredForConfiguredStatus": true
    }
  ],
  "coverageSummary": {
    "primaryScope": "operator-supplied",
    "coverageLabel": "Customer-manufacturer technical documentation assembly with signed Stella evidence services.",
    "observedSoftwareKinds": ["technical-file-inputs", "conformity-dossier-artifacts", "release-evidence-refs"],
    "operatorSuppliedGaps": [
      "manufacturer-product-identity",
      "intended-purpose-and-risk-classification",
      "conformity-route-decision",
      "non-stella-product-evidence"
    ],
    "supplierEvidenceProfile": "stella.supplier-evidence"
  },
  "jurisdictions": ["EU"],
  "features": ["exports", "auditor-evidence"],
  "owners": [
    { "module": "ExportCenter", "path": "src/ExportCenter/", "responsibility": "technical file and dossier exports" },
    { "module": "CLI", "path": "src/Cli/", "responsibility": "offline export and verify commands" }
  ],
  "setupPrerequisites": ["cra.technical-documentation.signed-export"],
  "exports": ["cra.technical-file", "cra.conformity-dossier"],
  "reportingTimelines": [],
  "controlMappings": ["cra-tech-file-v1", "conformity-dossier-v1"],
  "compatibilityRoutes": ["stella export cra-tech-file", "stella export conformity-dossier"],
  "offlineMode": {
    "supported": true,
    "requiresLiveRegulatorEndpoint": false,
    "fixturePolicy": "golden export bundle fixtures"
  }
}

CLI Surface

The descriptor catalog and tenant readiness are exposed by the stella assurance command tree (built in src/Cli/StellaOps.Cli/Commands/Assurance/AssurancePackCommandGroup.cs):

CLI exit codes: 0 (success) when a pack status is configured; ServiceNotConfigured for any non-configured status (blocked, unavailable, disabled); general error when a packId is not found.

Status Result Shape

stella assurance pack status --json returns an assurance-pack-status.v1 object composed by AssurancePackStatusResult.Compose. Key fields:

State precedence in ComposeState: any secretValuesExposed or blocked component → blocked; else any unavailable component → unavailable; else Authority disabled → disabled; else configured only when there are zero reason codes, otherwise blocked.

For nis2 and dora, the descriptor itself is validated by GetDescriptorScopeReasonCodes, which adds (when missing): evidence-scopes-missing, evidence-source-lanes-missing, coverage-primary-scope-missing, operator-observed-estate-scope-missing, operator-supplied-scope-missing.

Other observed reason codes (emitted by the readiness clients): authority-api-unavailable, tenant-not-found, authority-readiness-invalid, pack-disabled, exportcenter-api-unavailable, export-profile-not-found, export-readiness-invalid, notify-api-unavailable, reporting-profile-not-found, reporting-readiness-invalid, secret-values-exposed. Downstream signing/trust reason codes such as signing-key-missing and tenant-export-trust-roots-missing are passed through verbatim from ExportCenter without exposing secret values.

Readiness APIs

stella assurance pack status fans out fail-closed to three named HttpClients. If a client has no BaseAddress, or the call throws / returns non-success, the corresponding line resolves to unavailable with a stable reason code rather than failing open.

The Authority assurance-packs readiness response drives pack enable/disable: a missing or enabled=false pack entry yields Authority state disabled with pack-disabled, which short-circuits export/timeline checks. The Authority endpoint returns enabled-pack settings (mode, claimBoundary, ownerRole, enabledBy, enabledAt, lastReviewedAt, configRevision) and per-pack readiness flags (authorityProfileConfigured, operatorApproverConfigured, retentionPolicyReviewed, reasonCodes[]).

Determinism And Offline Rules

• Pack descriptors MUST be sorted by packId for CLI/Web listing.
• Descriptor JSON examples MUST be canonicalizable with ordinal-sorted object keys.
• Tests MUST NOT fetch live regulator schemas or live authority endpoints.
• Descriptor changes MUST be versioned and linked from the sprint that changed them.