gaganrathod18/pacman repository overview

⁠🛡️ PacMan — Packet Analysis & Cyber Monitoring

High-Performance Network Security Monitor & Terminal Cyber Dashboard ("htop for network packets")

📖 Click here to view the Full Quickstart Guide →⁠

⁠📌 Overview

PacMan is a real-time, non-intrusive network packet analyzer and threat detection dashboard for Linux and macOS. It functions as an "htop for network packets", providing deep visibility into live network interfaces or offline .pcap capture files without introducing latency, blocking traffic, or kernel hooks.

⁠✨ Key Features

• 🖥️ Rich 13-Tab FTXUI Terminal Dashboard:

  • Overview: Real-time bandwidth sparkline, 50/50 live alert feed, protocol mix, and flow overview.
  • Flows: Connection stream table showing source/destination IPs, GeoIP, TCP state (ESTAB, SYN, FIN, RST), session duration, and byte volume.
  • Alerts & IDS: Centralized security threat stream with payload hex-dump inspector.
  • DNS Log: Real-time stream of DNS queries and TLS SNI hostnames.
  • Crypto & JA3: Passive TLS handshake parser extracting TLS versions (1.3/1.2/1.1), cipher suites, and JA3 fingerprints.
  • Firewall & IPS: Passive simulation matrix tracking blocked IPs, attack signature gauges, and auto-mitigation heuristics.
  • Endpoints & Analytics: Connection matrix identifying port scanners ([!]) and ranking Top Talkers / Top Domains.
  • Traffic Graph & Protocols: 300-second historical bandwidth sparklines and traffic class breakdowns.

• 🔍 Deep Packet Inspection (DPI) & Hostname Extraction:

  • Extracts domain names from TLS Client Hello SNI extensions, HTTP Host headers, and DNS queries without decryption.

• 🛡️ Rule-Based Threat Detection:

  • Automatic detection of port scans, high connection floods, unknown domains, and high-volume data transfers.

• 🌐 Interactive Interface Selector:

  • Queries system adapters live at startup (pcap_findalldevs) displaying UP/DOWN status, IPv4 addresses, and interface types ([wifi], [ethernet], [loopback]).

• 📊 Offline PCAP Analysis & HTML/CSV Reporting:

  • Parses .pcap capture files and generates structured CSV and interactive HTML reports in reports/.

• 🐳 Full Containerization:

  • Multi-stage Docker build supporting host network live monitoring (--net=host) and container bridge inspection.

⁠💻 Supported Environments

⁠🚀 Quick Start (Build from Source)

⁠1. Clone Repository & Install Dependencies

git clone https://github.com/gaganrathod18/pacman.git
cd pacman

sudo apt-get update
sudo apt-get install -y cmake g++ git make libpcap-dev libcurl4-openssl-dev

sudo dnf install -y cmake gcc-c++ git make libpcap-devel libcurl-devel

sudo pacman -S cmake gcc git make libpcap curl

brew install cmake libpcap curl

⁠2. Build Project

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cd build && make -j4 2>&1 | tail -5

⁠3. Run Modes

⁠🟢 Live Network Capture (Interactive TUI)

# Sudo required for raw socket capture
sudo ./build/pacman live config/pacman.conf

⁠📁 Offline PCAP File Analysis

./build/pacman analyze pcaps/test_dpi.pcap config/pacman.conf

⁠🐳 Running with Docker

⁠Pull directly from Docker Hub (Fastest)

Official Image: gaganrathod18/pacman⁠

# 1. Pull latest image from Docker Hub
docker pull gaganrathod18/pacman:latest

# 2. Run live interactive dashboard
docker run -it --rm --net=host --cap-add=NET_RAW --cap-add=NET_ADMIN gaganrathod18/pacman:latest live config/pacman.conf

# 3. Run offline PCAP analysis
docker run -it --rm gaganrathod18/pacman:latest analyze pcaps/test_dpi.pcap config/pacman.conf

⁠Docker Compose

# Live host network capture
docker compose run --rm pacman-live

# Offline PCAP analysis
docker compose run --rm pacman-analyze

⁠⌨️ Dashboard Hotkeys

  ┌─────────────────────────────────────────────────────────────┐
  │  [← / →]       Navigate between 13 dashboard panels         │
  │  [↑ / ↓] / [k/j] Scroll flows and log stream tables         │
  │  [Q] / [Esc]   Quit and exit dashboard                      │
  └─────────────────────────────────────────────────────────────┘

⁠⚙️ Configuration (config/pacman.conf)

Key settings in config/pacman.conf:

• interface: Capture interface name (default: any or chosen interactively).
• refresh_ms: Terminal UI refresh rate in milliseconds (default: 400).
• high_connection_threshold: Connection count alert trigger (default: 50).
• port_scan_threshold: Unique ports alert trigger (default: 15).
• virus_total_api_key: Optional API key for automated malicious domain reputation lookups.

⁠📜 License

Distributed under the MIT License⁠.