Skip to main content
The registry command validates that a container image comes from a trusted registry based on a policy file. This ensures images are pulled only from approved sources.

​
Usage

check-image registry <image> --registry-policy <file>

​
Description

The registry command extracts the registry hostname from the image reference and validates it against a policy file. The policy can specify either trusted registries (allowlist) or excluded registries (blocklist). This check helps:
  • Enforce image provenance policies
  • Prevent unauthorized image sources
  • Ensure images come from approved registries
  • Maintain supply chain security
  • Comply with organizational security policies
Registry validation is automatically skipped for non-registry transports (OCI layout, archives)

​
Flags

​
--registry-policy
string
required
Path to registry policy file (JSON or YAML format). Use - to read from stdin.Short form: -r
​
--output
string
default:"text"
Output format: text or jsonShort form: -o
​
--color
string
default:"auto"
Color output mode: auto, always, never
​
--log-level
string
default:"info"
Set log level: trace, debug, info, warn, error, fatal, panic

​
Policy File Format

The policy file must specify either trusted-registries (allowlist) or excluded-registries (blocklist), but not both.

​
Allowlist Mode (Trusted Registries)

Only registries in the list are allowed: 
trusted-registries:
  - docker.io
  - ghcr.io
  - gcr.io
  - registry.example.com

​
Blocklist Mode (Excluded Registries)

All registries except those in the list are allowed: 
excluded-registries:
  - untrusted.example.com
  - malicious-registry.net

​
Examples

​
Validate with policy file

check-image registry nginx:latest --registry-policy registry-policy.json

​
Validate fully qualified image

check-image registry docker.io/library/nginx:latest --registry-policy registry-policy.yaml

​
Policy from stdin

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

​
Dynamic policy generation

cat registry-policy.yaml | \
  check-image registry myapp:latest --registry-policy -

​
JSON output

check-image registry nginx:latest --registry-policy policy.json -o json

​
Output

​
Text Format

When validation passes: 
✓ Registry docker.io is trusted

Details:
  Registry: docker.io
When validation fails: 
✗ Registry untrusted.example.com is not trusted

Details:
  Registry: untrusted.example.com
When skipped (non-registry transport): 
✓ Registry validation skipped (not applicable for this transport)

​
JSON Format

{
  "check": "registry",
  "image": "nginx:latest",
  "passed": true,
  "message": "Registry docker.io is trusted",
  "details": {
    "registry": "docker.io"
  }
}
Skipped (non-registry): 
{
  "check": "registry",
  "image": "oci:/path/to/layout:1.0",
  "passed": true,
  "message": "Registry validation skipped (not applicable for this transport)",
  "details": {
    "skipped": true
  }
}

​
Exit Codes

CodeMeaningExample
0Registry is trusted or check skippeddocker.io with trusted-registries containing docker.io
1Registry is not trusteduntrusted.com with trusted-registries not containing untrusted.com
2Execution errorInvalid policy file, missing registry-policy flag

​
Configuration

When using the all command, configure registry validation in your config file: 
checks:
  registry:
    registry-policy: config/registry-policy.yaml

​
Inline Policy

You can embed the policy directly in the all-checks config: 
checks:
  registry:
    registry-policy:
      trusted-registries:
        - docker.io
        - ghcr.io
        - gcr.io

​
Implementation Details

  • Extracts registry hostname from image reference
  • Default registry is docker.io for images without explicit registry
  • Policy must specify exactly one mode (trusted or excluded)
  • Registry matching is exact (no wildcards or patterns)
  • Validation is skipped for OCI layout and archive transports

​
Common Issues

​
Missing registry-policy flag

Error: required flag(s) "registry-policy" not set
Solution: Always provide --registry-policy flag with a valid policy file.

​
Both trusted and excluded specified

Error: policy must specify either trusted-registries or excluded-registries, not both
Solution: Use only one mode in your policy file.

​
Neither trusted nor excluded specified

Error: policy must specify either trusted-registries or excluded-registries
Solution: Add at least one of the required fields to your policy file.

​
Registry mismatch

If your image reference doesn’t include a registry, docker.io is assumed: 
# These are equivalent
check-image registry nginx:latest --registry-policy policy.json
check-image registry docker.io/library/nginx:latest --registry-policy policy.json

​
Best Practices

Use allowlist mode (trusted-registries) for stricter security
Include all registries used by your base images
Document why each registry is trusted in comments
Regularly review and update your registry policy
Use environment-specific policies (dev vs prod)
Don’t add unknown registries to the trusted list without vetting them first

​
Registry Hostname Extraction

check-image extracts the registry hostname from the image reference:
Image ReferenceExtracted Registry
nginx:latestdocker.io
docker.io/nginx:latestdocker.io
docker.io/library/nginx:latestdocker.io
ghcr.io/user/app:v1ghcr.io
registry.example.com:5000/app:latestregistry.example.com:5000
localhost:5000/test:latestlocalhost:5000
  • all - Run all checks including registry validation
  • secrets - Validate image doesn’t contain secrets
  • labels - Validate image labels

Build docs developers (and LLMs) love

Get started for freeTalk to us