Chaosreader is a specialized network forensics tool that reconstructs TCP and UDP sessions from packet capture files (pcap). It extracts and reassembles application-level data including HTTP responses, FTP uploads/downloads, SMTP messages, telnet sessions, and more. Widely used in digital forensics, incident response, and network analysis.
# Clone the repository
git clone https://github.com/m57/chaosreader.git
cd chaosreader
# Make scripts executable
chmod +x chaosreader.pl
# Run directly
./chaosreader.pl --help
# Install Perl if not present
sudo apt-get install perl perl-doc
# Install required CPAN modules
cpan install Getopt::Long Data::Dumper
# Verify installation
perl -v
# Ubuntu/Debian
sudo apt-get install chaosreader
# macOS (Homebrew)
brew install chaosreader
# Manual installation
cp chaosreader.pl /usr/local/bin/
chmod +x /usr/local/bin/chaosreader.pl
# Extract all sessions from pcap file
chaosreader.pl capture.pcap
# Specify output directory
chaosreader.pl -D output_dir/ capture.pcap
# Process multiple pcap files
chaosreader.pl *.pcap
# Extract to specific format
chaosreader.pl -w output_dir/ capture.pcap
# Create output directory structure
mkdir analysis-results
chaosreader.pl -D analysis-results/ network-capture.pcap
# View extracted files
ls -la analysis-results/
| Command | Description |
|---|
-D, --dir | Specify output directory for extracted files |
-w | Output format selection (html, text, raw) |
-v, --verbose | Enable verbose output for detailed analysis |
-q, --quiet | Suppress non-essential output |
-i, --input | Explicitly specify input pcap file |
-o, --output | Specify output file base name |
--tcp | Process TCP sessions only |
--udp | Process UDP sessions only |
--filter | Apply BPF filter to pcap |
--no-http | Skip HTTP session extraction |
--no-ftp | Skip FTP session extraction |
--raw | Output raw binary data |
# Extract all HTTP requests and responses
chaosreader.pl capture.pcap -D http-output/
# Process HTTPS sessions (encrypted - limited extraction)
chaosreader.pl capture.pcap
# Analyze HTTP headers and bodies
chaosreader.pl -v capture.pcap | grep -i "http\|request\|response"
# Extract specific domain traffic
tcpdump -r capture.pcap "port 80 or port 443" -w http-only.pcap
chaosreader.pl http-only.pcap -D http-analysis/
# Extract FTP upload/download sequences
chaosreader.pl capture.pcap -D ftp-output/
# Analyze FTP commands and responses
chaosreader.pl -v capture.pcap | grep -i "ftp\|retr\|stor"
# Filter FTP-specific traffic
tcpdump -r capture.pcap "port 21" -w ftp-only.pcap
chaosreader.pl ftp-only.pcap -D ftp-analysis/
# Extract email messages
chaosreader.pl capture.pcap -D email-output/
# Process mail server communications
chaosreader.pl -v capture.pcap | grep -i "smtp\|mail"
# Filter SMTP traffic
tcpdump -r capture.pcap "port 25 or port 587 or port 465" -w smtp-only.pcap
chaosreader.pl smtp-only.pcap -D email-analysis/
# Reconstruct telnet terminal sessions
chaosreader.pl capture.pcap -D telnet-output/
# Analyze telnet interactive commands
chaosreader.pl -v capture.pcap | grep -i "telnet\|23"
# Extract telnet credentials (if unencrypted)
tcpdump -r capture.pcap "port 23" -w telnet-only.pcap
chaosreader.pl telnet-only.pcap -D telnet-analysis/
# Extract DNS queries and responses
chaosreader.pl capture.pcap -D dns-output/
# Analyze domain lookups
chaosreader.pl -v capture.pcap | grep -i "dns\|53"
# Filter DNS traffic
tcpdump -r capture.pcap "port 53" -w dns-only.pcap
chaosreader.pl dns-only.pcap -D dns-analysis/
# Extract specific source IP sessions
chaosreader.pl --filter "src 192.168.1.100" capture.pcap -D output/
# Analyze traffic between two hosts
chaosreader.pl --filter "host 192.168.1.100 and host 10.0.0.50" capture.pcap -D output/
# Process traffic on specific port
chaosreader.pl --filter "port 80" capture.pcap -D output/
# Combine multiple filters
chaosreader.pl --filter "tcp and (port 80 or port 443)" capture.pcap -D output/
# Exclude specific traffic
chaosreader.pl --filter "not (port 53 or port 123)" capture.pcap -D output/
# Extract TCP sessions only
chaosreader.pl --tcp capture.pcap -D tcp-output/
# Extract UDP sessions only
chaosreader.pl --udp capture.pcap -D udp-output/
# Skip specific protocol extraction
chaosreader.pl --no-http capture.pcap -D output/
# Verbose analysis
chaosreader.pl -v capture.pcap -D verbose-output/ > analysis.log
# Typical output organization
output/
├── index.html # HTML index of all sessions
├── conversations/ # TCP/UDP conversation files
│ ├── 001_192-168-1-100_to_10-0-0-50.txt
│ └── 002_10-0-0-50_to_192-168-1-100.txt
├── files/ # Extracted binary files
│ ├── ftp_upload.bin
│ └── http_response.bin
├── mail/ # Email messages
├── http/ # HTTP requests/responses
└── raw/ # Raw session data
# Generate HTML report
chaosreader.pl capture.pcap -D html-output/
# View results
open html-output/index.html
# or
firefox html-output/index.html
# Generate text-based analysis
chaosreader.pl -w capture.pcap -D text-output/
# View session summary
cat text-output/chaos.summary
# Step 1: Extract all sessions
chaosreader.pl -v suspicious-traffic.pcap -D incident-analysis/ > analysis.log
# Step 2: Review extracted files
ls -lah incident-analysis/
# Step 3: Examine index
cat incident-analysis/index.html
# Step 4: Analyze specific sessions
cat incident-analysis/conversations/001_*
# Step 5: Document findings
grep -r "GET\|POST\|login\|password" incident-analysis/ > findings.txt
# Extract HTTP traffic
tcpdump -r capture.pcap "port 80 or port 443" -w web-traffic.pcap
chaosreader.pl web-traffic.pcap -D web-analysis/
# Review HTTP requests
cat web-analysis/http/*
# Check for injection attempts
grep -i "script\|sql\|union\|select" web-analysis/conversations/*
# Analyze response codes
grep -i "200\|301\|401\|403\|500" web-analysis/*
# Extract email sessions
tcpdump -r capture.pcap "port 25 or port 587 or port 465 or port 110 or port 143" -w email.pcap
chaosreader.pl email.pcap -D email-analysis/
# Review sender/recipient
grep -i "from:\|to:\|subject:" email-analysis/mail/*
# Check attachments
ls -la email-analysis/files/
# Analyze headers
cat email-analysis/conversations/*
# Extract all sessions
chaosreader.pl capture.pcap -D exfil-analysis/
# Check for file transfers
ls -la exfil-analysis/files/
# Analyze file sizes
du -sh exfil-analysis/files/*
# Review FTP sessions
cat exfil-analysis/conversations/*ftp*
# Check HTTP uploads
grep -i "post\|upload\|multipart" exfil-analysis/conversations/*
# Reconstruct complete TCP streams
chaosreader.pl capture.pcap -D streams/
# Review stream files
cat streams/conversations/001_*
# Verify stream integrity
wc -l streams/conversations/*
# Process packets with sequence verification
chaosreader.pl -v capture.pcap -D reordered/ > reorder.log
# Check for packet loss
grep -i "lost\|missing\|sequence" reorder.log
# Analyze packet drops
tcpdump -r capture.pcap -n | tail -20
# Extract temporal information
chaosreader.pl -v capture.pcap -D timeline/ 2>&1 | grep -i "time\|date"
# Review session start/end times
cat timeline/index.html | grep -i "time"
# Create chronological analysis
ls -lt timeline/conversations/* | head -20
# Calculate pcap file hash
sha256sum capture.pcap > evidence.sha256
# Document analysis results
md5sum analysis-results/* > file-hashes.txt
# Create evidence inventory
ls -lah analysis-results/ > inventory.txt
# Document original capture
file capture.pcap
stat capture.pcap
# Log analysis activities
echo "Analysis started: $(date)" > analysis-log.txt
chaosreader.pl capture.pcap -D results/ 2>&1 | tee -a analysis-log.txt
# Generate final report
echo "Analysis completed: $(date)" >> analysis-log.txt
# Comprehensive analysis report
{
echo "=== Chaosreader Analysis Report ==="
echo "Capture file: $(file capture.pcap)"
echo "Analysis date: $(date)"
echo "Analysis directory: $(pwd)/results/"
echo ""
echo "=== Sessions Extracted ==="
wc -l results/conversations/*
echo ""
echo "=== Files Recovered ==="
ls -lah results/files/
} > forensic-report.txt
# Verify pcap file validity
tcpdump -r capture.pcap -c 5
# Check file size
ls -lh capture.pcap
# Enable verbose mode
chaosreader.pl -v capture.pcap -D debug/ > debug.log
# Review debug output
tail -50 debug.log
# Process large pcaps in chunks
tcpdump -r large-capture.pcap -w chunk1.pcap -c 100000
tcpdump -r large-capture.pcap -w chunk2.pcap -c 100000
# Process each chunk
chaosreader.pl chunk1.pcap -D output1/
chaosreader.pl chunk2.pcap -D output2/
# Check file encoding
file results/conversations/*
# Convert encoding if needed
iconv -f ISO-8859-1 -t UTF-8 input.txt -o output.txt
# Review binary data
hexdump -C results/files/* | head -20
# Export filtered traffic from Wireshark
# File > Export Specified Packets > pcap format
# Analyze exported file
chaosreader.pl wireshark-export.pcap -D ws-analysis/
# Capture and analyze in one workflow
tcpdump -i eth0 -w live-capture.pcap
chaosreader.pl live-capture.pcap -D live-analysis/
# Export alerts as pcap
# Use IDS logs to identify sessions of interest
# Analyze specific malicious sessions
chaosreader.pl suspicious-session.pcap -D alert-analysis/
# Process in batches
for pcap in *.pcap; do
chaosreader.pl "$pcap" -D "${pcap%.pcap}_output/"
done
# Parallel processing
parallel chaosreader.pl {} -D {.}_output/ ::: *.pcap
# Use filters to reduce data
chaosreader.pl --filter "tcp and port 80" large-capture.pcap -D filtered/
# Process subset first
tcpdump -r large.pcap -w subset.pcap -c 50000
chaosreader.pl subset.pcap -D preview/
- Verify hash: Always verify pcap integrity before and after analysis
- Document procedure: Record all commands and parameters used
- Preserve evidence: Create read-only copies of original files
- Cross-reference: Compare findings with other tools (Wireshark, tshark)
- Timeline analysis: Build chronological timeline of events
- Export findings: Save all extracted data with proper metadata
- Chain of custody: Maintain detailed logs of analysis activities
| Scenario | Approach |
|---|
| Web attack investigation | Filter port 80/443, review HTTP requests/responses |
| Credential theft | Search for FTP, telnet, HTTP Basic Auth sessions |
| Data exfiltration | Identify large file transfers, check FTP uploads |
| Malware communication | Extract DNS queries, HTTP beacons, C2 traffic |
| Email investigation | Filter SMTP/POP3/IMAP ports, extract messages |
| Network reconnaissance | Analyze DNS queries, port scans, service probes |
