Overview
A Python command-line tool that scans container image tar archives layer by layer, detecting secrets, SUID binaries, exposed environment files, and secrets that survive deletion within Docker image history. It understands Docker’s layered format, allowing it to catch credentials that were removed from the final image but remain recoverable from earlier layers.
layerscan scan --file myimage.tar
[HIGH] layer sha256:a1b2c3... AWS access key found in /app/config.py
[CRITICAL] layer sha256:d4e5f6... Private key found in /root/.ssh/id_rsa (deleted in layer sha256:789abc...)
[MEDIUM] layer sha256:a1b2c3... SUID binary: /usr/bin/custom-tool
[HIGH] layer sha256:a1b2c3... .env file exposes PASSWORD= in /app/.env
The Problem
Removing a file from a Docker image does not erase it from history. Each RUN, COPY, or ADD instruction creates a new layer; a secret committed in layer 3 and deleted in layer 4 is still fully readable by anyone who pulls the image. Standard image scanners that only inspect the final filesystem miss these ghost secrets entirely.
What It Detects
| Detector | What It Finds |
|---|
| Secrets | AWS keys, private keys, GitHub tokens, passwords, API keys in file contents |
| SUID | Files with the SUID bit set in tar member metadata |
| Environment files | Sensitive variable assignments in .env files (passwords, tokens, API keys) |
| Deleted secrets | Secrets in files later removed via whiteout entries, traced back to the originating layer |
Usage
layerscan scan --file <archive.tar>
layerscan scan --file <archive.tar> --output json
layerscan scan --file <archive.tar> --severity medium
Options
| Option | Values | Default | Description |
|---|
--file | path | required | Path to the tar archive |
--output | text, json | text | Output format |
--severity | low, medium, high, critical | low | Minimum severity to report |
Exit codes
| Code | Meaning |
|---|
| 0 | No findings at or above the requested severity |
| 1 | One or more findings detected |
| 2 | Scan error |
Simple tars scan all files in a single pass. Docker image tars produced by docker save are processed in manifest order, enabling cross-layer state tracking and the detection of deleted secrets.
Tech Stack
| Component | Detail |
|---|
| Language | Python 3.10+ |
| Input format | Tar archives, Docker image tars (docker save) |
| Output formats | Text, JSON |
| Test framework | pytest with auto-generated fixture tars |
GitHub Repository
github.com/FrancescoCitti/container-vulnerability-scanner