Docker Execution¶

All pentest tools run inside the pentest-tools Docker container. This is an iron rule with no exceptions -- it ensures isolation, reproducibility, and zero host contamination.

The Iron Rule¶

Docker-Only Execution

ALL pentest tools MUST run inside Docker. NEVER execute tools locally on the host machine.

The only exceptions are:

git -- version control
gh -- GitHub CLI
docker itself -- container management
Text editors / IDE commands

If a tool is not in Docker, add it to the Dockerfile first. Never pip install or go install on the host.

Why Docker¶

Benefit	Explanation
Isolation	Tools cannot access host filesystem beyond the mounted volume
Reproducibility	Same tool versions, same PATH, same dependencies on every machine
No host contamination	Go binaries, Python packages, and system libraries stay inside the container
Consistent PATH	All tools are pre-configured and accessible without manual PATH setup
Cross-platform	Works identically on Windows, macOS, and Linux

Image Setup¶

Building the Image¶

docker build -t pentest-tools .

The image name is pentest-tools (local build). The Dockerfile at the project root is an all-in-one container that includes curl-impersonate, ysoserial, Playwright, and all scanning/testing tools.

Rebuilding¶

Rebuild after any Dockerfile change:

docker build -t pentest-tools .

Tool Invocation¶

Single Command¶

docker run --rm -v $(pwd):/work pentest-tools <tool> <args>

Interactive Session¶

docker run --rm -it -v $(pwd):/work pentest-tools

Python Scripts¶

Always Use the Virtual Environment

Inside Docker, always use /opt/pentest-venv/bin/python3 -- never bare python3. The system Python has no packages installed; all dependencies are in the virtual environment.

# Run a Python script
docker run --rm -v $(pwd):/work pentest-tools \
    /opt/pentest-venv/bin/python3 /work/script.py

# Run the Playwright crawler
docker run --rm -v $(pwd):/work pentest-tools \
    /opt/pentest-venv/bin/python3 /work/browser/crawler.py --role admin

Volume Mounting¶

The -v $(pwd):/work flag mounts the current directory as /work inside the container. This gives tools access to:

scope.txt -- target scope definition
credentials.json -- multi-user credentials
context.json -- engagement state
wordlists/ -- custom wordlists
logs/ -- output directory for tool results
findings/ -- vulnerability reports
evidence/ -- response dumps and screenshots

All tool output written to /work/ persists on the host after the container exits (--rm).

Common Examples¶

Reconnaissance¶

# Subdomain enumeration
docker run --rm -v $(pwd):/work pentest-tools \
    subfinder -d example.com -o /work/recon/subdomains.txt

# HTTP probing
docker run --rm -v $(pwd):/work pentest-tools \
    httpx -l /work/recon/subdomains.txt -silent -status-code -title

Discovery¶

# Content discovery with ffuf
docker run --rm -v $(pwd):/work pentest-tools \
    ffuf -w /work/wordlists/common.txt -u https://example.com/FUZZ -o /work/discovery/ffuf-results.json

# JavaScript analysis
docker run --rm -v $(pwd):/work pentest-tools \
    jsluice urls /work/discovery/scripts/*.js

Scanning¶

# Nuclei vulnerability scanning
docker run --rm -v $(pwd):/work pentest-tools \
    nuclei -l /work/discovery/targets.txt -o /work/logs/nuclei-results.txt

# SQL injection testing
docker run --rm -v $(pwd):/work pentest-tools \
    sqlmap -u "https://example.com/api/search?q=test" --batch --output-dir=/work/logs/sqlmap/

Playwright Browser¶

# Headless browser crawl
docker run --rm -v $(pwd):/work pentest-tools \
    /opt/pentest-venv/bin/python3 /work/browser/crawler.py \
    --target https://example.com --role admin

Adding New Tools¶

If a tool is missing from the container:

Edit the Dockerfile at the project root
Add the installation commands (apt, go install, pip install, etc.)
Rebuild: docker build -t pentest-tools .
Verify: docker run --rm pentest-tools which <tool-name>

Never Install on Host

Do not install pentest tools on the host machine. This breaks reproducibility and may leave artifacts on your system.

Windows-Specific Notes¶

Heredoc Limitation¶

Critical: Heredocs Fail in Docker on Git Bash (Windows)

docker run ... python3 << 'PYEOF' fails silently on Git Bash for Windows -- stdin heredoc is not piped into the container.

Fix: Write a .py file on the host, then run it via Docker:

# WRONG -- fails silently on Windows Git Bash
docker run --rm -v $(pwd):/work pentest-tools python3 << 'PYEOF'
print("hello")
PYEOF

# CORRECT -- write file first, then execute
cat > /tmp/script.py << 'PYEOF'
print("hello")
PYEOF
docker run --rm -v $(pwd):/work pentest-tools \
    /opt/pentest-venv/bin/python3 /work/tmp/script.py

Python Command¶

On the host (Windows), use python not python3 -- only python.exe is on PATH. Inside Docker, always use /opt/pentest-venv/bin/python3.

UTF-8 Encoding¶

For Python scripts that output to stdout on Windows, use binary mode to avoid cp1252 encoding errors:

import sys
sys.stdout.buffer.write(content.encode('utf-8'))

Docker and VPN¶

Host VPN Does Not Route Docker Traffic

If you are connected to a VPN on the host, Docker container traffic does not automatically route through it. See VPN Routing for the vpn-start.sh solution.

Docker and Proxy¶

When using --proxy to route through Burp Suite or Caido, the proxy flag is passed to tools inside the container. TLS verification is disabled (-k) to allow the proxy to intercept HTTPS traffic. See Proxy Integration for details.