Configuration Files

Check Image uses configuration files to define validation policies and parameters. All configuration files support both JSON and YAML formats, and can be read from disk or standard input.

File Format Support

Check Image automatically detects file format based on file extension:

JSON

Files with .json extension

YAML

Files with .yaml or .yml extension

When reading from stdin with -, format is auto-detected by content: JSON starts with { or [, otherwise treated as YAML.

Configuration File Types

Check Image uses different configuration files for different purposes:

Registry Policy Files

Define which container registries are trusted or blocked.

JSON
YAML

config/registry-policy.json

{
  "trusted-registries": [
    "index.docker.io",
    "ghcr.io",
    "gcr.io",
    "quay.io",
    "public.ecr.aws",
    "mcr.microsoft.com",
    "registry.redhat.io",
    "registry.gitlab.com"
  ]
}

config/registry-policy.yaml

trusted-registries:
  - index.docker.io
  - ghcr.io
  - gcr.io
  - quay.io
  - public.ecr.aws
  - mcr.microsoft.com
  - registry.redhat.io
  - registry.gitlab.com

trusted-registries

array

Allowlist of trusted registries. Only images from these registries are allowed. Mutually exclusive with excluded-registries.

excluded-registries

array

Blocklist of excluded registries. All registries except these are allowed. Mutually exclusive with trusted-registries.

check-image registry nginx:latest --registry-policy config/registry-policy.json
check-image registry ghcr.io/myorg/app:latest --registry-policy config/registry-policy.yaml

Secrets Policy Files

Control secrets detection behavior and define exclusions for known safe patterns.

JSON
YAML

config/secrets-policy.json

{
  "check-env-vars": true,
  "check-files": true,
  "excluded-paths": [
    "/usr/share/doc/**",
    "/usr/share/examples/**",
    "/usr/share/man/**"
  ],
  "excluded-env-vars": [
    "PUBLIC_KEY",
    "SSH_PUBLIC_KEY"
  ],
  "custom-env-patterns": [],
  "custom-file-patterns": []
}

config/secrets-policy.yaml

check-env-vars: true
check-files: true
excluded-paths:
  - /usr/share/doc/**
  - /usr/share/examples/**
  - /usr/share/man/**
excluded-env-vars:
  - PUBLIC_KEY
  - SSH_PUBLIC_KEY
custom-env-patterns: []
custom-file-patterns: []

check-env-vars

boolean

default:"true"

Enable environment variable scanning for sensitive patterns.

check-files

boolean

default:"true"

Enable file system scanning across all image layers.

excluded-paths

array

File paths to exclude from scanning. Supports glob patterns with ** for recursive matching.

excluded-env-vars

array

Environment variable names to exclude from scanning (case-sensitive).

custom-env-patterns

array

Additional environment variable patterns to detect (case-insensitive regex).

custom-file-patterns

array

Additional file path patterns to detect (regex).

check-image secrets nginx:latest --secrets-policy config/secrets-policy.json
check-image secrets nginx:latest --secrets-policy config/secrets-policy.yaml

The secrets check works out-of-the-box with sensible defaults when no policy file is provided.

Labels Policy Files

Define required OCI annotations (labels) and their validation rules.

JSON
YAML

config/labels-policy.json

{
  "required-labels": [
    {
      "name": "maintainer"
    },
    {
      "name": "org.opencontainers.image.version",
      "pattern": "^v?\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$"
    },
    {
      "name": "org.opencontainers.image.vendor",
      "value": "MyCompany"
    },
    {
      "name": "org.opencontainers.image.source"
    },
    {
      "name": "org.opencontainers.image.created",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
    }
  ]
}

config/labels-policy.yaml

required-labels:
  - name: maintainer
  - name: org.opencontainers.image.version
    pattern: ^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$
  - name: org.opencontainers.image.vendor
    value: MyCompany
  - name: org.opencontainers.image.source
  - name: org.opencontainers.image.created
    pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$

required-labels

array

Array of label validation rules. Each rule has a name and optional value or pattern.

required-labels[].name

string

required

Label name (OCI annotation key).

required-labels[].value

string

Exact value the label must have. Mutually exclusive with pattern.

required-labels[].pattern

string

Regular expression the label value must match. Mutually exclusive with value.

Validation modes:

Existence check: Only name specified (label must be present)
Exact match: name and value specified (label value must exactly match)
Pattern match: name and pattern specified (label value must match regex)

Usage

check-image labels nginx:latest --labels-policy config/labels-policy.json
check-image labels ghcr.io/myorg/app:v1.0 --labels-policy config/labels-policy.yaml

Ports Policy Files

Define allowed exposed ports.

JSON
YAML

config/allowed-ports.json

{
  "allowed-ports": [
    80,
    443
  ]
}

config/allowed-ports.yaml

allowed-ports:
  - 80
  - 443

allowed-ports

array

Array of allowed port numbers (integers).

check-image ports nginx:latest --allowed-ports @config/allowed-ports.json
check-image ports nginx:latest --allowed-ports @config/allowed-ports.yaml

The @ prefix indicates a file path. Without it, the argument is treated as a comma-separated list.

Platforms Policy Files

Define allowed OS/architecture combinations.

JSON
YAML

config/allowed-platforms.json

{
  "allowed-platforms": [
    "linux/amd64",
    "linux/arm64",
    "linux/arm/v7"
  ]
}

config/allowed-platforms.yaml

allowed-platforms:
  - linux/amd64
  - linux/arm64
  - linux/arm/v7

allowed-platforms

array

Array of allowed platform strings in OS/Architecture or OS/Architecture/Variant format.

check-image platform nginx:latest --allowed-platforms @config/allowed-platforms.json
check-image platform nginx:latest --allowed-platforms @config/allowed-platforms.yaml

All Checks Configuration Files

Define which checks to run and their parameters for the all command.

JSON
YAML

config/config.json

{
  "checks": {
    "age": {
      "max-age": 90
    },
    "size": {
      "max-size": 500,
      "max-layers": 20
    },
    "ports": {
      "allowed-ports": "@config/allowed-ports.json"
    },
    "registry": {
      "registry-policy": "config/registry-policy.json"
    },
    "root-user": {},
    "secrets": {
      "secrets-policy": "config/secrets-policy.json",
      "skip-env-vars": false,
      "skip-files": false
    },
    "labels": {
      "labels-policy": "config/labels-policy.json"
    },
    "healthcheck": {},
    "entrypoint": {},
    "platform": {
      "allowed-platforms": "@config/allowed-platforms.json"
    }
  }
}

config/config.yaml

checks:
  age:
    max-age: 90
  size:
    max-size: 500
    max-layers: 20
  ports:
    allowed-ports: "@config/allowed-ports.json"
  registry:
    registry-policy: config/registry-policy.json
  root-user: {}
  secrets:
    secrets-policy: config/secrets-policy.json
    skip-env-vars: false
    skip-files: false
  labels:
    labels-policy: config/labels-policy.json
  healthcheck: {}
  entrypoint: {}
  platform:
    allowed-platforms: "@config/allowed-platforms.json"

checks

object

Map of check names to their configuration. Only checks present in this object are executed.

Usage

check-image all nginx:latest --config config/config.json
check-image all nginx:latest --config config/config.yaml

Precedence rules:

Without --config: all 10 checks run with defaults
With --config: only checks present in config file run
--include overrides config file check selection
--skip removes checks from any selection
CLI flags override config file values

Inline Configuration

The all command config file supports embedding policies directly as objects instead of file paths.

JSON
YAML

config/config-inline.json

{
  "checks": {
    "registry": {
      "registry-policy": {
        "trusted-registries": ["docker.io", "ghcr.io"]
      }
    },
    "labels": {
      "labels-policy": {
        "required-labels": [
          {"name": "maintainer"},
          {"name": "org.opencontainers.image.version", "pattern": "^v?\\d+\\.\\d+\\.\\d+$"}
        ]
      }
    },
    "secrets": {
      "secrets-policy": {
        "check-env-vars": true,
        "check-files": false,
        "excluded-paths": ["/usr/share/**"]
      }
    },
    "ports": {
      "allowed-ports": [80, 443]
    }
  }
}

config/config-inline.yaml

checks:
  registry:
    registry-policy:
      trusted-registries:
        - docker.io
        - ghcr.io
  labels:
    labels-policy:
      required-labels:
        - name: maintainer
        - name: org.opencontainers.image.version
          pattern: ^v?\d+\.\d+\.\d+$
  secrets:
    secrets-policy:
      check-env-vars: true
      check-files: false
      excluded-paths:
        - /usr/share/**
  ports:
    allowed-ports:
      - 80
      - 443

Benefits

Single file contains all configuration
Easier version control
Simpler deployment
Mix inline and file references

Use Cases

CI/CD pipelines
Docker builds
Kubernetes deployments
Portable validation configs

Usage

check-image all nginx:latest --config config/config-inline.yaml
check-image all nginx:latest --config config/config-inline.json --max-age 30

Reading from Standard Input

All file arguments support reading from stdin using - as the path.

echo '{"trusted-registries": ["docker.io", "ghcr.io"]}' | \
  check-image registry nginx:latest --registry-policy -

Size limit: Stdin input is limited to 10MB to prevent memory exhaustion.

Stdin conflict: --config -, --allowed-ports @-, and other stdin-reading flags cannot be combined with --password-stdin.

Dynamic Configuration from Pipelines

jq -n '{"trusted-registries": ["docker.io"]}' | \
  check-image registry nginx:latest --registry-policy -

File Locations

Check Image looks for configuration files in the following locations:

Explicit paths

Absolute or relative paths specified in flags (e.g., --registry-policy /etc/check-image/registry.json).

Current directory

Files in the current working directory (e.g., --registry-policy registry-policy.json).

Relative paths

Paths relative to the current directory (e.g., --registry-policy config/registry-policy.json).

Use relative paths in scripts and CI/CD pipelines for portability.

Best Practices

Version control policies

Store policy files in your repository alongside your Dockerfile for versioned, traceable validation rules.

Use YAML for readability

YAML is more human-readable and easier to maintain than JSON for complex policies.

Validate policies

Test policy files with simple images before using them in production pipelines.

Document custom patterns

Add comments (in YAML) or a separate README explaining custom patterns and exclusions.

Image Reference Syntax

Learn about transport prefixes and image references

Authentication

Configure credentials for private registries

Output Formats

Control output format and color modes

All Command

Run multiple checks with a single configuration file

Get Started

Usage

Commands

Integrations

Advanced

File Format Support

JSON

YAML

Configuration File Types

Registry Policy Files

Secrets Policy Files

Labels Policy Files

Ports Policy Files

Platforms Policy Files

All Checks Configuration Files

Inline Configuration

Benefits

Use Cases

Reading from Standard Input

Dynamic Configuration from Pipelines

File Locations

Best Practices

Version control policies

Use YAML for readability

Validate policies

Document custom patterns

Image Reference Syntax

Authentication

Output Formats

All Command

Build docs developers (and LLMs) love

Get Started

Usage

Commands

Integrations

Advanced

​File Format Support

JSON

YAML

​Configuration File Types

​Registry Policy Files

​Secrets Policy Files

​Labels Policy Files

​Ports Policy Files

​Platforms Policy Files

​All Checks Configuration Files

​Inline Configuration

Benefits

Use Cases

​Reading from Standard Input

​Dynamic Configuration from Pipelines

​File Locations

​Best Practices

Version control policies

Use YAML for readability

Validate policies

Document custom patterns

​Related Topics

Image Reference Syntax

Authentication

Output Formats

All Command

Build docs developers (and LLMs) love

File Format Support

Configuration File Types

Registry Policy Files

Secrets Policy Files

Labels Policy Files

Ports Policy Files

Platforms Policy Files

All Checks Configuration Files

Inline Configuration

Reading from Standard Input

Dynamic Configuration from Pipelines

File Locations

Best Practices

Related Topics