netrain 0.2.0

Matrix-style network packet monitor with threat detection
Documentation

NetRain 🌧️

╔╗╔═╗╔╦╗╦═╗╔═╗╦╔╗╔
║║║╣  ║ ╠╦╝╠═╣║║║║
╝╚╚═╝ ╩ ╩╚═╩ ╩╩╝╚╝

"Welcome to the real world." - Morpheus

A Matrix-style network packet monitor with real-time threat detection and stunning terminal visualizations. Built with Rust for maximum performance.

CI Status GitHub release License: MIT GitHub stars

🎬 Demo

Coming Soon: GIFs showing the Matrix rain effect in action

⚡ Performance That'll Blow Your Mind

  • 212x faster packet parsing (1.2ns vs 100ns target) 🚀
  • Stable 60 FPS rendering with thousands of particles
  • Sub-millisecond threat detection (29ns per packet)
  • Zero-allocation hot paths for maximum efficiency

✨ Features

🌊 Visual Experience

  • Authentic Matrix rain with Japanese katakana characters
  • Rainbow mode for critical threats
  • 3D depth illusion with variable column speeds
  • Particle effects on packet arrival
  • Real-time animations with smooth interpolation

🛡️ Security Monitoring

  • Port scan detection with time-window analysis
  • DDoS attack detection (SYN floods, traffic spikes)
  • Anomaly detection for malformed packets
  • Real-time threat visualization with color-coded alerts

📊 Network Analysis

  • Protocol classification (TCP, UDP, HTTP, HTTPS, DNS, SSH)
  • Live packet capture with pcap integration
  • Traffic statistics and rate monitoring
  • Performance metrics (FPS, memory usage, packet rates)

🎮 User Experience

  • Demo mode for showcasing without network access
  • Keyboard controls (Q to quit, D for demo)
  • Responsive UI that adapts to terminal size
  • Professional terminal interface with styled borders

🚀 Installation

Current Version: v0.2.0 - View Changelog

Quick Install

Using Cargo (All Platforms)

cargo install netrain

Using Homebrew (macOS/Linux)

# Coming soon!
brew tap marcuspat/netrain
brew install netrain

Using Install Script

curl -sSL https://raw.githubusercontent.com/marcuspat/netrain/main/install.sh | bash

Prerequisites

  • libpcap development libraries (for packet capture)
  • Rust 1.70+ (only for building from source)

Ubuntu/Debian

sudo apt-get update
sudo apt-get install libpcap-dev

macOS

# libpcap is included with macOS
# No additional installation needed

Windows

# Install WinPcap or Npcap
# https://npcap.com/

Build from Source

# Clone the repository
git clone https://github.com/marcuspat/netrain.git
cd netrain

# Build the project
cargo build --release

# Run NetRain
./target/release/netrain

# Or run in demo mode (no network access needed)
./target/release/netrain --demo

Quick Demo

# Try the demo mode first (no root privileges needed)
cargo run -- --demo

🎯 Usage

Basic Usage

# Monitor live network traffic (requires root/admin privileges)
sudo ./target/release/netrain

# Demo mode (safe to run without privileges)
./target/release/netrain --demo

Keyboard Controls

  • Q - Quit the application
  • D - Toggle demo mode
  • Ctrl+C - Emergency exit

Understanding the Interface

Matrix Rain Panel (Left 70%)

  • Green characters falling like rain represent network packets
  • Faster falling indicates higher traffic or threats
  • Rainbow colors appear during critical security events
  • Character density correlates with network activity

Statistics Panel (Right 30%)

  • Performance - FPS, packet rate, memory usage
  • Protocol Stats - Breakdown by protocol type
  • Threat Monitor - Real-time security alerts
  • Packet Log - Recent network activity

🔧 Configuration

Running with Custom Interface

# Specify network interface (Linux)
sudo ./target/release/netrain --interface eth0

# Capture specific protocols
sudo ./target/release/netrain --filter "tcp port 80"

Performance Tuning

# Enable high-performance mode
sudo ./target/release/netrain --performance

# Adjust frame rate
sudo ./target/release/netrain --fps 120

🧪 Development

Running Tests

# Run all tests
cargo test

# Run specific test suite
cargo test --test integration_tests

# Run with coverage
cargo tarpaulin --out html

Benchmarks

# Run performance benchmarks
cargo bench

# View benchmark results
open target/criterion/report/index.html

Debug Mode

# Run with debug logging
RUST_LOG=debug cargo run -- --demo

📈 Technical Architecture

Performance Optimizations

  • Zero-allocation packet parsing using unsafe optimizations
  • Lookup tables for character generation (11x faster)
  • Object pooling for matrix characters and columns
  • SIMD operations where applicable
  • Lock-free atomic counters for performance metrics

Security Features

  • Time-window analysis for pattern detection
  • Configurable thresholds for different attack types
  • Multi-threaded packet processing with lock-free coordination
  • Memory-safe implementation despite performance optimizations

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Fork the repo and clone your fork
git clone https://github.com/yourusername/netrain.git
cd netrain

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes and test
cargo test
cargo clippy
cargo fmt

# Commit and push
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

📋 System Requirements

Minimum Requirements

  • OS: Linux, macOS, or Windows
  • RAM: 256 MB
  • CPU: Any 64-bit processor
  • Network: Any interface supported by pcap

Recommended for Best Experience

  • Terminal: Modern terminal with Unicode support
  • Colors: 256-color or True Color support
  • Size: At least 80x24 characters
  • Privileges: Root/Administrator for live packet capture

🐛 Troubleshooting

Common Issues

Permission Denied

# On Linux/macOS, packet capture requires root privileges
sudo ./target/release/netrain

# Or use demo mode
./target/release/netrain --demo

No Network Interface Found

# List available interfaces
ip link show  # Linux
ifconfig      # macOS

# Use demo mode if no interfaces available
./target/release/netrain --demo

Terminal Display Issues

# Ensure terminal supports Unicode
export LANG=en_US.UTF-8

# For best experience, use a modern terminal like:
# - Alacritty, Kitty, WezTerm (recommended)
# - iTerm2 (macOS), Windows Terminal (Windows)

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • The Matrix franchise for inspiration
  • Rust community for amazing performance tools
  • ratatui for the terminal UI framework
  • pcap library maintainers
  • All the security researchers who make threat detection possible

📞 Support

"There is no spoon... only packets." 🥄

Built with ❤️ in Rust

⭐ Star on GitHub | 🍴 Fork | 📋 Issues