From 57dc08370e53cd9bcb9babfea374bb7ebed51845 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 9 Jun 2026 23:01:03 +0000
Subject: [PATCH] Revert README to detailed image-rich version
---
README.md | 479 ++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 357 insertions(+), 122 deletions(-)
diff --git a/README.md b/README.md
index d977d22..5b6dac4 100644
--- a/README.md
+++ b/README.md
@@ -1,159 +1,394 @@
-# OneAlert
-
-Open-source OT/ICS security operations platform built with FastAPI, React, PostgreSQL, AI-assisted investigation agents, MITRE ATT&CK mapping, Suricata/Zeek event ingestion, SBOM tracking, response planning, and compliance workflows.
-
-[](https://github.com/mangod12/OneAlert/actions/workflows/ci.yml)
-
-## What Is In This Repo
-
-| Area | Path | What it does |
-|---|---|---|
-| FastAPI backend | `backend/main.py` | Application entrypoint, middleware, health, metrics, router mounting, DB init, scheduler startup. |
-| API routers | `backend/routers/` | Auth, assets, alerts, OT, organizations, compliance, SBOM, topology, billing, integrations, events, cases, MITRE, hunting, response plans, validation. |
-| Domain models | `backend/models/` | Assets, alerts, cases, events, organizations, integrations, SBOM, compliance, topology, subscriptions, users. |
-| Services | `backend/services/` | CVE ingestion, enrichment, notification, AI agents, compliance, MITRE, topology, policy, remediation, SIEM/webhook integrations. |
-| Middleware | `backend/middleware/` | Rate limiting, request IDs, metrics, and security headers. |
-| Frontend | `frontend-v2/` | React 19 + TypeScript + Vite + Tailwind application. |
-| Legacy/static frontend | `frontend/`, `backend/templates/` | Static and template-based screens kept for compatibility/demo paths. |
-| Migrations | `alembic/` | Alembic migrations for organizations, integrations, SBOM, compliance, network topology, subscriptions, and remediation. |
-| Docs | `docs/` | Architecture, code map, AI context, screenshots, and demo notes. |
-| Tests | `tests/`, `tests/e2e/` | Backend pytest suite plus Playwright E2E checks. |
-
-## Core Capabilities
-
-- Asset inventory for OT/IT environments.
-- CVE and vendor advisory ingestion.
-- Suricata and Zeek security event parsing.
-- Case and investigation workflows.
-- MITRE ATT&CK technique mapping.
-- Natural-language hunt endpoint backed by AI services and SQL generation paths.
-- Response plan generation and approval-oriented remediation flow.
-- Compliance framework/control seed data.
-- SBOM tracking.
-- Organization and user management.
-- Integration configuration for SIEM, Slack, ServiceNow, Sentinel, Splunk, PagerDuty, and webhooks.
-- Metrics, request IDs, rate limiting, and security headers.
-
-## Agent And Automation Model
-
-The backend contains specialized services under `backend/services/agents/`:
-
-- `detect.py` for detection-oriented analysis.
-- `triage.py` for alert/case triage.
-- `hunt.py` for threat hunting support.
-- `response.py` for response-plan generation.
-- `purple.py` for validation-style workflows.
-- `compliance.py` for compliance mapping assistance.
-
-Agent output is governed by backend policy, response-plan, audit, and validation routes. OT/ICS safety matters: the codebase is structured around human-reviewable response planning rather than blind autonomous control of industrial assets.
-
-## Runtime Architecture
-
-```text
-FastAPI backend
- -> middleware: request ID, metrics, security headers, rate limiting
- -> routers: assets, alerts, events, cases, hunt, MITRE, response plans, SBOM, compliance
- -> services: parsers, CVE feeds, AI agents, policy, topology, notifications
- -> database: SQLAlchemy + Alembic
- -> frontend: React/Vite app and static/template fallback paths
-```
+
+
OneAlert AI Security OS
+
+ Open-source autonomous cyber defense for industrial networks
+
+
+ AI agents that detect, investigate, hunt, and respond to threats across your OT/ICS infrastructure — with human approval gates and full audit trails.
+
+
+ Live Demo ·
+ Features ·
+ Quick Start ·
+ Architecture
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+
+---
+
+## Try It Now
+
+**Live demo:** https://cybersec-saas-498310931350.us-central1.run.app/app/
+
+| | |
+|---|---|
+| Email | `admin@example.com` |
+| Password | `password123` |
+
+> Pre-loaded with a realistic water treatment plant: 11 OT/IT assets, a **multi-stage attack scenario** (VPN compromise → lateral movement → PLC access attempt), AI-generated investigation case with MITRE ATT&CK mapping, and 15+ security events.
+
+---
+
+## See It In Action
+
+
+ 
+
Security posture dashboard with KPIs, severity breakdown, and risk heatmap
+
+
+
+
+
+
+
AI-generated investigation case with MITRE ATT&CK mapping and attack timeline
+ |
+
+
+
MITRE ATT&CK coverage heatmap with technique search
+ |
+
+
+
+
+
Natural-language threat hunting with AI-generated queries
+ |
+
+
+
Suricata/Zeek security events with severity filtering
+ |
+
+
+
+
+
CVE vulnerability alerts with AI remediation
+ |
+
+
+
OT/IT asset inventory with Purdue model classification
+ |
+
+
+
+---
+
+## Why This Exists
+
+Enterprise SOC tools cost $300K-$800K/yr. SMB manufacturers with PLCs, SCADA systems, and OT networks can't afford them — but they're increasingly targeted. OneAlert gives them an **AI blue team** that:
+
+- Ingests Suricata/Zeek network telemetry
+- Detects anomalies with AI agents (not just static rules)
+- Correlates alerts into investigation cases with MITRE ATT&CK mapping
+- Generates response plans with human approval gates
+- Hunts for threats using natural language
+- Enforces OT safety constraints (no autonomous actions on PLCs)
+
+---
+
+## Features
+
+### AI Agent Pipeline
+
+Six specialized agents working as a team:
+
+| Agent | What It Does |
+|-------|-------------|
+| **Detect Agent** | Analyzes event statistics for port scans, OT protocol anomalies, C2 patterns |
+| **Triage Agent** | Correlates alerts + events into investigation cases with MITRE ATT&CK mapping |
+| **Hunt Agent** | Takes natural-language hypotheses, generates SQL queries, outputs Sigma rules |
+| **Response Agent** | Generates response plans with ordered containment actions |
+| **Purple Agent** | Simulates ATT&CK techniques to validate detection coverage |
+| **Compliance Agent** | Maps platform data to IEC 62443 and NIST CSF controls |
+
+### Governed Autonomy
+
+- **5 autonomy levels** (L0 read-only to L4 crisis mode)
+- **OT safety constraint**: Purdue Level 0-3 assets always require human approval for containment
+- **Full agent ledger**: Every AI decision logged with model, tokens, reasoning
+- **Policy engine**: Action approval rules by zone, asset type, and autonomy level
+- **Approval workflow**: Approve/reject response plans via REST API before execution
+- **Action executor**: 12 action types (notify, block IP, isolate host, quarantine VLAN, etc.)
+
+### PII and Secret Redaction
+
+- **8 pattern types**: emails, SSNs, credit cards, API keys, bearer tokens, passwords, private keys, JWTs
+- **Integrated into event ingestion**: secrets stripped before storage and LLM processing
+- **Preserves network observables**: IPs, ports, domains, hostnames kept for security analysis
+
+### Purple-Team Validation
+
+- **Simulated ATT&CK testing**: 8 technique categories with atomic test library
+- **Dry-run/lab/production modes**: production mode requires explicit human approval
+- **Detection coverage metrics**: per-technique detection rates and gap analysis
+- **Control result tracking**: which detection rules fired, which missed
+
+### Semantic Search and Blast Radius
+
+- **Natural-language case search**: TF-IDF ranking with zero external dependencies
+- **Similar incident retrieval**: cosine similarity matching with shared MITRE technique highlighting
+- **Blast radius graph**: entity relationship visualization (assets, IPs, MITRE techniques per case)
+
+### Security Event Ingestion
+
+- **Suricata EVE JSON** parser (alerts, DNS, HTTP, TLS, flows)
+- **Zeek log** parser (conn, dns, http, ssl, files, notice)
+- **Webhook receiver** for Filebeat/Fluentd real-time ingestion
+- **File upload** for offline analysis
+
+### MITRE ATT&CK Integration
+
+- Enterprise + ICS matrix (16 tactics, 30+ techniques)
+- Auto-mapping from Suricata signatures to techniques
+- Detection coverage heatmap per tactic
+- Searchable technique browser
+
+### Threat Hunt Lab
+
+- Natural-language input: *"Look for lateral movement from engineering workstation to PLC subnet"*
+- AI generates SQL queries against your event data
+- Auto-generated Sigma detection rules from confirmed findings
+- Read-only query safety validation (blocks INSERT/UPDATE/DELETE)
+
+### OT/ICS Vulnerability Management
+
+- Multi-source CVE aggregation (NVD, CISA KEV, ICS-CERT, Cisco PSIRT, Microsoft MSRC)
+- AI-powered OT-aware remediation (compensating controls for critical zones)
+- EPSS exploit probability scoring
+- SBOM analysis (CycloneDX/SPDX)
+- Passive device discovery with Purdue model classification
+
+### Compliance-as-Code
+
+- IEC 62443-3-3 (10 controls) + NIST CSF 2.0 (11 controls)
+- Automated evidence collection from platform data
+- Continuous compliance scoring
-## Local Development
+### Multi-Tenancy and Billing
+
+- Organization model with role-based access (admin/analyst/viewer)
+- Stripe billing (Free, Starter $499, Pro $1,999, Enterprise $4,999/mo)
+- SIEM integrations (Splunk, Sentinel, ServiceNow, PagerDuty)
+
+---
+
+## Quickstart
+
+### One-Command Demo
```bash
git clone https://github.com/mangod12/OneAlert.git
cd OneAlert
-
-python -m venv .venv
-. .venv/Scripts/activate # Windows PowerShell users can use .venv\Scripts\Activate.ps1
pip install -r requirements.txt
-
-set SECRET_KEY=replace-with-local-dev-secret
-set DATABASE_URL=sqlite+aiosqlite:///./onealert.db
-uvicorn backend.main:app --reload --port 8000
+python -m backend.demo
```
-Open:
-
-- API root: `http://localhost:8000`
-- Health: `http://localhost:8000/health`
-- Readiness: `http://localhost:8000/health/ready`
-- Metrics: `http://localhost:8000/metrics`
-- Swagger: `http://localhost:8000/docs`
+Open http://localhost:8000/app/ — demo data auto-loads with attack scenario.
-Frontend v2:
+### Docker
```bash
-cd frontend-v2
-npm install
-npm run dev
+docker compose up --build
```
-## Configuration
+### Local Development
-Start from `.env.example`.
+```bash
+# Backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python -m uvicorn backend.main:app --reload
-Important settings:
+# Frontend
+cd frontend-v2 && npm install && npm run dev
+```
-| Variable | Purpose |
-|---|---|
-| `SECRET_KEY` | JWT/session signing secret. |
-| `DATABASE_URL` | SQLite/PostgreSQL SQLAlchemy URL. |
-| `DISABLE_SCHEDULER` | Disables scheduled feed/alert jobs for local debugging. |
-| `MAILGUN_API_KEY`, `MAILGUN_DOMAIN` | Optional email notification configuration. |
-| `AI_PROVIDER`, `AI_BASE_URL`, `AI_API_KEY` | Optional AI provider configuration. |
-| `CORS_ORIGINS` | Allowed frontend origins. |
+### Environment Variables
-Do not publish real production credentials in README examples.
+```bash
+# Required for AI agents
+AI_PROVIDER=anthropic # or openai, ollama, vllm, groq
+ANTHROPIC_API_KEY=sk-ant-... # or AI_API_KEY for OpenAI-compatible
+
+# Optional
+AI_TRIAGE_MODEL=claude-sonnet-4-20250514
+AI_BASE_URL=http://localhost:11434/v1 # for Ollama/vLLM
+SECRET_KEY=your-production-secret
+DATABASE_URL=postgresql://user:pass@host/db
+```
-## Tests And Quality
+---
-Backend:
+## Architecture
-```bash
-python -m compileall backend/
-pytest -v
+```
+ OneAlert AI Security OS
+ ┌─────────────────┬───────────────────┬───────────────────────┐
+ │ Sensor Layer │ Agent Layer │ Control Plane │
+ │ │ │ │
+ │ Suricata EVE │ Detect Agent │ Policy Engine │
+ │ Zeek Logs │ Triage Agent │ Autonomy Levels │
+ │ Syslog/Auth │ Hunt Agent │ Approval Workflow │
+ │ OT Discovery │ Response Agent │ Agent Ledger │
+ │ PII Redaction │ Purple Agent │ OT Zone Constraints │
+ │ │ Compliance Agent │ Action Executor │
+ ├─────────────────┼───────────────────┼───────────────────────┤
+ │ Data Layer │ AI Runtime │ Frontend │
+ │ │ │ │
+ │ PostgreSQL │ Claude (default) │ Dashboard │
+ │ SQLite (dev) │ OpenAI-compat │ Cases & Investigations│
+ │ Event Store │ Ollama/vLLM │ Events Viewer │
+ │ Agent Ledger │ Model Routing │ MITRE ATT&CK Map │
+ │ Semantic Search│ │ Hunt Lab │
+ │ │ │ Response Plans │
+ │ │ │ Purple-Team Validation│
+ └─────────────────┴───────────────────┴───────────────────────┘
```
-Frontend:
+### Data Flow
-```bash
-cd frontend-v2
-npm run lint
-npm run build
+```
+Suricata/Zeek Events ──► Ingest API ──► Event Store
+ │
+ Detect Agent (anomaly detection)
+ │
+CVE Alerts (NVD/CISA/ICS-CERT) ──► Triage Agent (correlation + MITRE)
+ │
+ Investigation Cases
+ │
+ Response Agent (governed plans)
+ │
+ Human Approval ──► Execute Actions
```
-E2E:
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | FastAPI, Python 3.11+, SQLAlchemy 2.0 async |
+| Frontend | React 19, Vite 8, Tailwind CSS v4, Zustand, Recharts |
+| AI Runtime | Provider-agnostic (Claude, GPT-4o, Ollama, vLLM, Groq) |
+| Database | PostgreSQL (prod), SQLite (dev) |
+| Auth | JWT + GitHub OAuth + TOTP MFA |
+| Deploy | Docker, Google Cloud Run |
+| CI | GitHub Actions, 330+ tests (309 pytest + 22 Playwright E2E) |
+
+---
+
+## API Overview
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /api/v1/events/ingest` | Webhook receiver for security events |
+| `POST /api/v1/events/upload` | Upload Suricata/Zeek log files |
+| `POST /api/v1/cases/pipeline` | Run full AI agent pipeline |
+| `POST /api/v1/cases/auto-triage` | Run triage agent on recent data |
+| `POST /api/v1/hunt/` | Start natural-language threat hunt |
+| `GET /api/v1/mitre/coverage` | MITRE ATT&CK detection coverage |
+| `GET /api/v1/cases/` | List investigation cases |
+| `GET /api/v1/alerts/` | List vulnerability alerts |
+| `GET /api/v1/events/stats` | Event ingestion statistics |
+| `GET /api/v1/cases/search?q=` | Semantic case search |
+| `GET /api/v1/cases/{id}/similar` | Find similar incidents |
+| `GET /api/v1/cases/{id}/blast-radius` | Blast radius entity graph |
+| `GET /api/v1/response-plans/` | List response plans |
+| `POST /api/v1/response-plans/{id}/approve` | Approve a response plan |
+| `POST /api/v1/response-plans/{id}/execute` | Execute approved plan |
+| `POST /api/v1/validation/runs` | Create purple-team validation run |
+| `POST /api/v1/validation/runs/{id}/execute` | Run ATT&CK technique tests |
+| `GET /api/v1/validation/coverage` | Detection coverage by technique |
+
+Full API docs at `/docs` when running locally.
+
+---
+
+## Project Structure
-```bash
-cd tests/e2e
-npm install
-npx playwright test
```
+backend/
+├── services/ai/ # Provider-agnostic LLM runtime
+├── services/agents/ # Detect, Triage, Hunt, Response, Purple agents
+├── services/mitre/ # MITRE ATT&CK integration
+├── services/parsers/ # Suricata + Zeek event parsers
+├── models/ # SQLAlchemy models + Pydantic schemas
+├── routers/ # FastAPI route handlers
+├── services/pii_redactor.py # PII/secret redaction pipeline
+├── services/action_executor.py # Response action execution
+├── services/semantic_search.py # TF-IDF search + blast radius
+└── services/ # CVE, compliance, billing, notifications
+
+frontend-v2/src/
+├── pages/ # Dashboard, Cases, Events, HuntLab, MitreMap, ResponsePlans, Validation
+├── components/ # Charts, layout, shared UI
+└── stores/ # Zustand auth state
+
+tests/ # 309 pytest tests
+tests/e2e/ # Playwright E2E against Cloud Run
+docs/ # AI_CONTEXT, ARCHITECTURE, CODEMAP, VISION
+```
+
+---
-The GitHub Actions CI installs Python dependencies, compiles the backend, and runs pytest with test environment variables.
+## How OneAlert Compares
-## Deployment
+| Capability | OneAlert | Wazuh | SecurityOnion | OSSEC | Caldera |
+|------------|:--------:|:-----:|:-------------:|:-----:|:-------:|
+| AI-powered triage | Yes (6 agents) | No | No | No | No |
+| MITRE ATT&CK mapping | Auto-mapped | Manual rules | Manual | No | Yes |
+| OT/ICS protocol support | Modbus, S7, EtherNet/IP | Limited | Zeek-based | No | No |
+| Natural-language threat hunting | Yes | No | No | No | No |
+| Governed response (approval gates) | Yes (L0-L4) | No | No | No | No |
+| Purple-team validation | Built-in | No | No | No | Yes (core) |
+| PII redaction before LLM | Yes | N/A | N/A | N/A | N/A |
+| Suricata + Zeek ingestion | Yes | Yes | Yes | No | No |
+| Compliance (IEC 62443, NIST CSF) | Automated | Manual | No | No | No |
+| SBOM analysis | Yes | No | No | No | No |
+| Self-hostable | Yes | Yes | Yes | Yes | Yes |
+| SaaS billing (Stripe) | Built-in | No | No | No | No |
-Deployment assets in this repo:
+**OneAlert's differentiator**: AI agents that investigate and respond, not just collect logs. Every action governed by policy with human approval for OT assets.
-- `Dockerfile`
-- `docker-compose.yml`
-- `cloudbuild.yaml`
-- `DEPLOYMENT.md`
-- `CLOUD_SQL_SETUP.md`
-- `scripts/deploy.py`
-- `scripts/setup_cloud_sql.sh`
+---
-The configured GitHub repository homepage points to the active Cloud Run deployment. Verify the deployment health before demoing because Cloud Run services and seeded demo state can change independently of the README.
+## Built For
-## Current Limitations
+| Industry | Use Case |
+|----------|----------|
+| **Water/Wastewater** | Monitor PLCs controlling chemical dosing and pump stations |
+| **Manufacturing** | Protect HMIs and SCADA systems on the factory floor |
+| **Energy/Utilities** | Detect lateral movement from IT to OT control networks |
+| **MSSPs** | Multi-tenant SOC-as-a-Service for industrial clients |
+| **Security Teams** | Purple-team validation of detection coverage |
+| **Compliance** | Automated IEC 62443 and NIST CSF evidence collection |
-- Startup creates tables for development convenience; production schema changes should use Alembic migrations.
-- The repo contains both `frontend-v2/` and legacy frontend/template paths.
-- AI-backed paths need provider configuration; deterministic or non-AI service paths should remain usable without it.
-- Integration senders require external service credentials to exercise end-to-end.
+---
+
+## Contributing
+
+Contributions welcome! Areas where help is most valuable:
+
+- **New event parsers**: Windows Event Log, AWS CloudTrail, Azure Activity
+- **MITRE coverage**: More technique mappings and detection rules
+- **Sigma ecosystem**: Import/export Sigma rules, test against event data
+- **UI/UX**: Dashboard widgets, case visualization, topology graph
+- **OT protocols**: Additional ICS protocol parsers (BACnet, HART-IP)
+
+---
## License
-See [License](License).
+MIT — see [License](License).
+
+---
+
+
+ Built for the security teams that can't afford a $500K SOC platform but still need one.
+