aya/traffic-monitor

Traffic Monitor

A high-performance eBPF-based network traffic monitoring tool built with Aya. This tool monitors incoming traffic at the XDP (eXpress Data Path) layer and logs traffic from IP addresses that are not in a configured permitted list.

Features

• XDP-based monitoring: High-performance packet processing at the network driver level
• CIDR range support: Configure permitted IP ranges using CIDR notation
• Protocol detection: Identifies and logs TCP, UDP, ICMP, and other IP protocols
• Flexible actions: Option to log-only or log-and-drop non-permitted traffic
• Real-time statistics: Periodic summaries of traffic patterns
• JSON configuration: Easy-to-manage configuration files
• Structured logging: Multiple output formats (JSON, CSV, JSONL, Console) for analytics
• Log analysis: Built-in analysis script with threat detection and traffic insights

Architecture

The tool consists of two main components:

1. eBPF Program (traffic_monitor.bpf.rs): Runs in kernel space at the XDP layer

   • Parses Ethernet and IP headers
   • Checks source IPs against permitted CIDR ranges
   • Logs non-permitted traffic via ring buffer
   • Optionally drops packets based on configuration

2. Userspace Program (main.rs): Manages the eBPF program and processes events

   • Loads and configures the eBPF program
   • Processes events from the ring buffer
   • Provides statistics and logging
   • Handles configuration management

Installation

From the aya repository root:

cd traffic-monitor
cargo build --release

Usage

Basic Usage

# Monitor interface eth0 with default configuration (log only)
sudo ./target/release/traffic-monitor --interface eth0 --config configs/default.json

# Monitor with packet dropping enabled
sudo ./target/release/traffic-monitor --interface eth0 --config configs/default.json --drop-packets

# Verbose logging
sudo ./target/release/traffic-monitor --interface eth0 --config configs/default.json --verbose

Configuration

Create a JSON configuration file with permitted CIDR ranges:

{
  "permitted_cidrs": [
    "127.0.0.0/8",
    "10.0.0.0/8", 
    "172.16.0.0/12",
    "192.168.0.0/16"
  ]
}

Example configurations are provided in the configs/ directory:

• default.json: Standard private networks and localhost
• strict.json: Only localhost and a specific /24 network

Command Line Options

• --interface, -i: Network interface to attach to (required)
• --config, -c: Path to JSON configuration file (required)
• --drop-packets: Drop non-permitted packets instead of just logging
• --verbose, -v: Enable verbose logging
• --log-format: Log output format (console, json, csv, jsonl)
• --log-file: Log output file path (required for non-console formats)
• --log-buffer-size: Log buffer size in bytes (default: 8192)

Examples

Generate Test Traffic

# Run the test traffic generator
cargo run --example test-traffic

Monitor Specific Interface

# Monitor a specific interface
sudo ./target/release/traffic-monitor -i eth0 -c configs/default.json

Strict Monitoring with Packet Dropping

# Only allow localhost and 192.168.1.0/24, drop everything else
sudo ./target/release/traffic-monitor -i eth0 -c configs/strict.json --drop-packets

Structured Logging Examples

# Log to JSON file for analysis
sudo ./target/release/traffic-monitor -i eth0 -c configs/default.json \
  --log-format json --log-file traffic.json

# Log to CSV file for spreadsheet analysis
sudo ./target/release/traffic-monitor -i eth0 -c configs/default.json \
  --log-format csv --log-file traffic.csv

# Log to JSONL file (recommended for log analysis)
sudo ./target/release/traffic-monitor -i eth0 -c configs/default.json \
  --log-format jsonl --log-file traffic.jsonl

Log Analysis

# Analyze traffic logs with automatic format detection
python3 scripts/analyze_logs.py traffic.jsonl

# Analyze CSV logs
python3 scripts/analyze_logs.py traffic.csv --format csv

# Export detailed analysis report
python3 scripts/analyze_logs.py traffic.jsonl --export-report analysis.json

Testing

Run the test suite:

# Unit tests
cargo test

# Integration tests
cargo test --test integration_tests

# All tests with verbose output
cargo test -- --nocapture

XDP vs Other eBPF Hook Points

XDP (chosen for this implementation):

• ✅ Highest performance (runs before kernel network stack)
• ✅ Efficient packet dropping with minimal CPU overhead
• ✅ Bypasses kernel networking for dropped packets
• ❌ Limited packet modification capabilities
• ❌ No connection tracking context

TC (Traffic Control):

• ✅ More packet modification options
• ✅ Access to more kernel network state
• ❌ Lower performance than XDP
• ❌ Runs after some kernel processing

Socket Filter:

• ✅ Socket-level visibility
• ✅ Application context
• ❌ Much lower performance
• ❌ Only sees traffic for monitored sockets

Performance Considerations

• Ring Buffer Size: Default 256KB, adjust based on traffic volume
• Statistics Interval: Default 60 seconds, can be modified in event_handler.rs
• Maximum CIDR Ranges: Default 256, can be increased in the eBPF program
• Memory Usage: Minimal kernel memory footprint, userspace scales with unique IPs seen

Troubleshooting

Permission Issues

# Ensure you have CAP_SYS_ADMIN or run as root
sudo ./target/release/traffic-monitor ...

XDP Attachment Issues

If XDP attachment fails, try SKB mode (modify XdpFlags::default() to XdpFlags::SKB_MODE in main.rs):

program.attach(&opt.interface, XdpFlags::SKB_MODE)?;

Interface Not Found

# List available interfaces
ip link show

High CPU Usage

• Reduce ring buffer polling frequency
• Increase statistics interval
• Consider using TC hook for lower performance requirements

Security Considerations

• Runs with elevated privileges (CAP_SYS_ADMIN)
• Packet dropping can cause denial of service
• Log rotation recommended for high-traffic environments
• Monitor for resource exhaustion with many unique source IPs

Development

Building eBPF Program

The eBPF program is automatically built via build.rs using aya-build.

Adding New Features

1. Modify the eBPF program in src/traffic_monitor.bpf.rs
2. Update userspace handling in src/main.rs and related modules
3. Add tests in tests/integration_tests.rs
4. Update configuration schema if needed

Debugging

Enable eBPF program logging:

# View eBPF logs
sudo cat /sys/kernel/debug/tracing/trace_pipe

License

This project follows the same license as the Aya project (MIT OR Apache-2.0).