docker

Docker Source

Overview

The Docker source enables TruffleHog to scan Docker images for secrets, credentials, and sensitive data. It supports scanning images from multiple sources including Docker registries, local Docker daemon, and tarball files.

Docker Fundamentals

What is Docker?

Docker is a containerization platform that packages applications and their dependencies into isolated containers. A Docker image is a read-only template used to create containers, consisting of multiple layers stacked on top of each other.

Key Docker Terminology

Features

• Multiple Image Sources: Scan images from remote registries, local Docker daemon, or tarball files
• Layer-by-Layer Scanning: Examines each layer independently for comprehensive coverage
• History Metadata Scanning: Analyzes image build history for exposed secrets in commands
• Concurrent Processing: Parallel layer scanning for improved performance
• Authentication Support: Multiple authentication methods for private registries
• File Exclusion: Configure patterns to skip specific files or directories
• Size Limits: Automatically skips files exceeding 50MB to optimize performance

Configuration

Connection Types

The Docker source supports several image reference formats:

// Remote registry (default)
"nginx:latest"
"myregistry.com/myapp:v1.0.0"
"gcr.io/project/image@sha256:abcd1234..."

// Local Docker daemon
"docker://nginx:latest"

// Tarball file
"file:///path/to/image.tar"

Authentication Methods

1. Unauthenticated (Public Images)

For public images that don't require authentication:

YAML Configuration:

sources:
  - type: docker
    name: public-images
    docker:
      unauthenticated: {}
      images:
        - nginx:latest
        - alpine:3.18

CLI Usage:

trufflehog docker --image nginx:latest

2. Basic Authentication

For private registries requiring username and password:

YAML Configuration:

sources:
  - type: docker
    name: private-registry
    docker:
      basic_auth:
        username: myuser
        password: mypassword
      images:
        - myregistry.com/private-image:latest
        - myregistry.com/another-image:v1.0.0

CLI Usage:

Trufflehog does not provide basic authentication using username and password through CLI at the moment.

3. Bearer Token

For registries using token-based authentication (e.g., Dockerhub registry):

YAML Configuration:

sources:
  - type: docker
    name: truffle-packages
    docker:
      bearer_token: "ghp_xxxxxxxxxxxxxxxxxxxx"
      images:
        - myorg/myapp:latest
        - myorg/frontend:v2.1.0

CLI Usage:

trufflehog docker --image myorg/myapp:latest --bearer-token eyJ_xxxxxxxxxxxxxxxxxxxx

4. Docker Keychain

Uses credentials from your local Docker configuration (~/.docker/config.json):

YAML Configuration:

sources:
  - type: docker
    name: local-docker-creds
    docker:
      docker_keychain: true
      images:
        - myregistry.com/private-image:latest
        - docker.io/myorg/app:latest

CLI Usage:

# First, authenticate with Docker
docker login myregistry.com

# Then scan using stored credentials
trufflehog docker --image myregistry.com/private-image:latest

Prerequisites:

# Authenticate with your registry first
docker login
docker login ghcr.io
docker login quay.io

# Verify credentials are stored
cat ~/.docker/config.json

File Exclusion

Exclude specific files or directories from scanning using glob patterns:

trufflehog docker --image myregistry.com/private-image:latest --exclude-paths **/*.log

How Image Scanning Works

Scanning Process

1. Image Retrieval: Fetches the image from the specified source (registry, daemon, or file)
2. History Scanning: Extracts and scans image configuration history for secrets in build commands
3. Layer Processing: Iterates through each layer in parallel
4. File Extraction: Decompresses and extracts files from each layer
5. Content Scanning: Analyzes file contents for secrets and credentials
6. Chunk Generation: Emits chunks of data to the detection engine

What Gets Scanned

• Layer Contents: All files within each image layer
• Build History: Commands used to build the image (FROM, RUN, ENV, etc.)
• Configuration: Environment variables and labels
• Metadata: Image annotations and custom metadata

What Doesn't Get Scanned

• Files larger than 50MB (configurable limit)
• Files matching exclude patterns
• Empty layers (no content changes)

Usage Examples

Scanning a Public Image

trufflehog docker --image nginx:latest

Scanning Multiple Images

trufflehog docker --image nginx:latest --image postgres:13 --image redis:alpine

Scanning from Local Docker Daemon

trufflehog docker --image docker://myapp:local

Scanning a Tarball

# First, save an image to a tarball
docker save myapp:latest -o myapp.tar

# Then scan it
trufflehog docker --image file:///path/to/myapp.tar

Scanning Private Registry with Authentication

docker login my-registry.io
trufflehog docker --image my-registry.io/private-app:v1.0.0

Testing Results

Integration Test Results

Troubleshooting

Common Issues

Issue: Authentication failures with private registries

Solution: Ensure credentials are correct and have pull permissions. Use docker login first when using Docker Keychain method.

Issue: Out of memory errors with large images

Solution: Reduce concurrency or scan smaller images. Consider increasing available memory.

Issue: Slow scanning performance

Solution: Enable concurrent processing, use local daemon instead of remote registry, or exclude unnecessary directories.

Issue: Files not being scanned

Solution: Check exclude patterns and file size limits. Verify files are under 50MB.