stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

test fixes and new product advisories work

Browse Source
This commit is contained in:
master
2026-01-28 02:30:48 +02:00
parent 82caceba56
commit 644887997c
288 changed files with 69101 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/modules/export-center/architecture.md
View File

@@ -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.

152
docs/modules/export-center/registry-compatibility.md Normal file
View File

@@ -0,0 +1,152 @@
# Registry Compatibility Matrix
> Sprint: SPRINT_0127_001_0001_oci_referrer_bundle_export
> Module: ExportCenter
This document provides detailed compatibility information for OCI referrer discovery across container registries.
## OCI 1.1 Referrers API Support
The OCI Distribution Spec v1.1 introduced the native referrers API (), which enables efficient discovery of artifacts linked to container images. Not all registries support this API yet.
### Support Matrix
| Registry | OCI 1.1 API | Fallback Tags | Artifact Type Filter | Notes |
|----------|-------------|---------------|---------------------|-------|
| **Docker Hub** | Partial | Yes | Limited | Rate limits may affect discovery; partial OCI 1.1 support |
| **GitHub Container Registry (GHCR)** | No | Yes | N/A | Uses tag-based discovery |
| **Google Container Registry (GCR)** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Google Artifact Registry** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Amazon ECR** | Yes | Yes | Yes | Requires proper IAM permissions for referrer operations |
| **Azure Container Registry (ACR)** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Harbor 2.0+** | Yes | Yes | Yes | Full OCI 1.1 support; older versions require fallback |
| **Harbor 1.x** | No | Yes | N/A | Fallback only |
| **Quay.io** | Partial | Yes | Limited | Support varies by version and configuration |
| **JFrog Artifactory** | Partial | Yes | Limited | Requires OCI layout repository type |
| **Zot** | Yes | Yes | Yes | Full OCI 1.1 support |
| **Distribution (registry:2)** | No | Yes | N/A | Reference implementation without referrers API |
### Legend
- **OCI 1.1 API**: Native support for endpoint
- **Fallback Tags**: Support for tag-schema discovery pattern ()
- **Artifact Type Filter**: Support for query parameter
## Per-Registry Details
### Docker Hub
- **API Support**: Partial OCI 1.1 support
- **Fallback**: Yes, via tag-based discovery
- **Authentication**: Bearer token via Docker Hub auth service
- **Rate Limits**: 100 pulls/6 hours (anonymous), 200 pulls/6 hours (authenticated)
- **Known Issues**:
- Rate limiting can affect large bundle exports
- Some artifact types may not be discoverable via native API
### GitHub Container Registry (GHCR)
- **API Support**: No native referrers API
- **Fallback**: Yes, required for all referrer discovery
- **Authentication**: GitHub PAT or GITHUB_TOKEN with scope
- **Rate Limits**: GitHub API rate limits apply
- **Known Issues**:
- Referrers must be pushed using tag-schema pattern
- Artifact types embedded in tag suffix (e.g., , , )
### Google Container Registry / Artifact Registry
- **API Support**: Full OCI 1.1 support
- **Fallback**: Yes, as backup
- **Authentication**: Google Cloud service account or gcloud auth
- **Rate Limits**: Generous; project quotas apply
- **Known Issues**: None significant
### Amazon Elastic Container Registry (ECR)
- **API Support**: Full OCI 1.1 support
- **Fallback**: Yes, as backup
- **Authentication**: IAM role or access keys via
- **Rate Limits**: 1000 requests/second per region
- **Known Issues**:
- Requires IAM permissions for OCI operations
- Cross-account referrer discovery needs proper IAM policies
### Azure Container Registry (ACR)
- **API Support**: Full OCI 1.1 support
- **Fallback**: Yes, as backup
- **Authentication**: Azure AD service principal or managed identity
- **Rate Limits**: Tier-dependent (Basic: 1000 reads/min, Standard: 3000, Premium: 10000)
- **Known Issues**: None significant
### Harbor
- **API Support**: Full OCI 1.1 support in Harbor 2.0+
- **Fallback**: Yes
- **Authentication**: Harbor user credentials or robot account
- **Rate Limits**: Configurable at server level
- **Known Issues**:
- Harbor 1.x does not support referrers API
- Project-level permissions required
### Quay.io / Red Hat Quay
- **API Support**: Partial (version-dependent)
- **Fallback**: Yes
- **Authentication**: Robot account or OAuth token
- **Rate Limits**: Account tier dependent
- **Known Issues**:
- Support varies significantly by version
- Some deployments may have referrers API disabled
### JFrog Artifactory
- **API Support**: Partial (requires OCI layout)
- **Fallback**: Yes
- **Authentication**: API key or access token
- **Rate Limits**: License-dependent
- **Known Issues**:
- Repository must be configured as Docker with OCI layout
- Referrers API requires Artifactory 7.x+
## Discovery Methods
### Native Referrers API (OCI 1.1)
The preferred method queries the registry referrers endpoint directly:
### Fallback Tag-Schema Discovery
For registries without OCI 1.1 support, tags following the pattern are enumerated:
Each matching tag is then resolved to get artifact metadata.
## Troubleshooting
### Common Issues
| Issue | Registry | Solution |
|-------|----------|----------|
| 404 on referrers endpoint | GHCR, Distribution | Use fallback tag discovery |
| Rate limit exceeded | Docker Hub | Authenticate or reduce concurrency |
| Permission denied | ECR, ACR | Check IAM/RBAC permissions |
| No referrers found | All | Verify artifacts were pushed with referrer relationship |
| Timeout | All | Increase timeout_seconds, check network |
### Diagnostic Commands
## Related Documentation
- [Export Center Architecture](architecture.md#oci-referrer-discovery)
- [Offline Bundle Format](../airgap/guides/offline-bundle-format.md#oci-referrer-artifacts)
- [Registry Referrer Troubleshooting Runbook](../../runbooks/registry-referrer-troubleshooting.md)
- [OCI Distribution Spec v1.1](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.