Chaosreader

Overview

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.

Installation

From Source

# 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

Perl Installation

# 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

Package Manager

# 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

Quick Start

Basic Session Extraction

# 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

Output Organization

# Create output directory structure
mkdir analysis-results
chaosreader.pl -D analysis-results/ network-capture.pcap

# View extracted files
ls -la analysis-results/

Core Commands and Options

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

Protocol-Specific Extraction

HTTP/HTTPS Sessions

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

FTP Sessions

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

SMTP/Email Sessions

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

Telnet Sessions

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

DNS Sessions

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

Advanced Filtering and Analysis

Using BPF Filters

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

Protocol-Specific Processing

# 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

Output Formats and Interpretation

Directory Structure

# 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

HTML Output

# Generate HTML report
chaosreader.pl capture.pcap -D html-output/

# View results
open html-output/index.html
# or
firefox html-output/index.html

Text Output

# Generate text-based analysis
chaosreader.pl -w capture.pcap -D text-output/

# View session summary
cat text-output/chaos.summary

Practical Forensic Analysis Workflows

Complete Incident Analysis

# 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

Web Attack Analysis

# 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/*

Email Investigation

# 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/*

Data Exfiltration Detection

# 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/*

Session Reconstruction Techniques

TCP Stream Reassembly

# Reconstruct complete TCP streams
chaosreader.pl capture.pcap -D streams/

# Review stream files
cat streams/conversations/001_*

# Verify stream integrity
wc -l streams/conversations/*

Handling Out-of-Order Packets

# 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

Session Timeline Analysis

# 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

Evidence Preservation and Documentation

Hash Verification

# 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

Chain of Custody

# 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

Report Generation

# 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

Troubleshooting Common Issues

No Sessions Extracted

# 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

Memory/Performance Issues

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

Encoding/Decoding Issues

# 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

Integration with Other Tools

Combined with Wireshark

# Export filtered traffic from Wireshark
# File > Export Specified Packets > pcap format

# Analyze exported file
chaosreader.pl wireshark-export.pcap -D ws-analysis/

Combined with tcpdump

# Capture and analyze in one workflow
tcpdump -i eth0 -w live-capture.pcap
chaosreader.pl live-capture.pcap -D live-analysis/

Combined with Zeek/Suricata

# Export alerts as pcap
# Use IDS logs to identify sessions of interest

# Analyze specific malicious sessions
chaosreader.pl suspicious-session.pcap -D alert-analysis/

Performance Optimization

Large File Handling

# Process in batches
for pcap in *.pcap; do
  chaosreader.pl "$pcap" -D "${pcap%.pcap}_output/"
done

# Parallel processing
parallel chaosreader.pl {} -D {.}_output/ ::: *.pcap

Memory-Efficient Analysis

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

Best Practices for Network Forensics

• 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

Common Analysis Patterns

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