ForenSys is a modern, real-time Security Operations Center (SOC) dashboard and behavior-based EDR/XDR response platform built for high-performance security teams. It integrates a real-time system telemetry & behavioral rule engine written in Python (FastAPI) with an interactive Next.js (TypeScript) cyber-themed dashboard using WebSockets.
ForenSys streams real host telemetry and runs local behavioral threat analysis to drive all platform components:
- Self-Protection Mode & Trusted Context Filter: Built-in platform self-preservation layer (
AssetTrustManager) that dynamically registers ForenSys platform PIDs, project installation paths, local listening ports, and active network interface IPs (192.168.1.x,127.0.0.1). System internal activity is logged in a Self-Protection Audit while strictly suppressing false-alarm alerts, risk score inflation, and auto-remediation containment actions against ForenSys itself. - Behavior-Based EDR Rule Engine & Incident Correlation: Modular stateful rule engine that evaluates ICMP Floods, Port Scans, Brute Force Authentication, DNS Beaconing, Reverse Shells, and Data Exfiltration. Deterministically maps IPv6 attack source addresses to public IPv4 addresses (via SHA-256 hashing) for consistent threat visualization and SOAR integration, while preserving original telemetry logs.
IncidentCorrelationEngineclusters multi-stage alerts into unifiedCorrelatedIncident(ICMP01,SCAN01,AUTH01,EXFIL01) timelines mapped to MITRE ATT&CK tactics with confidence and risk scores. - Consolidated Security Alerts Workspace (
/dashboard/alerts): Merged security workspace displaying active threat alerts and correlated intrusion sequences. Features severity counters that dynamically exclude resolved alerts, subtle non-glowing card backgrounds for resolved items, and a dedicated Resolved tab filter. - Master-Detail EDR Rules Catalog & Dynamic Thresholds (
/dashboard/rules): Master-detail 2-column rule catalog allowing SOC administrators to adjust behavioral thresholds (e.g. ICMP Flood limit, sliding time windows) in real-time. Configuration changes immediately persist toconfig.jsonand in-memory detection rule evaluations, restricted strictly to Admin role users. - Accurate MTTD & MTTR Performance Analytics (
/dashboard/analytics):- MTTD (Mean Time to Detect): Measures exact latency from the first packet arrival of an attack stream to rule alert generation (e.g., ~1.4s).
- MTTR (Mean Time to Remediate): Measures exact latency from alert generation to automated SOAR containment completion (IP block and evidence vault sealing) (e.g., ~0.9s).
- Forensic Evidence Vault & SHA-256 Sealing: Automated forensic evidence collection engine (
EvidenceManager) that captures process hierarchies, socket history, packet headers, and system logs upon incident creation. Evidence packages (EVD-ICMP01,EVD-EXFIL01) are hashed using SHA-256 digests and immutably sealed. - SOAR Auto-Remediation & Perimeter Defense Engine: Automated SOAR containment execution engine (
SOAREngine) that blocks attacking remote IPs via macOSpfctlpacket filter rules, captures packet snapshots (.pcap), dumps process environment metadata, and dispatches analyst notifications with one-click Rollback capabilities. - Auto Remediation History Console (
/dashboard/automation): Dedicated audit trail view displaying all executed containment actions, target IPs, triggering EDR rules, execution statuses (success,rolled_back,skipped), and instant single-click Rollback and Clear History controls. - Firewall Rules & IP Blocklist Console (
/dashboard/playbooks): Dedicated perimeter defense console displaying active macOS PF firewall rules, active perimeter blocklists, block reasons, registered EDR rule catalogs, and Block / Unblock IP controls with zero-delay cursor feedback. - Command Center Dashboard: Live host metrics (real CPU, RAM, Disk, Uptime), threat level gauges, real-time alert tickers, and active IP blocklist counters. Features a high-fidelity user profile dropdown menu with active status tags, role labels, and user management access.
- Real-Time Network Telemetry: Streams active TCP/UDP connections and local listening sockets. Uses a non-root
lsoffallback collector on macOS to map sockets to their owner process names and PIDs. - Network Intelligence Console: Displays active network indicators of compromise, geolocated peers, and active network connections. Features interactive Recharts density/type breakdown graphs, regex-powered search filter fields, CSV/JSON report exporters, and direct Iris AI deep-dives for forensic analysis.
- Real-Time Network Traffic Audit: Live packet capture stream powered by Scapy (BPF-based packet capture) that sniffs TCP/UDP/ICMP traffic across host interfaces. Drops telemetry from blocked IPs in real-time. Includes custom live charts (Top Active Talkers, Protocol Distribution), search and protocol filtering, clear logs, and pause/resume control.
- Log Explorer: Live streaming log explorer capturing active system log streams with level, process, subsystem, and category filters. Features regex search mode with real-time error syntax feedback, inline query term highlighting, CSV/JSON exporters, and direct Iris analyzer hooks.
- Context-Aware AI Security Assistant (Iris): Built-in Security Assistant analyzing live SOC state to reconstruct attack chains and answer analysis questions.
- JWT Authentication & Granular RBAC: Token-based user sessions using JSON Web Tokens (JWT) with password verification via bcrypt. Supports custom roles (
Admin,Analyst,Responder,Viewer) and department-based permissions across all dashboards and automation workspaces.
- Framework: Next.js 16 (App Router / Turbopack)
- Language: TypeScript
- State Management: Zustand
- Real-Time Delivery: WebSocket Client (
lib/api-client.ts) - Styling: Tailwind CSS & Glassmorphism design tokens
- Visuals: Shadcn UI, Framer Motion, Recharts, Lucide Icons, Sonner
- Framework: FastAPI & Uvicorn
- Rule Engine & EDR:
BehaviorStateEngine,RuleEngine,IncidentCorrelationEngine,AssetTrustManager,SOAREngine,EvidenceManager - Collectors:
psutil(System resources),lsof/netstat(Socket-to-Process mapping),scapy(BPF packet capture via libpcap) - Network Intelligence: Emerging Threats Blocklist IP loader & IP Geolocator
- Transport: JSON-serialized WebSocket server
- Node.js: v18+ and
npm - Python: v3.10+ (with
venvsupport)
# Google Gemini API key for Iris AI Security Assistant (Optional, defaults to local rules-based fallback)
GEMINI_API_KEY=your_api_key_here
# Backend FastAPI server URL (Optional, defaults to http://localhost:8000)
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000# Secret key used for signing JWT access and refresh tokens
JWT_SECRET_KEY=your_jwt_secret_key-
Clone the Repository:
git clone https://github.com/yourusername/forensys.git cd forensys -
Install Frontend Dependencies:
npm install
-
Start the Unified Dev Environment: You can start both the Next.js frontend and the FastAPI backend concurrently using one of the following commands:
- Standard Mode (Simulated telemetries fallback):
npm run dev
- Privileged Mode (Real BPF-based packet capture & macOS PF Firewall control):
npm run dev:privileged
- Standard Mode (Simulated telemetries fallback):
-
Access the SOC Console: Open http://localhost:3000 in your browser. The dashboard will connect to the backend WebSocket automatically.
-
Run End-to-End EDR Simulation & Verification Tests:
# Run Self-Protection Unit Test Suite backend/.venv/bin/python -m unittest backend/tests/test_self_protection.py # Run End-to-End Attack Pipeline Simulation backend/.venv/bin/python backend/scripts/simulate_attacks.py
├── app/ # Next.js App Router Pages
│ └── dashboard/ # EDR/SOC Modules (Alerts, Forensics, Automation, Playbooks, Rules, etc.)
├── backend/ # Python Telemetry & EDR/XDR Engine
│ ├── analyzers/ # Threat detection & IP blocklist matching
│ ├── collectors/ # Telemetry scripts (system, logs, network, processes, traffic)
│ ├── pipeline/ # EDR Architecture: RuleEngine, Correlation, Self-Protection, SOAR, Evidence
│ ├── scripts/ # Attack simulation scripts
│ ├── tests/ # Unit test suites
│ ├── main.py # FastAPI server entrypoint
│ └── requirements.txt # Backend Python dependencies
├── components/ # React UI Components
├── lib/ # Next.js client integration
│ ├── api-client.ts # WebSocket / REST client setup
│ └── app-store.ts # Zustand global state manager
└── scripts/ # Development automation scripts
This project is for security analysis, EDR/XDR engineering, and SOC portfolio purposes only.