Skip to content

4. Docker

Jump to bottom
six2dez edited this page May 16, 2025 · 6 revisions

Docker Usage Guide

This guide explains how to run reconFTW using Docker, which provides a portable, isolated environment for reconnaissance and vulnerability scanning. Docker simplifies setup by bundling all dependencies, making it ideal for users who want to avoid manual tool installation. reconFTW supports three Docker workflows: pulling the official image from DockerHub, building a custom image from the repository, and creating an Ax Framework Controller image for distributed scanning.

Prerequisites:

  • Docker installed (version 20.10 or higher recommended).
  • At least 10 GB of free disk space and 4 GB of RAM.
  • Configured API keys and settings (see Post-Installation Guide).
  • Optional: Docker Rootless or user namespaces for non-root output files (see Docker Security Docs).

Note: Always review the Post-Installation Guide to configure reconftw.cfg, API keys, and notification settings for optimal results.

📔 Table of Contents

1. Pull from DockerHub

The easiest way to use reconFTW is to pull the official image from DockerHub.

Steps

  1. Pull the Image:

    docker pull six2dez/reconftw:main

    Pulls the latest reconFTW image (tag main).

  2. Download the Config File:

    wget https://raw.githubusercontent.com/six2dez/reconftw/main/reconftw.cfg

    Downloads the default reconftw.cfg for customization.

  3. Create an Output Directory:

    mkdir Recon
chmod 777 Recon

    Creates a directory for scan results and sets permissions to avoid access issues.

  4. Run the Container:

    docker run -it --rm \
  -v "${PWD}/reconftw.cfg:/reconftw/reconftw.cfg" \
  -v "${PWD}/Recon/:/reconftw/Recon/" \
  six2dez/reconftw:main -d example.com -r

    Runs a full recon scan (-r) on example.com, mounting the config file and output directory.

Notes

  • Config Customization: Edit reconftw.cfg to enable API keys, notifications, or specific modules (see Configuration File Guide).
  • Volume Mounts:
    • -v "${PWD}/reconftw.cfg:/reconftw/reconftw.cfg": Mounts the local config file.
    • -v "${PWD}/Recon/:/reconftw/Recon/": Mounts the output directory to persist results.
  • Flags:
    • -it: Enables interactive mode with a terminal.
    • --rm: Removes the container after execution to save space.
  • Rootless Setup: To avoid output files being owned by root, configure Docker Rootless or User Namespaces.

Example with Custom Options

Run a passive-only scan with AI reporting:

docker run -it --rm \
  -v "${PWD}/reconftw.cfg:/reconftw/reconftw.cfg" \
  -v "${PWD}/Recon/:/reconftw/Recon/" \
  six2dez/reconftw:main -d example.com -p -y

2. Build from Repository

Building a custom image allows you to modify the Dockerfile, embed API keys, or tailor the environment (e.g., for ARM architectures).

Steps

  1. Clone the Repository (Sparse Checkout):

    mkdir reconftw
cd reconftw
git init -b main
git remote add origin https://github.com/six2dez/reconftw.git
git sparse-checkout set "Docker/"
git pull --depth=1 origin main

    Downloads only the Docker/ directory to save space.

  2. Build the Image:

    docker buildx build -t reconftw \
  --build-arg COLLAB_SERVER='i0m1y4j3fu.canarytokens.com' \
  --build-arg XSS_SERVER='six2dez.xss.ht' \
  --build-arg SHODAN_API_KEY='XXXXXXXXXXXXX' \
  --build-arg LANG='en_US.UTF-8' \
  --build-arg LANGUAGE='en_US' \
  Docker/.

    Builds a custom image named reconftw with embedded API keys.

  3. Run the Image:

    docker run -it --rm \
  -v "${PWD}/Recon/:/reconftw/Recon/" \
  reconftw -d example.com -s

    Runs a subdomain enumeration scan (-s) with results saved to Recon/.

Notes

  • Build Arguments:
    • COLLAB_SERVER, XSS_SERVER, SHODAN_API_KEY: Optional API keys embedded in the image.
    • LANG, LANGUAGE: Set locale (default is en_US.UTF-8).
    • Omit build arguments to use defaults or configure via reconftw.cfg.
  • Custom Dockerfile: Modify Docker/Dockerfile to add tools, change base images, or support ARM (e.g., Raspberry Pi, macOS M1/M2).
  • Disk Space: Ensure at least 10 GB free for the build process.
  • Sparse Checkout: Reduces download size by fetching only the Docker/ directory.

Example Custom Dockerfile (ARM Support)

For ARM-based systems (e.g., macOS M1/M2):

# syntax=docker/dockerfile:1.4
FROM ubuntu:22.04

# Install dependencies for ARM
RUN apt-get update && apt-get install -y \
    golang-go \
    rust-all \
    git \
    curl \
    wget \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Clone and install reconFTW
RUN git clone https://github.com/six2dez/reconftw /reconftw
WORKDIR /reconftw
RUN ./install.sh

# Set entrypoint
ENTRYPOINT ["./reconftw.sh"]

Build with:

docker buildx build -t reconftw-arm --platform linux/arm64 -f Dockerfile .

3. Build Ax Framework Controller Image

This workflow creates a Docker image preconfigured for distributed scanning with the Ax Framework, ideal for large-scale scans.

Prerequisites

  • Ax Framework installed locally or access to a supported cloud provider (e.g., AWS, Linode, DigitalOcean).
  • Cloud provider API key with sufficient permissions.
  • At least 20 GB of free disk space for the image (Ax images are large, >18 GB).
  • Configured API keys and tool settings (see Post-Installation Guide).

Steps

  1. Create a Working Directory:

    mkdir reconftw
cd reconftw

    Sets up a directory for configuration files and the Dockerfile.

  2. Add Configuration Files: Copy or create the following files in the reconftw directory:

    • reconftw.cfg: Download from GitHub and customize.
    • github_tokens.txt: List GitHub Personal Access Tokens (one per line, see Post-Installation Guide).
    • provider-config.yaml: Subfinder API configuration (see Subfinder Docs).
    • personal.json: Ax Framework provider configuration (example below).

    Example personal.json (for Linode):

    {
  "do_key": "YOUR_LINODE_API_KEY",
  "region": "us-east",
  "provider": "linode",
  "default_size": "g6-standard-1",
  "appliance_name": "",
  "appliance_key": "",
  "appliance_url": "",
  "email": ""
}

    Replace YOUR_LINODE_API_KEY with your Linode API key. Adjust region and default_size for other providers (e.g., AWS, DigitalOcean).

  3. Create the Dockerfile: Save the following as Dockerfile in the reconftw directory:

    # syntax=docker/dockerfile:1.4
FROM six2dez/reconftw:main

# Copy configuration files
COPY reconftw.cfg /reconftw/reconftw.cfg
COPY github_tokens.txt /root/Tools/.github_tokens
COPY provider-config.yaml /root/.config/subfinder/provider-config.yaml
COPY personal.json /root/.axiom/accounts/personal.json

# Regenerate SSH keys and configure Ax Framework
RUN <<EOT
# Remove default SSH keys
find /root/.ssh -type f -delete
ssh-keygen -b 2048 -t rsa -f /root/.ssh/axiom_rsa -q -N ""
cat /root/.ssh/axiom_rsa.pub > /root/.axiom/configs/authorized_keys

# Configure Ax provider
axiom-account personal

# Initialize Ax provisioner (exits with code 1, so ignore failure)
axiom-build reconftw || :
EOT

# Set entrypoint
ENTRYPOINT ["/reconftw/reconftw.sh"]

    This Dockerfile extends the base image, adds configs, regenerates SSH keys, and sets up Ax.

  4. Build the Image:

    docker buildx build -t reconftw-axiom -f Dockerfile .

    Builds an image named reconftw-axiom and creates an Ax image (axiom-reconftw-xxxxxxxxxx) with your cloud provider.

  5. Run the Image:

    docker run -it --rm \
  -v "${PWD}/Recon/:/reconftw/Recon/" \
  reconftw-axiom -d example.com -r -v

    Runs a full recon scan (-r) with Ax Framework distributed scanning (-v).

Notes

  • Disk Space: Ensure your cloud provider supports images >18 GB (check provider limits).
  • Configuration Files: Add more files (e.g., notify/provider-config.yaml) to the Dockerfile as needed.
  • Ax Setup: Verify Ax is installed locally and configured (~/.axiom/axiom.json) before building.
  • Cloud Provider: Adjust personal.json for your provider (e.g., AWS: "provider": "aws", "region": "us-east-1").
  • SSH Keys: The Dockerfile regenerates SSH keys to avoid using defaults, ensuring security.

Example with AWS Provider

Update personal.json for AWS:

{
  "do_key": "AWS_ACCESS_KEY_ID:AWS_SECRET_ACCESS_KEY",
  "region": "us-east-1",
  "provider": "aws",
  "default_size": "t3.micro",
  "appliance_name": "",
  "appliance_key": "",
  "appliance_url": "",
  "email": ""
}

Rebuild and run as above.

4. Exposed Ports

reconFTW exposes ports 85-90 for specific tools (e.g., web servers for SSRF testing). To access these ports, map them when running the container.

Example

docker run -it --rm \
  -v "${PWD}/reconftw.cfg:/reconftw/reconftw.cfg" \
  -v "${PWD}/Recon/:/reconftw/Recon/" \
  -p 85-90:85-90 \
  six2dez/reconftw:main -d example.com -r

Maps host ports 85-90 to container ports 85-90.

Notes

  • Use -p only if your scan requires external access to these ports (e.g., SSRF or blind XSS testing).
  • Ensure no conflicting services are running on the host ports.
  • Credits to GitHub Issue #271 for identifying this feature.

5. Best Practices

  • Rootless Docker: Use Docker Rootless or User Namespaces to prevent output files from being owned by root. Example: 
    docker run --user $(id -u):$(id -g) ...
  • Volume Permissions: Set chmod 777 on the output directory to avoid permission issues: 
    chmod 777 Recon
  • Config Backup: Save a copy of reconftw.cfg before modifying to revert changes if needed.
  • API Key Security: Avoid embedding sensitive API keys in the Dockerfile for public builds; use reconftw.cfg or environment variables.
  • Resource Allocation: Allocate sufficient CPU and memory for large scans (e.g., --deep or -a): 
    docker run --cpus="2" --memory="4g" ...
  • Clean Up: Use --rm to remove containers after execution and periodically prune unused images: 
    docker image prune
  • ARM Compatibility: For ARM systems (e.g., Raspberry Pi, macOS M1/M2), build a custom image with --platform linux/arm64.
  • Ax Framework: Test Ax connectivity before running distributed scans (axiom-fleet ls).
  • AI Reporting: Ensure the container has access to a local AI model (e.g., Ollama) for -y scans: 
    docker run --network host ... -y

6. Troubleshooting

  • Permission Denied on Output Files:
    • Use Docker Rootless or user namespaces (see Docker Docs).
    • Set chmod 777 Recon before running the container.
  • Missing Results:
    • Verify reconftw.cfg is mounted correctly (-v "${PWD}/reconftw.cfg:/reconftw/reconftw.cfg").
    • Check API keys in reconftw.cfg (e.g., SHODAN_API_KEY, GITHUB_TOKENS).
  • Build Failures:
    • Ensure sufficient disk space (>10 GB for standard, >20 GB for Ax).
    • Check Dockerfile syntax and build arguments.
    • Run with --no-cache to avoid stale layers: 
      docker buildx build --no-cache -t reconftw .
  • Ax Framework Issues:
    • Verify personal.json has valid credentials and provider settings.
    • Check Ax fleet status (axiom-fleet ls) and cloud provider limits.
  • Tool Installation Errors:
    • Inspect container logs: 
      docker run -it six2dez/reconftw:main bash
    • Rerun ./install.sh inside the container with DEBUG_STD="" in reconftw.cfg.
  • Network Issues:
    • Ensure the container has internet access (--network host if needed).
    • Check proxy settings (proxy_url in reconftw.cfg).
  • AI Reporting Errors:
    • Confirm Ollama is running on the host and accessible (--network host).
    • Verify AI_MODEL and AI_REPORT_TYPE in reconftw.cfg.

For further assistance, join the Discord server or Telegram group.

Next Steps

Clone this wiki locally