test fixes and new product advisories work

2026-01-28 02:30:48 +02:00
parent 82caceba56
commit 644887997c
288 changed files with 69101 additions and 375 deletions
--- a/docs/modules/export-center/architecture.md
+++ b/docs/modules/export-center/architecture.md
@@ -82,8 +82,8 @@ All endpoints require Authority-issued JWT + DPoP tokens with scopes `export:run

 Audit bundles are a specialized Export Center output: a deterministic, immutable evidence pack for a single subject (and optional time window) suitable for audits and incident response.

- **Schema**: `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json` (bundle index/manifest with integrity hashes and referenced artefacts).
- The index must list Rekor entry ids and RFC3161 timestamp tokens when present; offline bundles record skip reasons in predicates.
+- **Schema**: `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json` (bundle index/manifest with integrity hashes and referenced artefacts).
+- The index must list Rekor entry ids and RFC3161 timestamp tokens when present; offline bundles record skip reasons in predicates.
 - **Core APIs**:
  - `POST /v1/audit-bundles` - Create a new bundle (async generation).
  - `GET /v1/audit-bundles` - List previously created bundles.
@@ -117,6 +117,78 @@ Adapters expose structured telemetry events (`adapter.start`, `adapter.chunk`, `
 - **Attestation.** Cosign SLSA Level 2 template by default; optional SLSA Level 3 when supply chain attestations are enabled. Detached signatures stored alongside manifests; CLI/Console encourage `cosign verify --key <tenant-key>` workflow.
 - **Audit trail.** Each run stores success/failure status, signature identifiers, and verification hints for downstream automation (CI pipelines, offline verification scripts).

+## OCI Referrer Discovery
+
+Mirror bundles automatically discover and include OCI referrer artifacts (SBOMs, attestations, signatures, VEX statements) linked to container images via the OCI 1.1 referrers API.
+
+### Discovery Flow
+
+```
+┌─────────────────┐     ┌───────────────────────┐     ┌─────────────────┐
+│  MirrorAdapter  │────▶│  IReferrerDiscovery   │────▶│   OCI Registry  │
+│                 │     │  Service              │     │                 │
+│  1. Detect      │     │  2. Probe registry    │     │  3. Query       │
+│     images      │     │     capabilities      │     │     referrers   │
+│                 │     │                       │     │     API         │
+└─────────────────┘     └───────────────────────┘     └─────────────────┘
+                                   │
+                                   ▼
+                        ┌───────────────────────┐
+                        │  Fallback: Tag-based  │
+                        │  discovery for older  │
+                        │  registries (GHCR)    │
+                        └───────────────────────┘
+```
+
+### Capability Probing
+
+Before starting referrer discovery, the export flow probes each unique registry to determine capabilities:
+
+- **OCI 1.1+ registries**: Native referrers API (`/v2/{repo}/referrers/{digest}`)
+- **OCI 1.0 registries**: Fallback to tag-based discovery (`sha256-{digest}.*` tags)
+
+Capabilities are cached per registry host with a 1-hour TTL.
+
+**Logging at export start:**
+```
+[INFO] Probing 3 registries for OCI referrer capabilities before export
+[INFO] Registry registry.example.com: OCI 1.1 (referrers API supported, version=OCI-Distribution/2.1, probe_ms=42)
+[WARN] Registry ghcr.io: OCI 1.0 (using fallback tag discovery, version=registry/2.0, probe_ms=85)
+```
+
+### Telemetry Metrics
+
+| Metric | Description | Tags |
+|--------|-------------|------|
+| `export_registry_capabilities_probed_total` | Registry capability probe operations | `registry`, `api_supported` |
+| `export_referrer_discovery_method_total` | Discovery operations by method | `registry`, `method` (native/fallback) |
+| `export_referrers_discovered_total` | Referrers discovered | `registry`, `artifact_type` |
+| `export_referrer_discovery_failures_total` | Discovery failures | `registry`, `error_type` |
+
+### Artifact Type Mapping
+
+| OCI Artifact Type | Bundle Category | Example |
+|-------------------|-----------------|---------|
+| `application/vnd.cyclonedx+json` | `sbom` | CycloneDX SBOM |
+| `application/vnd.spdx+json` | `sbom` | SPDX SBOM |
+| `application/vnd.openvex+json` | `vex` | OpenVEX statement |
+| `application/vnd.csaf+json` | `vex` | CSAF document |
+| `application/vnd.in-toto+json` | `attestation` | in-toto attestation |
+| `application/vnd.dsse.envelope+json` | `attestation` | DSSE envelope |
+| `application/vnd.slsa.provenance+json` | `attestation` | SLSA provenance |
+
+### Error Handling
+
+- If referrer discovery fails for a single image, the export logs a warning and continues with other images
+- Network failures do not block the entire export
+- Missing referrer artifacts are validated during bundle import (see [ImportValidator](../airgap/guides/offline-bundle-format.md))
+
+### Related Documentation
+
+- [Registry Compatibility Matrix](registry-compatibility.md)
+- [Offline Bundle Format](../airgap/guides/offline-bundle-format.md#oci-referrer-artifacts)
+- [Registry Referrer Troubleshooting](../../runbooks/registry-referrer-troubleshooting.md)
+
 ## Distribution flows
 - **HTTP download.** Console and CLI stream bundles via chunked transfer; supports range requests and resumable downloads. Response includes `X-Export-Digest`, `X-Export-Length`, and optional encryption metadata.
 - **OCI push.** Worker uses ORAS to publish bundles as OCI artefacts with annotations describing profile, tenant, manifest digest, and provenance reference. Supports multi-tenant registries with `repository-per-tenant` naming.