ft_nmap

Network port scanner with nmap-like host specification and multi-threaded scanning.

Craft raw packets, send probes, analyze responses, report port states.

Warning

This is an educational project. It has not been independently audited for correctness or security. Must be run as root (raw sockets require CAP_NET_RAW).

Table of Contents

• Supported Platforms
• Features
• Build
• Usage
• Options
• Host Specification
• Port Specification
• Scan Types
• Timing and Performance
• IDS/Firewall Evasion
• Source Address Hiding
• Service and OS Detection
• Output Options
• File Input
• Examples
• License

Supported Platforms

Platform	Status
Linux	Supported

Designed for Linux kernel > 3.14 (Debian 7.0 stable).

Features

• Eight scan techniques: SYN, NULL, ACK, FIN, XMAS, UDP, MAIMON, WINDOW + custom TCP flags
• nmap-like host specification: CIDR, per-octet ranges, wildcards, comma lists, and any combination
• Flexible port ranges: single ports, ranges, comma-separated lists, or - for all 65535
• Multi-threaded scanning: up to 250 threads with configurable host-group parallelism
• Timing templates: -T0 (paranoid) through -T5 (insane), with individual overrides
• Probe retransmission: configurable retries for unanswered probes
• IDS/firewall evasion: packet fragmentation, decoys, TTL spoofing, bad checksums, data padding, source port control
• Source address hiding: IP spoofing, interface binding, MAC spoofing (link-layer mode)
• Service version detection: connect-based probing with regex matching against nmap-service-probes DB
• OS detection: SYN fingerprinting against nmap-os-db
• Output controls: --open, --reason, file output (-oN), packet tracing, verbose mode
• File input: read target hosts from a file, one spec per line
• Raw packet crafting: built on libpcap, no dependency on nmap itself

Build

Dependencies

• C11 compatible compiler
• CMake (>= 3.18)
• Ninja

1. Configure with Ninja

cmake -B build -G "Ninja Multi-Config" .

2. Build

cmake --build build --config Release

The Ninja Multi-Config generator lets you use other build types like Debug, RelWithDebInfo, or Asan.

The resulting binary is in build/<build-type>/.

Usage

ft_nmap [Options] {target specification}

At least one target host must be provided, either as a positional argument or via --file.

./ft_nmap 192.168.1.1
./ft_nmap -p 80,443 -s SYN scanme.nmap.org
./ft_nmap -t 100 -f targets.txt

Options

Target

Short	Long	Argument	Default	Description
-f	--file	PATH	(none)	File containing host specs to scan

Scan Parameters

Short	Long	Argument	Default	Description
-p	--ports	SPEC	1-1024	Ports to scan (see Port Specification)
-s	--scan	TYPE[,TYPE..]	all	Scan types (see Scan Types)
	--scan-flags	FLAGS	(none)	Custom TCP flags (hex 0x03 or symbolic SYN,FIN)

Timing and Performance

Short	Long	Argument	Default	Description
-T	--timing	0-5	3	Timing template (see Timing and Performance)
-t	--threads	N	from -T	Number of threads, 0-250
	--scan-delay	MS	from -T	Min delay between probes (ms)
	--timeout	MS	from -T	Response wait timeout (ms)
	--max-retries	N	from -T	Max retransmissions for unanswered probes
	--host-group	N	1	Max hosts scanned simultaneously

IDS/Firewall Evasion

Short	Long	Argument	Default	Description
-F	--fragment			Fragment packets (8-byte fragments)
	--mtu	N		Fragment with specific MTU (multiple of 8)
-D	--decoy	IPs		Decoy IPs: d1,d2,...,ME,...
	--ttl	N		Set IP TTL
	--data-length	N		Append N random bytes to probes
	--bad-sum			Send packets with bad checksums
-g	--source-port	N		Use given source port number

Source Address Hiding

Short	Long	Argument	Default	Description
-S	--source-ip	IP		Spoof source IP address
-e	--interface	NAME		Use specified network interface
	--spoof-mac	MAC		Spoof MAC address (link-layer mode)

Detection

Short	Long	Argument	Default	Description
	--version-detect			Probe open ports for service versions
-O	--os-detect			Enable OS detection
	--version-db	PATH		Service probes file path
	--os-db	PATH		OS fingerprint DB file path

Output

Short	Long	Argument	Default	Description
-v	--verbose			Increase verbosity level
	--open			Only show open ports
	--reason			Show reason for each port state
-o	--output	PATH		Save output to file (-oN)
	--packet-trace			Log all sent/received packets
	--randomize-hosts			Shuffle target host order
	--host-timeout	MS		Give up on host after N ms

Other

Short	Long	Description
	--help	Show help message
	--version	Show version

Host Specification

Targets are passed as positional arguments. Each argument is a single host spec that gets expanded independently.

Format	Example	Expands to
Single IP	192.168.1.1	1 host
Hostname / FQDN	scanme.nmap.org	1 host (stored as-is, resolved at scan time)
CIDR	192.168.1.0/24	256 hosts
Per-octet range	192.168.1-5.1	5 hosts
Per-octet wildcard	192.168.1.*	256 hosts
Per-octet comma	192.168.1,2.1	2 hosts
Mixed per-octet	192.168.1,3-5,7.1	5 hosts

Per-octet expressions produce a cartesian product across all four octets:

# 2 values in 3rd octet x 10 values in 4th octet = 20 hosts
./ft_nmap 192.168.1,2.1-10

A single spec cannot expand to more than 65536 addresses (prevents accidental OOM).

Port Specification

Ports are specified with -p / --ports. The syntax supports:

Format	Example	Description
Single port	80	One port
Range	1-1024	Inclusive range
Comma-separated	80,443,8080	List of ports or ranges
All ports	-	Shorthand for 1-65535

Default: 1-1024. Duplicates are removed and the list is sorted.

./ft_nmap -p 22,80,443 192.168.1.1
./ft_nmap -p 1-100,443,8000-9000 192.168.1.1
./ft_nmap -p - 192.168.1.1       # all 65535 ports

Scan Types

Specify one or more scan types with -s / --scan (comma-separated). When omitted, all eight are run. Use --scan-flags to set arbitrary TCP flags for a custom scan.

Type	Description
SYN	TCP SYN (half-open) scan
NULL	TCP scan with no flags set
ACK	TCP ACK scan (firewall rule mapping)
FIN	TCP FIN scan
XMAS	TCP scan with FIN, PSH, and URG flags set
UDP	UDP scan
MAIMON	TCP FIN/ACK scan (Maimon scan)
WINDOW	TCP Window scan (like ACK but checks window field)
CUSTOM	Custom TCP flags via --scan-flags

Each scan classifies ports into one of: Open, Closed, Filtered, Unfiltered, or Open|Filtered.

./ft_nmap -s SYN 192.168.1.1
./ft_nmap -s SYN,UDP 192.168.1.1
./ft_nmap --scan-flags SYN,FIN 192.168.1.1

Timing and Performance

Control scan speed, stealth, and parallelism with -T timing templates or individual flags.

Timing Templates (-T)

-T sets sensible defaults for threads, probe delay, timeout, retries, and host-group size. Individual flags always override the template.

-T	Name	Threads	Scan Delay	Timeout	Retries	Host Group
0	Paranoid	0	300000 ms	15000 ms	10	1
1	Sneaky	0	15000 ms	15000 ms	10	1
2	Polite	0	400 ms	10000 ms	10	1
3	Normal	0	0 ms	10000 ms	10	1
4	Aggressive	100	0 ms	1250 ms	6	1
5	Insane	250	0 ms	300 ms	2	1

Individual Controls

Flag	Description
--scan-delay MS	Minimum time between consecutive probes to the same host. Higher values reduce detection risk.
--timeout MS	How long to wait for responses after the last probe is sent.
--max-retries N	How many times to retransmit a probe that received no response.
--host-group N	Maximum number of hosts scanned simultaneously. Probes from all active hosts share the thread pool.

Parallelism

Scanning has two dimensions of parallelism controlled independently:

• --threads N: total thread pool size. Threads send probes (build + send). More threads = more probes in flight.
• --host-group N: how many hosts are scanned at the same time. Each active host has its own pcap receiver.

# Fast single-host scan: 250 threads all hitting one host
./ft_nmap -T5 192.168.1.1

# Fast multi-host scan: 10 hosts active, 100 threads shared
./ft_nmap -t 100 --host-group 10 -f targets.txt

# Stealthy: sequential probes, 15s between each
./ft_nmap -T1 192.168.1.1

# Aggressive timing but custom timeout
./ft_nmap -T4 --timeout 5000 192.168.1.1

IDS/Firewall Evasion

Techniques to bypass intrusion detection systems and firewalls.

Packet Fragmentation (-F / --mtu)

Split probe packets into small fragments. -F uses 8-byte fragments; --mtu lets you specify a custom MTU (must be a multiple of 8).

./ft_nmap -F -s SYN 192.168.1.1
./ft_nmap --mtu 16 -s SYN 192.168.1.1

Decoys (-D)

Mix your real probe traffic with decoy source IPs. Use ME to position your real IP within the decoy list.

./ft_nmap -D 10.0.0.1,10.0.0.2,ME,10.0.0.3 192.168.1.1

Other Evasion Options

Flag	Description
--ttl N	Set a specific IP TTL value (1-255)
--data-length N	Append N random bytes to each probe to disguise packet signatures
--bad-sum	Send packets with intentionally bad checksums
-g N	Use a specific source port (e.g. 53 or 80 to bypass firewall rules)

./ft_nmap --ttl 64 --data-length 40 -s SYN 192.168.1.1
./ft_nmap -g 53 -s SYN 192.168.1.1

Source Address Hiding

Options for controlling the apparent source of scan traffic.

Flag	Description
-S IP	Spoof the source IP address (you won't see replies unless you can sniff)
-e NAME	Bind to a specific network interface
--spoof-mac MAC	Spoof the Ethernet source MAC address (implies link-layer send mode)

./ft_nmap -S 10.0.0.99 -e eth0 192.168.1.1
./ft_nmap --spoof-mac 00:11:22:33:44:55 -e eth0 192.168.1.1

Service and OS Detection

Service Version Detection (--version-detect)

After scanning, connect to open ports and probe them with the nmap-service-probes database to identify running services and versions.

./ft_nmap --version-detect -s SYN -p 22,80,443 192.168.1.1
./ft_nmap --version-detect --version-db /path/to/nmap-service-probes 192.168.1.1

OS Detection (-O)

Send SYN fingerprinting probes and match responses against the nmap-os-db database.

./ft_nmap -O -s SYN 192.168.1.1
./ft_nmap -O --os-db /path/to/nmap-os-db 192.168.1.1

Output Options

Flag	Description
-v	Increase verbosity (can be repeated: -v -v)
--open	Only show open ports in the output
--reason	Show the reason for each port's state
-o PATH	Save normal output to a file (-oN style)
--packet-trace	Log all sent and received packets
--randomize-hosts	Shuffle the order in which hosts are scanned
--host-timeout MS	Give up on a host after N milliseconds

./ft_nmap --open --reason -s SYN 192.168.1.1
./ft_nmap -v -o results.txt 192.168.1.1
./ft_nmap --packet-trace -s SYN -p 80 192.168.1.1
./ft_nmap --randomize-hosts --host-timeout 30000 -f targets.txt

File Input

Use -f / --file to read host specs from a file. Each line is treated as a separate host spec (same syntax as CLI arguments). Empty lines and lines starting with # are skipped.

# targets.txt
192.168.1.0/24
10.0.0.1-10
scanme.nmap.org

./ft_nmap -f targets.txt

File targets and CLI targets can be combined:

./ft_nmap -f targets.txt 10.0.1.1

Examples

# Single host, default ports (1-1024), all scan types
./ft_nmap 192.168.1.1

# SYN scan on specific ports
./ft_nmap -s SYN -p 22,80,443 192.168.1.1

# Scan a /24 subnet with 100 threads
./ft_nmap -t 100 192.168.1.0/24

# Wildcard: scan all hosts in 10.0.0.*
./ft_nmap 10.0.0.*

# Per-octet ranges: 192.168.{1,2}.{1-10} = 20 hosts
./ft_nmap 192.168.1,2.1-10

# All ports, UDP only
./ft_nmap -s UDP -p - 192.168.1.1

# Multiple targets from file and CLI
./ft_nmap -f targets.txt -p 80,443 10.0.1.1

# Aggressive scan with custom timeout
./ft_nmap -T4 --timeout 5000 192.168.1.1

# Stealthy scan: 15s between probes
./ft_nmap -T1 -s SYN -p 22,80,443 192.168.1.1

# Parallel host scanning: 10 hosts at once
./ft_nmap -t 100 --host-group 10 -f targets.txt

# Custom TCP flags (SYN+FIN)
./ft_nmap --scan-flags SYN,FIN -p 80 192.168.1.1

# Fragmented SYN scan with decoys
./ft_nmap -F -D 10.0.0.1,10.0.0.2,ME -s SYN 192.168.1.1

# Version detection on common ports
./ft_nmap --version-detect -s SYN -p 22,80,443 192.168.1.1

# OS detection
./ft_nmap -O -s SYN 192.168.1.1

# Only show open ports with state reasons, save to file
./ft_nmap --open --reason -o results.txt -s SYN 192.168.1.1

# Verbose scan with packet tracing
./ft_nmap -v --packet-trace -s SYN -p 80 192.168.1.1

License

Licensed under the Apache License 2.0.