GO — Healthy across the board

• Last commit 2d ago
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Clair is a static vulnerability scanner for container images (OCI/Docker) that indexes container layers and matches them against known vulnerability databases to identify security risks. It provides a REST API for clients to submit container images for analysis and retrieve vulnerability reports, enabling transparent security assessment of containerized infrastructure. Modular monolithic service: core vulnerability indexing and matching logic lives in the main Go packages, with separate conceptual layers for indexing (Documentation/concepts/indexing.md), matching (Documentation/concepts/matching.md), and notifications (Documentation/concepts/notifications.md). A REST API layer handles external requests, and the system interacts with updaters for vulnerability data (Documentation/concepts/updatersandairgap.md).

DevOps engineers, container registry operators (like Project Quay users), and CI/CD pipeline maintainers who need automated vulnerability scanning integrated into image builds and deployments. Security teams use Clair to maintain compliance and track vulnerabilities across container fleets.

Production-ready and actively maintained. Clair has been in active development with a mature v4 release (as evidenced by the modular architecture in Documentation/concepts/), comprehensive CI/CD workflows in .github/workflows/, and a detailed changelog in .chglog/. The project is part of Project Quay, a stable enterprise container registry.

Low risk for production use. The codebase is well-organized with established CI/CD pipelines (main.yml, tests.yml, nightly-ci.yml), clear contribution guidelines in .github/CONTRIBUTING.md, and documented release processes (.github/workflows/cut-release.yml, prepare-release.yml). Main branch stability caveat noted in README suggests pinning to official releases rather than HEAD.

Active development with recent release preparation workflows (cut-release.yml, prepare-release.yml) and nightly CI testing indicating continuous iteration. The repository maintains changelog automation (.chglog/config.yml) and dependency management via Dependabot (.github/dependabot.yml), suggesting regular updates and security patch cycles.

Clone and build: git clone https://github.com/quay/clair.git && cd clair && make. The Makefile orchestrates the build (present in root and .github/workflows/). Review Documentation/contribution/building.md for detailed setup instructions and dependencies.

Daily commands: Build with make (Makefile at root), then run the binary with configuration file (config pattern in Documentation/). Typically: ./clair -config config.yaml. The Dockerfile shows production deployment as a container. See .github/workflows/main.yml for CI build steps.

• cmd/clair/main.go — Entry point for the Clair server; every contributor must understand how the application bootstraps and initializes core components.
• cmd/config.go — Central configuration parsing and validation; critical for understanding how Clair reads environment and file-based config across all subsystems.
• Documentation/concepts.md — Core conceptual documentation covering indexing, matching, and notifications; essential reading before implementing features.
• clair-error/errors.go — Custom error types and error handling patterns used throughout the codebase; must be understood for consistent error propagation.
• cmd/clairctl/client.go — CLI client implementation for interacting with Clair API; demonstrates the expected API contract and communication patterns.
• Makefile — Build orchestration and development workflow; contributors need to understand how to build, test, and deploy Clair.
• .github/workflows/main.yml — Primary CI/CD pipeline defining test, build, and release automation; essential for understanding the contribution and release process.

Add a New Configuration Option

1. Define the configuration struct field in the appropriate section of cmd/config.go, with struct tags for YAML/JSON unmarshaling and validation (cmd/config.go)
2. Add test cases in cmd/config_test.go to verify parsing and validation of the new option (cmd/config_test.go)
3. Document the new option in Documentation/reference/config.md with description, type, and example values (Documentation/reference/config.md)
4. Update the example configuration file or add a test case in cmd/testdata if appropriate (cmd/testdata/ComplexJSON/config.json)

Add a New clairctl Subcommand

1. Create a new file in cmd/clairctl/ following the pattern of existing commands (e.g., manifest.go, report.go) with a function signature that accepts context and command arguments (cmd/clairctl/main.go)
2. Use cmd/clairctl/client.go to make API calls to Clair server, following the established HTTP client patterns (cmd/clairctl/client.go)
3. Implement output formatting using one of the formatter types (jsonformatter.go, textformatter.go, xmlformatter.go) or create a new formatter (cmd/clairctl/jsonformatter.go)
4. Register the command in cmd/clairctl/main.go by adding a subcommand entry with appropriate flag handling (cmd/clairctl/main.go)
5. Add command documentation to Documentation/reference/clairctl.md (Documentation/reference/clairctl.md)

Handle a New Error Type

1. Define a new error type in clair-error/errors.go, following the existing error wrapping patterns using Go's errors.As and errors.Is patterns (clair-error/errors.go)
2. If the error is notification-related, add handling in clair-error/notifications.go (clair-error/notifications.go)
3. Propagate the error appropriately from the component that detects it (e.g., configuration loader, API handler) to cmd/clair/main.go for final handling (cmd/clair/main.go)
4. Add test coverage in clair-error/errors.go test file demonstrating error matching and unwrapping (clair-error/errors.go)

Update Documentation for a Core Concept

1. Update the relevant concept file in Documentation/concepts/ (e.g., indexing.md, matching.md) with new information or architecture changes (Documentation/concepts.md)
2. Update the corresponding reference documentation in Documentation/reference/ if configuration or API changes are involved (Documentation/reference/api.md)
3. Add or update a deployment diagram/howto guide in Documentation/howto/ if the change affects operational concerns (Documentation/howto/deployment.md)
4. Update README.md if the change significantly alters the project's scope or capabilities (README.md)

• Go — Chosen for cross-platform compilation, static binary deployment, fast execution, and built-in concurrency primitives for parallel container layer scanning.
• PostgreSQL / SQLite — Provides persistent, queryable storage for indexed container contents and vulnerability metadata; supports complex matching queries across large datasets.
• OCI/Docker Image Format — Clair analyzes container images in OCI and Docker formats—the de facto standards for containerized applications; enables vulnerability scanning at the registry level.

• Separate Indexer and Matcher components (can be run together or distributed)

  • Why: Allows flexible deployment: combined for simplicity, distributed for horizontal scaling and isolation of read-heavy vs write-heavy workloads.
  • Consequence: Increased operational complexity in distributed mode; requires inter-component communication and database consistency guarantees.

• Asynchronous notification delivery (optional notifier component)

  • Why: Prevents API response latency from being blocked by out-of-band notification systems; decouples Clair from vulnerability consumer systems.
  • Consequence: Notifications may be delayed; requires reliable message queue and idempotent delivery mechanisms.

• Pluggable updater architecture for vulnerability sources

  • Why: Allows Clair to ingest vulnerabilities from multiple sources (NVD, distribution-specific feeds) without core code changes.
  • Consequence: Updaters must be maintained separately; air-gapped environments require manual distribution of

Configuration is critical: the service requires a valid config.yaml with database connection strings and vulnerability updater settings (see Documentation/concepts/updatersandairgap.md) or it will not start. PostgreSQL backend is assumed but not explicitly packaged — must be provisioned separately. The 'main branch instability' warning in README means development branches may have breaking schema changes; always test against a released version in staging. Updater synchronization is asynchronous; initial vulnerability data population can take time depending on feed size. DCO (Developer Certificate of Origin) is required for all contributions (see DCO file); commits must be signed.

• Image Layer Indexing — Clair's core operation: it decomposes container images into layers and indexes each layer's filesystem to extract package metadata, which is essential for vulnerability matching
• Vulnerability Matching / Correlation — The algorithm that maps indexed packages to known CVEs; understanding match strategies (exact version, ranges, platform-specific rules) is key to debugging false positives/negatives
• Updaters (Feed Synchronization) — Pluggable components that fetch vulnerability data from sources (NVD, distro repos, etc.) and keep the database current; critical for understanding data freshness and airgap deployments
• Notification System (Push Model) — Clair can push vulnerability alerts when new CVEs are discovered for already-indexed images, enabling reactive security workflows rather than purely query-driven models
• OCI/Docker Image Manifest Processing — Understanding how Clair parses manifests, resolves layer digests, and fetches layer content is essential for indexing API debugging and integration with registries
• Authentication & Authorization (API Security) — Clair exposes a potentially sensitive API (access to vulnerability data); concepts/authentication.md likely documents authz patterns — important for secure deployment in multi-tenant environments
• Database Schema Evolution (Migrations) — As a stateful service backed by PostgreSQL, Clair must handle schema versioning across releases; understanding migration patterns prevents data corruption and enables safe upgrades

• aquasecurity/trivy — Alternative container vulnerability scanner with similar static analysis goals but different architecture (standalone binary vs. Clair's service model)
• anchore/grype — Another container scanning tool in Go; Grype focuses on dependency-based vulnerabilities while Clair emphasizes OS-level scanning
• quay/quay — Project Quay container registry that integrates Clair as its vulnerability scanning backend; primary consumer of Clair's API
• opencontainers/image-spec — OCI Image Specification standard that Clair implements for layer inspection and image manifest parsing
• coreos/clair-legacy — Historical predecessor (v2/v3); Clair v4 in this repo was a major architectural redesign, but the legacy repo provides context on evolution

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for OpenAPI specification validation in CI

The repo has Documentation/contribution/openapi.md suggesting OpenAPI specs exist, but there's no dedicated CI workflow to validate OpenAPI schemas against code changes. This prevents specification drift and ensures API documentation stays synchronized with implementation. Adding a GitHub Action to validate OpenAPI specs (similar to the existing .yamllint workflow) would catch breaking API changes early.

• [ ] Create .github/workflows/openapi-validation.yml to validate OpenAPI schemas
• [ ] Reference Documentation/contribution/openapi.md to understand the OpenAPI setup
• [ ] Add validation step that runs on PRs touching Documentation/reference/api.md or API-related code
• [ ] Configure workflow to fail if schemas don't match code or have syntax errors

Add comprehensive testing guide with examples in Documentation/howto/testing.md

Documentation/howto/testing.md exists but is sparse. The repo has extensive test infrastructure (listing_test.go visible, nightly-ci.yml, tests.yml workflows) but new contributors lack guidance on writing tests for different components (indexer, matcher, notifier). Adding specific test examples and patterns would lower contribution friction.

• [ ] Expand Documentation/howto/testing.md with sections for: unit tests, integration tests, and end-to-end tests
• [ ] Add code examples for testing indexer, matcher, and notifier components (referenced in Documentation/reference/)
• [ ] Document how to run tests locally matching the CI workflows in .github/workflows/tests.yml
• [ ] Include examples of mocking database interactions and vulnerability data

Create CLI documentation and examples for clairctl in Documentation/howto/clairctl-guide.md

Documentation/reference/clairctl.md exists as reference docs, but there's no how-to guide with practical examples. Given the complexity of container scanning workflows, a step-by-step guide with common scenarios (scanning images, checking vulnerabilities, integration with CI) would help adoption and reduce support burden.

• [ ] Create Documentation/howto/clairctl-guide.md with practical examples
• [ ] Add sections: basic setup, scanning a container image, querying vulnerabilities, integrating with CI/CD pipelines
• [ ] Reference the architecture diagrams already present (clairv4_combo_.png, clairv4_distributed_.png) to show deployment context
• [ ] Include troubleshooting section linking to Configuration reference

• Add integration tests for the notification system (Documentation/concepts/notifications.md exists but test coverage gaps are typical) — start by examining .github/workflows/tests.yml to understand the test infrastructure, then add tests in a new notifications_test.go file
• Document the air-gap updater workflow with a concrete example: create a new markdown file under Documentation/concepts/ showing step-by-step how to set up an offline vulnerability feed using concepts from updatersandairgap.md
• Implement missing OpenAPI schema validation for edge cases in the API layer — review Documentation/contribution/openapi.md and add test cases for malformed image manifest inputs in the indexing endpoint

The Clair codebase shows moderate security posture with several actionable findings. Primary concerns include Go version mismatches between build configuration and module specification, reliance on unstable main branch for potential deployments, and incomplete visibility into transitive dependencies. Docker configuration has minor issues with unversioned image tags. The project demonstrates good practices with proper licensing, DCO requirements, and structured security documentation. Recommended actions: (1) Align Go versions, (2) enforce release-based deployments, (3) complete full dependency audit, (4) pin all Docker image versions, and (5) implement automated security scanning in CI/CD pipeline.

• Medium · Go Version Mismatch Between Module and Docker Build — go.mod (line: go 1.22.0) and Dockerfile (line: ARG GO_VERSION=1.25). The go.mod file specifies Go 1.22.0, but the Dockerfile uses GO_VERSION=1.25. This version mismatch could lead to inconsistent builds, potential compatibility issues, and may use a Go version with unresolved vulnerabilities in the build process. Fix: Align Go versions between go.mod and Dockerfile. Update go.mod to 'go 1.25' or update Dockerfile to use GO_VERSION=1.22, ensuring consistency across build environments.
• Medium · Unreleased Development Code in Use — README.md and general repository practice. The README explicitly states 'The main branch may be in an unstable or even broken state during development.' Using the main branch for production deployments introduces significant risk of instability, security regressions, and undisclosed vulnerabilities. Fix: Always deploy from official releases rather than the main branch. Document this requirement clearly for users and CI/CD pipelines.
• Low · Limited Dependency Information — go.mod (incomplete view). Only one Go dependency (google/go-cmp v0.7.0) is visible in the provided config/go.mod file. The main project likely has additional dependencies in the root go.mod that were not provided, making a complete security assessment of transitive dependencies impossible. Fix: Perform a complete dependency audit using 'go mod graph' and 'go list -u -m all' to identify all transitive dependencies and check for known vulnerabilities using 'go list -json -m all | nancy sleuth' or similar tools.
• Low · Docker Image Source and Base Image Security — docker-compose.yaml (lines with 'latest' tags). The Dockerfile and docker-compose.yaml reference multiple public Docker images (quay.io/projectquay/golang, docker.io/library images). While these are legitimate registries, using 'latest' tags for some images (postgres-exporter, pyroscope) in docker-compose.yaml bypasses version pinning and increases supply chain risk. Fix: Pin all Docker image tags to specific versions. Replace 'latest' with explicit version numbers (e.g., 'postgres-exporter:v0.14.0'). Regularly scan base images for vulnerabilities using tools like Trivy.
• Low · Incomplete Dockerfile Arguments — Dockerfile (incomplete ARG declaration). The Dockerfile has an incomplete ARG statement with no value specified (visible as 'ARG' on a line by itself in the provided snippet). This may indicate copy-paste errors or incomplete configuration. Fix: Review and complete all ARG declarations in the Dockerfile. Ensure all build arguments are properly defined with descriptive names and default values where appropriate.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/quay/clair shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live quay/clair repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/quay/clair.

What it runs against: a local clone of quay/clair — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in quay/clair | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of quay/clair. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/quay/clair.git
#   cd clair
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of quay/clair and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "quay/clair(\\.git)?\\b" \\
  && ok "origin remote is quay/clair" \\
  || miss "origin remote is not quay/clair (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/clair/main.go" \\
  && ok "cmd/clair/main.go" \\
  || miss "missing critical file: cmd/clair/main.go"
test -f "cmd/config.go" \\
  && ok "cmd/config.go" \\
  || miss "missing critical file: cmd/config.go"
test -f "Documentation/concepts.md" \\
  && ok "Documentation/concepts.md" \\
  || miss "missing critical file: Documentation/concepts.md"
test -f "clair-error/errors.go" \\
  && ok "clair-error/errors.go" \\
  || miss "missing critical file: clair-error/errors.go"
test -f "cmd/clairctl/client.go" \\
  && ok "cmd/clairctl/client.go" \\
  || miss "missing critical file: cmd/clairctl/client.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/quay/clair"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.