johncostanzo/network-toolbox repository overview

⁠Network Toolbox

A hardened Debian-based Docker container preconfigured with essential networking and reconnaissance tools. It is designed for SSH-based terminal access with a persistent workspace and a non-root operating model.

Disclaimer: This image bundles network scanning and reconnaissance tools (including nmap and arp-scan). Only use them against networks and systems you own or have explicit authorization to test - scanning networks without permission may violate the law in your jurisdiction. This software is provided as is, without warranty of any kind; use it at your own risk.

⁠Features

• Minimal Debian Bookworm Slim base image
• SSH access using key-based authentication
• Non-root default user (toolbox)
• Persistent workspace for scripts, data, and scan results
• Automatic nightly image rebuilds

⁠Included Tools

⁠Reconnaissance & Scanning

⁠Networking Utilities

⁠Remote Access

⁠Text Editing

⁠Security

• Runs as the non-root toolbox user by default
• Root SSH login is disabled
• Password authentication is disabled
• SSH key authentication only
• Minimal Debian Bookworm Slim image reduces the attack surface
• Passwordless sudo is available for the toolbox user when elevated privileges are required

⁠Project Structure

network-toolbox/
├── data/                 # Configs, target lists, notes
├── results/              # Scan results, reports, logs
├── scripts/              # Automation and helper scripts
└── ssh/                  # Container SSH configurations
    └── authorized_keys   # Injected SSH public keys

⁠Directory Permissions & Ownership

To ensure proper data persistence and container access, the host file system must maintain strict ownership and permission definitions:

Note: UID/GID 1000 corresponds directly to the internal non-root toolbox user executing tasks inside the running container.

⁠Docker Compose Configuration

Deploy the toolbox using the following compose.yaml specification. This deployment utilizes host network mode and adds capabilities required for low-level packet manipulation.

services:
  toolbox:
    image: johncostanzo/network-toolbox:latest
    container_name: network-toolbox
    hostname: network-toolbox
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    restart: unless-stopped
    stdin_open: true
    tty: true
    volumes:
      - /volume1/docker/network-toolbox/results:/workspace/results
      - /volume1/docker/network-toolbox/scripts:/workspace/scripts
      - /volume1/docker/network-toolbox/data:/workspace/data
      - /volume1/docker/network-toolbox/ssh:/home/toolbox/.ssh:ro

⁠Persistent Directories

The following directories are mounted into the container and persist across upgrades:

data/
results/
scripts/

Store scan outputs, scripts, target lists, and notes here so they are retained when the container is rebuilt or updated.

⁠SSH Access

Connect using your SSH private key:

ssh -i /path/to/id_ed25519 toolbox@<SERVER_IP>

The corresponding public key is read by the container directly from the local ssh/authorized_keys volume mount. The private key remains safe on your local client machine.

⁠Example Commands

Scan the local Class C subnet (192.168.1.0/24) to discover active hosts and open ports:

nmap 192.168.1.0/24

Discover active IP addresses on the local network using ARP requests (requires root/sudo):

arp-scan --localnet

Scan for open ports between 1 and 1024 on a specific host using Netcat verbose mode without sending data (-zv):

nc -zv 192.168.1.1 1-1024

Perform a standard DNS lookup for openai.com to view its A records and nameserver response:

dig openai.com

Fetch the raw HTML source content of a web page over a secure HTTPS connection:

curl https://example.com

Connect to a remote web server over port 443 to inspect the SSL/TLS certificate chain and handshake details:

openssl s_client -connect example.com:443