This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Container Catalog

Per-distro serverless catalog API for Hummingbird container images.

Features

  • Image Directory - Browse all container images with metadata
  • Tag Browser - View tags, digests, architectures per image
  • Specifications - Per-architecture OCI config details (env, cmd, user, labels)
  • SBOM - Per-architecture package lists from syft scans with a Hermeto build-only merge
  • Vulnerabilities - CVE scanning results via Grype
  • CVE Metrics - Catalog-wide vulnerability aggregate
  • Provenance - Source traceability from SLSA attestations
  • Release History - Timeline of past builds with drill-down
  • Deprecation status - Stream and release status from OCI labels
  • OpenAPI Spec - Machine-readable API documentation at /v1/openapi.json
  • Swagger UI - Interactive API explorer at /v1/docs/
  • External Images - CVE comparison with external image sources
  • External Comparison UI - Side-by-side CVE and SBOM comparison between Hummingbird and external counterparts

Architecture

Rust serverless stack deployed as two isolated per-distro stacks:

  • API Lambda - DynamoDB pass-through (~10ms response)
  • Sync Lambda - Incremental DynamoDB sync from SNS Release events (~22 registry calls per release), then enqueues one index event per release
  • Index Lambda (index-lambda) - Queue-driven Syft runs per architecture, writes the SBOM items to DynamoDB, uploads native Syft JSON to S3 for scanner consumption (same function shape as the external index — the future unified function)
  • Scan Lambda (scan-lambda) - SQS-triggered CVE scanning via Grype from native Syft JSON in S3, per-digest processing with first_seen tracking and partial batch failure reporting
  • Enqueue Lambda (enqueue-lambda) - Hourly EventBridge-triggered fan-out that checks Grype DB for updates and enqueues non-superseded digests to SQS
  • Metrics Lambda (metrics-lambda) - DynamoDB Stream-triggered vulnerability aggregate
  • External Release Lambda (external-release-lambda) - Scheduled trigger feeding the external sync queue
  • External Sync Lambda (external-sync-lambda) - Registry tag resolution and DynamoDB metadata writes for external images
  • External Index Lambda (external-index-lambda) - Syft SBOM generation for external images, uploads to S3 for Grype scanning
  • DynamoDB - Pre-computed JSON items (single-table PK/SK design, Streams: KEYS_ONLY)
  • S3 ScanDataBucket - Native Syft JSON storage for scanner data (gzipped, keyed by grype/{image}/{digest_hex}.json.gz for Hummingbird and grype-external/{registry}/{digest_hex}.json.gz for external images; SPDX SBOMs are stored at sbom/{image}/{digest_hex}.json.gz for Hummingbird and sbom-external/{registry}/{digest_hex}.json.gz for external images — the sbom* prefixes match no scan notification filter)
  • SQS IndexQueue - Decouples the index (syft) path from sync: the Sync Lambda enqueues one tag-release event per release after its DynamoDB writes; failed index records are retried individually via SQS batch-item-failure semantics, redriving to the IndexDLQ after 3 attempts
  • SQS ScanQueue - Central queue for scan tasks (fed by both grype/ and grype-external/ S3 event notifications and Enqueue Lambda)
  • CloudFront - CDN with per-endpoint cache TTLs
  • catalog sync - Full DynamoDB population from GitLab + Quay.io OCI v2 registry
  • catalog scan - CLI CVE scanning via Grype; reads native Syft JSON from S3 (--bucket required); historic releases read the same S3 objects, and digests whose object is missing are skipped with a warning
  • catalog index - CLI Syft JSON generation for backfilling S3
  • Catalog SPA - Lit 3 web app served from S3 via CloudFront

Scanner Architecture

CVE vulnerability data must match direct grype <image> scans exactly for all images. Synthetic Syft JSON (built from stored SBOM packages) cannot reliably reproduce the native output because Grype relies on metadata fields, artifact relationships, and deduplication logic that are lost in the SPDX-to-API roundtrip. Additionally, raw SPDX from the build system contains package bloat (e.g. Go sub-modules, empty-version entries) that native Syft filters out when scanning a compiled binary directly.

To guarantee exact-match results, the scanner chain stores native Syft JSON in S3 rather than DynamoDB: a single image’s Syft JSON is typically 1-10 MB (gzipped to 100 KB - 1 MB), which exceeds DynamoDB’s 400 KB item limit. S3 has no per-object size constraint, avoids provisioned throughput costs for large blobs, and supports event notifications for triggering downstream scanners. The Index Lambda runs syft <image> on each new release and uploads the full output to s3://{bucket}/grype/{image}/{hex}.json.gz. The S3 upload fires an event notification to SQS, which triggers the Scan Lambda to read the native JSON, run Grype, and write per-canonical vulnerability data to DynamoDB.

Each syft run extracts image layers into its own temp directory, passed to the syft child via TMPDIR and removed when the run finishes; concurrent runs never share temp data. Dirs left behind by killed runs are swept before each new run (age-gated to never touch a possibly-active run).

When running inside a Lambda, the syft child process inherits GOMEMLIMIT derived as 90% of AWS_LAMBDA_FUNCTION_MEMORY_SIZE (injected by Lambda, in MB; e.g. 3072 MB → 2764 MiB). This makes the cgroup limit and the GC soft limit share a single source of truth — a memory bump auto-rescales both with no code change. Outside Lambda (CLI catalog index backfill, local runs) the variable is absent and Go’s defaults apply. Without GOMEMLIMIT, Go’s default GOGC=100 lets syft’s heap grow to 2× its live size (~2.8 GB for large multi-layer images → ~5.7 GB peak), exceeding the Lambda cgroup and causing OOM-kills. If a future image’s live heap grows beyond the limit, the scan degrades to slower GC thrash rather than an instant kill.

The scanner chain is decoupled from the catalog data chain by a queue: the SNS Release event triggers the Sync Lambda (catalog data to DynamoDB), which then enqueues one index event per release; the Index Lambda consumes those events (Syft JSON to S3). The event carries everything the index needs, so the slow syft path never blocks the sync invocation and a failed record is retried individually by the queue.

Grype runs with --by-cve: some ecosystems (e.g. Go modules) are otherwise reported using their native GHSA or Go vulnerability DB ID rather than a CVE. --by-cve reports the CVE ID instead wherever grype’s own local vulnerability database has that cross-reference, with no added network call. An ID with no known CVE anywhere in that database is returned as-is.

Vulnerability components include the source RPM filename from the syft scan when available. Consumers can group affected binary RPMs by this value.

CVE Data Flow

graph TD
    subgraph Hummingbird
        Attestation[(Registry .sbom attestations)] -->|"fetch + merge"| Index
        Konflux([Konflux Release])
        Konflux -->|SNS| Sync[SyncFunction]
        Sync -->|"index events via SQS"| Index[IndexFunction]
        Sync -->|update| Tags[(Tags)]
        Index -->|upload| S3Syft[(S3 grype/)]
        Index -->|write| SbomItems[(SBOM items)]
    end

    subgraph External Images
        ExtSchedule([Schedule 6h]) -->|invoke| ExtRelease[ExternalReleaseFunction]
        ExtRelease -->|"per registry via SQS"| ExtSync[ExternalSyncFunction]
        ExtSync -->|"per-tag release events via SQS"| ExtIndex[ExternalIndexFunction]
        ExtIndex -->|upload| S3Ext[(S3 grype-external/)]
        ExtIndex -->|write| ExtSbomItems[(External SBOM items)]
        ExtSync -->|update| ExtTags[(External Tags)]
    end

    Tags -->|read| Scan[ScanFunction]
    ExtTags -->|read| Scan
    S3Syft -->|"S3 event via SQS"| Scan
    S3Ext -->|"S3 event via SQS"| Scan
    Hourly([Schedule 1h]) -->|invoke| Enqueue[EnqueueFunction]
    Enqueue --> Gate[check Grype DB]
    Gate -->|"fan out via SQS"| Scan
    Scan -->|update| Vulns[(Vulnerabilities)]
    Vulns -->|"stream via ESM"| Metrics[MetricsFunction]
    Tags -->|"stream via ESM"| Metrics
    Metrics -->|"write aggregate"| CatalogVulns[(Catalog Vulnerabilities)]

    classDef lambda fill:#d4e6f1,stroke:#2980b9
    classDef dynamo fill:#fdebd0,stroke:#e67e22
    classDef trigger fill:#d5f5e3,stroke:#27ae60
    classDef gate fill:#e5e7e9,stroke:#7f8c8d
    class Sync,Scan,Enqueue,Metrics,Index,ExtRelease,ExtSync,ExtIndex lambda
    class Vulns,Tags,ExtTags,CatalogVulns,S3Syft,S3Ext,S3Spdx,S3ExtSpdx,SbomItems,ExtSbomItems,Attestation dynamo
    class Konflux,Hourly,ExtSchedule trigger
    class Gate gate

The sbom/ and sbom-external/ records are the recovery inputs for the already-indexed path: each index function persists its primary-arch SPDX before the grype* blob, which is deliberately the last write — it is the dedup key and the scan trigger, so it never arms before its recovery input exists. Both planes share the same ordering guarantee: the sync function’s DynamoDB writes complete before its index events are enqueued — the queue is the ordering barrier. The attestation edge is internal-only: the Hummingbird index fetches the per-arch Hermeto attestations from the registry and merges build-only entries into each arch’s SBOM; external images have no attestation input.

Prerequisites

  • Rust 1.75+ (for building backend)
  • Node.js 22+ (for building frontend)
  • AWS credentials (for DynamoDB access and deployment)
  • SAM CLI (for deployment)

API Endpoints

Both namespaces share the same response types and URL structure. The Hummingbird prefix is /v1/images/{name}, the external prefix is /v1/external-images/{name} where {name} is a percent-encoded registry reference (e.g. docker.io%2Flibrary%2Fnginx). DynamoDB partition keys are IMAGE#{name} and EXTERNAL#{registry} respectively.

Suffix Response type HB Ext
(directory) DirectoryResponse ✅ ✅
(config) ExternalImagesConfig ✅
/{…} ImageResponse ✅ ✅
/{…}/tags TagsResponse ✅ ✅
/{…}/details/{canonical} DetailsResponse ✅ ✅
/{…}/sbom/{canonical} SbomResponse ✅ ✅
/{…}/vulnerabilities/{canonical} VulnerabilitiesResponse ✅ ✅
/{…}/history/{stream}/{variant} HistoryResponse ✅ ✅
/{…}/releases/details/{digest} DetailsResponse ✅ ✅
/{…}/releases/sbom/{digest} SbomResponse ✅ ✅
/{…}/releases/vulnerabilities/{digest} VulnerabilitiesResponse ✅ ✅
/v1/vulnerabilities CatalogVulnerabilitiesResponse ✅

GET /v1/openapi.json and GET /v1/docs/ serve the OpenAPI 3.1 spec and Swagger UI for all endpoints.

Response types

DirectoryResponse

Catalog-level image listing with aggregate statistics. Used for both Hummingbird (CATALOG/DIRECTORY) and external (CATALOG/EXTERNAL_DIRECTORY) image directories.

Field Type Description
images ImageSummary[] All images in the catalog
image_count u32 Total number of images
variant_count u32 Total unique variant names across all images
stream_variant_count u32 Total published (stream, variant) pairs
stream_count u32 Total version streams across all images
tag_count u32 Total tags across all images
release_count u32 Total releases across all images

ImageSummary

Per-image summary used in both directory listings and as the base of ImageResponse.

Field Type Hummingbird External
name String Image name (e.g. python) Registry reference (e.g. docker.io/library/nginx)
summary String From summary OCI label Omitted — no OCI labels available from upstream registries
application_category String From io.hummingbird-project.application-category label Omitted — Hummingbird-specific label
description String From org.opencontainers.image.description label or README Omitted — no README available from upstream registries
latest_tag String Most recent canonical tag Same
pull_url String quay.io/…/{name}:latest {registry}:{latest_tag}
oldest_created String? Earliest OCI created timestamp Same
architectures String[] From OCI manifest list Same
variants VariantDescription[] From containers repo From config
stream_variant_count u32 Computed from tags Same
streams String[] From containers repo directory names From config
deprecated_streams String[] Streams with deprecated=true label Always [] — external images have no deprecation mechanism
tag_count u32 Number of tags Same
release_count u32 Sum of history entries Same

ImageResponse

Full image detail — flattens ImageSummary into the top level with additional fields.

Field Type Hummingbird External
(all ImageSummary fields) (see above) (see above)
readme_html String README rendered as HTML Omitted — no README available from upstream
licenses String[] SPDX identifiers from the attestation SBOM’s runtime packages Omitted — no license labels on upstream images

TagsResponse

Field Type Description
tags Tag[] Tags ordered by oldest_created desc
variants VariantDescription[] Available variant descriptions

Tag

Field Type Hummingbird External
name String Tag name (e.g. 3.14.2) Same
canonical String Most specific tag for this release Same (by semver specificity)
variant String From containers repo From config
pull_url String quay.io/…:{tag} {registry}:{tag}
digest String Manifest list digest Same
sizes {arch: bytes} Compressed layer sizes from OCI manifest Same
architectures String[] From OCI manifest list Same
oldest_created String? Earliest OCI created timestamp Same
stream String From containers repo directory name From config
deprecated bool From deprecated=true OCI label Always false — no deprecation mechanism for external images
superseded bool Computed by mark_superseded Same

DetailsResponse / ArchDetails

Per-architecture OCI container configuration keyed by architecture name (e.g. {"amd64": {...}, "arm64": {...}}).

Field Type Hummingbird External
user String From OCI config Same
env {key: value} From OCI config Same
entrypoint String[] From OCI config Same
cmd String[] From OCI config Same
exposed_ports String[] From OCI config Same
volumes String[] From OCI config Same
working_dir String From OCI config Same
stop_signal String From OCI config Same
labels {key: value} From OCI config Same
created String? From OCI config root Same
source_repo String From SLSA attestation Omitted — no signed attestations on upstream images
source_commit String From SLSA attestation Omitted — no signed attestations on upstream images
containerfile String From SLSA attestation Omitted — no signed attestations on upstream images
slsa_level String From SLSA attestation Omitted — no signed attestations on upstream images
build_system String From SLSA attestation Omitted — no signed attestations on upstream images

SbomResponse / ArchSbom

Per-architecture package list keyed by architecture name.

Field Type Hummingbird Rawhide External
runtime_count u32 From the syft scan From the syft scan (Hermeto merge disabled — see below) Same as Hummingbird
build_count u32 From the Hermeto merge Always 0 Always 0 — Hermeto is a Konflux-specific build tool
source_count u32 Always 0 — arch=src entries are skipped Always 0 Always 0 — Hermeto is a Konflux-specific build tool
packages SbomPackage[] All known architectures — one ArchSbom per arch from the manifest list Same All known architectures — one ArchSbom per arch from the manifest list

SbomPackage

Field Type Notes
name String Package name (e.g. python3-libs, github.com/caddyserver/caddy/v2).
evr String Version. RPM: version-release (e.g. 1.33-5.1.hum1); other types: upstream version (e.g. v2.9.1).
type String Package ecosystem, carried verbatim from the Syft artifact type: rpm, go-module, python, npm, gem, dotnet, java-archive. Items written before the syft-native switch may carry purl-derived names (golang, pypi, nuget, maven).
license String SPDX license expression, NOASSERTION when unknown.
sourcerpm String Full source RPM filename (e.g. python3-3.14.2-1.fc42.src.rpm). Only set for RPM runtime packages.
category String runtime (Syft) or build (Hermeto binary with no syft twin). source appears only on legacy items — arch=src entries are skipped.
purl String Full purl string (e.g. pkg:golang/golang.org/x/crypto@0.35.0).
cpes String[] CPE 2.3 identifiers.

Schema revision 1.1.0: the arch map of SbomResponse serializes its keys sorted (byte-stable writes of identical data; semantically identical JSON for consumers). As SBOM content regeneration from the native syft scans rolls out, the type vocabulary switches to the syft-native names above — until an image’s items are regenerated they keep the purl-derived names, so the type value itself distinguishes regenerated from legacy items (go-module and python only appear on regenerated items; legacy items carry golang and pypi).

SBOM content sources: the Index Lambda builds items from the native syft scan of each architecture — all runtime packages, with the type vocabulary carried verbatim from syft — and merges the per-arch Hermeto attestation on top: attestation entries with a syft runtime twin (same name and version-release; a leading RPM epoch prefix on the syft side, e.g. 1:3.5.5-1.hum1, is excluded from the comparison) are dropped, and no-twin entries with a matching arch (or noarch) become build rows carrying their attestation purl verbatim. arch=src entries are skipped — source rows are not emitted, the SRPM identity is derivable from any binary row’s sourcerpm. A version skew keeps both entries — visible, never a silent drop. The merge is gated by the distro switch (classify_by_hermeto): Hummingbird merges; Rawhide serves syft-only items. The attestation SPDX itself remains load-bearing only for derived fields in sync (OVERVIEW licenses, the variant-label fallback) and the conditionally-seeded RELEASE_SBOM for digests that were never scanned while current (an atomic write-if-absent write) — SBOM item content no longer depends on the mobster-merged attestation.

Historical items: items written before the cutover keep their attestation-derived content and purl-derived type vocabulary until the SBOM backfill regenerates them from the stored scan blobs (see the schema revision note above for the interim marker). Digests with no scan blob at all keep their attestation-derived RELEASE_SBOM seed indefinitely.

HistoryResponse / HistorySummary

Release timeline for a specific (stream, variant) combination.

Field Type Hummingbird External
digest String Manifest list digest Same
oldest_created String Earliest OCI created Same
architectures String[] From OCI manifest list Same
source_commit String From SLSA attestation Omitted — no signed attestations on upstream images
source_repo String From SLSA attestation Omitted — no signed attestations on upstream images

VulnerabilitiesResponse

Vulnerability scan results are identical in structure. The only behavioral difference: ignore_list (CPE-based false-positive suppression) is populated for Hummingbird images but empty for external images, since suppression rules are maintained per Hummingbird image.

Timestamp Fields

The oldest_created field on ImageSummary, Tag, and HistorySummary is the earliest OCI created timestamp across all architectures in the release. All architectures were built at or after this date, making it useful for conservative staleness detection.

The specifications endpoint returns per-architecture data keyed by architecture name. Each architecture’s created field is the direct OCI config root timestamp for that specific architecture.

Deprecation status

The containers repository can mark an image stream with the io.hummingbird-project.deprecated=true OCI label. The catalog exposes this status in two places:

  • Tag.deprecated identifies a release carrying the label.
  • ImageSummary.deprecated_streams lists streams whose current release is deprecated.

Both fields are additive API fields. Older DynamoDB items without these fields are read as active releases with no deprecated streams.

Usage

All tools are built as a single catalog binary with subcommands (api, sync, sync-lambda, scan, scan-lambda, index, index-lambda, enqueue-lambda, metrics, metrics-lambda). The binary is built in the Rust container and CLI subcommands are run in the gitlab-ci container (which provides grype, syft, and other tools). Only make and podman are required.

Sync

# Dry run (print items to stdout)
make container-catalog/sync ARGS="--distro rawhide --dry-run"

# Populate DynamoDB
make container-catalog/sync ARGS="--distro rawhide --table-name <table>"

Sync Lambda

The sync-lambda subcommand runs as an AWS Lambda function triggered by SNS Release events from kubernetes-event-forwarder. It incrementally syncs a single image release to DynamoDB (~22 registry API calls per release vs ~104 for a full sync).

The Lambda:

  1. Decodes gzip+base64 SNS messages
  2. Filters for Succeeded releases targeting the configured Quay.io namespace. Ignores DELETED events and releases with a non-null deletionTimestamp.
  3. Fetches OCI manifest data for the new digest
  4. Writes per-digest items (DETAILS, RELEASE_DETAILS, and a RELEASE_SBOM seed for digests that were never scanned while current — an atomic write-if-absent conditional write, so a sweep or a retried invocation can never overwrite index-normalized content); SBOM#{canonical} items are written by the Index Lambda
  5. Merges into aggregate items (TAGS, HISTORY, OVERVIEW, DIRECTORY)
  6. Fetches README from GitLab for OVERVIEW content (uses README.md for Hummingbird, rawhide/README.md for Rawhide)
  7. Enqueues one index event per release on the IndexQueue — the message carries the image, the canonical just written, the digest, and the manifest-list architectures, everything the Index Lambda needs (it never reads TAGS). A redelivered release re-emits (the known-digest early exit is cheap and the index dedups); historical releases do not emit.

The attestation SBOM fetch remains load-bearing for OVERVIEW licenses and the variant-label fallback — moving licenses off the attestation is follow-up polish.

Registry fetch errors (manifest, SBOM, attestation) propagate as hard failures so the Lambda retries automatically (up to 2 retries with backoff) before sending to the DLQ. GitLab README failures are non-fatal – the existing README is preserved if the fetch fails.

Environment Variable Description
TABLE_NAME DynamoDB table name
INDEX_QUEUE_URL SQS queue URL for index events
DISTRO rawhide or hummingbird
SENTRY_DSN Optional Sentry DSN for error tracking

Index

The index subcommand generates native Syft JSON for all non-superseded image digests and uploads them to S3 for scanner consumption. It reads the image directory and TAGS from DynamoDB, checks S3 for existing objects (dedup via HeadObject), runs syft <image> --platform linux/amd64, gzips the output, and uploads to s3://{bucket}/grype/{image}/{hex}.json.gz.

# Dry run (show what would be uploaded)
make container-catalog/index ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --dry-run"

# Backfill S3 for all images
make container-catalog/index ARGS="--distro hummingbird --table-name <table> --bucket <bucket>"

# Backfill a single image
make container-catalog/index ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --image caddy"

Index Lambda

The index-lambda subcommand runs as an AWS Lambda function triggered by the IndexQueue (SQS, BatchSize: 1, batch-item-failure reporting). The Sync Lambda enqueues one TagReleaseEvent per release after its writes; it is the same event shape and per-event processing structure as the external index — the function is the future unified index, with the blob-key prefixes and the Hermeto-merge gating as per-deployment configuration. It generates the native Syft JSON for scanner consumption and owns the SBOM items.

The Lambda:

  1. Parses TagReleaseEvent records (image, canonicals, digest, architectures); a record that fails to parse or process is reported as an SQS batch-item failure and retried individually by the queue, redriving to the IndexDLQ after 3 attempts.
  2. Checks S3 for existing objects (HeadObject dedup by digest). On a hit, it heals any canonical whose SBOM# item is missing (canonical rename, DLQ replay) by rebuilding it from the persisted SPDX record — RELEASE_SBOM#{hex} is only written when absent, so a recovered primary-arch-only item cannot downgrade a multi-arch item. Blobs written by the catalog index CLI carry no persisted SPDX; the recovery skips those with a warning (the SBOM backfill is their designated repair).
  3. Resolves the architecture list and the per-arch Hermeto attestations from the manifest list over the public registry (no IAM). A missing per-arch attestation degrades that arch to syft-only; a manifest-list failure falls back to the event’s recorded architectures.
  4. Runs syft <image>@<digest> --platform linux/{arch} for every architecture, bounded by the invocation deadline: the primary arch (amd64 when present, otherwise the first) runs with dual output (syft-json + spdx-json — its spdx is the persisted recovery input) and is a hard failure; the remaining arches run native-only, and their failures degrade the SBOM to primary-arch-only.
  5. Merges Hermeto build-only entries per arch (see SBOM content sources).
  6. Re-verifies every canonical against the registry after all arch scans, immediately before the writes: canonicals that moved to a newer digest are dropped, a digest no canonical references anymore is discarded entirely (no items, no upload), and a failed verification fails the record after the writes so the retry heals the skipped canonical.
  7. Writes SBOM#{canonical} per still-current canonical plus RELEASE_SBOM#{hex} to DynamoDB, then the primary-arch SPDX to s3://{bucket}/sbom/{image}/{hex}.json.gz with primary-arch object metadata (the recovery input for step 2), then the gzipped syft JSON to s3://{bucket}/grype/{image}/{hex}.json.gz — the last write and the completion marker that triggers the Scan Lambda via S3→SQS and arms the dedup key.

TAGS is never read — the event carries everything the function needs, and canonical identity is re-resolved against the registry.

Failures are retried by the queue (up to 3 attempts) before the IndexDLQ. S3 gaps can be backfilled with the catalog index CLI (it writes S3 objects only); SBOM item gaps are healed by the already-indexed recovery on the next event or DLQ redrive, or by the SBOM backfill.

Environment Variable Description
SCAN_DATA_BUCKET S3 bucket for scanner data
TABLE_NAME DynamoDB table name
SCAN_KEY_PREFIX Scan-blob key prefix (default grype/)
SBOM_KEY_PREFIX SPDX-record key prefix (default sbom/)
DISTRO rawhide or hummingbird
SENTRY_DSN Optional Sentry DSN for error tracking

Scan

The scan subcommand reads image listings and tags from DynamoDB and runs Grype against each image using native Syft JSON from S3 (--bucket is required). Results include a first_seen timestamp per CVE, tracked at the group+variant+stream level and carried across releases for SLI computation.

Tagged scans read native Syft JSON from S3 (grype/{image}/{hex}.json.gz), matching the lambda pipeline. Historic releases (--scope all) read the same S3 objects; digests whose object is missing are skipped with a warning.

# Dry run (print items to stdout)
make container-catalog/scan ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --dry-run"

# Scan and write to DynamoDB (purge stale vuln data first, implies --scope=all)
make container-catalog/scan ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --purge"

# Scan only non-superseded (current) tags
make container-catalog/scan ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --scope non-superseded"

# Scan all releases including historic (tagless) releases
make container-catalog/scan ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --scope all"

# Scan a single image
make container-catalog/scan ARGS="--distro hummingbird --table-name <table> --bucket <bucket> --image caddy --dry-run"

Scan Lambda

The scan-lambda subcommand runs as an AWS Lambda function triggered by SQS messages. Two paths feed the ScanQueue for Hummingbird images, and two parallel paths for external images:

  1. Real-time (S3 event notification): When the Index Lambda uploads a new Syft JSON to S3, an s3:ObjectCreated event (filtered on grype/ prefix) is sent directly to SQS
  2. Hourly (Enqueue Lambda): Fans out all non-superseded digests when the Grype vulnerability database has been updated, sending {"bucket": "...", "key": "grype/{image}/{hex}.json.gz"} messages
  3. External real-time: When the External Index Lambda uploads Syft JSON to grype-external/{registry}/{hex}.json.gz, the same ScanQueue receives the event
  4. External hourly: The Enqueue Lambda also fans out external re-scans using grype-external/{registry}/{hex}.json.gz keys

The Lambda accepts both S3 event notification JSON and direct {"bucket", "key"} messages. It detects the S3 key prefix to dispatch between two code paths:

  • grype/ prefix → Hummingbird path: writes IMAGE#{name}/VULNERABILITIES#{canonical} and IMAGE#{name}/RELEASE_VULNERABILITIES#{hex}
  • grype-external/ prefix → external path: parses (registry, hex) from the key, then writes EXTERNAL#{registry}/VULNERABILITIES#{canonical} and EXTERNAL#{registry}/RELEASE_VULNERABILITIES#{hex} using the same Grype scan and first_seen tracking logic as Hummingbird

For each message the Lambda:

  1. Downloads and decompresses the native Syft JSON from S3
  2. Runs Grype on the raw bytes
  3. Looks up all canonical tags matching the digest from the TAGS item
  4. Writes VULNERABILITIES#{canonical} for each matching tag (with first_seen tracking) and RELEASE_VULNERABILITIES#{hex} once per digest

Processing is per-digest: a single Syft JSON serves all canonicals sharing that digest, avoiding redundant Grype invocations.

The Lambda downloads and hydrates the Grype DB on the first handler invocation of each cold start (cached in /tmp for warm invocations), processes one message per batch, and reports partial batch failures so failed records return to the queue.

Concurrency is capped at 100 concurrent invocations (ScalingConfig on the SQS event source). Every Grype DB update triggers a full-catalog rescan fan-out of several hundred scans, and without a cap the event source scales with that backlog — measured at ~490 concurrent executions, about half the account’s shared 1000-execution limit, with each cold container downloading the multi-GB Grype DB. The cap keeps one function at ~10% of the account budget and amortizes the DB setup across warm invocations. The template deploys to both the hummingbird and rawhide stacks, so the theoretical simultaneous maximum is 2 × 100 from the scan Lambdas plus 2 × 5 from the external index Lambdas — 210 of the account limit.

Environment Variable Description
TABLE_NAME DynamoDB table name
DISTRO rawhide or hummingbird
SENTRY_DSN Optional Sentry DSN for error tracking

Enqueue Lambda

The enqueue-lambda subcommand runs hourly via EventBridge Schedule. On each invocation it performs a lightweight HTTP GET of the public Grype DB listing (latest.json, ~200 bytes) and compares the built timestamp against the stored CATALOG/LAST_FULL_SCAN_DB item in DynamoDB. If the DB hasn’t changed, it returns early (~23 of 24 hourly invocations short-circuit). When an update is detected it runs two fan-out loops:

  1. Hummingbird images: reads the image directory and all TAGS items, deduplicates by digest, and sends one SQS message per unique digest. Messages use {"bucket": "...", "key": "grype/{image}/{hex}.json.gz"}.
  2. External images: reads the external-images config from DynamoDB (CATALOG/EXTERNAL_CONFIG), then for each configured registry reads EXTERNAL#{registry}/TAGS and fans out non-superseded digests with grype-external/{registry}/{hex}.json.gz keys. If no TAGS item exists (first run, before External Sync Lambda), the registry is skipped. A malformed or missing EXTERNAL_CONFIG degrades gracefully — a warning is logged and the Hummingbird fan-out already sent is unaffected.

Both loops use the same SendMessageBatch batching and !superseded digest filter.

Environment Variable Description
TABLE_NAME DynamoDB table name
DISTRO rawhide or hummingbird
SCAN_QUEUE_URL SQS queue URL for scan messages
SCAN_DATA_BUCKET S3 bucket for scanner data
GRYPE_DB_LATEST_URL Grype DB listing URL (has sensible default)
SENTRY_DSN Optional Sentry DSN for error tracking

Metrics

The metrics subcommand performs a one-shot read of all non-superseded vulnerability data from DynamoDB and writes the catalog-wide vulnerability aggregate to DynamoDB (PK=CATALOG, SK=VULNERABILITIES).

make container-catalog/metrics ARGS="--table-name <table>"

Metrics Lambda

The metrics-lambda subcommand runs as a DynamoDB Stream-triggered Lambda that writes a catalog-wide vulnerability aggregate to DynamoDB (served by GET /v1/vulnerabilities).

How It Works

The Lambda is triggered by DynamoDB Stream events filtered on VULNERABILITIES# and TAGS changes, with a 60-second batching window and reserved concurrency of 1 (single instance). It maintains an in-memory active CVE table across warm invocations:

  • Cold start: Reads CATALOG/DIRECTORY, all TAGS, and all non-superseded VULNERABILITIES# items from DynamoDB to build the full table (~2-3s at 10000 tags)
  • Warm invocations: Incrementally updates the table from stream event keys (~50-100 GetItem calls per batch)
  • After each invocation: Recomputes the aggregate

Stream events for EXTERNAL# PKs (external images) are intentionally excluded from the aggregate. The incremental_update path filters on pk.starts_with("IMAGE#") so that external-image VULNERABILITIES# stream events do not pollute the Hummingbird-only CATALOG/VULNERABILITIES item. The GET /v1/vulnerabilities endpoint reflects only Hummingbird CVE data.

Environment Variable Description
TABLE_NAME DynamoDB table name
DISTRO rawhide or hummingbird
SENTRY_DSN Optional Sentry DSN

Deployment

make container-catalog/build
make container-catalog/deploy

External Images

The external images feature enables CVE comparison between Hummingbird and external image sources (e.g. standard upstream registries). External image data is exposed under the /v1/external-images/ namespace, which is fully additive — existing /v1/images/ clients are unaffected.

Overview

External images share the same DynamoDB table as Hummingbird images but use an EXTERNAL#{registry} PK prefix instead of IMAGE#{name}, where {registry} is the full registry pull reference (e.g. docker.io/library/nginx). The same response types, SK patterns, and API conventions apply: tags, details, SBOM, vulnerabilities, history, and release snapshots all work identically. Provenance fields (source_repo, source_commit, containerfile, slsa_level, build_system) are empty strings for external images — they are not available from upstream registries.

The /v1/external-images/config endpoint returns the config that maps Hummingbird images to their external sources. The join key for a given image detail page (IMAGE#{repository}) is the repository on each tag entry (resolved from the source-level default when not set per-tag). Clients filter tag entries by repository, then match stream and variant values against the page’s stream/variant selection to construct the /v1/external-images/{percent-encoded-registry}/… URLs (registry refs containing / must be percent-encoded in the URL path).

Tag-based discovery and re-verification (resolve_digest — HEAD manifest by tag, used by both External Sync and External Index) goes directly to registry-1.docker.io with anonymous tokens from auth.docker.io (service=registry.docker.io). HEAD manifest requests are free against Docker Hub’s pull limit (100 manifest GETs per hour per IP, verified empirically), return docker-content-digest, and always resolve to Docker Hub’s current view of the tag. ratelimit-remaining from each HEAD response is logged as a numeric budget gauge.

Digest-pinned architecture fetches (fetch_details — manifest GETs by digest) and syft image pulls both route through mirror.gcr.io first, with a direct-docker.io fallback on any failure. Digest-pinned requests are content-addressed and cannot be stale, so the mirror is a safe first attempt; the fallback covers mirror ingestion lag on a freshly discovered digest. In Lambda each syft attempt runs under a per-call budget derived from the invocation deadline; in CLI mode syft runs until it exits or the operator interrupts it. Stored data uses the canonical docker.io/... registry name; other registries are accessed directly.

Configuration Format

The external-images configuration is stored in DynamoDB at CATALOG/EXTERNAL_CONFIG and served at GET /v1/external-images/config. The JSON config is maintained outside this repo (e.g. in the infrastructure repo) and applied to DynamoDB via the catalog config set CLI command.

The config is a flat list of sources. Each source maps registry tags to (repository, stream, variant) triples — the same concepts Hummingbird uses for canonical determination and mark_superseded. Stream and repository values are whatever the corresponding Hummingbird image uses. Variant names use Hummingbird names where an equivalent exists (e.g. builder for upstream dev images); upstream-only variants like slim or alpine keep their upstream names.

Each tag carries its own repository — the Hummingbird repository the tag’s comparison belongs to. This allows tags from the same upstream registry to join different Hummingbird repositories (e.g. docker.io/library/caddy tags 2 → repository caddy and 2-builder → repository xcaddy):

{
  "sources": [
    {
      "registry": "docker.io/library/caddy",
      "tags": [
        {
          "tag": "2",
          "repository": "caddy",
          "stream": "2",
          "variant": "default"
        },
        {
          "tag": "2-builder",
          "repository": "xcaddy",
          "stream": "2",
          "variant": "builder"
        }
      ],
      "variants": [
        {
          "name": "default",
          "description": "Caddy server",
          "base": "default",
          "builder": false,
          "fips": false
        },
        {
          "name": "builder",
          "description": "Build image with xcaddy",
          "base": "default",
          "builder": true,
          "fips": false
        }
      ]
    }
  ]
}

Every tag must carry a repository — the per-tag form is the only shape. The older source-level repository field (a default inherited by all tags) was transitional and has been removed: configs are parsed with deny_unknown_fields, so a source-level repository is now a parse error. The containers aggregation emits per-tag repository on every tag.

Stream Assignment

External image stream values follow the same rules as Hummingbird images (see Choosing a Stream Value in the containers repo). Key rules for external image config:

  • If the Hummingbird image uses numbered streams (e.g. "1.27", "3.14"), external image tags must map to the same stream values. A Docker Hub latest tag maps to the current numbered stream — it is never a separate "latest" stream alongside numbered ones.
  • Use "latest" as a stream value only for sources where no meaningful version series exists (rolling releases, date-based versions).
  • The assign_canonicals function groups tags by (stream, variant, digest). Within each group, the most semver-specific tag becomes canonical. When latest and 1.27 both map to stream "1.27" and resolve to the same digest, 1.27 wins by specificity.

Variant values share the Hummingbird vocabulary where equivalents exist: use "builder" for upstream dev images that add a shell and package manager (e.g. Chainguard’s latest-dev), and "default" for plain runtime images. Upstream-only variants with no Hummingbird equivalent (e.g. "slim", "alpine" on Docker Hub) keep their upstream names. CVE data for all tracked variants is served the same way, so clients can present them however fits.

To add a new image or source, update the config JSON and run catalog config set --file <path> --table-name <table> to apply the change to DynamoDB (no Lambda redeploy needed).

External Release Lambda

Triggered by EventBridge on a schedule (every 6 hours). Reads the external-images config from DynamoDB and sends one SQS message per configured registry to ExternalSyncQueue via send_batch. Sends unconditionally — change detection is handled downstream by External Sync Lambda.

The Lambda is lightweight: one DynamoDB GetItem and one or two SQS SendMessageBatch calls per invocation. No registry calls, no S3 access.

Environment Variable Description
TABLE_NAME DynamoDB table name
DISTRO hummingbird (no-op on rawhide)
EXTERNAL_SYNC_QUEUE_URL SQS queue URL for per-registry messages
SENTRY_DSN Optional Sentry DSN for error tracking

External Sync Lambda

Triggered by ExternalSyncQueue (SQS, BatchSize: 1). Each invocation processes one registry reference — identical scope to SyncFunction processing one Konflux release.

  1. Resolves all configured tags to digests via registry HEAD requests. Digests are validated (sha256:[0-9a-f]{64}) before use. Attestation manifests (platform.architecture = "unknown") are filtered out. All configured tags must resolve successfully; partial resolution aborts the write to prevent silently shrinking the TAGS item.
  2. Compares with current EXTERNAL#{registry}/TAGS in DynamoDB; early-returns if no digests changed (no-op on most invocations).
  3. Groups tags by digest within each (stream, variant) pair; picks canonical by semver specificity (1.27.2 beats 1.27).
  4. Writes DETAILS, RELEASE_DETAILS, HISTORY, OVERVIEW, and EXTERNAL_DIRECTORY to DynamoDB.
  5. Emits one SQS message per non-superseded digest to ExternalIndexQueue. Emission is unconditional rather than change-detection based: the index Lambda’s S3 existence check makes an event for an already-indexed digest a cheap no-op, and unconditional emission restores the self-healing of the old per-registry topology — canonical renames with unchanged digests get their SBOM records backfilled on the next sync write. When several canonicals resolve to the same digest, they share one event and one scan. Each message carries everything External Index Lambda needs: registry, canonicals, digest, architectures.
  6. Writes TAGS last so it serves as a completion marker — a crashed invocation will be retried in full, and an SQS send failure in step 5 is retried without the early-exit firing (TAGS still holds the old state).

The moment sync observes a changed digest is the release event for an external image — sync stands where the Hummingbird build system stands.

Environment Variable Description
TABLE_NAME DynamoDB table name
DISTRO rawhide or hummingbird
EXTERNAL_INDEX_QUEUE_URL SQS queue URL for per-tag index events
SENTRY_DSN Optional Sentry DSN for error tracking

External Index Lambda

Triggered by ExternalIndexQueue (SQS, BatchSize: 1). Each invocation processes one digest from a release event emitted by External Sync Lambda. The event carries everything needed — registry, canonicals, digest, architectures — so TAGS is not read, eliminating the first-run race between the two lambdas.

  1. Validates the event at the queue boundary (registry, digest, canonicals, architectures). Checks S3 for an existing grype-external/{registry}/{hex}.json.gz object; skips if already present (idempotent, mirrors IndexFunction). If the S3 object exists but a canonical’s DynamoDB SBOM item is missing (e.g. a canonical rename after the last syft run), the SBOM is backfilled from the persisted SPDX at sbom-external/{registry}/{hex}.json.gz — one scan serves every canonical of the digest.
  2. Runs Syft with dual output for the primary architecture (amd64 when present, otherwise the first architecture of the event — some upstream images are single-arch non-amd64): syft-json for Grype, spdx-json for the SBOM. Then one spdx-json run per remaining architecture; one ArchSbom per arch is stored in the SbomResponse.
  3. Re-verifies the registry digest has not changed during the Syft run. If the digest changed, the output is discarded to avoid indexing a stale digest. SBOM writes happen only after this verification.
  4. Writes one SBOM#{canonical} per canonical of the digest (all from this single scan) plus RELEASE_SBOM#{hex} to DynamoDB.
  5. Uploads the gzipped Syft JSON to S3; the S3 event notification triggers the Scan Lambda via SQS. SPDX is stored separately at sbom-external/{registry}/{hex}.json.gz (different prefix to avoid triggering a spurious scan).

Each invocation is bounded to one digest’s architecture matrix (minutes, not the whole registry), so timeout and OOM blast radius are per-digest rather than per-registry. DLQ entries are single-digest releases — replayable and meaningful. DLQ entries are not retried automatically: recover via SQS DLQ redrive, or wait for the registry’s next change (any change re-emits every non-superseded digest).

Environment Variable Description
TABLE_NAME DynamoDB table name
SCAN_DATA_BUCKET S3 bucket for scanner data
DISTRO rawhide or hummingbird
SENTRY_DSN Optional Sentry DSN for error tracking

Data Freshness and Known Asymmetries

  • External images are polled every 6 hours. Grype DB re-scans run hourly, same as Hummingbird images.
  • The CATALOG/VULNERABILITIES aggregate (GET /v1/vulnerabilities) reflects only Hummingbird CVE data. There is no external-images catalog-wide CVE aggregate.
  • Sources that offer only a latest tag and have no numbered version series will always have "latest" as their canonical.

For per-field availability differences between the two namespaces, see the response type tables in the API Endpoints section.

Docker Hub Limits and mirror.gcr.io Behavior

Reference data for the routing decisions in the External Sync and External Index Lambdas (measured 2026-11-10).

Docker Hub metering

Only manifest GETs count against the pull limit — one unit each (index and platform manifests separately). HEAD manifest requests, blob HEAD/GETs, auth token requests, and tag listing GETs are unmetered.

Access type Limit (anonymous) Notes
Manifest GETs 100 / hour / IPv4 (or IPv6 /64) ratelimit-limit: 100;w=3600 in headers
Manifest HEADs Unmetered Still returns docker-content-digest
Blob GETs / HEADs Unmetered Measured; Docker docs do not confirm
Auth token fetches Unmetered
Tag listing GETs Unmetered Full listing in one response; paginated via ?n=&last=; mirror.gcr.io serves the same endpoint as its cache inventory

The registry API endpoint is registry-1.docker.io (the bare docker.io host redirects to the Docker website). Anonymous tokens are issued by auth.docker.io with service=registry.docker.io and per-repository scope; they are valid for approximately 5 minutes. ratelimit-remaining is present on HEAD responses; resolve_digest logs it as a budget gauge.

Routing policy

Request Route Reason
resolve_digest (HEAD by tag) registry-1.docker.io direct Tags are mutable; mirror can serve stale. HEADs are unmetered.
fetch_details (GET by digest) mirror.gcr.io → docker.io fallback Content-addressed — cannot be stale. Mirror-first; falls back direct on any failure.
Syft image pulls mirror.gcr.io → docker.io fallback Mirror-first; retries direct on any failure.

mirror.gcr.io receives all digest-addressed traffic from this service as the first attempt.

Routing requirements

The routing design is governed by the following requirements:

  • R1 — tag resolution is authoritative: resolve_digest HEADs go directly to registry-1.docker.io with anonymous auth.docker.io tokens. Tags are mutable; HEAD manifest requests are unmetered and always return Docker Hub’s current view of the tag.
  • R2 — digest-addressed fetches go mirror-first with direct fallback: fetch_details (manifest list, per-arch manifests, config blobs) and the @digest-pinned syft pulls both try mirror.gcr.io first. Content-addressed fetches cannot be stale — only missing — so the mirror is safe; the direct fallback covers mirror ingestion lag on a freshly discovered digest (the window between direct tag resolution and the mirror ingesting the new object). The fallback costs ~1 + archs metered manifest GETs, only on a mirror miss; when the mirror serves the request the metered budget stays at zero.
  • R3 — mirror failures fall back to docker.io: any failure on a mirror GET retries the same request directly against docker.io — both for syft pulls (via run_syft_outputs in scanner.rs) and for fetch_details metadata GETs (via routed_get in external_sync_lambda.rs). Reliability is the reason; error-classification by response body would be brittle. A fallback costs approximately 2–3 metered manifest GETs for a syft pull (blobs are unmetered) or ~1 + archs GETs for a fetch_details miss; the fallback granularity for a pull is the whole ref since syft fetches from a single reference. In Lambda each attempt runs under a per-call budget derived from the invocation deadline (deadline − now − 60 s headroom for post-scan work); a zero remaining budget returns the error before spawning. In CLI mode syft runs until it exits or the operator interrupts it — Ctrl-C causes kill_on_drop to terminate the child and TempDirGuard to remove its temp dir. The stale sweep uses the owner PID as the garbage authority: a syft temp dir is removed when its owner process has exited.
  • R4 — Accept-set consistency: resolve_digest HEADs include both index and platform manifest media types (application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.index.v1+json, plus the single-manifest types) so a tag resolves to the index digest rather than a platform-specific one. The same Accept set is used for fetch_details GETs via the mirror.
  • R5 — bounded concurrency against the mirror: the mirror’s anonymous limiter escalates to persistent per-IP 429s under sustained load, so pull fan-out must stay bounded. Partially holds via External Index Lambda MaximumConcurrency: 5.
  • R6 — ratelimit-remaining budget gauge: resolve_digest logs the ratelimit-remaining header from each Docker Hub HEAD response as a numeric structured field (remaining), including from error responses (e.g. 429) where remaining=0 is most actionable. The header is returned on HEAD responses at no additional cost. The header value may carry a window suffix (100;w=3600) — only the numeric prefix is parsed.

mirror.gcr.io behavior

  • Demand-driven cache: objects ingest only when requested; each object (tag mapping, manifest, blob) warms independently.
  • Digest-addressed content: served cold (fetched from Docker Hub on miss). Whole-image cold pulls work end-to-end once warmed.
  • Blob ingestion is async and flaky: a pull can fail with BLOB_UNKNOWN for layers that ingest over subsequent requests (observed taking days). Retries serve as cache warming.
  • Eviction: images not requested for approximately 5 days are removed. Cached does not mean stable.
  • Rate limiting: burst 429s after approximately 10 rapid manifest requests, escalating to a persistent per-IP throttle under sustained load. Bounds pull fan-out concurrency.
  • HEAD is unreliable as a cache probe: can 404 for content that is cached and servable. GET /v2/{repo}/tags/list lists cached tag mappings only — digest-addressed content can be served while its tag is unlisted.

Configuration

catalog sync

Argument Description
--distro rawhide or hummingbird
--table-name DynamoDB table name
--purge Delete all items before writing
--cache-dir Cache directory (auto-detected)
--image Sync only a specific repo
--legacy-discovery Use GitLab-based repo discovery

catalog index

Argument Description
--distro rawhide or hummingbird
--table-name DynamoDB table name (for image/tag discovery)
--bucket S3 bucket for scanner data
--dry-run Print what would be uploaded without uploading
--image Index only a specific image
--parallel Number of concurrent operations (default: 2)

catalog scan

Argument Description
--distro rawhide or hummingbird
--table-name DynamoDB table name (required)
--bucket S3 bucket with native Syft JSON (required)
--scope non-superseded, tags (default), or all
--dry-run Print items without writing
--purge Purge vuln data before writing (implies --scope all)
--parallel Number of concurrent scans (default: 4)
--image Scan only a specific image
--tag Scan only a specific tag (requires --image)

catalog config

catalog config set --file <path> --table-name <table> reads the external-images JSON config and writes it to the DynamoDB item CATALOG/EXTERNAL_CONFIG. Run once on initial setup and after each config change. No Lambda redeploy is needed — all External* Lambdas read config from DynamoDB at invocation time.

Argument Description
--table-name DynamoDB table name
--file Path to external-images JSON file

SAM Parameters

Parameter Description
Distro rawhide or hummingbird
CacheEnabled Enable CloudFront caching
CatalogDomainName Catalog web UI domain
ApiDomainName API domain
HostedZoneId Route53 hosted zone
CorsOrigins Comma-separated CORS origins (default *)
SnsTopicArn SNS topic ARN for Release events (enables sync/index/external Lambdas)

The External Release, Sync, and Index Lambdas are all conditioned on HasSnsTopicArn (a feature flag historically tied to the Release-events topic) and are only deployed for the hummingbird stack. The external chain itself is queue-based: the EXTERNAL_SYNC_QUEUE_URL and EXTERNAL_INDEX_QUEUE_URL environment variables are set automatically from the queue resources defined in the same SAM template.

Frontend

The catalog web UI is a Lit 3 SPA (Web Components) with Tailwind CSS, built per-distro with Vite. Source is in container-catalog/frontend/.

The image detail view includes an External tab (gated behind VITE_VULNERABILITIES_ENABLED) that compares Hummingbird images against their external counterparts. It shows a summary card with CVE and runtime package count deltas, side-by-side severity breakdowns, a categorized CVE table (only-in-upstream / only-in-Hummingbird / shared), and an SBOM package diff.

Only make and podman are required (no local Node.js needed). Defaults from .envrc.defaults are applied automatically.

# Install dependencies
make container-catalog/frontend/setup

# Development server at http://localhost:5173
make container-catalog/frontend/dev

# Production build
make container-catalog/frontend/build

Host variants (*-host) run without podman (for CI or local Node.js).

Frontend Build Variables

Variable Description
VITE_API_URL API base URL for the distro
VITE_DISTRO rawhide or hummingbird
VITE_DISTRO_LABEL Display label for current distro
VITE_OTHER_CATALOG_URL URL of the other distro’s catalog (optional, hides link if unset)
VITE_OTHER_DISTRO_LABEL Display label for other distro (optional)
VITE_VULNERABILITIES_ENABLED Show vulnerabilities and external comparison tabs

Development

# Backend
cargo test                    # Run tests
cargo clippy --all-targets   # Lint
cargo fmt                     # Format

# Frontend (host variants, requires local Node.js)
cd container-catalog/frontend
npm run typecheck             # Type check
npm run build                 # Production build

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

1 - Container Catalog Design Decisions

Design Decision Registry (DDR) for container-catalog — every major design choice, the alternatives considered, and why the chosen approach won. For operational usage, see Container Catalog.

DDR-1: Historical RELEASE_SBOM writer survives the SBOM cutover as a write-if-absent seed

Decision: When the index function takes over SBOM-item writes, sync’s build_release_sbom_item keeps its RELEASE_SBOM#{hex} construction, written via an atomic write-if-absent conditional write (put_content_versioned with attribute_not_exists(ver) — every post-cutover writer stamps ver, so the condition blocks any rewrite of normalized content); the historical branch of merge_release writes only digest-keyed items; SBOM#{canonical} becomes index-exclusive.

Context: The SBOM cutover (W1 MR2) moves SBOM-item writes from sync to index. Index only writes for digests current in TAGS; the SBOM backfill enumerates scan blobs. Digests that were never scanned while current therefore lose every writer. Production census (2026-11-11, 10 images, 10,697 history digests, vuln-item presence as the scan/blob proxy): 228 digests (2.1%) have an SBOM item but were never scanned — 225 from 2026-04, before the scan pipeline wrote blobs, plus ~1/month of new misses (events raced out of TAGS, dropped events). The registry tagging model (unique sha256-{hex}/timestamp tags per build; ~a dozen moving plain version tags) means every rebuild supersedes the previous digest out of TAGS, so this population accrues slowly but indefinitely. The only code path that can serve these digests is the catalog sync CLI’s historical sweep — the production sync Lambda processes only each event’s release and never sweeps. The sweep is an on-demand repair/repopulation tool (“Full DynamoDB population”, --purge).

Alternatives: (a) Accept the gap — delete the RELEASE_SBOM construction outright; SBOM items become exclusively the index/backfill domain; the frozen 225 keep their existing items, new misses get history and details but no SBOM, documented as a known gap. (b) Keep an unconditional retained write — preserve today’s behavior for the historical branch unchanged. (c) Extend the backfill to synthesize RELEASE_SBOM from attestations for no-blob digests.

Rationale: (a) rejected because a repair tool with a measured blind spot is an operational footgun: after an incident or data loss, a catalog sync run would leave SBOM holes nothing else can fill (no blob → the backfill enumerates blobs and skips them; no event → index never sees them). (b) rejected because the sweep population is dominated by ex-current, blob-backed digests that the SBOM backfill normalizes to scan-derived content; sync’s writes are unconditional (batch_write; put_content_versioned has no content comparison), so every CLI run would overwrite blob-derived items back to attestation-derived content, silently undoing the backfill. (c) rejected because the backfill is one-off by design — it cannot cover future misses, only the current cohort. The write-if-absent seed keeps the repair tool complete for exactly the population only it can reach, while the conditional write makes it converge with the backfill instead of fighting it: sync seeds once (attestation-derived, today’s field spellings — consistent with the accepted mixed-vocabulary story for no-blob digests), index and the backfill own the final content for blob-backed digests, and a CLI run never rewrites an item that already exists. Zero new IAM (one DDB read); ~20 lines retained plus the guard, confined to a CLI-only code path.

DDR-2: Index invocation converges on the queue-decoupled pattern

Decision: The internal index function drops its SNS Release subscription and consumes a queue of tag-release events; sync performs its DynamoDB writes and then enqueues one event per release canonical, using the shared TagReleaseEvent shape (the promoted ExternalTagReleaseEvent). The function is shaped as the future unified index — the same per-event processing structure as the external index, with the event shape and blob-key prefixes already shared — so the external plane’s unification (retiring external-index-lambda into this function) remains a small, well-bounded change.

Context: The internal index was SNS-triggered like sync, which forced it to read TAGS to learn a release’s canonicals — introducing the sync-fast/index-slow race (TAGS-absent → retry → DLQ) and requiring per-image error aggregation inside one invocation. The external plane had already solved invocation decoupling: its sync resolves tags, writes TAGS, then enqueues per-digest events to an index queue whose batch-item-failure semantics provide per-record retry for free. Downstream of sync’s writes the two planes are the same pattern; only the chain’s head differs (the internal producer is the near-realtime bus event, the external one a 6-hour poll).

Alternatives: (a) Keep the SNS trigger and heal the TAGS race with retries — the race class stays, one slow image can block the record, and the two index functions keep divergent shapes. (b) Unify into a single shared deployment rather than two deployments of one function — rejected for blast-radius isolation: a bad deployment would take out both planes at once. (c) Defer the convergence to the external-plane MR — rejected: every week of divergence adds code that both index functions must carry, and the queue convergence was already decided for the internal plane on its own merits.

Rationale: Queue decoupling deletes the TAGS-race class by construction: the event is emitted after the writes it depends on and carries everything the index needs (canonicals, digest, architectures), so the index never reads TAGS and canonical identity is re-resolved against the registry. SQS batch-item failures replace hand-rolled per-image aggregation with the platform’s own per-record retry. Sync redelivery is harmless — a duplicate event hits the index’s dedup skip and flows into the recovery path, which is the recovery’s designed purpose. The canonical re-verification stays regardless of ordering: the moved-digest mid-scan race is real in any invocation shape. Shaping the internal index as the unified function now (shared event type, external’s processing structure, env-configured prefixes) keeps MR4 small: point the external queue at the function and delete external-index-lambda, plus four parameterizations the planes still differ on — the DDB partition key (IMAGE# vs EXTERNAL#), the pull-reference source (config.pull_registry vs the raw registry reference), the arch source (manifest list via fetch_arch_attestations vs the event’s architectures), and the Hermeto-merge gating (classify_by_hermeto from DISTRO vs none). The event shape and the blob-key prefixes are already zero-code.