cc69d332e3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- 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.
213 lines
5.0 KiB
Markdown
213 lines
5.0 KiB
Markdown
# 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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
- [Sealed Mode Contract](./sealed-mode.md) - Sealed environment operation
|
|
- [Verification Policy Contract](./verification-policy.md) - Attestation verification
|
|
- [Export Bundle Contract](./export-bundle.md) - Export job scheduling
|