RyanJBush/soc-threat-detection-and-incident-response-platform

# SOC Threat Detection & Incident Response Platform ## 1. Project title **SOC Threat Detection & Incident Response Platform** ## 2. Executive summary This project is a full-stack SOC portfolio platform for ingesting synthetic security events, running Python-based detections, and managing alert-to-incident response workflows. It includes a FastAPI backend with detection logic, triage/incident APIs, and operational metrics, plus a React dashboard for analyst workflows. The goal is to demonstrate practical detection engineering and SOC operations in a transparent, reviewable codebase. ## 3. Security problem this project solves SOC teams need a realistic way to show end-to-end blue-team workflow: event ingestion, threat detection, alert triage, escalation, and response tracking. This repository provides that pipeline using synthetic telemetry so reviewers can evaluate detection logic, triage decisions, and incident handling in one system. ## 4. Key features - Event ingestion endpoints for single events, batch ingestion, stream-style ingestion, replay, and seeded scenarios. - Detection engine with implemented rule-based and anomaly-style logic (including confidence scoring and evidence capture). - Alert creation with deduplication/correlation, severity, explanation, MITRE technique metadata, and recommended next steps. - Analyst triage actions: status transitions, assignment, notes, timeline entries, and true/false-positive feedback. - Incident workflows: create incidents, link alerts, update incident status, and review incident audit timeline. - Metrics endpoints for SOC KPIs (including open/high-severity counts, MTTD, MTTR, and detection coverage). - Role-based access control across Admin, Analyst, Detection Engineer, and Viewer roles. - Frontend views for dashboard, events, alerts, alert investigation, incidents, detections/jobs, and hunting queries. ## 5. Tech stack - **Backend:** Python, FastAPI, SQLAlchemy - **Data/processing:** PostgreSQL, pandas, scikit-learn - **Frontend:** React + Vite, React Router, Recharts - **Security/search services:** JWT auth, optional Elasticsearch event indexing - **Dev workflow:** Docker Compose, Makefile, pytest, ruff, ESLint ## 6. Detection and incident response workflow 1. Ingest events via `/api/events` (single, batch, stream, replay, scenarios, or simulation run). 2. Queue detection jobs and process them to generate detections and alerts. 3. Correlate repeated signals into active alerts using correlation IDs and dedup windows. 4. Triage alerts in the UI/API (status updates, assignment, investigation notes, feedback, timeline). 5. Escalate related alerts into incidents and track incident lifecycle (`open` → `investigating` → `contained` → `closed`). 6. Monitor SOC performance through metrics and dashboard summaries. ## 7. Architecture overview - **API layer (`backend/app/routers`)**: auth, events, detections, alerts, incidents, jobs, hunting, metrics, platform. - **Detection/services layer (`backend/app/services`)**: detection catalog, detection engine, job orchestration, MITRE enrichment, audit logging, feature flags, scenario seeding. - **Data layer (`backend/app/models.py`)**: organizations, users, events, detections, alerts, incidents, notes, analyst feedback, jobs, audit logs. - **UI layer (`frontend/src`)**: SOC dashboard and analyst-facing pages for ingestion, investigation, triage, and response. ## 8. Setup and installation ### Option A: Docker make dev ### Option B: Local development make install make backend-dev make frontend-dev ### Demo credentials - `admin / admin123` - `analyst / analyst123` - `deteng / deteng123` - `viewer / viewer123` ### Quick verification flow 1. Start services. 2. Log in to the frontend at `http://localhost:5173`. 3. Use the **Events** page to ingest events or seed a scenario. 4. Review generated results in **Alerts**, **Alert Detail**, **Incidents**, **Detections**, and **Dashboard**. ## 9. Example security use cases - Detect and triage brute-force login behavior from repeated failed authentication attempts. - Investigate suspicious login anomalies such as unusual login hours and impossible travel patterns. - Track potential privilege escalation or account manipulation activity. - Surface IOC-style events when `threat_intel_match` metadata is present. - Correlate and escalate multiple related alerts into a single incident response case. ## 10. Skills demonstrated - Detection engineering in Python (rules, anomaly logic, confidence scoring, dedup/correlation). - SOC alert triage and incident response process design and implementation. - Security event ingestion and log-analysis workflow development. - Analyst tooling: dashboards, investigation views, timeline artifacts, and KPI tracking. - Secure API design with JWT authentication and RBAC permissions. - Full-stack delivery using FastAPI, PostgreSQL, and React. ## 11. Resume-ready project description Built a full-stack **SOC Threat Detection & Incident Response Platform** with FastAPI, PostgreSQL, and React to ingest synthetic security telemetry, run rule/anomaly-based detections, generate correlated alerts, and manage analyst triage through incident escalation. Implemented SOC metrics (MTTD/MTTR, coverage, false-positive signals), RBAC, hunting queries, and investigation artifacts to demonstrate practical detection engineering and blue-team response workflows. ## 12. Future improvements - Add more scenario packs and expand detection coverage for additional attack behaviors. - Improve alert tuning workflows using analyst feedback history. - Expand hunting capabilities beyond current selector-based Sigma-like query handling. - Add pagination/filter controls to more frontend views for larger datasets. **Scope note:** This project is designed for portfolio and learning use with synthetic data and should not be treated as a production SIEM replacement.