Skip to main content
Check Image is a Go-based CLI tool designed for validating container images. It ensures that images meet specific standards such as size, age, ports, and security configurations.

​
What is Check Image?

Check Image helps you enforce container image policies across your infrastructure by validating images against a comprehensive set of security and operational checks. Whether you’re working locally, in CI/CD pipelines, or with GitHub Actions, Check Image provides consistent validation across all environments.

​
Key Features

Security Validation

Check for non-root users, exposed ports, embedded secrets, and trusted registries

Operational Standards

Validate image size, age, layer count, and required labels

Multiple Formats

Support for Docker daemon, remote registries, OCI layouts, and archive formats

Flexible Integration

CLI, Docker container, GitHub Action, and CI/CD pipeline support

​
Available Checks

Check Image provides 10 validation checks:
CheckDescription
ageValidates image is not older than specified days
sizeValidates image size and layer count limits
registryValidates image comes from trusted registry
portsValidates only authorized ports are exposed
root-userValidates image runs as non-root user
healthcheckValidates image has healthcheck defined
secretsScans for embedded passwords, tokens, and keys
entrypointValidates startup command uses exec form
labelsValidates required OCI annotations are present
platformValidates image platform (OS/Architecture)

​
Use Cases

​
CI/CD Pipeline Validation

Validate images before deployment to ensure they meet your organization’s security standards: 
check-image all myapp:latest --config .check-image/config.yaml

​
Security Scanning

Scan images for common security issues like root users and embedded secrets: 
check-image root-user nginx:latest
check-image secrets myapp:latest --secrets-policy policies/secrets.yaml

​
Registry Trust Verification

Ensure images only come from approved registries: 
check-image registry ghcr.io/myorg/app:latest \
  --registry-policy policies/registry.yaml

​
GitHub Actions Integration

Automatically validate images in your GitHub workflows: 
- uses: jarfernandez/[email protected]
  with:
    image: myorg/myapp:${{ github.sha }}
    config: .check-image/config.yaml

​
How It Works

Check Image connects to container registries and Docker daemons to inspect image metadata and configuration. It can validate:
  • Image manifests for size, layer count, and platform information
  • Image configurations for user settings, exposed ports, healthchecks, and startup commands
  • Image labels for required OCI annotations
  • Image layers for embedded secrets and sensitive files
  • Registry sources against trusted/blocked lists
Check Image works without requiring Docker daemon access for remote registry images. This makes it ideal for CI/CD environments where you want to validate images after pushing to a registry.

​
Supported Image Sources

Check Image supports multiple image transport formats (Skopeo-compatible syntax):
  • Default (Docker daemon → remote registry fallback): nginx:latest
  • OCI Layout directories: oci:/path/to/layout:latest
  • OCI Archive tarballs: oci-archive:/path/to/image.tar:latest
  • Docker Archive (from docker save): docker-archive:/path/to/saved.tar:nginx:latest

​
Exit Codes

Check Image uses standard exit codes for easy integration with scripts and CI/CD:
Exit CodeMeaningExample
0Validation succeededImage passes all checks
1Validation failedImage is too old, runs as root, exposes unauthorized ports
2Execution errorInvalid config file, image not found, invalid arguments

​
Output Formats

All commands support both human-readable text and JSON output: 
# Human-readable output (default)
check-image age nginx:latest --max-age 30

# JSON output for scripting
check-image age nginx:latest --max-age 30 --output json
JSON output includes full validation details and is ideal for:
  • CI/CD pipeline integration
  • Automated reporting
  • Programmatic analysis
  • Webhook payloads

​
Next Steps

Installation

Install Check Image using Homebrew, Go, Docker, or pre-built binaries

Quick Start

Get started with your first image validation in 3 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us