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

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

Built with ❤️ in Rust

⭐ Star on GitHub | 🍴 Fork | 📋 Issues