NMAP Agent v2.0 - Red Team Scanner

A comprehensive Go-based nmap scanner agent designed for cyber defense competitions. Features parallel scanning, UDP detection, vulnerability scripts, IP rotation, and automatic result caching.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Enabling Parallel Mode
• Ports and Scripts
• Troubleshooting

---

Features

Scanning Capabilities

• Parallel scanning - Run multiple scans concurrently with worker pool
• TCP + UDP - Comprehensive coverage including DNS, SNMP, TFTP
• 170+ ports - All common services, databases, web apps, Windows services
• NSE vulnerability scripts - Detect EternalBlue, Heartbleed, anonymous FTP, empty passwords
• OS detection - Identify operating systems
• Service version detection - Identify software versions

Reliability

• Result caching - Never lose data if upload fails
• Automatic retry - Configurable retry attempts for uploads
• Cached result recovery - Automatically uploads cached results on startup
• Adaptive timing - Automatically slows down if hosts are missed

Evasion

• IP rotation - Change source IP between scans (with runner.sh)
• Stealth mode - Optional decoy scanning

---

Prerequisites

Operating System

• Linux (tested on Ubuntu 22.04/24.04, Debian 12, Kali)

Required Software

1. Go 1.21 or later

# Check if installed
go version

# If not installed (Ubuntu/Debian):
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

2. nmap

# Ubuntu/Debian
sudo apt update && sudo apt install -y nmap

# Verify
nmap --version

3. Root access (required for SYN scans and IP rotation)

---

Installation

Step 1: Extract the Agent

# Create directory
sudo mkdir -p /opt/nmap-agent
cd /opt

# Extract (assuming zip is in current directory)
sudo unzip nmap-agent-improved.zip
sudo mv nmap-agent-improved/* /opt/nmap-agent/
cd /opt/nmap-agent

Step 2: Build the Agent

# Download dependencies
go mod tidy

# Build the binary
go build -o nmap-agent-improved

# Verify it built
ls -la nmap-agent-improved

Step 3: Configure the Agent

# Copy example config
cp env_example .env

# Edit configuration
nano .env

Minimum required configuration in .env:

API_USER=scanner
API_PASS=your_secure_password
API_URL_BASE=http://YOUR_DASHBOARD_IP:8080

Step 4: Create Scanner User on Dashboard

Before the agent can connect, you need to create a user account on the dashboard:

1. Log into the NMAP Dashboard as admin
2. Go to Users page
3. Click + Add User
4. Fill in:
   • Username: scanner (or whatever you set in API_USER)
   • Password: (whatever you set in API_PASS)
   • Roles: Enable Scanner checkbox
   • Activate immediately: Yes
5. Click Create

Step 5: Test the Agent

# Run a single scan to test
sudo ./nmap-agent-improved

# You should see:
# [*] Authentication successful
# [+] Got job: xxx-xxx (range: 10.x.x.x/24, team: Team Name)
# [*] Starting TCP scan...
# ...

Step 6: Set Up Continuous Scanning (Optional)

# Make runner executable
chmod +x runner.sh

# Run with IP rotation
sudo ./runner.sh

# Or run with parallel mode AND IP rotation
sudo PARALLEL_MODE=true ./runner.sh

---

Configuration

Required Variables

Variable	Description	Example
API_USER	Scanner username	scanner
API_PASS	Scanner password	SecurePass123
API_URL_BASE	Dashboard URL (no trailing slash)	http://10.255.252.10:8080

Scan Options

Variable	Default	Description
SCAN_TIMEOUT	10	Minutes before scan times out
ENABLE_UDP	true	Scan UDP ports (DNS, SNMP, etc.)
ENABLE_SCRIPTS	true	Run NSE vulnerability scripts
STEALTH_MODE	false	Use decoy IPs
ADAPTIVE_TIMING	true	Retry slower if few hosts found

Parallel Mode Options

Variable	Default	Description
MAX_PARALLEL	3	Number of concurrent scans

Reliability Options

Variable	Default	Description
RETRY_ATTEMPTS	3	Times to retry failed uploads
RETRY_DELAY	5	Seconds between retry attempts
CACHE_DIR	/tmp/nmap-agent-cache	Where to cache results

Runner.sh Options

Variable	Default	Description
INTERFACE	eth0	Network interface for IP rotation
GATEWAY	10.255.252.254	Default gateway
PARALLEL_MODE	false	Enable parallel scanning
SLEEP_BETWEEN_SCANS	0	Seconds to wait between scans
LOG_FILE	/var/log/nmap-agent-rotation.log	Log file path

---

Usage

Single Scan Mode (Default)

Run one scan and exit. Good for testing.

sudo ./nmap-agent-improved

Parallel Mode

Process all available jobs using a worker pool. Scans multiple teams simultaneously.

sudo ./nmap-agent-improved -p

Continuous Mode

Run scans continuously without IP rotation.

sudo ./nmap-agent-improved -c

With IP Rotation (Recommended for Competition)

The runner.sh script handles continuous scanning with IP rotation between each scan.

# Single scan mode with IP rotation
sudo ./runner.sh

# Parallel mode with IP rotation (RECOMMENDED)
sudo PARALLEL_MODE=true ./runner.sh

View Help

./nmap-agent-improved -h

---

Enabling Parallel Mode

There are three ways to enable parallel scanning:

Option 1: Environment Variable (Recommended)

sudo PARALLEL_MODE=true ./runner.sh

Option 2: Edit runner.sh

Change line 11 from:

PARALLEL_MODE="${PARALLEL_MODE:-false}"

To:

PARALLEL_MODE="${PARALLEL_MODE:-true}"

Option 3: Direct Command

# Without IP rotation
sudo ./nmap-agent-improved -p

# With IP rotation (manual)
sudo ./nmap-agent-improved -p && rotate_ip.sh

---

Ports and Scripts

TCP Ports Scanned (170+)

• Standard: 21, 22, 23, 25, 53, 80, 110, 135, 139, 143, 443, 445
• Email: 465, 587, 993, 995
• Databases: 1433, 1521, 3306, 5432, 6379, 27017, 9042, 9200
• Remote Access: 3389, 5900-5902, 5985-5986
• Web/Apps: 8080, 8443, 8000, 8888, 9000, 9090, 10000
• Windows/AD: 88, 389, 464, 636, 3268, 3269
• Containers: 2375, 2376, 6443, 10250

UDP Ports Scanned

• 53 (DNS), 67-68 (DHCP), 69 (TFTP), 123 (NTP)
• 161-162 (SNMP), 500 (IKE), 514 (Syslog)
• 1194 (OpenVPN), 1812-1813 (RADIUS)

NSE Vulnerability Scripts

Script	Detects
ftp-anon	Anonymous FTP access
mysql-empty-password	Empty MySQL root password
ms-sql-empty-password	Empty MSSQL sa password
redis-info	Unauthenticated Redis
mongodb-databases	Unauthenticated MongoDB
smb-vuln-ms17-010	EternalBlue vulnerability
smb-vuln-ms08-067	Conficker vulnerability
ssl-heartbleed	Heartbleed vulnerability
http-shellshock	Shellshock vulnerability

---

Troubleshooting

"no job available"

• Check that teams exist in the dashboard with valid IP ranges
• Verify the scanner user has the "scanner" role
• Check the Jobs page to see if jobs are being created

"login failed"

• Verify credentials in .env match the dashboard user
• Check that the user is active in the dashboard
• Ensure API_URL_BASE is correct (no trailing slash)
• Test connectivity: curl http://DASHBOARD_IP:8080/health

"scan failed" or timeout

• Ensure nmap is installed: which nmap
• Verify you're running as root
• Check if the target network is reachable: ping 10.1.1.1
• Try increasing SCAN_TIMEOUT=15
• Try disabling UDP: ENABLE_UDP=false

No data appearing in dashboard

• Check the agent's output for errors
• Verify the job shows as "complete" in the Jobs page
• Check for cached results: ls /tmp/nmap-agent-cache/
• Check dashboard server logs

Scans too slow

• Disable UDP: ENABLE_UDP=false
• Disable scripts: ENABLE_SCRIPTS=false
• Increase parallel workers: MAX_PARALLEL=5

IP rotation not working

• Verify running as root
• Check interface name: ip link show
• Verify gateway is correct for your network
• Check logs: tail -f /var/log/nmap-agent-rotation.log

---

Example Session Output

 _   _ __  __          _____                                 _   
| \ | |  \/  |   /\   |  __ \       /\                      | |  
|  \| | \  / |  /  \  | |__) |     /  \   __ _  ___ _ __ | |_ 
...
[*] Configuration:
    API URL:        http://10.255.252.10:8080
    Max Parallel:   3
    Scan Timeout:   10 min
    UDP Scanning:   true
    NSE Scripts:    true
[*] Authentication successful
[+] Got job: abc-123 (range: 10.1.1.0/24, team: Team Alpha)
[*] Starting TCP scan...
[*] Starting UDP scan...
[+] Scan complete: 7 hosts, 42 open ports in 124.5s
    10.1.1.1 (Windows Server 2019): 22/tcp, 135/tcp, 445/tcp, 3389/tcp
    [!] VULN 10.1.1.1:445 - smb-vuln-ms17-010: VULNERABLE
    10.1.1.10 (Ubuntu 20.04): 22/tcp, 80/tcp, 3306/tcp
    [!] VULN 10.1.1.10:3306 - mysql-empty-password: root has empty password
[+] Results uploaded successfully

[*] === Session Statistics ===
    Runtime:         2m15s
    Total Scans:     1
    Successful:      1
    Hosts Found:     7
    Ports Found:     42

---

License

BSD 2-Clause License