DZAJTCPER - TCP CWND Monitor & Analyzer

Comprehensive TCP congestion window monitoring and analysis toolkit using eBPF for kernel-level monitoring with advanced filtering, visualization, and reporting capabilities.

🚀 Features

Real-time eBPF monitoring of TCP CWND directly from kernel (kprobe on tcp_rcv_established)
Unified command interface through single ./run.sh script
Session-based organization with automatic timestamped folders
Advanced filtering by PID, addresses, ports, CWND ranges
Multiple chart types (timeline, connections, heatmap, overview)
Interactive HTML reports with Plotly visualization
Comprehensive HTML analysis reports with embedded charts and statistics
Live monitoring with real-time updates
Multiple report formats (text, JSON, HTML)
Automatic session management with cleanup functionality
Historical analysis of previously collected data
Automatic permission handling for seamless operation

📦 Installation

Prerequisites

Linux with eBPF support (kernel >= 5.x recommended)
Root/sudo privileges (for eBPF monitoring)
Python 3.8+

Quick Setup (recommended)

git clone https://github.com/LordPrinz/dzajtcper.git
cd dzajtcper
chmod +x install.sh
./install.sh

install.sh automatically:

Detects your distribution (Debian/Ubuntu, Fedora, CentOS/RHEL, Arch)
Installs system packages: bpfcc-tools, python3-bpfcc, linux-headers, python3-venv
Creates a Python virtual environment with --system-site-packages (required for BCC access)
Installs Python dependencies (pandas, matplotlib, seaborn, plotly) into the venv
Makes all scripts executable

Note: If you previously ran install.sh, running it again will automatically recreate the virtual environment from scratch to ensure a clean state.

Uninstallation

./uninstall.sh

Removes the Python virtual environment. Optionally removes generated output data (out/). System packages (BCC, etc.) are NOT removed automatically.

📷 Screenshots

🎯 Quick Start

1. Install

chmod +x install.sh
./install.sh

2. Monitor TCP for 30 seconds and analyze

./run.sh monitor --duration 30    # Automatically handles sudo
./run.sh analyze                  # Analyze latest session

3. Monitor and analyze in one command with HTML report

./run.sh quick --duration 60      # Monitor + analyze + generate HTML report automatically

📋 HTML Report Features:

📊 Complete statistics (connections, processes, CWND analysis)
📈 Embedded interactive charts
🔗 Connection analysis tables
📡 Per-process activity breakdown
Location: out/session_*/charts/tcp_analysis_*.html

4. Generate comprehensive report

./run.sh report                   # Generate HTML report from latest session

📁 Session Management

Output Directory Structure

All TCP CWND data is automatically organized in session directories with unified structure:

out/
├── session_20250911_143025/
│   ├── cwnd_log.csv                         # 📊 Raw TCP monitoring data
│   ├── charts/
│   │   ├── chart_20250911_143225_timeline.png       # 📈 Timeline chart
│   │   ├── chart_20250911_143225_connections.png    # 🔗 Connection analysis
│   │   ├── chart_20250911_143225_heatmap.png        # 🌡️ Traffic heatmap
│   │   ├── chart_20250911_143225_timeline_interactive.html  # 🎯 Interactive charts
│   │   └── tcp_analysis_20250911_143225.html        # 📋 Comprehensive HTML report
│   └── analysis_20250911_145030/            # 📊 Alternative analysis folder
│       ├── chart_20250911_145030_timeline.png       # 📈 Filtered analysis
│       └── chart_20250911_145030_connections.png    # 🔗 Filtered analysis
├── session_20250911_145123/
│   └── cwnd_log.csv                         # 📊 Session with data only
└── session_20250911_150245/
    ├── cwnd_log.csv                         # 📊 Raw data
    ├── charts/                              # 📈 Quick analysis charts + HTML report
    └── analysis_*_...                       # 📈 Additional analysis files

Session Commands

# List all sessions with data summary
./run.sh list

# Clean up empty session directories
./run.sh clean

💡 Usage Examples

Basic Monitoring

# Monitor indefinitely (Ctrl+C to stop)
./run.sh monitor

# Monitor for specific duration
./run.sh monitor --duration 300

Analyzing Previous Sessions

# Analyze latest session automatically
./run.sh analyze

# Analyze specific session
./run.sh analyze session_20250911_143025

# List available sessions
./run.sh list

# Clean empty sessions
./run.sh clean

Advanced Filtering

# Filter by destination port (HTTPS traffic)
./run.sh analyze --dport 443 --charts timeline connections

# Filter by source port (SSH traffic)
./run.sh analyze --sport 22 --charts heatmap

# Filter by PID (specific process)
./run.sh analyze --pid 1234 --charts timeline

# Filter by IP addresses
./run.sh analyze --saddr 192.168.1.100 --daddr 10.0.0.1

# Filter by CWND range
./run.sh analyze --cwnd-min 10 --cwnd-max 100

# Combine multiple filters
./run.sh analyze --dport 443 --cwnd-min 20 --charts timeline connections

Chart Generation

# Generate specific chart types
./run.sh analyze --charts timeline          # Only timeline
./run.sh analyze --charts connections       # Only connections
./run.sh analyze --charts heatmap          # Only heatmap
./run.sh analyze --charts overview         # Only overview
./run.sh analyze --charts timeline connections heatmap  # Multiple

# All charts (default behavior when no --charts specified)
./run.sh analyze

Quick Start (All-in-One)

# Quick monitoring: collect data + analyze + generate charts + HTML report
./run.sh quick --duration 60

# What Quick Start does:
# 1. Monitors TCP connections for specified duration (default: 60s)
# 2. Automatically analyzes collected data
# 3. Generates overview charts (timeline, connections, heatmap)
# 4. Creates comprehensive HTML analysis report in charts folder
# 5. Shows quick statistics summary

Report Generation

# Comprehensive HTML report
./run.sh report

# Report from specific session
./run.sh report session_20250911_143025

# Report with custom output name
./run.sh report session_20250911_143025 custom_analysis.html

# Quick monitoring with immediate report
./run.sh quick --duration 30 && ./run.sh report

Live Monitoring

# Live monitoring of latest session
./run.sh live

# Live monitoring for specific duration
./run.sh live --duration 60

🔧 Command Reference

Main Commands

Command	Description	Example
`monitor`	Start eBPF monitoring	`./run.sh monitor --duration 60`
`analyze`	Analyze existing data	`./run.sh analyze --dport 443`
`live`	Live monitoring dashboard	`./run.sh live --duration 60`
`quick`	Monitor + analyze + charts + HTML report	`./run.sh quick --duration 30`
`report`	Generate comprehensive report	`./run.sh report`
`list`	List all sessions	`./run.sh list`
`clean`	Clean empty sessions	`./run.sh clean`

Global Options

Option	Type	Description	Example
`--duration`	int	Monitoring duration in seconds	`--duration 300`
`--help`	flag	Show command help	`./run.sh --help`

Filter Options

Option	Type	Description	Example
`--pid`	int	Filter by process ID	`--pid 1234`
`--saddr`	string	Source address pattern	`--saddr 192.168.1.*`
`--daddr`	string	Destination address pattern	`--daddr 10.0.0.1`
`--sport`	int	Source port	`--sport 22`
`--dport`	int	Destination port	`--dport 443`
`--cwnd-min`	int	Minimum CWND value	`--cwnd-min 10`
`--cwnd-max`	int	Maximum CWND value	`--cwnd-max 100`

Chart Options

Chart Type	Description	Use Case
`timeline`	CWND evolution over time	Overall performance analysis
`connections`	Per-connection statistics	Connection comparison
`heatmap`	Activity intensity map	Pattern identification
`overview`	Summary statistics	Quick overview

Report Formats

Format	Description	Use Case
HTML	Rich formatted report with embedded charts	Detailed analysis and presentation
Text	Plain text summary	Quick review
JSON	Machine readable data	Automation/scripting

🛠️ Troubleshooting

Common Issues

1. `ModuleNotFoundError: No module named 'pandas'`

The virtual environment is missing or was created incorrectly. Re-run install:

./install.sh

This will remove the old venv and create a fresh one with all dependencies.

2. Permission Errors

# run.sh automatically handles sudo for monitoring commands
./run.sh monitor --duration 60   # Handles sudo automatically
./run.sh analyze                 # Handles file permissions automatically

3. No Data Collected

# Check if there's active TCP traffic
ss -tuln

# Use longer monitoring duration
./run.sh monitor --duration 120

# Generate some traffic
curl https://example.com

4. BCC / eBPF Errors

# Ensure kernel headers are installed
sudo apt install linux-headers-$(uname -r)

# Verify BCC is working
sudo python3 -c "from bcc import BPF; print('BCC OK')"

5. Empty Session Folders

# Clean up empty sessions
./run.sh clean

# Check if monitoring collected data
./run.sh list

6. Virtual Environment Not Found

If ./run.sh shows "Virtual environment not found!":

./install.sh    # Creates/recreates the venv

Performance Tips

Short analysis: 15-30 seconds monitoring
Performance testing: 2-5 minutes monitoring
Long-term analysis: 10+ minutes monitoring
Live monitoring: Use with active network traffic
Large datasets: Use filters to focus analysis

📊 Data Analysis Examples

Scenario 1: Web Server Performance

# Monitor during load test
./run.sh monitor --duration 300

# Analyze HTTP traffic
./run.sh analyze --dport 80 --charts timeline connections

# Generate comprehensive report
./run.sh report

Scenario 2: SSH Connection Analysis

# Monitor SSH activity
./run.sh monitor --duration 120

# Analyze SSH connections
./run.sh analyze --sport 22 --charts connections heatmap

Scenario 3: Database Connection Monitoring

# Monitor database traffic
./run.sh monitor --duration 180

# Analyze MySQL connections
./run.sh analyze --dport 3306

# Generate MySQL analysis report
./run.sh report

Scenario 4: Application-Specific Analysis

# Find application PID
pgrep nginx

# Monitor and analyze application traffic
./run.sh quick --duration 60
./run.sh analyze --pid 1234 --charts timeline connections

🏗️ Architecture

Project Structure

dzajtcper/
├── run.sh                  # 🎯 Unified command interface (uses venv Python)
├── tcp_monitor.py          # 🔧 CLI engine / orchestrator
├── tcp_cwnd_monitor.py     # 🔬 eBPF kprobe script (kernel-level tracing)
├── src/                    # 📦 Core modules
│   ├── data_loader.py      # 📊 Data loading and validation
│   ├── data_filter.py      # 🔍 Advanced filtering capabilities
│   ├── visualizer.py       # 📈 Chart generation (matplotlib, seaborn, plotly)
│   ├── monitor.py          # 📡 Live monitoring functionality
│   ├── reporter.py         # 📄 Report generation (text, JSON, HTML)
│   └── log_manager.py      # 📁 Session management
├── docs/                   # 📚 Documentation
│   ├── QUICK_START.md      # 🚀 Quick start guide
│   └── CHEAT_SHEET.md      # ⚡ Command cheat sheet
├── out/                    # 💾 Session data storage (generated)
├── venv/                   # 🐍 Python virtual environment (generated)
├── install.sh              # ⚙️ Installation script
├── uninstall.sh            # 🗑️ Uninstallation script
├── requirements.txt        # 📋 Python pip dependencies
└── README.md               # 📚 This documentation

How It Works

install.sh installs system BCC packages and creates a Python venv with --system-site-packages so that both pip packages (pandas, matplotlib...) and system BCC are accessible
run.sh resolves the venv Python interpreter and uses it for all commands; handles sudo for monitoring
tcp_cwnd_monitor.py attaches a kprobe to tcp_rcv_established via eBPF, reads snd_cwnd from struct tcp_sock, and sends events via perf buffer
tcp_monitor.py orchestrates monitoring sessions, analysis, chart generation, and reporting
src/ modules handle data loading, filtering, visualization, live monitoring, and report generation

Core Components

Session Manager (src/log_manager.py)
- Automatic session creation with timestamps
- Empty session cleanup
- Session listing and selection
DataLoader (src/data_loader.py)
- CSV data loading and validation
- Connection string creation
- Data integrity checks
DataFilter (src/data_filter.py)
- Method chaining for complex filters
- PID, address, port, CWND range filtering
- Time-based and connection-based filtering
ChartGenerator (src/visualizer.py)
- Timeline plots with high-contrast colors
- Connection analysis charts
- Activity heatmaps
- Interactive HTML charts (Plotly)
ReportGenerator (src/reporter.py)
- Comprehensive analysis reports
- Multiple output formats (text, JSON, HTML)
- Performance metrics calculation

📋 Requirements

OS: Linux with eBPF support (kernel >= 5.x recommended, 4.x supported)
Privileges: Root/sudo for eBPF monitoring
Python: 3.8+
System packages: bpfcc-tools, python3-bpfcc, linux-headers, python3-venv
Python packages (installed automatically by install.sh): pandas, matplotlib, seaborn, plotly

📚 Documentation

docs/QUICK_START.md - Complete guide to HTML reports and quick analysis
docs/CHEAT_SHEET.md - Command reference and examples

📝 License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
docs		docs
src		src
.gitignore		.gitignore
README.md		README.md
install.sh		install.sh
requirements.txt		requirements.txt
run.sh		run.sh
tcp_cwnd_monitor.py		tcp_cwnd_monitor.py
tcp_monitor.py		tcp_monitor.py
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation