Skip to main content

​
Description

Validates that the container image does not contain sensitive data (passwords, tokens, keys). Scans both environment variables and files across all image layers for common secret patterns.

​
Command Syntax

check-image secrets <image> [flags]

​
Flags

FlagShortTypeDefaultDescription
--secrets-policy-sstring-Secrets policy file (JSON or YAML) (optional)
--skip-env-vars-boolfalseSkip environment variable checks (optional)
--skip-files-boolfalseSkip file system checks (optional)
--output-ostringtextOutput format: text or json
--log-level-stringinfoLog level (trace, debug, info, warn, error, fatal, panic)

​
How It Works

​
Environment Variable Scanning

Scans all environment variables for sensitive patterns using case-insensitive keyword matching. Default patterns include:
  • password
  • passwd
  • secret
  • token
  • key
  • credential
  • auth
  • api
Default exclusions (known false positives):
  • PUBLIC_KEY
  • SSH_PUBLIC_KEY

​
File System Scanning

Scans all image layers for files matching sensitive patterns. Default patterns include: SSH Keys:
  • id_rsa - SSH private key
  • id_dsa - SSH private key
  • id_ecdsa - SSH private key
  • id_ed25519 - SSH private key
  • *.ppk - PuTTY private key
Cloud Credentials:
  • .aws/credentials - AWS credentials
  • .kube/config - Kubernetes config
Private Keys:
  • *.key - private key file
Password Files:
  • /etc/shadow - shadow password file
  • .pgpass - PostgreSQL password file
  • .my.cnf - MySQL credentials
  • .netrc - authentication credentials
Other Credentials:
  • .npmrc - NPM credentials
  • .git-credentials - Git credentials
  • secrets.json - secrets file
  • secrets.yaml - secrets file
  • secrets.yml - secrets file
  • wallet.dat - cryptocurrency wallet

​
Usage Examples

​
Basic Usage (No Policy File)

Runs with sensible defaults: 
check-image secrets nginx:latest

​
With Custom Policy File

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

​
Skip Environment Variable Checks

check-image secrets nginx:latest --skip-env-vars

​
Skip File System Checks

check-image secrets nginx:latest --skip-files

​
Policy from stdin

cat secrets-policy.yaml | check-image secrets nginx:latest --secrets-policy -

​
OCI Archive

check-image secrets oci-archive:/path/to/image.tar:latest --secrets-policy config/secrets-policy.json

​
Example Output

​
Text Format (Success)

✓ No secrets detected

​
Text Format (Failure)

✗ Secrets detected

Environment Variables (2):
  - AWS_SECRET_KEY: authentication credentials
  - DATABASE_PASSWORD: authentication credentials

Files (1):
  - /root/.aws/credentials (layer 3): AWS credentials

Total Findings: 3

​
JSON Format

{
  "check": "secrets",
  "image": "nginx:latest",
  "passed": false,
  "message": "Secrets detected",
  "details": {
    "env-var-findings": [
      {
        "name": "AWS_SECRET_KEY",
        "description": "authentication credentials"
      },
      {
        "name": "DATABASE_PASSWORD",
        "description": "authentication credentials"
      }
    ],
    "file-findings": [
      {
        "path": "/root/.aws/credentials",
        "layer-index": 3,
        "description": "AWS credentials"
      }
    ],
    "total-findings": 3,
    "env-var-count": 2,
    "file-count": 1
  }
}

​
Policy File Format

​
YAML Example

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:
  - MY_SECRET
  
custom-file-patterns:
  - "*.pem"

​
JSON Example

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

​
Policy Configuration Options

FieldTypeDefaultDescription
check-env-varsbooltrueEnable environment variable scanning
check-filesbooltrueEnable file system scanning
excluded-pathsarray[]Glob patterns for paths to exclude from file scanning
excluded-env-varsarray["PUBLIC_KEY", "SSH_PUBLIC_KEY"]Environment variable names to exclude
custom-env-patternsarray[]Additional keywords for environment variable scanning
custom-file-patternsarray[]Additional file patterns to detect

​
Exit Codes

| Exit Code | Meaning | Example | |-----------|---------|---------|----------| | 0 | No secrets detected | Image is clean | | 1 | Secrets detected | Image contains sensitive data | | 2 | Execution error | Invalid policy file, image not found |
  • config/secrets-policy.yaml - Sample secrets policy in YAML format
  • config/secrets-policy.json - Sample secrets policy in JSON format

​
Notes

  • The check scans all image layers, not just the final filesystem. Secrets in earlier layers remain in the image history.
  • Works out-of-the-box with sensible defaults when no policy file is provided.
  • Environment variable detection uses case-insensitive pattern matching.
  • Exclusion patterns support glob syntax (e.g., /usr/share/**).
  • CLI flags (--skip-env-vars, --skip-files) override policy file settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us