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 withfirst_seentracking 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.gzfor Hummingbird andgrype-external/{registry}/{digest_hex}.json.gzfor external images; SPDX SBOMs are stored atsbom/{image}/{digest_hex}.json.gzfor Hummingbird andsbom-external/{registry}/{digest_hex}.json.gzfor external images — thesbom*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/andgrype-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 (
--bucketrequired); 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.deprecatedidentifies a release carrying the label.ImageSummary.deprecated_streamslists 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:
- Decodes gzip+base64 SNS messages
- Filters for Succeeded releases targeting the configured Quay.io namespace.
Ignores
DELETEDevents and releases with a non-nulldeletionTimestamp. - Fetches OCI manifest data for the new digest
- 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 - Merges into aggregate items (TAGS, HISTORY, OVERVIEW, DIRECTORY)
- Fetches README from GitLab for OVERVIEW content (uses
README.mdfor Hummingbird,rawhide/README.mdfor Rawhide) - 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:
- Parses
TagReleaseEventrecords (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. - 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 thecatalog indexCLI carry no persisted SPDX; the recovery skips those with a warning (the SBOM backfill is their designated repair). - 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.
- 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. - Merges Hermeto build-only entries per arch (see SBOM content sources).
- 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.
- Writes
SBOM#{canonical}per still-current canonical plusRELEASE_SBOM#{hex}to DynamoDB, then the primary-arch SPDX tos3://{bucket}/sbom/{image}/{hex}.json.gzwithprimary-archobject metadata (the recovery input for step 2), then the gzipped syft JSON tos3://{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:
- Real-time (S3 event notification): When the Index Lambda uploads a new
Syft JSON to S3, an
s3:ObjectCreatedevent (filtered ongrype/prefix) is sent directly to SQS - 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 - External real-time: When the External Index Lambda uploads Syft JSON
to
grype-external/{registry}/{hex}.json.gz, the same ScanQueue receives the event - External hourly: The Enqueue Lambda also fans out external re-scans
using
grype-external/{registry}/{hex}.json.gzkeys
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: writesIMAGE#{name}/VULNERABILITIES#{canonical}andIMAGE#{name}/RELEASE_VULNERABILITIES#{hex}grype-external/prefix → external path: parses(registry, hex)from the key, then writesEXTERNAL#{registry}/VULNERABILITIES#{canonical}andEXTERNAL#{registry}/RELEASE_VULNERABILITIES#{hex}using the same Grype scan andfirst_seentracking logic as Hummingbird
For each message the Lambda:
- Downloads and decompresses the native Syft JSON from S3
- Runs Grype on the raw bytes
- Looks up all canonical tags matching the digest from the TAGS item
- Writes
VULNERABILITIES#{canonical}for each matching tag (withfirst_seentracking) andRELEASE_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:
- 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"}. - External images: reads the external-images config from DynamoDB
(
CATALOG/EXTERNAL_CONFIG), then for each configured registry readsEXTERNAL#{registry}/TAGSand fans out non-superseded digests withgrype-external/{registry}/{hex}.json.gzkeys. If no TAGS item exists (first run, before External Sync Lambda), the registry is skipped. A malformed or missingEXTERNAL_CONFIGdegrades 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, allTAGS, and all non-supersededVULNERABILITIES#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 Hublatesttag 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_canonicalsfunction groups tags by(stream, variant, digest). Within each group, the most semver-specific tag becomes canonical. Whenlatestand1.27both map to stream"1.27"and resolve to the same digest,1.27wins 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.
- 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. - Compares with current
EXTERNAL#{registry}/TAGSin DynamoDB; early-returns if no digests changed (no-op on most invocations). - Groups tags by digest within each
(stream, variant)pair; picks canonical by semver specificity (1.27.2beats1.27). - Writes DETAILS, RELEASE_DETAILS, HISTORY, OVERVIEW, and EXTERNAL_DIRECTORY to DynamoDB.
- 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. - 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.
- Validates the event at the queue boundary (registry, digest, canonicals,
architectures). Checks S3 for an existing
grype-external/{registry}/{hex}.json.gzobject; 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 atsbom-external/{registry}/{hex}.json.gz— one scan serves every canonical of the digest. - Runs Syft with dual output for the primary architecture (
amd64when present, otherwise the first architecture of the event — some upstream images are single-arch non-amd64):syft-jsonfor Grype,spdx-jsonfor the SBOM. Then onespdx-jsonrun per remaining architecture; oneArchSbomper arch is stored in theSbomResponse. - 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.
- Writes one
SBOM#{canonical}per canonical of the digest (all from this single scan) plusRELEASE_SBOM#{hex}to DynamoDB. - 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/VULNERABILITIESaggregate (GET /v1/vulnerabilities) reflects only Hummingbird CVE data. There is no external-images catalog-wide CVE aggregate. - Sources that offer only a
latesttag 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_digestHEADs go directly toregistry-1.docker.iowith anonymousauth.docker.iotokens. Tags are mutable;HEADmanifest 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 trymirror.gcr.iofirst. 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 (viarun_syft_outputsinscanner.rs) and forfetch_detailsmetadata GETs (viarouted_getinexternal_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 afetch_detailsmiss; 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 sheadroom 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 causeskill_on_dropto terminate the child andTempDirGuardto 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_digestHEADs 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 forfetch_detailsGETs 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-remainingbudget gauge:resolve_digestlogs theratelimit-remainingheader from each Docker HubHEADresponse as a numeric structured field (remaining), including from error responses (e.g. 429) whereremaining=0is most actionable. The header is returned onHEADresponses 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_UNKNOWNfor 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/listlists 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.