Skip to content

Home

Jump to bottom
Debdoot Manna edited this page Aug 3, 2026 · 3 revisions

🦈 SentinelShark Wiki

Welcome to the official SentinelShark Knowledge Base and System Wiki.

SentinelShark is a high-performance, modern desktop Network Intrusion Detection & Analysis System (NIDS) written in Python (PyQt6 + PyShark + httpx + SQLite). It dissects live network traffic (or .pcap capture files) and enriches public IP addresses in real time with threat intelligence from VirusTotal and AbuseIPDB.

📚 Wiki Navigation

  • 🏛️ Architecture & System Design

    • Decoupled threading model (QThread + qasync event loop).
    • Packet processing pipeline & threat enrichment flow.
    • Persistent SQLite database schema (threatcache.db).
    • Dynamic threat classification & color-coding rules.

  • 👤 User & Operator Guide

    • Installation & environment setup instructions.
    • Configuring VirusTotal & AbuseIPDB API keys (GUI Modal & Environment variables).
    • Live packet sniffing vs. PCAP analysis vs. Mock Traffic mode.
    • Using Berkeley Packet Filters (BPF).
    • Understanding the Packet Inspector, Hex Dump, and NIDS Dashboard.

  • 💻 Developer & Extension Guide

    • Codebase structure and module map.
    • Adding new Threat Intelligence providers (AlienVault OTX, Shodan, AbuseCH).
    • Extending protocol dissectors in app/core/parser.py.
    • Running and writing automated unit tests.

⚡ Quick Start

# 1. Clone repository
git clone https://github.com/DebdootManna/sentinelshark.git
cd SentinelShark

# 2. Activate virtual environment
source venv/bin/activate

# 3. Launch SentinelShark Desktop Application
python run.py

🛡️ Core Capabilities

Feature Description
Live Sniffing & PCAP Capture live interface packets via PyShark or read .pcap files.
AbuseIPDB Integration Fetch abuse confidence scores, report counts, and geographic country codes.
VirusTotal Integration Fetch malicious, suspicious, and harmless engine detection counts.
RFC 1918 Filtering Automatically filters out private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.1) to save API requests.
SQLite Caching Persists lookups in threatcache.db with a configurable 24-hour TTL.
Rate Limit Protection Background queue with automatic exponential backoff on HTTP 429 errors.
Hex Inspector Dual Hex & ASCII byte viewer with payload MD5 & SHA256 hashing.

Clone this wiki locally