Docker Deployment

Run NetScan in Docker containers for easy deployment, isolation, and consistent environments across different systems.

Overview

NetScan provides full Docker support with:

Multi-stage build: Optimized image with Rust performance module
Docker Compose: Easy orchestration with persistent volumes
Helper script: Simple commands for common operations
Web interface: Browser-based access via container

Quick Start

Get started with Docker in seconds:

# Clone repository
git clone https://github.com/G1A1B1E/NetScan.git
cd NetScan

# Build and run
docker compose up -d

# Attach to interactive menu
docker attach netscan

Or use the helper script:

# Build image
./docker.sh build

# Run interactive menu
./docker.sh run

Building the Image

Standard Build

# Build with Docker
docker build -t netscan .

# Build with Docker Compose
docker compose build

# Build with helper script
./docker.sh build

Build Options

# Build without cache (fresh build)
docker build --no-cache -t netscan .

# Build with specific Python version
docker build --build-arg PYTHON_VERSION=3.11 -t netscan .

# Build for specific platform
docker build --platform linux/amd64 -t netscan .

Dockerfile Structure

The multi-stage Dockerfile provides an optimized build:

# Stage 1: Rust builder (optional performance module)
FROM rust:1.75-slim AS rust-builder
WORKDIR /app
COPY rust_helpers/ ./rust_helpers/
RUN cd rust_helpers && cargo build --release

# Stage 2: Python runtime
FROM python:3.11-slim
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    nmap arp-scan iproute2 iputils-ping \
    && rm -rf /var/lib/apt/lists/*

# Copy application
COPY . .

# Install Python packages
RUN pip install --no-cache-dir requests netifaces

# Copy compiled Rust module
COPY --from=rust-builder /app/target/release/*.so ./helpers/

ENTRYPOINT ["./netscan"]
CMD ["--help"]

Running Containers

Interactive Mode

# Run interactive menu
docker run -it --rm --network host --cap-add NET_RAW netscan

# With helper script
./docker.sh run

MAC Lookup (No Special Permissions)

# Single lookup
docker run --rm netscan -l 00:11:22:33:44:55

# Batch lookup
docker run --rm -v $(pwd)/macs.txt:/data/macs.txt netscan -b /data/macs.txt

# With helper script
./docker.sh lookup 00:11:22:33:44:55

Network Scanning (Requires Permissions)

# Quick scan
docker run --rm --network host --cap-add NET_RAW netscan -s

# Full scan with all capabilities
docker run --rm \
  --network host \
  --cap-add NET_RAW \
  --cap-add NET_ADMIN \
  netscan -f

# Scan specific target
./docker.sh scan 192.168.1.0/24

⚠️ Required for Network Scanning:

--network host — Access to host network interfaces
--cap-add NET_RAW — Required for ping and ARP operations
--cap-add NET_ADMIN — Required for interface operations

Docker Compose

docker-compose.yml

version: '3.8'

services:
  netscan:
    build: .
    image: netscan:latest
    container_name: netscan
    stdin_open: true
    tty: true
    network_mode: host
    cap_add:
      - NET_RAW
      - NET_ADMIN
    volumes:
      - netscan-data:/app/data
      - netscan-logs:/app/logs
      - netscan-cache:/app/cache
      - netscan-exports:/app/exports
    environment:
      - NETSCAN_LOG_LEVEL=INFO
    restart: unless-stopped

  # Optional web interface
  netscan-web:
    build: .
    image: netscan:latest
    container_name: netscan-web
    network_mode: host
    cap_add:
      - NET_RAW
      - NET_ADMIN
    volumes:
      - netscan-data:/app/data
    command: ["-w", "--port", "8080"]
    profiles:
      - web

volumes:
  netscan-data:
  netscan-logs:
  netscan-cache:
  netscan-exports:

Basic Commands

# Start container
docker compose up -d

# Attach to running container
docker attach netscan

# View logs
docker compose logs -f

# Stop container
docker compose down

# Stop and remove volumes
docker compose down -v

Start with Web Interface

# Start with web profile
docker compose --profile web up -d

# Access web interface
open http://localhost:8080

Helper Script

The docker.sh script simplifies common Docker operations:

Available Commands

./docker.sh build              # Build the Docker image
./docker.sh run                # Run interactive menu
./docker.sh scan [target]      # Network scan (default: auto-detect)
./docker.sh lookup        # MAC address lookup
./docker.sh web [port]         # Start web interface
./docker.sh shell              # Open shell in container
./docker.sh logs               # View container logs
./docker.sh clean              # Remove containers and images

Examples

# Build and run
./docker.sh build
./docker.sh run

# Scan home network
./docker.sh scan 192.168.1.0/24

# Look up Apple device
./docker.sh lookup AC:DE:48:00:11:22

# Start web interface on port 9000
./docker.sh web 9000

# Debug issues
./docker.sh shell
./docker.sh logs

Persistent Volumes

Docker Compose creates persistent volumes for data:

Volume	Path	Purpose
`netscan-data`	/app/data	OUI database, configurations
`netscan-logs`	/app/logs	Application logs
`netscan-cache`	/app/cache	Lookup cache
`netscan-exports`	/app/exports	Exported scan results

Mount Local Directories

# Mount local exports directory
docker run --rm \
  --network host \
  --cap-add NET_RAW \
  -v $(pwd)/exports:/app/exports \
  netscan -s -o /app/exports/scan.json

Backup Volumes

# Backup data volume
docker run --rm -v netscan-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/netscan-data.tar.gz -C /data .

# Restore data volume
docker run --rm -v netscan-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/netscan-data.tar.gz -C /data

Environment Variables

Configure NetScan behavior with environment variables:

Variable	Default	Description
`NETSCAN_LOG_LEVEL`	INFO	Logging level (DEBUG, INFO, WARN, ERROR)
`NETSCAN_CACHE_TTL`	3600	Cache TTL in seconds
`NETSCAN_TIMEOUT`	5	Network timeout in seconds
`NETSCAN_THREADS`	auto	Number of scan threads

# Run with custom environment
docker run --rm \
  -e NETSCAN_LOG_LEVEL=DEBUG \
  -e NETSCAN_TIMEOUT=10 \
  --network host \
  --cap-add NET_RAW \
  netscan -s

Web Interface in Docker

Start Web Server

# Using docker compose
docker compose --profile web up -d

# Using docker run
docker run -d \
  --name netscan-web \
  --network host \
  --cap-add NET_RAW \
  netscan -w --port 8080

# Using helper script
./docker.sh web 8080

Access the Interface

# Open in browser
open http://localhost:8080

# Or using curl
curl http://localhost:8080/api/status

Advanced Usage

Custom Dockerfile

Create a custom image with additional tools:

FROM netscan:latest

# Add additional tools
RUN apt-get update && apt-get install -y \
    wireshark-common \
    tcpdump \
    && rm -rf /var/lib/apt/lists/*

# Custom configuration
COPY my-config.json /app/config/

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: netscan
spec:
  replicas: 1
  selector:
    matchLabels:
      app: netscan
  template:
    metadata:
      labels:
        app: netscan
    spec:
      hostNetwork: true
      containers:
      - name: netscan
        image: netscan:latest
        command: ["-w", "--port", "8080"]
        securityContext:
          capabilities:
            add: ["NET_RAW", "NET_ADMIN"]
        ports:
        - containerPort: 8080

CI/CD Integration

# GitHub Actions example
name: Build NetScan Docker
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Build image
        run: docker build -t netscan .
      
      - name: Test image
        run: docker run --rm netscan --version
      
      - name: Push to registry
        run: |
          docker tag netscan ghcr.io/${{ github.repository }}:latest
          docker push ghcr.io/${{ github.repository }}:latest

Troubleshooting

No devices found

# Ensure host network mode
docker run --network host ...

# Check network interfaces inside container
./docker.sh shell
ip addr show

Permission denied

# Add required capabilities
docker run --cap-add NET_RAW --cap-add NET_ADMIN ...

Container won't start

# Check logs
docker logs netscan

# Run with debug output
docker run -e NETSCAN_LOG_LEVEL=DEBUG netscan

Web interface not accessible

# Check if port is exposed
docker ps -a

# Check if web server is running
docker exec netscan ps aux | grep python