🛡️ NetSentinel

Cybernetic Network Intelligence & Active Defense Platform

NetSentinel is a full-stack cybersecurity monitoring suite that bridges the gap between low-level kernel operations and high-level visualization. It combines a custom-built C Agent for raw packet capture and OS inspection with a modern Node.js backend and React frontend to visualize network threats in real-time.

---

📸 System Overview

Secure Access

Authentication gateway simulating a secure terminal environment.

Mission Control

The Signals Intelligence dashboard providing real-time telemetry, DPI (Deep Packet Inspection), and threat level assessment.

Threat Mapping

Global visualization of network traffic origins and threat vectors.

Academy Training

Interactive learning environment for cybersecurity concepts.

Wargames Simulation

Live-fire cyber range for red team/blue team exercises.

---

🧠 System Architecture

The system operates on a custom binary pipeline designed for speed and transparency.

graph LR
    subgraph Kernel ["Kernel Space (Linux)"]
        A[Network Interface] -->|"Raw Sockets (AF_PACKET)"| B(C Agent)
        proc["/proc Filesystem"] -->|"Read FDs & TCP Table"| B
    end
    
    subgraph Backend ["Backend (Node.js)"]
        B -->|"TCP Stream (Binary Structs)"| C(IPC Server)
        C -->|"Parse Buffer"| D{Packet Parser}
        D -->|Store| E[("TimescaleDB")]
        D -->|Emit| F[Socket.io]
    end
    
    subgraph Frontend ["Frontend (React)"]
        F -->|WebSocket| G[Mission Control Dashboard]
        G -->|Visuals| H[Attack Surface & Heatmaps]
    end

Loading

1. The Agent (C Language)

• Raw Sockets (AF_PACKET): Bypasses the OS network stack to capture Ethernet frames directly from the wire.
• Kernel Inspection: Reads /proc/net/tcp to map active connections and /proc/self/fd to visualize file descriptors.
• IPC Client: Buffers captured packets and streams them via a custom TCP protocol to the backend.

2. The Core (Node.js & TimescaleDB)

• Binary Protocol: Receives raw binary streams from the C agent and manually unpacks them based on the PacketMetadata C struct memory layout.
• Active Defense: Implements logic for Geofencing, Firewall rule management, and IPS (Intrusion Prevention System) signatures.
• TimescaleDB: Uses a PostgreSQL extension for high-performance time-series logging of network traffic.

3. The Interface (React & Vite)

• Cyberpunk UI: Built with Tailwind CSS and Framer Motion for a high-fidelity, cinematic "hacker" aesthetic.
• Visualization: Uses recharts for traffic analysis and react-simple-maps for geospatial threat tracking.

---

🚀 Modules & Features

1. Visual Intelligence (Geo & Topology)

NetSentinel transforms raw logs into geography and geometry.

• Threat Map: Plots source IPs using GeoIP databases. Red lines indicate traffic from blocked nations.
• Topology Graph: A dynamic node-link diagram showing the relationship between the Internet, your Firewall, and active local ports.
• Packet Tracer: An interactive simulator that lets you inject fake packets (e.g., SQLi, XSS) to test your WAF rules.

2. The Academy (Story Mode)

A gamified curriculum that teaches networking concepts by visualizing your own live traffic.

Prologue: Experience the cinematic history of the internet.

Active Defense: Engage in scenarios against simulated state actors.

Layer 2 Discovery: Visualize ARP broadcasts and MAC address resolution.

3. Wargames (Cyber Range)

A live-fire exercise environment where you can act as both the Red Team (Attacker) and Blue Team (Defender).

Attack Vectors:

• SQL Injection: Inject malicious payloads to test WAF signatures.
• SYN Flood: Simulate DDoS attacks to test rate-limiting.
• Brute Force: Attempt credential stuffing against SSH.

Defense Logs: Watch the SOC (Security Operations Center) feed react to your attacks in real-time.

4. Active Defense (Shield)

• Firewall Manager: Create iptables rules directly from the UI (Drop/Accept).
• Geo-Fencing: Block traffic from specific high-risk countries (e.g., KP, RU, CN).
• WAF Signatures: Toggle specific regex rules to block application-layer attacks.
• File Integrity Monitor (FIM): Watches critical system files (like /etc/passwd) for unauthorized changes.

5. Kernel Space Inspection

• Memory View: Visualizes the sk_buff (Socket Buffer) structure directly from kernel memory.
• Socket Correlation: Maps active kernel sockets to user-space processes (PIDs), showing exactly which app is talking to whom.

---

🛠️ Installation & Setup

Prerequisites

• Linux Environment (Required for the C Agent's raw sockets)
• Node.js (v18+)
• PostgreSQL with TimescaleDB extension enabled
• GCC Compiler

1. Database Setup

Ensure PostgreSQL is running and create the database:

CREATE DATABASE netsentinel;
-- Enable TimescaleDB extension inside the DB
\c netsentinel
CREATE EXTENSION IF NOT EXISTS timescaledb;

2. Backend Setup

cd backend
npm install

# Configure Environment
# Create a .env file if needed (defaults are set in config.js)
# DB_HOST=localhost
# DB_USER=postgres
# DB_PASS=yourpassword

# Start the Server
npm start
# Output: 🚀 NetSentinel Backend running on port 3000
# Output: [IPC] Intelligence Bridge listening on port 8000

3. Agent Compilation & Run

The agent requires root privileges to open Raw Sockets (AF_PACKET).

cd agent
make clean
make

# Run the agent (Must be run as sudo!)
sudo ./netsentinel_agent
# Output: [SNIFFER] Starting Raw Socket...
# Output: [IPC] Connected to Node.js Agent!

4. Frontend Setup

cd frontend
npm install

# Start the Development Server
npm run dev
# Access at http://localhost:5173

---

🔌 The Custom Protocol

To communicate between C and Node.js efficiently, we use a custom packed binary structure (__attribute__((packed))).

Packet Structure (292 Bytes):

Field	Size	Description
type	1 Byte	Msg Type (Traffic=1, Alert=2, OS=3)
timestamp	4 Bytes	UNIX Timestamp
src_ip / dst_ip	8 Bytes	IPv4 Addresses
dst_port	2 Bytes	Destination Port
protocol	1 Byte	TCP (6) / UDP (17)
payload_size	4 Bytes	Size of the data payload
ttl	1 Byte	Time To Live (OS Fingerprinting)
tcp_flags	1 Byte	SYN, ACK, FIN, RST
mac_headers	12 Bytes	Source & Dest MAC
payload	256 Bytes	Sanitized ASCII Payload Snippet

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

---

🛡️ License

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

⚠️ Disclaimer: NetSentinel is intended for educational and defensive purposes only. The authors are not responsible for misuse of the sniffing or offensive simulation capabilities. Always ensure you have proper authorization before monitoring network traffic.

---

🌟 Acknowledgments

Built with passion for cybersecurity education and network transparency.

Tech Stack:

• C (Agent)
• Node.js + Express (Backend)
• React + Vite (Frontend)
• TimescaleDB (Time-series Database)
• Socket.io (Real-time Communication)
• Tailwind CSS + Framer Motion (UI)

---

Made with ⚡ by ARYA DASGUPTA!