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.

⚡ Quick Start: Install Rust → cargo install netrain → sudo netrain (or netrain --demo)

🎬 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 cascading 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)
• IP address tracking with real-time packet counting
• Top active IPs display showing most active network endpoints
• Enhanced packet log with 70% more screen space for better visibility
• 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)
• Responsive UI that adapts to terminal size
• Professional terminal interface with styled borders

🚀 Installation

From crates.io (Recommended)

Requirements: Rust 1.70+ must be installed first

cargo install netrain

From Source

Requirements: Rust 1.70+ must be installed first

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

# Build the project
cargo build --release

# The binary will be at ./target/release/netrain

📋 Prerequisites

Install Rust (Required)

NetRain requires Rust 1.70+ for both installation methods above.

# Install Rust via rustup (recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Verify installation
rustc --version
cargo --version

Alternatively, visit rustup.rs for other installation options.

Install libpcap (For packet capture)

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
# Download from: https://npcap.com/

🎯 Usage

# Run with packet capture (requires root/admin)
sudo netrain

# Run in demo mode (no root required)
netrain --demo

# Show help
netrain --help

# Show version
netrain --version

Keyboard Controls

• Q - Quit the application

Understanding the Interface

Matrix Rain Panel (Left 70%)

• Green characters falling like rain represent network packets
• White leading characters indicate active packet transmission
• Character density correlates with network activity
• Responsive animation with consistent 60 FPS performance

Packet Log Panel (Main Center Area)

• Top Active IPs - Shows the 3 most active IP addresses with packet counts
  • Format: #1 192.168.1.105 (15 pkts)
  • Real-time updates as traffic flows
• Enhanced packet display - Extended to 70% of screen space for better visibility
• Protocol color coding - Different colors for HTTP, HTTPS, DNS, SSH, TCP, UDP
• Real-time timestamps - Shows exact time of packet capture
• Live packet stream - Up to 50 recent packets with automatic scrolling

Statistics Panel (Right 30%)

• Performance - FPS, packet rate, memory usage
• Protocol Stats - Breakdown by protocol type with live counts
• Threat Monitor - Real-time security alerts
• Network Graphs - Compact sparklines for each protocol type

🧪 Development

Running Tests

cargo test

Benchmarks

cargo bench

📈 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
• Pre-configured thresholds for different attack types
• Multi-threaded packet processing with lock-free coordination
• Memory-safe implementation despite performance optimizations

🤝 Contributing

We welcome contributions!

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

"cargo: command not found"

# Install Rust first (includes cargo)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Verify installation
cargo --version

Permission Denied

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

# Or use demo mode
netrain --demo

No Network Interface Found

# Use demo mode if no interfaces available
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)

"Killed" Error During Installation (Linux)

If you get a "signal: 9, SIGKILL: kill" error when running cargo install netrain on Linux, your system likely doesn't have enough memory to compile the dependencies.

Common on: VPS/cloud instances with ≤1GB RAM

Solution 1: Add Swap Space (Recommended)

# Create a 4GB swap file
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make it permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Now try installing again
cargo install netrain

Solution 2: Reduce Compilation Parallelism

# Limit cargo to 1 job to reduce memory usage
export CARGO_BUILD_JOBS=1
cargo install netrain

Solution 3: Use Pre-built Binary Check if pre-built binaries are available for your release:

# Visit https://github.com/marcuspat/netrain/releases
# Download the appropriate binary for your system
# For example, for Linux x86_64:
wget https://github.com/marcuspat/netrain/releases/download/vX.Y.Z/netrain-linux-amd64.tar.gz
tar -xzf netrain-linux-amd64.tar.gz
sudo mv netrain /usr/local/bin/
sudo chmod +x /usr/local/bin/netrain

Note: Replace vX.Y.Z with the actual version number

📝 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

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues