spectra

TCP/IP header walker and firewall evaluation tool. Systematically probes every dimension of the TCP/IP header space against a target, mapping which packets get through (ACK), get rejected (RST), get ICMP-rejected, or get silently dropped. Includes multi-step attack chains that test real-world evasion vectors from the Ptacek-Newsham paper.

Requirements

• Linux (raw sockets with IP_HDRINCL)
• Root / sudo (CAP_NET_RAW)
• gcc, ncurses-dev, pthreads

Build

make

Usage

sudo ./spectra <host> <ports> [options]

Examples

# Full probe suite against a single port
sudo ./spectra 10.0.0.1 443

# Multiple ports (full matrix on first, reachability on rest)
sudo ./spectra 10.0.0.1 22,80,443,8080

# Port range
sudo ./spectra 10.0.0.1 1-1024 --flags-only

# Quiet mode (no TUI, summary to stdout)
sudo ./spectra 10.0.0.1 80 -q

# Custom rate and concurrency
sudo ./spectra 10.0.0.1 443 -j 4 -d 50 -t 5000

# TCP mutations only (skip IP layer)
sudo ./spectra 10.0.0.1 80 --tcp-only

# Full matrix on every port
sudo ./spectra 10.0.0.1 22,80,443 --all-ports

Options

-j N           Worker concurrency (default: 16)
-t MS          Probe timeout in ms (default: 2000)
-d MS          Global inter-probe delay in ms (default: 10)
-o FILE        Write JSONL log to file (default: auto-generated)
-q             Quiet mode — no TUI, summary to stdout
-i IFACE       Bind to specific interface
-s PORT        Source port base (default: 40000)
--tcp-only     Skip IP header mutations
--ip-only      Skip TCP header mutations
--flags-only   Only walk TCP flag combinations
--all-ports    Run full matrix against every port
--no-icmp      Skip ICMP response capture

TUI Keys

q  quit (graceful shutdown)
p  pause/resume probing
f  toggle feed auto-scroll
d  cycle breakdown dimension
s  toggle stateful mode (handshake before walking)

Probe Space (~640 probes per port)

TCP Header Mutations

• Flags: all 512 combinations (9 bits: SYN/ACK/FIN/RST/PSH/URG/ECE/CWR/NS)
• Fields: window (4), sequence (4), ack (3), data offset (3), urgent pointer (3), reserved bits (1)
• Options (valid): MSS, window scaling, SACK, timestamps, unknown type
• Options (malformed): len=0, len=1, length overflow, duplicate MSS, duplicate timestamps, 40x NOP, options past data offset, MSS=0+WS=14, multiple unknown types, data after EOL

IP Header Mutations

• TTL: auto-detected floor + standard values (never wastes probes on intermediate routers)
• Fragmentation flags: DF, MF, offsets
• Protocol field: TCP, HOPOPT, ICMP, UDP, GRE, ESP, 0xFF, random values
• Total length: correct, undersize, oversize
• IP options: record route, timestamp, loose/strict source routing, NOP

Advanced Techniques (v2)

• Fragment attacks: tiny split (8B/16B), overlapping, reversed order, incomplete (resource exhaustion)
• TCP state machine: cold FIN/ACK/PSH, XMAS, NULL, Maimon, window scan, SYN+data
• Modern TCP options: TCP Fast Open, MPTCP, TCP-AO, experimental (253/254)
• IP encapsulation: IP-in-IP (proto 4), GRE (proto 47)

Ptacek-Newsham Evasion Suite (v3)

• Bad checksums: corrupt IP, TCP, or both — tests whether firewall validates
• Split handshake: 4-way and 5-way simultaneous open (bypasses stateful tracking)
• Overlapping segments: forward, backward, full overlap with conflicting data
• PAWS evasion: timestamps 0 and 1 (triggers silent drop on PAWS-aware hosts)
• RST injection: out-of-window RST/RST+ACK
• TTL insertion: TTL floor-1 and floor-2 (reaches firewall, dies before target)
• Trusted port spoofing: source ports 53/80/20/443
• Zero window: SYN and ACK with window=0
• SYN with payload: 1B, 4B, 100B data in SYN packets
• Cold RST/FIN: connection teardown without prior handshake
• Connection reuse: double SYN, RST+SYN on same port
• Fragment exhaustion: 10 orphan first-fragments
• Bogus IP: version=5, IHL=0, IHL=2

Multi-Step Attack Chains (v4)

Full exploitation flows that test insertion vectors:

1. TTL insertion chain: benign decoy at low TTL (IDS accepts, dies en route), then real payload at full TTL (IDS treats as retransmit, target processes)
2. Checksum insertion chain: bad-checksum decoy (IDS accepts, target drops), then valid payload at same seq (IDS ignores, target processes)
3. PAWS insertion chain: old-timestamp decoy (IDS accepts, PAWS-aware target drops), then valid-timestamp payload
4. RST desync chain: handshake, out-of-window RST (IDS tears down state, target ignores), then data on the blind connection
5. Overlap insertion chain: two segments with conflicting overlap regions — IDS and target reassemble differently
6. Connection reuse chain: FIN close, immediate SYN reopen before firewall state cleanup

Output

JSONL log (auto-generated or -o), one object per line:

{
  "ts": 1773528000,
  "target": "10.0.0.1",
  "port": 443,
  "result": "ACK",
  "rtt_us": 1423,
  "ip": { "ttl": 64, "df": true, "mf": false, "frag_off": 0, "proto": 6, "tot_len": 40 },
  "tcp": { "flags": "SYN", "win": 1024, "seq": 0, "ack": 0, "off": 5, "urg": 0, "reserved": 0 },
  "mutation": "chain=CSUM_insert"
}

Results: ACK (through), RST (rejected), FIN (teardown), ICMP_UNREACH (firewall reject), ICMP_TTL (TTL expired), DROP (silent drop).

Adaptive Synthesis (Phase 2)

In quiet mode (-q), spectra automatically runs a second phase after the scout probes complete. The synthesis engine:

1. Classifies scout results into 12 orthogonal dimensions (flags, port, payload, fragment, options, timestamp, TTL, window, checksum, encap, doff, urg)
2. Scores each dimension using dual metrics: surprise (how selective the firewall is) and reliability (how consistently probes pass)
3. Generates compound probes that stack multiple working dimensions together
4. Runs up to 3 iterations with parameter variation on blocked dimensions
5. Discovers combinatorial detection rules — firewall heuristics that block multi-anomaly packets even when each anomaly passes individually

Analysis

# Full analysis report with security assessment
./spectra-analyze scan.jsonl

# Brief summary only
./spectra-analyze scan.jsonl --brief

# Compare two runs (before/after firewall rule change)
./spectra-analyze after.jsonl --diff before.jsonl

# Machine-readable JSON output
./spectra-analyze scan.jsonl --json

Kernel RST Suppression

spectra auto-detects and offers to add the required iptables rule at startup:

iptables -A OUTPUT -p tcp --tcp-flags RST RST -d <target> -j DROP

Without this rule, the kernel's TCP stack sends RST for SYN-ACKs it didn't initiate, corrupting results. The rule is auto-removed on clean exit.

Architecture

src/spectra.h       331 lines   types, structs, function declarations
src/walker.c       1855 lines   mutation strategy engine, attack chains
src/synthesizer.c   691 lines   adaptive compound synthesis with iterative deepening
src/probe.c         643 lines   raw socket TX, packet crafting, fragment/encap/payload senders
src/main.c          435 lines   CLI, thread orchestration, signal handling, JSONL logging
src/tui.c           311 lines   ncurses TUI with 11 breakdown dimensions
src/listener.c      284 lines   TCP/ICMP RX, BPF filter, response matching, timeout tracking
src/target.c         70 lines   host/port parsing, DNS resolution
src/checksum.c       44 lines   IP and TCP checksum computation
spectra-analyze     543 lines   post-run analysis, diff, security assessment (Python)

5,207 lines total. 4 threads: TUI (main), walker (probe generation), worker pool (packet TX), listener (response RX). Phase 2 synthesis runs after scout phase completes.