d# layerscan
A container layer vulnerability scanner that inspects tar archives for secrets, SUID binaries, environment file exposures, and secrets that persist in image history after deletion.
The package requires Python 3.10 or later.
pip install -e ".[dev]"layerscan scan --file <archive.tar>
layerscan scan --file <archive.tar> --output json
layerscan scan --file <archive.tar> --severity medium| 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 |
| Code | Meaning |
|---|---|
| 0 | No findings at or above the requested severity |
| 1 | One or more findings detected |
| 2 | Scan error |
Secrets — Scans file contents for patterns including AWS access keys, private keys, GitHub tokens, passwords, and API keys.
SUID — Reports files with the SUID bit set in the tar member metadata.
Environment files — Scans .env files for sensitive variable assignments such as passwords, tokens, and API keys.
Deleted secrets — For Docker image archives (those containing a manifest.json), the scanner processes layers in manifest order and reports secrets found in files that were subsequently removed via whiteout entries. The secret is reported against the layer that introduced the deletion, reflecting its presence in image history.
Simple tars: all files are scanned in a single pass.
Docker image tars produced by docker save: layers are processed in manifest order, enabling cross-layer state tracking and deleted secret detection.
The test suite uses pytest. Fixture tar files are generated automatically on the first test run via tests/conftest.py.
pytest tests/ -vTo inspect individual fixtures manually:
layerscan scan --file tests/fixtures/secrets.tar
layerscan scan --file tests/fixtures/clean.tar
layerscan scan --file tests/fixtures/suid.tar --output json | python -m json.tool
layerscan scan --file tests/fixtures/deleted_secret.tar
layerscan scan --file tests/fixtures/env.tar --severity mediumThe clean.tar fixture must produce exit code 0. All other fixtures produce exit code 1.