Skip to content
/ rustshark Public

RUSTSHARK is a professional deep packet inspection tool built entirely in Rust, designed to provide memory-safe, high-performance network traffic analysis.

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

ChronoCoders/rustshark

BranchesTags

Repository files navigation

  ____  _   _ ____ _____ ____  _   _    _    ____  _  __
 |  _ \| | | / ___|_   _/ ___|| | | |  / \  |  _ \| |/ /
 | |_) | | | \___ \ | | \___ \| |_| | / _ \ | |_) | ' / 
 |  _ <| |_| |___) || |  ___) |  _  |/ ___ \|  _ <| . \ 
 |_| \_\\___/|____/ |_| |____/|_| |_/_/   \_\_| \_\_|\_\
                                                          
      🦈 Deep Packet Inspection - Zero Memory Bugs 🦈

Version Rust License

Professional packet inspection tool built with Rust - Memory safe, blazingly fast

🚀 Features

  • Real-time Packet Capture - Live packet capture via Npcap/libpcap
  • 🌐 Web-Based Dashboard - Real-time monitoring with interactive visualizations (NEW!)
  • WebSocket Streaming - Live packet data streamed to browser in real-time
  • PCAP File I/O - Read and write PCAP/PCAP-NG files (Wireshark compatible)
  • Multi-Protocol Support - Ethernet, IPv4, TCP, UDP, DNS, HTTP
  • Flow Tracking - Bidirectional flow analysis with statistics
  • Anomaly Detection - Port scan, DDoS, DNS tunneling detection with alerts
  • Network Topology - Interactive graph visualization of network connections
  • Protocol Charts - Visual breakdown of traffic by protocol (TCP/UDP/DNS/HTTP)
  • Interface Aliases - User-friendly interface selection (wifi, vpn, eth)
  • Verbose Analysis - Detailed packet inspection with protocol headers
  • 100% Rust - Backend and frontend both written in Rust (Leptos + WebAssembly)
  • Zero Unsafe Code - 100% memory safety guaranteed by Rust

📦 Installation

Prerequisites

Windows:

  1. Install Npcap with WinPcap API-compatible mode
  2. Download Npcap SDK and extract to C:\npcap-sdk\
  3. Set environment variable:
   setx LIB "C:\npcap-sdk\Lib\x64;%LIB%"
  1. Open a new terminal for changes to take effect

Linux:

sudo apt-get install libpcap-dev

macOS:

brew install libpcap

Build from Source

# Clone repository
git clone https://github.com/ChronoCoders/rustshark.git
cd rustshark

# Build release version
cargo build --release

# Binary location
./target/release/rustshark

🎯 Quick Start

Option 1: Web Dashboard (Recommended for Visual Analysis)

Build and run the web dashboard:

# Windows
build-dashboard.cmd

# Linux/macOS
chmod +x build-dashboard.sh
./build-dashboard.sh

# Run the server
target/release/rustshark-server

# Open browser to http://localhost:3000
# Login: admin / password

Features:

  • 📊 Real-time packet statistics and live stream
  • 🥧 Protocol distribution pie charts
  • 🌐 Network topology visualization
  • 📈 Timeline charts with historical data
  • 🚨 Anomaly detection alerts with notifications
  • ⚙️ Configuration panel for capture settings
  • 🔐 Secure authentication

See DASHBOARD.md for full documentation.

Option 2: Command-Line Interface (CLI)

List Available Interfaces:

rustshark --list

Capture Packets:

# Capture 100 packets from WiFi
rustshark wifi --count 100

# Capture with verbose output
rustshark wifi --count 50 --verbose

# Capture from specific interface by number
rustshark 5 --count 100

# Capture from VPN
rustshark vpn --count 50 --verbose

Command-Line Options

USAGE:
    rustshark [OPTIONS] [INTERFACE]

ARGS:
    <INTERFACE>    Network interface (name, alias, or number)

OPTIONS:
    -l, --list              List available network interfaces
    -c, --count <NUM>       Number of packets to capture [default: 100]
    -v, --verbose           Enable verbose output with full packet details
    -o, --output <FILE>     Save captured packets to PCAP/PCAP-NG file
    -i, --input <FILE>      Read and analyze packets from PCAP/PCAP-NG file
    -f, --format <FORMAT>   Output file format: pcap or pcapng [default: pcap]
    -L, --log-level <LEVEL> Set log level [default: info]
    -h, --help              Print help information
    -V, --version           Print version information

💾 PCAP File Operations

RUSTSHARK supports both standard PCAP and modern PCAP-NG file formats, compatible with Wireshark and other analysis tools.

Save Captured Packets to File

# Save to PCAP format (default)
rustshark wifi --count 1000 --output capture.pcap

# Save to PCAP-NG format (explicitly)
rustshark wifi --count 1000 --output capture.pcapng --format pcapng

# Format is auto-detected from file extension
rustshark wifi --count 1000 --output capture.pcapng  # Uses PCAP-NG

# Capture with verbose output and save to file
rustshark wifi --count 500 --verbose --output traffic.pcap

Read and Analyze PCAP Files

# Read PCAP file
rustshark --input capture.pcap

# Read PCAP-NG file
rustshark --input capture.pcapng

# Read with verbose analysis
rustshark --input capture.pcap --verbose

# Analyze DNS and HTTP traffic from file
rustshark --input web-traffic.pcap --verbose

Format Support

Format Extension Features
PCAP .pcap Standard format, wide compatibility
PCAP-NG .pcapng Modern format, better metadata support

Both formats include:

  • Microsecond precision timestamps - Accurate packet timing
  • Full packet data - Complete Ethernet frames preserved
  • Wireshark compatibility - Open files directly in Wireshark
  • Standard compliance - Follows libpcap/pcapng specifications

Use Cases

  • Traffic Analysis - Capture now, analyze later
  • Forensics - Preserve evidence for investigation
  • Testing - Create test datasets for protocol development
  • Sharing - Exchange packet captures with team members
  • Integration - Process captures with other tools (Wireshark, tcpdump, tshark)

🌐 Protocol Support

Layer 2 - Data Link

  • ✅ Ethernet II - MAC addresses, EtherType

Layer 3 - Network

  • ✅ IPv4 - Source/destination IP, protocol, TTL, flags
  • ✅ IPv6 - Full IPv6 support with extension headers (Hop-by-Hop, Routing, Fragment, Destination Options, Authentication, ESP)
  • ✅ ARP - Address Resolution Protocol for MAC-IP resolution
  • ✅ ICMPv4 - Echo Request/Reply, Destination Unreachable, Time Exceeded, Redirect, and more
  • ✅ ICMPv6 - IPv6 ICMP including Neighbor Discovery, Router Advertisement/Solicitation

Layer 4 - Transport

  • ✅ TCP - Ports, sequence numbers, flags, window size
  • ✅ UDP - Ports, length, checksums

Layer 7 - Application

  • ✅ DNS - Full query/response parsing

    • Query types: A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, ANY
    • Response codes: NOERROR, NXDOMAIN, SERVFAIL, REFUSED
    • Domain name compression support
    • TTL extraction
    • mDNS support (port 5353)

  • ✅ HTTP - Complete request/response parsing

    • Methods: GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, CONNECT, TRACE
    • Headers: Host, User-Agent, Content-Type, Content-Length, Server
    • Cookie detection
    • Status codes: 1xx-5xx

  • ✅ DHCP - Dynamic Host Configuration Protocol (Discover, Offer, Request, ACK, NAK, Release, Inform)

  • ✅ FTP - File Transfer Protocol commands and responses (USER, PASS, RETR, STOR, LIST, etc.)

  • ✅ SMTP - Simple Mail Transfer Protocol with email message parsing (HELO, MAIL, RCPT, DATA, etc.)

  • ✅ SSH - Secure Shell Protocol version exchange and key exchange

  • ✅ Telnet - Terminal emulation protocol with command negotiation

  • ✅ SNMP - Simple Network Management Protocol (v1, v2c, v3) with Get/Set/Trap support

  • ⏳ HTTPS/TLS - Planned for future phase

🏗️ Architecture

rustshark/
├── crates/
│   ├── capture/           # Packet capture engine (Npcap/libpcap)
│   ├── parser/            # Core protocol parsers (Ethernet/IPv4/IPv6/TCP/UDP/ARP/ICMP)
│   ├── flow/              # Flow tracking & analysis
│   ├── detection/         # Anomaly detection algorithms
│   ├── dns/               # DNS protocol parser
│   ├── http/              # HTTP protocol parser
│   ├── dhcp/              # DHCP protocol parser
│   ├── ftp/               # FTP protocol parser
│   ├── smtp/              # SMTP protocol parser
│   ├── ssh/               # SSH protocol parser
│   ├── telnet/            # Telnet protocol parser
│   ├── snmp/              # SNMP protocol parser
│   ├── pcap/              # PCAP/PCAP-NG file I/O
│   ├── storage/           # Data persistence (placeholder)
│   ├── ui/                # Terminal UI components (placeholder)
│   ├── rustshark-server/  # 🌐 Web server (Axum + WebSocket)
│   └── rustshark-web/     # 🌐 Frontend (Leptos + WebAssembly)
├── rustshark-cli/         # Command-line interface
└── assets/                # 🌐 Web dashboard assets (HTML/CSS)

Design Principles

  1. Zero Unsafe Code - 100% safe Rust, no unsafe blocks
  2. Modular Architecture - Each protocol is a separate crate
  3. Performance First - Zero-copy parsing where possible
  4. Extensible - Easy to add new protocols
  5. Production Ready - Comprehensive error handling
  6. 100% Rust Stack - Backend (Axum) + Frontend (Leptos/WASM), zero JavaScript

🎨 Interface Aliases

RUSTSHARK provides user-friendly aliases for common interface types:

Alias Matches Description
wifi, wlan, wireless Wi-Fi adapters Wireless network cards (802.11)
eth, ethernet Ethernet adapters Wired network cards (RJ45)
vpn, wireguard, wg VPN tunnels WireGuard, OpenVPN, etc.
loop, loopback, lo Loopback Local loopback (127.0.0.1)
bt, bluetooth Bluetooth Bluetooth network adapters
1-9 By number Select interface by list number

Examples

# Using alias
rustshark wifi --count 100

# Using interface number
rustshark 5 --count 100

# Using exact name
rustshark "\Device\NPF_{9F834F7A-D906-4C95-84C4-8DF8E4ECCC4E}" --count 100

📊 Output Examples

Basic Output

[1] Packet captured: 122 bytes
[2] Packet captured: 138 bytes
[3] Packet captured: 282 bytes
    [DNS Query: google.com]
[4] Packet captured: 154 bytes
    [DNS Response: google.com - 1 answers]
[5] Packet captured: 66 bytes
    [HTTP Request: GET http://example.com/]

Verbose Output

------------------------------------------------------------
[Packet #3]
  Ethernet:
    Source MAC:      d0:57:7b:40:a8:f3
    Destination MAC: 74:6f:88:9c:15:b4
    EtherType:       0x0800
  IPv4:
    Source IP:       192.168.1.5
    Destination IP:  8.8.8.8
    Protocol:        17
    Total Length:    82
  UDP:
    Source Port:     51234
    Dest Port:       53
    Length:          62
    Payload:         54 bytes
  DNS:
    Transaction ID:  0x1a2b
    Type:            Query
    Questions:       1
      - google.com (A)

🌐 Web Dashboard

RUSTSHARK now includes a powerful real-time web dashboard built entirely in Rust!

Features

  • 📊 Real-Time Statistics - Live packet/byte counts, flows, and throughput
  • 🥧 Protocol Distribution - Interactive pie charts showing traffic breakdown
  • 🌐 Network Topology - Visual graph of network connections and devices
  • 📈 Timeline View - Historical packet activity with bar charts
  • 🚨 Anomaly Alerts - Real-time security alerts with notifications
  • 🔍 Flow Analysis - Searchable table of active network flows
  • ⚙️ Configuration - Web-based interface for capture settings
  • 🔐 Authentication - Secure JWT-based login system

Quick Start

Windows:

build-dashboard.cmd
target\release\rustshark-server.exe

Linux/macOS:

./build-dashboard.sh
./target/release/rustshark-server

Access Dashboard:

Architecture

  • Backend: Axum web server + WebSocket for real-time streaming
  • Frontend: Leptos framework compiled to WebAssembly
  • Communication: REST API + WebSocket for live updates
  • 100% Rust: No JavaScript - entire stack written in Rust!

Documentation

See DASHBOARD.md for complete documentation including:

  • API endpoints
  • WebSocket protocol
  • Configuration options
  • Security considerations
  • Performance tuning

See WINDOWS_SETUP.md for Windows-specific setup.

🔍 Anomaly Detection

RUSTSHARK includes built-in anomaly detection for common attacks:

Port Scan Detection

  • Triggers when a source IP connects to 10+ different ports within 60 seconds
  • Identifies reconnaissance attempts

DDoS Detection

  • Triggers when a destination IP receives 100+ packets within 10 seconds
  • Identifies flooding attacks

DNS Tunneling Detection

  • Triggers when DNS queries exceed 512 bytes (5+ times within 60 seconds)
  • Identifies data exfiltration via DNS

📈 Development Status

✅ Completed Phases

  • Phase 1: Foundation - Project structure, workspace setup

  • Phase 2: Protocol Parsing - Ethernet, IPv4, TCP, UDP parsers

  • Phase 3: Flow Analysis - Flow tracking, statistics

  • Phase 4: Anomaly Detection - Port scan, DDoS, DNS tunneling

  • Phase 5: Real Packet Capture - Npcap/libpcap integration

  • Phase 6A: Documentation - v0.2.0 release, README

  • Phase 6B: DNS Parser - Complete DNS protocol support

  • Phase 6C: HTTP Parser - Complete HTTP protocol support

  • Phase 8: PCAP File I/O - Read/write PCAP and PCAP-NG files

  • Phase 9: JSON Export - JSON logging and export (integrated in dashboard)

  • Phase 10: Web Dashboard - ✨ COMPLETED! Real-time web visualization

    • Axum backend with WebSocket support
    • Leptos frontend compiled to WebAssembly
    • Real-time packet streaming and statistics
    • Protocol distribution charts
    • Network topology visualization
    • Timeline view with historical data
    • Anomaly detection alerts
    • JWT authentication
    • Configuration management
    • 100% Rust implementation (no JavaScript!)

  • Phase 7: Advanced Protocols - ✨ COMPLETED! IPv6, ARP, ICMP, DHCP, FTP, SMTP, SSH, Telnet, SNMP

    • IPv6 with full extension header support
    • ARP for MAC-IP resolution
    • ICMPv4 and ICMPv6 with all message types
    • DHCP with all message types
    • FTP command and response parsing
    • SMTP with email message parsing
    • SSH version exchange and key exchange
    • Telnet with command negotiation
    • SNMP v1/v2c/v3 support

⏳ Planned Phases

  • Phase 8: TLS/HTTPS - SSL/TLS protocol analysis and HTTPS decryption
  • Phase 11: Machine Learning - Traffic classification, anomaly detection
  • Phase 12: Cloud Integration - Remote monitoring, cloud storage

📝 Version History

v0.4.0-dev (Current Development)

  • ✨ NEW: Real-time Web Dashboard - Complete web-based monitoring interface
  • ✨ Axum Backend Server - High-performance async web server with WebSocket support
  • ✨ Leptos Frontend - Rust-based WebAssembly frontend (zero JavaScript!)
  • ✨ WebSocket Streaming - Real-time packet data pushed to browser
  • ✨ Interactive Visualizations:
    • Live packet stream with real-time updates
    • Protocol distribution pie charts (TCP/UDP/DNS/HTTP/HTTPS)
    • Network topology graph with nodes and edges
    • Timeline charts showing historical packet activity
    • Anomaly detection dashboard with severity levels
  • ✨ REST API - Full RESTful API for statistics, flows, and configuration
  • ✨ JWT Authentication - Secure login system with token-based auth
  • ✨ Configuration Panel - Web-based interface for capture settings
  • ✨ Cross-Platform Support - Windows, Linux, and macOS
  • ✨ Build Scripts - Automated build for both Unix (.sh) and Windows (.cmd)
  • 📝 Comprehensive Documentation - DASHBOARD.md and WINDOWS_SETUP.md guides

v0.3.0

  • ✨ Added DNS parser module with full query/response support
  • ✨ Added HTTP parser module with request/response parsing
  • ✨ PCAP file I/O support - Read and write PCAP/PCAP-NG files
  • ✨ Enhanced verbose output with protocol-specific details
  • ✨ Support for all major DNS record types (A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV)
  • ✨ Support for all HTTP methods (GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, CONNECT, TRACE)
  • ✨ Wireshark-compatible file format support
  • ✨ Microsecond precision timestamps in PCAP files
  • ✨ Auto-detection of PCAP format from file extension
  • 🐛 Improved error handling in protocol parsers

v0.2.0 (2025-11-28)

  • ✨ Real packet capture with Npcap/libpcap
  • ✨ Interface alias system (wifi, vpn, eth, loopback, bluetooth)
  • ✨ Bidirectional flow tracking
  • ✨ Enhanced CLI with interface selection
  • 🐛 Fixed all clippy warnings
  • 📝 Production-ready release

v0.1.0 (2025-11-27)

  • 🎉 Initial release
  • ✨ Mock packet capture mode for testing
  • ✨ Basic protocol parsing (Ethernet, IPv4, TCP, UDP)
  • ✨ Flow tracking and statistics
  • ✨ Anomaly detection (port scan, DDoS, DNS tunneling)
  • 📝 Command-line interface

🛠️ Development

Building

# Development build (with debug symbols)
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run clippy (linter)
cargo clippy

# Check code formatting
cargo fmt --check

Testing

# Run all tests
cargo test

# Run tests for specific crate
cargo test -p rustshark-parser

# Run with verbose output
cargo test -- --nocapture

Code Quality

  • Zero Unsafe Code - No unsafe blocks in the entire codebase
  • Zero Clippy Warnings - All clippy lints resolved
  • Comprehensive Tests - Unit tests for all parsers
  • Documentation - Inline documentation for all public APIs

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow Rust naming conventions
  • Add tests for new features
  • Update documentation
  • Ensure cargo clippy passes
  • Format code with cargo fmt

📄 License

MIT License

Copyright (c) 2025 Chronocoder

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

👤 Author

Chronocoder

🙏 Acknowledgments

  • Npcap - Windows packet capture library
  • libpcap - Unix packet capture library
  • Axum - High-performance web framework
  • Leptos - Reactive Rust web framework
  • Tokio - Async runtime for Rust
  • Rust Community - For the amazing language and ecosystem

📚 References

Made with ❤️ and 🦀 Rust

Report Bug · Request Feature

About

RUSTSHARK is a professional deep packet inspection tool built entirely in Rust, designed to provide memory-safe, high-performance network traffic analysis.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages