Contraband

Contraband is a pure Go network egress assessment framework for security operators and network defenders. It evaluates perimeter firewalls, corporate forward proxies, and Data Loss Prevention (DLP) inspection engines through automated L4 port sweeps, proxy authentication traversal, protocol smuggling across 20+ channels, and real-time telemetry.

flowchart LR
    Client["Contraband Client<br/>(L4 Sweep + Evasion + DLP)"] --> Proxy["Corporate Proxy / NGFW<br/>(PAC, NTLM/Kerberos, uTLS)"]
    Proxy --> Server["Contraband Server<br/>(Multi-Port Reflection)"]
    Server --> Hub["LiveHub Telemetry Engine"]
    Hub --> Dashboard["Web Dashboard (:8080)<br/>(Real-Time SSE + Telemetry)"]
    Client -.->|"--sync-report"| Hub

flowchart LR
    Client["Contraband Client<br/>(L4 Sweep + Evasion + DLP)"] --> Proxy["Corporate Proxy / NGFW<br/>(PAC, NTLM/Kerberos, uTLS)"]
    Proxy --> Server["Contraband Server<br/>(Multi-Port Reflection)"]
    Server --> Hub["LiveHub Telemetry Engine"]
    Hub --> Dashboard["Web Dashboard (:8080)<br/>(Real-Time SSE + Telemetry)"]
    Client -.->|"--sync-report"| Hub

Command Center Live HUD

Contraband provides a unified real-time operations dashboard served directly by the reflection listener. It visualizes concurrent egress streams, bandwidth utilization, DLP bypass efficiency, and dynamic Egress Exposure Index (EEI) metrics as probes traverse perimeter controls.

Figure 1: Contraband Command Center live telemetry dashboard showing radial metric dials, bandwidth throughput, EEI posture rating, and active multi-zone egress streams (PCI CDE, Corporate LAN, Cloud VPC).

Protocol & Port Telemetry Matrix

Monitor 20 active protocol smuggling channels, open outbound egress ports, and live Server-Sent Events (SSE) telemetry logs with sub-second reflection confirmations.

Figure 2: Protocol smuggling rack monitor and egress port listener matrix tracking real-time probe arrivals and payload reflections.

Synchronized Multi-Zone Reports Ledger

Client assessment results from segmented network zones automatically stream to the central listener, synchronizing findings, exposure scores, and downloadable forensic artifacts.

Figure 3: Synchronized client assessment ledger aggregating multi-zone audits with direct HTML, JSON, SARIF, and firewall rule export.

30-Second Quickstart

1. Start Listener & Live Dashboard

Run on your external staging or assessment listener host:

contraband server \
  --live-dashboard :8080 \
  --ports full \
  --protocols all \
  --evidence-dir ./evidence

Open http://<server-ip>:8080/dashboard to view the live dashboard.

Figure 4: Contraband reflection server initialization with multi-port binding (:21 to :50051), TLS fallback, and live SSE event bus telemetry.

2. Run Egress Assessment

Run on the target internal assessment host:

contraband client \
  --server 198.51.100.1 \
  --ports full \
  --protocols all \
  --dlp all \
  --sync-report http://198.51.100.1:8080 \
  --output-html report.html \
  --output-json report.json \
  --output-sarif report.sarif

Figure 5: Contraband client performing pre-flight port checks, protocol smuggling, DLP signature evasion, and EEI posture scoring.

3. Assessment Scenarios by Environment

Scenario A: Stealth & Low-and-Slow EDR Evasion

Throttle exfiltration rate to 100 KB/s with randomized inter-packet jitter (2s–10s), Chrome TLS fingerprinting, and AES-256-GCM + Zstandard transform chaining to blend with routine background traffic:

contraband client \
  --server 198.51.100.1 \
  --protocols https_post,dns_over_https \
  --cadence low-and-slow \
  --throughput 100KB/s \
  --interval-min 2s \
  --interval-max 10s \
  --tls-fingerprint chrome \
  --transforms aes_gcm,zstd,base64 \
  --passphrase "AssessmentSecretKey2026!"

Scenario B: High-Throughput QUIC & UDP Deep Packet Inspection

Paces a 2 MB DLP payload at a steady 1 MB/s across discrete 64 KB chunks to evaluate NGFW deep-packet inspection over modern UDP-based HTTP/3 and SMB-over-QUIC listeners:

contraband client \
  --server 198.51.100.1 \
  --protocols http3_quic,smb_quic \
  --size 2MB \
  --rate 1MB/s \
  --chunk-size 64KB \
  --cadence steady \
  --sync-report http://198.51.100.1:8080

Scenario C: Corporate Proxy Traversal (NTLM / Negotiate / WPAD)

Auto-detects WinHTTP/WPAD proxy configurations or routes through an explicit corporate forward proxy with NTLM authentication and HTTP/2 multiplexing:

contraband client \
  --server 198.51.100.1 \
  --proxy "http://corp-proxy.internal:8080" \
  --proxy-auth ntlm \
  --protocols http_post,https_post,websocket \
  --ports 80,443,8080,8443

Scenario D: Restricted & Air-Gapped Egress (DNS-Only Smuggling)

When all outbound direct TCP egress is blocked and only recursive internal DNS resolvers are reachable, tunnels chunked payloads over authoritative DNS TXT and A queries:

contraband client \
  --server tunnel.egress.example.com \
  --protocols dns_txt,dns_a \
  --size 500KB \
  --chunk-size 64KB \
  --rate 50KB/s

Scenario E: Steganographic Carrier Smuggling (Deep File / DPI Bypass)

Embeds encrypted synthetic PCI/PII records into the least significant bits (LSB) of PNG/BMP pixel matrices or polyglot files to bypass content-disarm and deep file inspection:

contraband client \
  --server 198.51.100.1 \
  --protocols https_post \
  --stego png \
  --carrier-type json \
  --dlp pci,pii \
  --transforms aes_gcm

Scenario F: Enterprise Multi-Zone Segmentation Audit

Tags outbound telemetry with network segment identifiers (pci-enclave, dmz, workstations) to isolate cross-segmentation leakage and aggregate zone comparisons on the centralized dashboard:

contraband client \
  --server 198.51.100.1 \
  --zone "pci-enclave" \
  --ports standard \
  --protocols web,file,cloud \
  --dlp pci \
  --sync-report http://198.51.100.1:8080

Scenario G: Pre-Flight Safety Dry Run (Zero Sockets, Zero Wire Traffic)

Validates target DNS reachability, port presets, and protocol handlers while confirming the <32 MB heap invariant without transmitting packets over the network:

contraband client \
  --server 198.51.100.1 \
  --protocols all \
  --dry-run

Interactive Forensic Reports

Contraband compiles complete assessment telemetry into zero-CDN, standalone HTML reports that can be safely opened offline or attached to client deliverables. Reports include interactive SVG speedometer gauges for the Egress Exposure Index (EEI), subscore breakdowns, probe matrices, and Layer 4 egress port heatmaps.

Figure 6: Standalone zero-dependency HTML forensic report featuring interactive EEI gauge, exposure subscores, and Layer 4 egress port heatmap.

Core CLI Flag Reference

Protocol Matrix

Wire Forensics & SHA-256 Reassembly Matrix

The table below documents the wire dissector filters, framing specifications, and bit-level SHA-256 payload reassembly verified across all 24 Layer 4 and Layer 7 transport protocols:

Detailed Documentation & Operator Wiki

All deep-dive technical specifications and operational manuals are indexed in the Operator Wiki:

License

Contraband is licensed under the Apache License 2.0.