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

"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 mode (netrain --demo) — no root or live interface needed. Recorded from the actual binary with asciinema + agg.

• Stable 60 FPS rendering with thousands of particles
• Sub-millisecond threat-detection logic — the detection function itself benchmarks at 29ns per packet in isolation (see PERFORMANCE_REPORT.md for the full disclaimer); this is a micro-benchmark of one function, not an end-to-end capture-to-alert measurement including pcap I/O and rendering
• Zero-allocation hot paths for maximum efficiency

• 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

• Port scan detection with time-window analysis
• DDoS-pattern alerts (traffic spike detection)
• Anomaly detection for malformed packets
• Real-time threat visualization with color-coded alerts

• 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)

• 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

Requirements: Rust 1.70+ must be installed first

cargo install netrain

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

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.

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

# libpcap is included with macOS
# No additional installation needed

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

# 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

• Q - Quit the application

• 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

• 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

• 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

cargo test

cargo bench

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

(SIMD is on the roadmap — see "Recommendations for Further Optimization" in PERFORMANCE_REPORT.md — but no SIMD code exists in this codebase today.)

• 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

We welcome contributions!

# 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

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

• 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

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

# Verify installation
cargo --version

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

# Or use demo mode
netrain --demo

# Use demo mode if no interfaces available
netrain --demo

# 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)

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

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

• 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

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