NetSentryx PRO 🛡️

Production-Grade Real-Time Network Observability & Threat Detection

NetSentryx PRO is a high-performance, event-driven network monitoring system built with Python. It provides real-time visibility into network traffic, anomaly detection, and structured alerting through a modern SaaS-style dashboard.

⚠️ Status: v0.1-alpha (Active Development)
This project is functional but still evolving. Expect breaking changes and ongoing architectural improvements.

---

🚀 Key Features

• ⚡ Event-Driven Architecture Internal lightweight event bus for decoupled processing.

• 📡 Real-Time Dashboard Live updates via WebSockets for alerts, flows, and logs.

• 🌊 Flow-Based Network Analysis Aggregates packets into flows with behavioral metrics.

• 🧠 Rule-Based Detection Engine Detects anomalies like:

  • traffic spikes
  • scanning behavior
  • flood attempts

• 🪵 Structured Logging System SQLite-backed logs with UTC timestamps.

• 🎛️ SaaS-Style UI Dark-themed observability dashboard inspired by Datadog-style layouts.

---

🏗️ Architecture Overview

[ Packet Capture / Simulator ]
↓
(EVENT BUS)
↓
┌─────────────────────────────┐
│ Flow Processor              │
│ Alert Engine                │
│ Log Manager                 │
└─────────────────────────────┘
↓
(EVENT STREAM)
↓
┌─────────────────────────────┐
│ Database (SQLite)           │
│ WebSocket Broadcast Layer   │
└─────────────────────────────┘
↓
[ FastAPI Dashboard UI ]

---

📁 Project Structure

src/
├── core/          # Time utils, config, logging
├── events/        # Event bus system
├── flows/         # Flow aggregation engine
├── alerts/        # Detection + alert manager
├── database/      # SQLAlchemy models + DB layer
├── dashboard/     # FastAPI + Web UI + WebSockets
├── utils/         # Simulation + helpers

---

🚀 Getting Started

🧰 Prerequisites

• Python 3.10+
• (Optional for live capture)
  • Windows: Npcap
  • Linux: libpcap-dev

---

📦 Installation (Recommended: UV)

1. Create virtual environment

uv venv

2. Activate environment

Windows

.venv\Scripts\activate

Linux/Mac

source .venv/bin/activate

---

3. Install dependencies

uv pip install -r requirements.txt

---

▶️ Run the Project

🧪 Simulation Mode (Recommended)

uv run python main.py --simulate

🌐 Live Mode

uv run python main.py

---

🌍 Dashboard Access

http://localhost:8000

---

⚙️ Configuration

config/config.yaml

• Network interface settings
• Dashboard port
• Storage paths

config/rules.yaml

• Enable/disable detection rules

• Adjust thresholds for:

  • traffic spikes
  • connection floods
  • anomalies

---

🧠 Current Limitations (Alpha Stage)

• Occasional UI refresh inconsistencies
• SQLite used (not scalable yet)
• Limited authentication/security layer
• Some internal type inconsistencies under refactor
• Event pipeline still evolving

---

🧭 Roadmap

v0.2 (Next)

• Full WebSocket-only data flow (remove polling APIs)
• Improved alert deduplication system
• Better flow correlation engine

v0.3

• PostgreSQL support
• Multi-node event processing
• Rule plugin system

v1.0

• Production-ready SOC observability platform
• SaaS-style multi-tenant dashboard
• Role-based access control

---

🤝 Contributing

We welcome contributions.

How to contribute:

git checkout -b feature/your-feature

uv run python main.py

• Ensure no breaking changes in API responses
• Keep outputs JSON-safe
• Follow UTC time standard across system

---

🧩 Good First Issues

• Improve alert deduplication logic
• Add pagination to logs API
• Enhance WebSocket reconnection handling
• UI improvements (dashboard cards + charts)
• Improve flow aggregation accuracy

---

🛡️ License

MIT License — feel free to use, modify, and contribute.

---

🚀 Vision

NetSentryx aims to become:

A lightweight, self-hosted SOC observability platform for developers, security engineers, and small teams.

---

📌 Version

v0.1-alpha