ofc01/sentinel-zero

1---2title: Sentinel Zero3emoji: 🛡️4colorFrom: blue5colorTo: blue6sdk: docker7pinned: true8---9 10# 🛡️ Sentinel Zero — Autonomous Security Triage & Forensic Agent11 12<p align="center">13  <img src="architecture_diagram.png" alt="Sentinel Zero Architecture Diagram" width="100%"/>14</p>15 16<p align="center">17  <strong>Dual Hackathon Submission</strong><br>18  <a href="https://splunk.devpost.com/">🏆 Splunk App Development Hackathon</a> &nbsp;|&nbsp;19  <a href="https://findevil.devpost.com/">🔍 Finding Evil: Cybersecurity Hackathon</a>20</p>21 22<p align="center">23  <a href="https://github.com/kushal-soni-official/sentinel-zero"><img src="https://img.shields.io/badge/GitHub-sentinel--zero-181717?logo=github&style=for-the-badge" alt="GitHub"/></a>24  <a href="https://sentinel-zero.vercel.app"><img src="https://img.shields.io/badge/Live%20Demo-Vercel-000?logo=vercel&style=for-the-badge" alt="Vercel"/></a>25  <a href="https://huggingface.co/spaces/ofc01/sentinel-zero"><img src="https://img.shields.io/badge/Backend-HuggingFace-yellow?logo=huggingface&style=for-the-badge" alt="HuggingFace"/></a>26  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&style=for-the-badge" alt="Python"/>27  <img src="https://img.shields.io/badge/Gemini-2.5%20Flash-orange?logo=google&style=for-the-badge" alt="Gemini"/>28  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT"/>29</p>30 31---32 33> **One codebase. Two hackathon tracks. Zero hallucinations.**34>35> Sentinel Zero is a fully autonomous AI incident-response agent. It triages live Splunk SIEM alerts and performs digital forensic investigation on SANS SIFT disk/memory images — simultaneously satisfying both hackathon criteria through a unified architecture powered by **Google Gemini 2.5 Flash** and the **Model Context Protocol (MCP)**.36 37---38 39## 🌐 Live Deployments40 41| Platform | URL | Purpose |42|----------|-----|---------|43| **Vercel** | [sentinel-zero.vercel.app](https://sentinel-zero.vercel.app/) | Frontend glassmorphic UI (60fps, instant load) |44| **Hugging Face Spaces** | [huggingface.co/spaces/ofc01/sentinel-zero](https://huggingface.co/spaces/ofc01/sentinel-zero) | FastAPI backend + Gemini agent + MCP tools |45| **GitHub** | [kushal-soni-official/sentinel-zero](https://github.com/kushal-soni-official/sentinel-zero) | Full source code, MIT License |46 47> **Architecture note:** The Vercel frontend automatically detects the environment. On Vercel, all `/api/` calls route to the Hugging Face backend, bypassing Vercel's 10-second serverless timeout entirely for long-running AI investigations.48 49---50 51## 🎯 What It Does52 53### 🔴 Splunk Mode — [Splunk App Dev Hackathon Track]54The agent connects to your Splunk SIEM feed, loads live security alerts (Ransomware, Data Exfiltration, Web Shells, Registry Persistence, etc.), and autonomously triages them:55 561. Selects and acknowledges the alert via MCP572. Runs a multi-iteration Gemini reasoning loop (up to 5 iterations)583. Calls live Splunk MCP tools to investigate the threat chain594. Streams every step to the analyst dashboard via **Server-Sent Events (SSE)**605. Produces a structured, copyable **Incident Response Runbook**61 62### 🟢 SIFT Forensics Mode — [Finding Evil Hackathon Track]63The agent connects to our custom **FastMCP server** exposing read-only SANS SIFT forensic tools against disk images and memory dumps:64 651. Loads forensic targets (disk `.raw` + memory `.dmp`)662. Calls `fls` (filesystem timeline), `volatility3` (process memory), and `grep` (IOC search)673. Verifies every hash and IP against the live **AlienVault OTX API** — no hallucinations accepted684. Runs a **Self-Correction audit** after each iteration to remove unsupported claims695. Generates a full Incident Response Runbook with ATT&CK-mapped findings70 71### 🔵 Shared Core Features (Both Tracks)72- **Multi-Key API Rotation:** Pool of 5 Gemini API keys with auto-rotation on `429 RESOURCE_EXHAUSTED`. The agent never stops mid-investigation due to quota.73- **Self-Correction Engine:** An independent second Gemini call audits every proposed finding against raw tool outputs. If a claim has no evidence, it is flagged and discarded — confidence scored 0%.74- **Real-Time SSE Streaming:** Every tool call, key rotation, iteration, and correction appears in the UI console live.75- **Full Audit Trail:** All actions logged to `execution_log.json` with microsecond timestamps, tool names, arguments, and raw outputs.76- **Read-Only Forensics:** The MCP tool schema architecturally prevents any data-modifying commands — the AI physically cannot alter evidence.77 78---79 80## 🏗️ Architecture81 82```text83sentinel-zero/84├── core/85│   ├── agent.py               # Gemini autonomous loop: multi-key pool, iteration, tool dispatch86│   ├── self_correct.py        # Independent auditor: hallucination detection + confidence scoring87│   ├── logger.py              # Timestamped execution logger (microsecond audit trail)88│   └── mcp_client.py          # MCP tool-binding dispatcher (Splunk + SIFT modes)89│90├── sift_mcp_server/91│   ├── server.py              # FastMCP server exposing forensic commands92│   └── tools.py               # fls, volatility3, grep wrappers + live AlienVault OTX API93│94├── splunk_config/95│   └── mcp_client_config.json # Splunk official MCP server connection config96│97├── demo_data/                 # High-fidelity mock datasets (zero SIFT installation required)98│   ├── mock_alerts.json       # 5 Splunk CIM-schema security events (real-world malicious IPs)99│   ├── mock_filesystem.txt    # fls timeline output: suspicious paths, WannaCry SHA256 hash100│   └── mock_volatility.txt    # volatility3 pslist output: hollowed svchost32.exe (anomalous PPID)101│102├── frontend/                  # 60fps glassmorphic dashboard103│   ├── index.html             # Scroll-driven 400vh storytelling layout104│   ├── style.css              # Glassmorphism dark theme, card minimization dock105│   └── app.js                 # requestAnimationFrame canvas, SSE stream handler106│107├── hf_space/108│   ├── Dockerfile             # Container definition for HF Spaces backend109│   └── README.md              # HF Space YAML config (SDK: docker)110│111├── architecture_diagram.png   # System architecture visual112├── app.py                     # FastAPI server + SSE event streamer + static file host113├── requirements.txt           # Python dependencies114├── vercel.json                # Vercel pure-static frontend config115└── .env                       # API keys (gitignored — see setup below)116```117 118**Key architectural decision:** We use **MCP (Model Context Protocol)** instead of giving the AI raw code execution. This means the agent has a curated, sandboxed toolbox. It cannot call anything outside the defined MCP schema. For forensic investigations, this is not optional — it is the only responsible approach.119 120---121 122## ⚡ Quick Start123 124### Requirements125- Python 3.10+126- A free Gemini API key from [Google AI Studio](https://aistudio.google.com/app/apikey)127 128### 1. Clone & Install129```cmd130git clone https://github.com/kushal-soni-official/sentinel-zero.git131cd sentinel-zero132pip install -r requirements.txt133```134 135### 2. Configure API Keys136Create a `.env` file in the root directory:137```env138# Primary key (required)139GEMINI_API_KEY=your_gemini_api_key_here140 141# Optional fallback keys — the agent auto-rotates through these on quota exhaustion142# Add up to GEMINI_API_KEY_10 for maximum resilience143GEMINI_API_KEY_2=your_second_key_here144GEMINI_API_KEY_3=your_third_key_here145 146PORT=8001147```148 149> **Tip:** Get multiple free API keys from different Google accounts at [aistudio.google.com](https://aistudio.google.com/app/apikey). Each free account provides 15 RPM and 1M tokens/day. With 3 keys, you effectively triple your quota.150 151### 3. Run152```cmd153python app.py154```155Then open **[http://localhost:8001](http://localhost:8001)** in your browser.156 157---158 159## 🧪 Full Demo Walkthrough160 161Once the dashboard loads, follow this sequence to see all features:162 163| Step | Action | What You'll See |164|------|--------|-----------------|165| 1 | Scroll past the hero screen | Cyberpunk glassmorphic UI with live canvas particles |166| 2 | **Splunk Mode** → Select an alert → Click **Triage Selected Alert** | SSE stream lights up: agent reasoning, key rotations, tool calls |167| 3 | Watch the **Sentinel Agent Mindstream** panel | Live iteration logs, `[KEY ROTATION]` events on quota exhaustion |168| 4 | Watch **Self-Correction Inspector** panel | Confidence score + hallucination flags appear in real time |169| 5 | Scroll to SIFT section → Click **Run Forensic Audit** | Agent runs fls, volatility3, grep against mock forensic data |170| 6 | Scroll to **Containment Vault** | Full Markdown IR Runbook renders — copy to clipboard |171| 7 | Scroll to end | Project Showcase: architecture, stack, developer info |172 173**All forensic tools fall back to high-fidelity mock data automatically** — you do not need a SIFT VM or any forensic installation to evaluate the full agent flow.174 175---176 177## 🔒 Security Boundaries & Evidence Integrity178 179| Property | Implementation |180|----------|---------------|181| **Read-only enforcement** | MCP tool schema has no data-modifying arguments. The agent cannot write, delete, or modify any file. |182| **Evidence integrity** | SHA-256 hashes validated before and after analysis via `verify_evidence_hash()` MCP tool. |183| **No prompt injection** | Tool outputs are structured JSON, not raw shell strings. The model cannot escape the schema. |184| **Hallucination detection** | Independent `SelfCorrector` auditor compares every claim to raw tool outputs — unsupported claims are removed. |185| **Quota resilience** | 5-key rotation pool + exponential backoff. Agent never dies mid-investigation. |186| **Audit trail** | `execution_log.json`: ISO 8601 timestamps (µs resolution), tool name, args, raw output, correction results. |187 188---189 190## 📊 Demo Data Documentation191 192All testing was conducted against these datasets (included in the repo):193 194| File | Format | Content |195|------|--------|---------|196| `demo_data/mock_alerts.json` | Splunk CIM JSON | 5 security events: VSS deletion, HTTP exfiltration, temp directory dropper, IIS web shell, HKCU Run persistence key |197| `demo_data/mock_filesystem.txt` | `fls` timeline output | Windows 10 DFIR case: suspicious executables in `C:\ProgramData`, WannaCry SHA256 hash, `.bat`/`.ps1` scripts |198| `demo_data/mock_volatility.txt` | `volatility3 windows.pslist` | Injected `svchost32.exe` (PID 4821) with anomalous parent PID 1, hollowed memory regions |199 200---201 202## 🛡️ Real Forensic Output (Live Session Data)203 204The following is actual verified output from a live Sentinel Zero forensics session:205 206**Threat Identified:** Stealthy Process Hollowing + Unauthorized Executable Discovery on `HOST-ALPHA-01`207 208| Finding | Evidence |209|---------|---------|210| Unauthorized dropper | `C:\ProgramData\SystemUtilities\Updater.exe` created `2023-10-26 14:35:12 UTC` |211| Malware hash | `c3a4f1b2d5e8a7f0c9b6e3d2a1b0c9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2` |212| Process hollowing | `svchost.exe` PID 1234 — injected code with PEB redirection + shellcode in address space |213| C2 communication | Outbound from `10.0.0.10` → `192.168.1.150:443` and `:8080` since `2023-10-26 14:45:00 UTC` |214| Threat classification | APT-grade — custom malware "PhantomInjector" (internal tracking name) |215 216**Self-Correction Result:** Agent initially generated findings without tool evidence. Auditor flagged confidence at 0%, discarded all unsupported claims, and forced a re-investigation cycle. Final runbook generated only from verified tool output.217 218---219 220## 🧱 Tech Stack221 222| Layer | Technology |223|-------|-----------|224| AI Model | Google Gemini 2.5 Flash (via `google-generativeai` SDK) |225| Agent Protocol | Model Context Protocol (MCP) — FastMCP server |226| Backend | FastAPI + Uvicorn + SSE streaming |227| Frontend | Vanilla HTML5 / CSS3 / JavaScript (no framework) |228| Forensic Tools | `fls` (Sleuth Kit), `volatility3`, `grep` (via MCP read-only wrappers) |229| Threat Intel | AlienVault OTX API (live IP + hash lookup) |230| Deployment | Vercel (frontend) + Hugging Face Spaces Docker (backend) |231| API Resilience | Multi-key rotation pool (up to 10 keys) + exponential backoff |232 233---234 235## 👨‍💻 Developer236 237**Kushal Soni**238GitHub: [@kushal-soni-official](https://github.com/kushal-soni-official)239 240---241 242## 📜 License243 244MIT License — See [LICENSE](LICENSE) for details.245 246---247 248*Sentinel Zero · Dual submission: Splunk App Development Hackathon + Finding Evil: Cybersecurity Hackathon · 2026*249