Wait, Clair doesn't monitor running containers?

Nope, it's static analysis only. Clair scans your images before deployment and tells you what vulnerabilities exist in the packages. It won't catch someone exploiting those vulnerabilities at runtime - that's [Falco's](https://falco.org/) job or whatever expensive runtime security platform your CISO bought.Think of it this way: Clair tells you your front door lock is broken, but it won't stop the burglar from walking through it.

Can it scan our private registry that requires seventeen different authentication methods?

Probably, but you'll hate the configuration process. Clair supports basic auth, bearer tokens, and certificate-based auth for private registries like [Harbor](https://goharbor.io/), [Quay Enterprise](https://quay.io/), and [AWS ECR](https://aws.amazon.com/ecr/).The fun part is when your registry uses some custom auth proxy, or when certificates expire, or when your network team changes firewall rules without telling you. Expect to debug connectivity issues every few months.

What happens when Clair finds hundreds of "critical" vulnerabilities?

Clair reports everything it finds - it doesn't decide what's actually critical for your environment. You'll get alerts for every CVE in your base Ubuntu image, including stuff for packages you don't even use.Most teams implement [Open Policy Agent](https://www.openpolicyagent.org/) or similar policy engines to filter results. Otherwise, you'll be drowning in alerts for theoretical vulnerabilities in packages your application never touches.

How often do vulnerability databases update (and break everything)?

Vulnerability sources update constantly - [Ubuntu USN](https://usn.ubuntu.com/) daily, [Debian DSA](https://www.debian.org/security/) as needed, [NVD](https://nvd.nist.gov/) multiple times per day. Each update can trigger matcher rebuilds that lock up scanning for 5-15 minutes.I've seen production deployments get blocked because Ubuntu released a security update mid-deployment and Clair was rebuilding its correlation database. Fun times.

Does it work in our air-gapped environment that can't talk to the internet?

Technically yes, practically no. You need to mirror vulnerability databases and container registries, sync them regularly, and pray nothing breaks. Red Hat's [air-gapped deployment guide](https://quay.github.io/clair/howto/air_gapped_database.html) makes it sound simple - it's a nightmare.Expect to spend weeks setting up database synchronization, only to discover you're missing critical vulnerability updates because one mirror failed silently.

Why doesn't it support our Node.js/Ruby applications fully?

Because [ClairCore](https://quay.github.io/claircore/) development focuses on the most common container ecosystems first. As of v4.8+, Clair supports Python, Go modules, and Java JARs with varying degrees of completeness. JavaScript and Ruby analyzers are still limited.For comprehensive language support, use [Trivy](https://github.com/aquasecurity/trivy) or [Grype](https://github.com/anchore/grype) instead. They're not as accurate for OS packages but cover way more languages.

How do I deal with all the false positives?

You build a whitelist of accepted vulnerabilities and pray your security team doesn't audit it. Most organizations maintain exception lists for: - CVEs in packages that aren't exposed (database drivers in web-only containers) - Vulnerabilities with no available fixes - Low-priority issues that would take longer to fix than the container lifespan

Can it find secrets or malware in our images?

Hell no. Clair only matches known CVE databases against detected packages. For secrets, use [TruffleHog](https://github.com/trufflesecurity/trufflehog). For malware, hope your base images aren't compromised and run [ClamAV](https://www.clamav.net/) if you're paranoid.

Why is scanning so slow for our machine learning images?

Because your TensorFlow container is 8GB with 73 layers and Clair downloads every single byte to analyze package contents. Network bandwidth, layer deduplication, and package analysis all impact performance.Smaller base images scan faster. Standardized base images (same layers across containers) scan much faster due to layer caching. Your monolithic ML image with custom-compiled everything will always be slow.

How do I fix Clair when it randomly stops working?

Check these in order: 1. PostgreSQL connection pool exhaustion (most common) 2. Vulnerability database update failures 3. Network connectivity to external CVE sources 4. Memory exhaustion during large image scanning 5. Webhook authentication failures with your registry The logs will tell you what's broken, but decoding the error messages takes practice. When in doubt, restart everything and see what breaks first.

Currently viewing the AI version

Switch to human version

Clair Container Vulnerability Scanner - AI-Optimized Technical Reference

Core Function

Clair performs static analysis of container images to detect known vulnerabilities by matching installed packages against CVE databases. Does NOT provide runtime monitoring or behavioral analysis.

Architecture & Process Flow

Three-Phase Operation

Indexing: Downloads entire image, analyzes layers, catalogs packages
- Performance impact: 2GB ML container with 47 layers = 3-20 minutes depending on network
- Layer deduplication optimization: Same base image scanned once across multiple containers
- Memory spike: Up to 4GB+ per worker for large images
Matching: Queries live vulnerability databases for current threat data
- Advantage: No rescanning needed when new CVEs discovered
- Risk: Database updates can lock scanning for 5-15 minutes during peak hours
Notifications: Webhook-based alerts (high failure rate due to configuration complexity)

Performance Characteristics

Scale Limits

Production capacity: ~10,000 images per Clair instance for sub-minute scans
Database requirements: Minimum 4 CPU cores, 8GB RAM for PostgreSQL
Network timeouts: Require 10+ minute ingress timeouts for large images
Memory limits: 1GB default is insufficient - plan for 3GB+ spikes

Performance Degradation Points

100,000+ indexed images: PostgreSQL query performance cliff without proper indexing
Daily vulnerability updates: Ubuntu USN, Debian DSA updates can lock system
Large ML containers: TensorFlow images (8GB, 73 layers) consistently slow

Supported Ecosystems (2025 Status)

Reliable Coverage

Linux distros: Ubuntu (most tested), Debian, RHEL/CentOS, Alpine, Amazon Linux
Languages: Python packages (solid), Go modules (v4.8+), Java JARs (improving), OS packages (excellent)

Limited/Poor Coverage

JavaScript/Node.js: Inadequate dependency analysis
Ruby gems: Hit-or-miss detection
Custom packages: Shell scripts, compiled binaries not supported

Deployment Strategies

Docker Compose (Development Only)

Failure modes:
- PostgreSQL connection exhaustion at 100 concurrent scans
- Redis memory limits during large image indexing
- Container restart loops during database downtime

Kubernetes Production

Critical requirements:
- Dedicated PostgreSQL cluster (not shared instance)
- 10+ minute ingress timeouts
- 4GB+ memory limits for indexer pods
- Network policies allowing registry → Clair communication

Registry Integration

Supported: Harbor (built-in), Quay.io (native), webhook-based triggers
Common failures:
- Webhook timeouts (indexing exceeds timeout)
- Authentication failures
- Network connectivity issues

Configuration Critical Points

Database Setup

Connection pool sizing: Default pools insufficient for production
SSL parameters: sslmode=require vs sslmode=verify-full - one typo breaks startup
Performance tuning: Regular VACUUM operations required, proper indexing essential

Vulnerability Data Sources

Default enabled: Ubuntu USN, Debian DSA, Red Hat RHSA, PyPI advisories
Rate limiting risk: Too many sources trigger external API limits
Air-gapped complexity: Requires vulnerability database mirroring (weekend project)

Competitive Analysis

Tool	Best For	Resource Cost	Accuracy Trade-off
Clair	Registry integration, massive scale	High (PostgreSQL + Redis + microservices)	Highest package accuracy
Trivy	CI/CD pipelines, quick results	Low (single binary)	Lower accuracy, broader language support
Grype	Speed + accuracy balance	Medium	Good compromise, less mature
Snyk Container	Executive dashboards	High (pricing scales with usage)	Good UX, API rate limits

Critical Failure Modes

Database-Related

Connection pool exhaustion: Most common production failure
Memory exhaustion: Large image analysis kills containers
Update locks: 5-15 minute scanning outages during vulnerability updates

Network-Related

Internet dependency: Requires access to NVD, Ubuntu, Debian CVE sources
Webhook failures: Silent notification delivery failures
Registry connectivity: Authentication changes break scanning

Operational

False positive overload: Base Ubuntu image generates 847+ alerts (90% irrelevant)
Missing vulnerabilities: Language-specific packages not detected
Air-gapped deployment: Complex mirroring setup, frequent sync failures

Resource Requirements (Real-World)

Minimum Production Setup

Database: 4 CPU cores, 8GB RAM PostgreSQL dedicated instance
Clair instances: 3GB+ memory per indexer, plan for spikes
Network: 10Mbps+ sustained for image downloads
Storage: Significant for vulnerability databases and layer cache

High Availability Considerations

Load balancer configuration: Complex webhook coordination
Database failover: Split-brain scenarios require planning
Geographic distribution: Latency impacts on large image scanning

Common Implementation Mistakes

Underestimating Resources

Memory limits: Default 1GB insufficient, causes OOM kills
Database sizing: Shared instances fail under scanning load
Network timeouts: Default Kubernetes settings cause scan failures

Configuration Errors

SSL connection strings: Unforgiving syntax breaks startup
Webhook payload formats: Change between versions, break integrations
Vulnerability source overload: Too many sources trigger rate limits

Operational Intelligence

Troubleshooting Priority Order

PostgreSQL connection pool status
Vulnerability database update failures
Network connectivity to CVE sources
Memory exhaustion during scanning
Registry webhook authentication

Success Indicators

Sub-minute scans: Standard containers on properly sized infrastructure
Layer deduplication working: Significant performance gains with standardized base images
Stable webhook delivery: Consistent notification flow without authentication failures

Warning Signs

Increasing scan times: Database performance degradation
Silent notification failures: Webhook delivery issues
Random scan failures: Resource exhaustion patterns

Integration Requirements

Prerequisites

Dedicated PostgreSQL cluster: Shared databases will fail
Redis instance: For caching and state management
Container registry access: Authentication and network connectivity
Internet access: For vulnerability database updates (unless air-gapped)

Success Metrics

Scan completion rate: >95% success rate
Time to detect: New vulnerabilities identified within hours of CVE publication
False positive ratio: <10% irrelevant alerts through proper filtering

This technical reference enables automated decision-making for Clair deployment, configuration, and operational management while preserving critical failure modes and resource requirements.

Useful Links for Further Investigation

Resources That Actually Help

Link	Description
Clair v4 Documentation	The official docs are actually decent once you get past the marketing speak. The deployment section will save you hours of debugging PostgreSQL connection issues.
GitHub Repository - quay/clair	Skip the README, go straight to the Issues tab. Every production problem you'll hit is already documented there. The Docker Compose example is the only one that actually works.
ClairCore Library Documentation	Only useful if you're hacking on Clair itself or need to understand why your Python wheel isn't getting detected. Dry reading but technically accurate.
Red Hat Quay Clair Integration	The one guide that explains PostgreSQL setup without handwaving the hard parts. If you're using Quay, this is the only doc you need.
Harbor Registry Clair Scanner	Harbor's built-in Clair works better than running it standalone. This doc explains why and how to set it up without the usual networking nightmares.
Scanning Container Images with Clair - Red Hat Blog	Actually explains the architecture instead of just listing features. Read this first to understand what you're getting into.
Clair GitHub Issues - "production" label	Real production failures with actual solutions. Better than any documentation for troubleshooting stuck scans and database problems.
IRC Channel #clair on Libera.Chat	The maintainers actually hang out here and answer questions. Way faster than GitHub issues for quick fixes. (Note: moved from Freenode after their 2021 meltdown)
CNCF Container Security Landscape	Shows you all the alternatives you should have considered before choosing Clair. Useful for justifying your decision to management.
Clair API Reference	The HTTP API is surprisingly well-designed. This doc shows you how to integrate without pulling your hair out. The webhook examples are copy-pasteable.
Example Integrations Repository	Community examples that mostly work. The Jenkins plugin is abandoned, but the GitLab CI example saved me two days of trial and error.

Clair Container Vulnerability Scanner - AI-Optimized Technical Reference

Core Function

Architecture & Process Flow

Three-Phase Operation

Performance Characteristics

Scale Limits

Performance Degradation Points

Supported Ecosystems (2025 Status)

Reliable Coverage

Limited/Poor Coverage

Deployment Strategies

Docker Compose (Development Only)

Kubernetes Production

Registry Integration

Configuration Critical Points

Database Setup

Vulnerability Data Sources

Competitive Analysis

Critical Failure Modes

Database-Related

Network-Related

Operational

Resource Requirements (Real-World)

Minimum Production Setup

High Availability Considerations

Common Implementation Mistakes

Underestimating Resources

Configuration Errors

Operational Intelligence

Troubleshooting Priority Order

Success Indicators

Warning Signs

Integration Requirements

Prerequisites

Success Metrics

Useful Links for Further Investigation

Resources That Actually Help

Related Tools & Recommendations

Snyk + Trivy + Prisma Cloud: Stop Your Security Tools From Fighting Each Other

GitOps Integration Hell: Docker + Kubernetes + ArgoCD + Prometheus

Kafka + MongoDB + Kubernetes + Prometheus Integration - When Event Streams Break

Trivy Scanning Failures - Common Problems and Solutions

Container Security Tools: Which Ones Don't Suck?

Docker Scout - Find Vulnerabilities Before They Kill Your Production

Anchore Engine Migration Guide - Moving to Syft & Grype

Container Security Pricing Reality Check 2025: What You'll Actually Pay

Snyk Container - Because Finding CVEs After Deployment Sucks

Aider - Terminal AI That Actually Works

GitHub Actions Marketplace - Where CI/CD Actually Gets Easier

GitHub Actions Alternatives That Don't Suck

GitHub Actions + Docker + ECS: Stop SSH-ing Into Servers Like It's 2015

RAG on Kubernetes: Why You Probably Don't Need It (But If You Do, Here's How)

Jenkins + Docker + Kubernetes: How to Deploy Without Breaking Production (Usually)

Jenkins Production Deployment - From Dev to Bulletproof

Jenkins - The CI/CD Server That Won't Die

GitLab CI/CD - The Platform That Does Everything (Usually)

GitLab Container Registry

GitHub Enterprise vs GitLab Ultimate - Total Cost Analysis 2025