Files

Docs CI / lint-and-preview (push) Has been cancelled

Details

Add unit tests for RabbitMq and Udp transport servers and clients

- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling.
- Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options.
- Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation.
- Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios.
- Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling.
- Included tests for UdpTransportOptions to verify default values and modification capabilities.
- Enhanced service registration tests for Udp transport services in the dependency injection container.

2025-12-05 19:01:12 +02:00

5.0 KiB

Raw Permalink 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/schemas/mirror-bundle.schema.json
Documentation: docs/airgap/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

Validate DSSE envelope structure
Verify RSA-PSS/SHA256 signature
Check trusted key fingerprint
Validate PAE encoding

TUF Validation

Verify root → snapshot → timestamp chain
Check version monotonicity
Validate expiry windows
Cross-reference hashes

Merkle Root Verification

Compute SHA-256 tree for bundle objects
Compare against stored Merkle root
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

Digest verification: All artifacts verified by SHA-256 digest
Stable ordering: Exports ordered deterministically
Immutable content: Bundle content is immutable once signed
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

Sealed Mode Contract - Sealed environment operation
Verification Policy Contract - Attestation verification
Export Bundle Contract - Export job scheduling

5.0 KiB Raw Permalink Blame History