stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
da27b9faa98619ece3407f731f0eacbc730cfffb
git.stella-ops.org/docs/contracts/mirror-bundle.md
master 044cf0923c docs consolidation
2026-01-07 10:23:21 +02:00

5.0 KiB
Raw Blame History

Mirror Bundle Contract (AIRGAP-56)

Contract ID: CONTRACT-MIRROR-BUNDLE-003 Version: 1.0 Status: Published Last Updated: 2025-12-05

Overview

This contract defines the mirror bundle format used for air-gap/offline operation. Mirror bundles package VEX advisories, vulnerability feeds, and policy packs for transport to sealed environments.

Implementation References

  • JSON Schema: docs/modules/airgap/schemas/mirror-bundle.schema.json
  • Documentation: docs/modules/airgap/guides/mirror-bundles.md
  • Importer: src/AirGap/StellaOps.AirGap.Importer/

Bundle Structure

MirrorBundle

Top-level bundle object.

{
  "schemaVersion": 1,
  "generatedAt": "2025-12-05T10:00:00Z",
  "targetRepository": "oci://registry.internal/stella/mirrors",
  "domainId": "vex-advisories",
  "displayName": "VEX Advisories",
  "exports": [
    { ... }
  ]
}
Field Type Required Description
schemaVersion integer Yes Bundle schema version (currently 1)
generatedAt datetime Yes ISO-8601 generation timestamp
targetRepository string No Target OCI repository
domainId string Yes Domain identifier
displayName string No Human-readable name
exports array Yes Exported data sets

BundleExport

Individual export within a bundle.

{
  "key": "vex-openvex-all",
  "format": "openvex",
  "exportId": "550e8400-e29b-41d4-a716-446655440000",
  "querySignature": "abc123def456",
  "createdAt": "2025-12-05T10:00:00Z",
  "artifactSizeBytes": 1048576,
  "artifactDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
  "sourceProviders": ["anchore", "github", "redhat"],
  "consensusRevision": "rev-2025-12-05-001",
  "policyRevisionId": "policy-v1.2.3",
  "policyDigest": "sha256:...",
  "consensusDigest": "sha256:...",
  "scoreDigest": "sha256:...",
  "attestation": {
    "predicateType": "https://stella.ops/attestation/vex-export/v1",
    "signedAt": "2025-12-05T10:00:01Z",
    "envelopeDigest": "sha256:...",
    "rekorLocation": "https://rekor.sigstore.dev/api/v1/log/entries/..."
  }
}

Export Formats

Format Description
openvex OpenVEX format
csaf CSAF VEX format
cyclonedx CycloneDX VEX format
spdx SPDX format
ndjson Newline-delimited JSON
json Standard JSON

AttestationDescriptor

Attestation metadata for signed exports.

{
  "predicateType": "https://stella.ops/attestation/vex-export/v1",
  "rekorLocation": "https://rekor.sigstore.dev/...",
  "envelopeDigest": "sha256:...",
  "signedAt": "2025-12-05T10:00:01Z"
}

BundleSignature

Signature for bundle integrity.

{
  "path": "bundle.sig",
  "algorithm": "ES256",
  "keyId": "key-2025-001",
  "provider": "default",
  "signedAt": "2025-12-05T10:00:02Z"
}

Domain IDs

Standard domain identifiers:

Domain ID Description
vex-advisories VEX advisory documents
vulnerability-feeds Vulnerability feed data
policy-packs Policy rule packages
sbom-catalog SBOM artifacts

Validation Requirements

DSSE Verification

  1. Validate DSSE envelope structure
  2. Verify RSA-PSS/SHA256 signature
  3. Check trusted key fingerprint
  4. Validate PAE encoding

TUF Validation

  1. Verify root → snapshot → timestamp chain
  2. Check version monotonicity
  3. Validate expiry windows
  4. Cross-reference hashes

Merkle Root Verification

  1. Compute SHA-256 tree for bundle objects
  2. Compare against stored Merkle root
  3. Validate staged content integrity

Import Flow

1. Receive bundle package
2. Validate DSSE signature
3. Verify TUF metadata chain
4. Compute and verify Merkle root
5. Register in bundle catalog
6. Apply to sealed environment

Registration API

Register Bundle

POST /api/v1/airgap/bundles
Content-Type: application/json

{
  "bundlePath": "/path/to/bundle.json",
  "trustRootsPath": "/path/to/trust-roots.json"
}

Response: 202 Accepted
{
  "importId": "...",
  "status": "validating"
}

Get Bundle Status

GET /api/v1/airgap/bundles/{bundleId}

Response: 200 OK
{
  "bundleId": "...",
  "domainId": "vex-advisories",
  "status": "imported",
  "exportCount": 3
}

Determinism Guarantees

  1. Digest verification: All artifacts verified by SHA-256 digest
  2. Stable ordering: Exports ordered deterministically
  3. Immutable content: Bundle content is immutable once signed
  4. Traceability: Full provenance chain via attestations

Unblocks

This contract unblocks the following tasks:

  • POLICY-AIRGAP-56-001
  • POLICY-AIRGAP-56-002
  • EXCITITOR-AIRGAP-56-001
  • EXCITITOR-AIRGAP-58-001
  • CLI-AIRGAP-56-001
  • AIRGAP-TIME-57-001

Related Contracts