<div align="center"> <pre> ██████╗ ██████╗ ███╗ ███╗ █████╗ ██████╗ ██╔════╝ ██╔═══██╗████╗ ████║██╔══██╗██╔══██╗ ██║ ███╗██║ ██║██╔████╔██║███████║██████╔╝ ██║ ██║██║ ██║██║╚██╔╝██║██╔══██║██╔═══╝ ╚██████╔╝╚██████╔╝██║ ╚═╝ ██║██║ ██║██║ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ </pre>

gomap

Fast TCP scanner in Go with service fingerprinting, native SYN scanning, stealth profiles, and multi-format output.

</div>

Navigation

• Current scope
• Installation
• Quick Start
• CLI Reference
• Detection Realism (-s)
• Stealth Benchmark (Lab)
• Output Formats
• Testing and Quality
• Project Layout
• Release Process
• APT Repository Publishing
• Responsible Use
• Quick Links

A fast TCP port scanner written in Go, with optional service/version detection, CIDR host discovery, adaptive timeout tuning, and multi-format output.

Current scope

• Fast concurrent TCP scanning with selectable engine (connect or syn).
• Default quick scan uses a curated top-port list normalized to unique ports (current effective size: 996).
• Optional service and version detection (-s).
• Single host, hostname, comma-separated targets, and CIDR ranges.
• CIDR active-host discovery by TCP probes (no ICMP ping).
• Robust scan controls for unstable networks: retries, backoff, adaptive timeout.
• Professional outputs: text, json, jsonl, csv.
• Per-host exposure summary in text mode.
• Ghost mode hardening: lower burst rate, heavier jitter, and fewer active probes.
• Ultra-stealth ghost defaults: low rate, low worker count, and reduced CIDR discovery probes.
• Optional HTTP identity randomization: --random-agent and --random-ip.

Installation

Build from source

git clone https://github.com/NexusFireMan/gomap.git
cd gomap
go build -o gomap .
./gomap -v

Optional helper scripts

./scripts/build.sh
./scripts/install.sh

Install with Go

go install github.com/NexusFireMan/gomap/v2@latest

Install with APT (Kali / Parrot / Debian)

GoMap is also prepared to be consumed from a signed APT repository published on GitHub Pages:

curl -fsSL https://nexusfireman.github.io/gomap/gomap-archive-keyring.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/gomap-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/gomap-archive-keyring.gpg] https://nexusfireman.github.io/gomap stable main" \
  | sudo tee /etc/apt/sources.list.d/gomap.list > /dev/null

sudo apt update
sudo apt install gomap

Notes:

• This is intended for Kali, Parrot, Debian, and close derivatives.
• Arch users should prefer an AUR package in a later phase rather than this APT repository.
• The Debian package installs the binary at /usr/bin/gomap.
• If gomap -v still shows an older version after apt install, check for older copies earlier in PATH:

which -a gomap
gomap --doctor
/usr/bin/gomap -v
hash -r

gomap --doctor reports:

• the active binary currently resolved in PATH
• all detected gomap copies in common locations
• the detected version of each copy
• the probable origin (apt, go install, manual install, user-local binary)
• whether gomap --remove can remove it safely

Behavior note:

• gomap --remove skips package-managed binaries such as /usr/bin/gomap
• to remove the APT installation itself, use sudo apt remove gomap

Example cleanup when an older user-local binary shadows the packaged one:

which -a gomap
gomap --doctor
/usr/bin/gomap -v
rm -f ~/.local/bin/gomap
hash -r
gomap -v

Validated in lab:

• apt update resolves InRelease and Packages correctly from https://nexusfireman.github.io/gomap
• apt install gomap installs the current release successfully on Kali
• /usr/bin/gomap -v shows embedded release metadata (version, commit, date)

Container image

Published images are available on GHCR:

docker pull ghcr.io/nexusfireman/gomap:latest

Run a standard scan:

docker run --rm --network host ghcr.io/nexusfireman/gomap:latest 10.0.11.6

Run native SYN scan:

docker run --rm --network host --cap-add NET_RAW ghcr.io/nexusfireman/gomap:latest --scan-type syn 10.0.11.6

Notes:

• --network host is recommended on Linux for predictable scan behavior.
• Native SYN scan additionally requires --cap-add NET_RAW.

Debian package artifacts

Each tagged release publishes .deb artifacts alongside archives and checksums. They can be installed directly with:

sudo dpkg -i gomap_<version>_linux_amd64.deb

Version metadata

• Release binaries and local script builds embed Version, Commit, and Date.
• gomap -up now prefers release binaries to preserve embedded build metadata in final installations.
• Plain go install builds may not include ldflags, so gomap -v also uses Go build info fallback when available.

Quick Start

# Default scan (top common ports)
./gomap 10.0.11.6

# Native SYN scan discovery (requires root/CAP_NET_RAW)
./gomap --scan-type syn 10.0.11.6

# Service/version detection on selected ports
./gomap -s -p 21,22,80,135,139,445,5985 10.0.11.6

# CIDR scan with automatic active-host discovery
./gomap -s --top-ports 300 10.0.11.0/24

# More robust scan profile for unstable networks
./gomap -s --retries 2 --adaptive-timeout --backoff-ms 40 --max-timeout 4500 10.0.11.9

# Machine output for automation
./gomap -s --format json --out scan.json 10.0.11.6

# Stealthier service detection profile
./gomap -g -s --random-agent --random-ip 10.0.11.0/24

# Maximum stealth for CIDR (skip discovery entirely)
./gomap -g -nd -s --random-agent --random-ip -p 22,80,443 10.0.11.0/24

CLI Reference

Usage:
  gomap <host|CIDR> [options]

Main options:
  -p                ports to scan (example: 80,443 or 1-1024 or - for all)
  --scan-type       connect|syn (default: connect)
  --top, --top-ports scan top N ports from curated top-1000 list
  --exclude-ports   remove ports from final scan set
  -s                enable service/version detection
  -g                ghost mode (slower, stealthier)
  -nd               disable host discovery for CIDR targets

Performance/robustness:
  --workers         concurrent workers (default: auto by mode)
  --rate            max scan rate in ports/second per host (0 = unlimited)
  --timeout         per-attempt dial timeout in ms (default: auto by mode)
  --retries         retries per port on timeout/error
  --backoff-ms      base exponential backoff between retries
  --adaptive-timeout enable dynamic timeout tuning (default: true)
  --max-timeout     adaptive timeout ceiling in ms
  --max-hosts       cap number of discovered hosts scanned

Output:
  --format          text|json|jsonl|csv
  --json            shortcut for --format json
  --csv             shortcut for --format csv
  --out             output file path
  --details         add latency/confidence/evidence columns (text only)

Stealth/identity (HTTP probes):
  --random-agent    randomize HTTP User-Agent on each request
  --random-ip       randomize HTTP X-Forwarded-For/X-Real-IP from target CIDR

Compatibility note:
  legacy aliases (`--ramdom-agent`, `--ip-ram`, `--ip-random`) are still accepted for backward compatibility.

Ghost defaults:
  - lower default rate and worker count
  - reduced host-discovery probes on CIDR (443,80,22)
  - use `-nd` to disable host discovery completely on CIDR
  - tradeoff: discovery may miss hosts that only expose non-probed ports (for example 139/445 only)

Maintenance:
  -v                show version/build info
  -up               update to latest version
  --remove          remove non-package gomap copies found in PATH/common locations
  --doctor          inspect active binary, PATH copies, and install origin

Detection Realism (-s)

When -s is enabled, gomap combines port-based hints and protocol/banner parsing to infer:

• HTTP/HTTPS server family/version where available.
• SSH/FTP/PostgreSQL/Redis/MySQL and other protocol banners.
• SMB-oriented identification for microsoft-ds targets.
• TLS handshake metadata where applicable (tls_version, tls_cipher, ALPN, certificate issuer).

Important: banner-based detection is heuristic. Always validate critical findings with a second tool.

--scan-type syn notes:

• Uses GoMap native raw TCP SYN probes for port discovery, then optional service detection on open ports.
• If SYN scan cannot run (insufficient privileges or unsupported OS), GoMap falls back to connect scan automatically.
• For noisy links, tune reliability explicitly with --retries and --rate.

Note: --random-ip randomizes HTTP headers only; it does not spoof the real TCP source IP.

Stealth Benchmark (Lab)

Benchmark executed on March 9, 2026 with:

• Scanner host: 10.0.11.11
• Targets: 10.0.11.0/24 (Windows 10.0.11.6, Linux