Skip to main content
check-image provides 12 commands for validating container images against security and operational standards. Each command can be run individually or together using the all command.

​
Available Commands

age

Validate that the image is not older than a specified number of days

size

Validate image size and layer count are within acceptable limits

registry

Validate that the image registry is trusted based on a policy file

ports

Validate that the image does not expose unauthorized ports

root-user

Validate that the image runs as non-root user

healthcheck

Validate that the image has a healthcheck defined

secrets

Validate that the image does not contain sensitive data

entrypoint

Validate that the image has a startup command defined and uses exec form

labels

Validate that the image has required labels with correct values

platform

Validate that the image platform is in the allowed list

all

Run all validation checks on a container image at once

version

Show check-image version with full build information

​
Command Categories

​
Security Validation

These commands ensure images meet security standards:
  • root-user - Prevents containers from running as root
  • secrets - Detects sensitive data in environment variables and files
  • registry - Ensures images come from trusted registries

​
Operational Standards

These commands validate operational best practices:
  • age - Ensures images are not outdated
  • size - Controls image bloat and layer count
  • healthcheck - Validates container health monitoring
  • entrypoint - Ensures proper startup command configuration

​
Configuration Validation

These commands check specific image configurations:
  • ports - Controls exposed network ports
  • labels - Validates OCI annotations and metadata
  • platform - Ensures correct OS/architecture compatibility

​
Orchestration

  • all - Runs multiple checks together with fail-fast support
  • version - Shows tool version and build information

​
Global Flags

All commands support these flags:
  • --output, -o - Output format: text (default) or json
  • --color - Color output mode: auto (default), always, never
  • --log-level - Set log level: trace, debug, info, warn, error, fatal, panic
  • --username - Registry username for authentication
  • --password - Registry password or token
  • --password-stdin - Read registry password from stdin

​
Exit Codes

Exit CodeMeaningExample
0Validation succeeded or no checks ranImage passes all checks
1Validation failedImage is too old, runs as root, exposes unauthorized ports
2Execution errorInvalid config file, image not found, invalid arguments

​
Image Reference Formats

All commands support multiple image sources: 
# Registry image (daemon with registry fallback)
check-image <command> nginx:latest
check-image <command> docker.io/library/nginx:latest

# OCI layout directory
check-image <command> oci:/path/to/layout:tag
check-image <command> oci:/path/to/layout@sha256:digest

# OCI tarball archive
check-image <command> oci-archive:/path/to/image.tar:tag

# Docker tarball archive
check-image <command> docker-archive:/path/to/image.tar:tag

​
Quick Start

# Run individual checks
check-image age nginx:latest --max-age 30
check-image size nginx:latest --max-size 100
check-image root-user nginx:latest

# Run all checks
check-image all nginx:latest

# Run all checks with config file
check-image all nginx:latest --config config.yaml

# Run specific checks only
check-image all nginx:latest --checks age,size,root-user

# Skip specific checks
check-image all nginx:latest --skip registry,labels

Getting Started

Learn how to install and use check-image

Configuration

Configure validation policies and thresholds

Build docs developers (and LLMs) love

Get started for freeTalk to us