Complete Clair Scanner Cheatsheet: Container Vulnerability Management

Introduction

Clair is an open-source container vulnerability scanner developed by CoreOS (now part of Red Hat). It analyzes container images to identify known security vulnerabilities in application dependencies. As organizations increasingly adopt containerized applications, Clair provides a critical security layer by detecting vulnerabilities before deployment, helping DevOps and security teams manage risk throughout the container lifecycle. Integrating Clair into CI/CD pipelines enables automated vulnerability detection, making container security a seamless part of the development workflow.

Core Concepts and Principles

Vulnerability Database Architecture

• Updaters: Fetch vulnerability data from various security databases
• Detectors: Identify features (packages, libraries) in containers
• Notifiers: Alert on discovered vulnerabilities
• Static Analysis: Examines container without executing it
• CVE Database: Common Vulnerabilities and Exposures repository

Key Terminology

• Container Image: Packaged software with dependencies
• Vulnerability: Known security weaknesses in software components
• Severity Levels: Critical, High, Medium, Low, Negligible
• False Positives: Incorrectly identified vulnerabilities
• Indexer: Extracts container content for analysis
• Matcher: Compares extracted data against vulnerability database

Clair Scanning Process

1. Environment Setup

• Install Clair (standalone or with container orchestration)
• Configure database backend (PostgreSQL)
• Set up vulnerability data sources
• Configure authentication/authorization
• Ensure network connectivity to registries

2. Container Analysis Workflow

• Image Extraction: Pull and decompress container layers
• Feature Detection: Identify operating system and packages
• Vulnerability Matching: Compare features against vulnerability database
• Report Generation: Create vulnerability assessment report
• Notification: Alert on detected issues (optional)

3. Integration Methods

• Direct API Integration: HTTP API calls to Clair server
• CI/CD Pipeline: Jenkins, GitLab CI, GitHub Actions
• Registry Integration: Harbor, Quay.io
• Kubernetes Integration: Via admission controllers or operators
• Command-line Tools: clairctl, klar, clair-scanner

Clair Implementation Options

Standalone Clair

# Run Clair with Docker
docker run -d --name clair -p 6060:6060 -p 6061:6061 \
  -v $PWD/clair_config:/etc/clair quay.io/projectquay/clair:v4.3.0 \
  -config /etc/clair/config.yaml

Clair with Docker Compose

version: '3'
services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: clair
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
      
  clair:
    image: quay.io/projectquay/clair:v4.3.0
    ports:
      - "6060:6060"  # API
      - "6061:6061"  # Health
    depends_on:
      - postgres
    volumes:
      - ./config:/etc/clair
    command: ["--config", "/etc/clair/config.yaml"]

volumes:
  postgres-data:

Sample Clair V4 Configuration

# config.yaml
introspection_addr: :6061
http_listen_addr: :6060
log_level: info

indexer:
  connstring: host=postgres port=5432 dbname=clair user=postgres password=password sslmode=disable
  scanners:
    - docker
    - package

matcher:
  connstring: host=postgres port=5432 dbname=clair user=postgres password=password sslmode=disable
  indexer_addr: indexer
  updater_sets:
    - alpine
    - aws
    - debian
    - oracle
    - rhel
    - suse
    - ubuntu

notifier:
  connstring: host=postgres port=5432 dbname=clair user=postgres password=password sslmode=disable
  delivery_interval: 1m
  poll_interval: 5m
  webhook:
    target: https://example.com/notify
    callback: https://clair-notifier/callback

Scanning Methods Comparison

Common CLI Commands

Using clairctl (Clair v4+)

# Report vulnerabilities in an image
clairctl report --host http://localhost:6060 --format json alpine:latest

# Export vulnerabilities to file
clairctl report --host http://localhost:6060 --format json alpine:latest > report.json

# Scan local image
clairctl report --host http://localhost:6060 --local --format json my-local-image:latest

Using clair-scanner

# Basic scan
clair-scanner --ip YOUR_LOCAL_IP alpine:latest

# Scan with whitelist
clair-scanner --whitelist whitelist.yml --ip YOUR_LOCAL_IP alpine:latest

# Output report to file
clair-scanner --ip YOUR_LOCAL_IP --report report.json alpine:latest

Using Klar

# Basic scan
CLAIR_ADDR=localhost:6060 klar alpine:latest

# Threshold-based exit codes
CLAIR_ADDR=localhost:6060 KLAR_SEVERITY_THRESHOLD=High klar alpine:latest

# JSON output
CLAIR_ADDR=localhost:6060 KLAR_FORMAT=json klar alpine:latest > report.json

Vulnerability Reporting and Analysis

Report Fields Explanation

• Name: CVE identifier or vendor-specific ID
• Description: Vulnerability explanation
• Severity: Impact rating (Critical, High, Medium, Low)
• FixedIn: Version where vulnerability is patched
• Package: Affected software package
• Layer: Container layer containing vulnerability
• CVSS: Common Vulnerability Scoring System metrics

Sample JSON Report Structure

{
  "Alpine 3.9.2": {
    "CVE-2019-5021": {
      "Name": "CVE-2019-5021",
      "Description": "Alpine Linux 3.9.2 or earlier...",
      "Severity": "Critical",
      "FixedIn": "3.9.3",
      "Link": "https://cve.mitre.org/...",
      "Package": "alpine-baselayout",
      "CVSS": "9.8"
    }
  }
}

Common Challenges and Solutions

Database Connectivity Issues

• Challenge: Clair can’t connect to PostgreSQL database
• Solution: Verify database credentials, network connectivity, and PostgreSQL configuration

Slow Scanning Performance

• Challenge: Scans take too long, especially for large images
• Solution:
  • Increase PostgreSQL resources
  • Implement caching layers
  • Use smaller base images
  • Parallelize scans when possible

False Positives

• Challenge: Reports show vulnerabilities that don’t apply
• Solution:
  • Implement vulnerability whitelisting
  • Use package-specific filters
  • Verify with secondary scanners
  • Keep vulnerability database updated

Integration Failures

• Challenge: CI/CD pipeline integration fails
• Solution:
  • Set appropriate timeouts
  • Implement retry mechanisms
  • Use health checks before scanning
  • Ensure correct API versions

Database Update Issues

• Challenge: Vulnerability database isn’t updating
• Solution:
  • Check network connectivity to sources
  • Verify updater configuration
  • Implement monitoring for update processes
  • Consider manual updates when necessary

Best Practices and Tips

Optimizing Scanning Efficiency

• Scan images as early as possible in development
• Use multi-stage builds to minimize final image size
• Implement layer caching to reduce scan times
• Prioritize vulnerabilities by severity
• Combine with other security tools (SBOM, runtime protection)

CI/CD Integration

• Set appropriate failure thresholds based on severity
• Create separate pipelines for different environments
• Add contextual information to scan results
• Configure notifications for key stakeholders
• Implement progressive scanning (quick scan → deep scan)

Vulnerability Management

• Establish clear remediation workflows
• Document exceptions with justification
• Implement auto-remediation where possible
• Track vulnerability metrics over time
• Conduct regular security reviews

Operational Excellence

• Monitor Clair performance and resource usage
• Implement high-availability configuration for production
• Automate database backups
• Create runbooks for common issues
• Keep Clair version updated

Clair vs. Other Container Scanners

Vulnerability Severity Assessment

Resources for Further Learning

Official Documentation

• Clair GitHub Repository
• Clair Architecture Documentation
• CoreOS/Red Hat Quay Documentation

Community Resources

• Clair Mailing List
• Quay.io Community Forums
• StackOverflow Clair Tags

Related Tools

• clairctl – Official Clair CLI
• clair-scanner – Simple command line scanner
• klar – Integration-focused Clair client
• Harbor – Container registry with Clair integration
• Kubernetes Clair Operator – K8s native deployment

Learning Resources

• OWASP Docker Security Cheatsheet
• Container Security by Liz Rice
• Red Hat Container Security Guide

Disclaimer: This cheatsheet provides general information about Clair scanner and container security best practices. Container security requirements vary based on organizational needs and compliance requirements. Always tailor your security approach to your specific environment and threat model.