AiSOC

An open-source, self-hostable AI SOC. The agent's prompts, tool calls, and rationale are logged step-by-step and replayable. MIT-licensed.

_{The community-maintained demo at tryaisoc.com runs on Fly.io and can go offline; see docs/operations/live-demo-runbook.md and use Codespaces as the always-on fallback.}

_{90-second walkthrough — agent investigates the seeded LockBit 3.0 case end-to-end. The rendered .mp4 + hero.gif land with the v8.0 launch; the brief is in docs/demo/SCREENCAST_SHOTLIST.md.}

---

Try AiSOC in 60 seconds

Four fastest paths to a working AiSOC investigation. Pick whichever matches what you already have on your machine:

If you have…	Run this	What you get
Python 3.10+ (no Docker)	pip install -e packages/aisoc-sandbox && aisoc-sandbox demo	Offline agent investigation walked through Detect → Triage → Hunt → Respond and printed to stdout. < 5 s. No API key, no network.
A browser (zero install)	Open in Codespaces	Browser IDE → pnpm aisoc:demo --no-open → click forwarded port 3000. ~5 min cold.
Docker + pnpm	git clone https://github.com/beenuar/AiSOC && cd AiSOC && pnpm aisoc:demo	Local stack on Postgres + Redis + Kafka + api + agents + web. Browser opens at INC-RT-001.
Nothing (clean Linux/macOS/Win)	curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh | bash	Bootstraps Docker, Node, pnpm, git for you; then runs pnpm aisoc:demo.

The first row is new: aisoc-sandbox is a zero-dependency, in-memory simulator of the agent funnel. Pick a bundled scenario (lateral-movement, aws-credential-exfil, phishing-payload, kubernetes-privesc, github-token-theft) or feed in your own JSON via --file. The other three rows boot the real stack and land you on /cases/INC-RT-001?tab=ledger — a LockBit 3.0 ransomware case mid-investigation, with the AI agent's prompts, tool calls, and rationale streaming into the Investigation Ledger. Stop the real stack with pnpm aisoc:demo:down.

Does the demo still boot on main? Every push runs compose-smoke (the same pnpm aisoc:demo path you'd run locally) and e2e against the seeded console; nightly compose-smoke-nightly repeats it with cold caches. A red badge below is a release-blocker.

Full multi-platform deploy guide is in apps/docs/docs/installation.md (Render, Fly.io, Docker Compose, Kubernetes, Terraform). Production-grade install with full storage tier: infra/helm/ or infra/terraform/.

---

What AiSOC is

AiSOC is a single self-hostable stack that ingests security events, correlates them, runs AI-driven investigation, and surfaces the result in a SOC console. The agent and the substrate are MIT-licensed, so you can read, fork, or replace either of them.

Three properties distinguish it from closed-source AI SOC vendors:

1. Agent decisions are logged. The Investigation Ledger stores the LLM prompt, the response, the evidence cited, and the downstream tool calls for every step of every run. Replays are available later.
2. The substrate has a public eval harness in CI. Five suites gate every PR targeting main / develop — alert reduction is a real measurement against a fixed 1 000-alert stream; three rubric-based suites are substrate self-consistency gates over a deterministic 200-incident dataset (55 templates) with per-template macros; a fifth gate validates the backing telemetry corpus. The benchmark page documents exactly what each suite measures and what it does not.
3. It runs entirely on your infrastructure. No callbacks to a vendor cloud and no data exfiltration for "model improvement."

The orchestrator is a ~600-line LangGraph in services/agents/. It is small enough to read end-to-end, swap models in, and patch.

---

How AiSOC compares

Capability	AiSOC	Wazuh	Splunk ES	Closed-source AI SOC
Open-source license	MIT	GPL-2	proprietary	proprietary
Self-hostable	yes	yes	enterprise-only	cloud-only
Autonomous AI investigation	LangGraph	no	partial (Splunk AI)	yes
Agent decision audit trail	public Investigation Ledger	n/a	n/a	not published
Public substrate eval harness	CI-gated, reproducible, with synthetic telemetry corpus + per-template macros	n/a	n/a	not published
Detection content	800 native + 6 000+ imported (Sigma / Splunk / Chronicle / CAR)	1 200+ rules	1 000+ apps	curated
Plugin SDK	Python / TypeScript / Go	YAML rules only	apps	proprietary
Data residency	your infra	your infra	partial	vendor cloud
Pricing	$0 (self-host)	$0 (self-host)	per ingest GB	enterprise

Closed-source AI SOC vendors ship working products. AiSOC's contribution is making the agent itself open, the per-step decision trail readable, and the substrate gated by a public eval harness on every PR targeting main / develop.

---

What you'll see in the console

Alerts queue — server-anchored SLA countdowns, atomic claim, one-click triage. Docs	Investigation Rail — narrative, pivot-path entity chips, 6-event timeline, recommended actions. Docs
/hunt workbench — type a hypothesis in English, get ES|QL / SPL / KQL back, save + schedule. Docs	Marketplace — plugins, playbooks, detections with one-click tenant install. Docs

_{The four tiles above are SVG placeholders. Real PNG screenshots ship with the next Phase 2 visuals rollup; the walkthrough video at the top of this README is the canonical reference until then.}

---

Architecture

flowchart LR
    subgraph Sources["Sources"]
        EDR["EDR / XDR"]
        SIEM["SIEM"]
        Cloud["Cloud APIs"]
        IDP["Identity"]
        Net["Network"]
    end

    subgraph Ingest["Ingest & Normalize"]
        Connectors["Connectors\n(Python · 69 vendors)"]
        OsqueryTLS["osquery-tls\n(Python · host telemetry)"]
        IngestSvc["Ingest worker\n(Go · OCSF)"]
        Enrich["Enrichment\n(Go · IOC + Shodan)"]
    end

    subgraph Spine["Event Spine"]
        Kafka[("Apache Kafka")]
    end

    subgraph Detect["Detect & Reason"]
        Fusion["Fusion\n(Python · ML)"]
        UEBA["UEBA\n(Python · baseline)"]
        Rules["Rule engine\n(Sigma · YARA · KQL)"]
        Agents["AI Agents\n(LangGraph)"]
    end

    subgraph Storage["Storage Tier"]
        PG[("PostgreSQL")]
        CH[("ClickHouse")]
        OS[("OpenSearch")]
        QD[("Qdrant")]
        N4[("Neo4j")]
        RD[("Redis")]
    end

    subgraph Surface["Surface"]
        API["Core API\n(FastAPI)"]
        Web["Web Console + Responder PWA\n(Next.js)"]
        MCP["MCP Server\n(TS · stdio)"]
    end

    Sources --> Connectors --> IngestSvc --> Kafka
    OsqueryTLS --> IngestSvc
    IngestSvc --> Enrich --> Kafka
    Kafka --> Fusion --> Storage
    Kafka --> UEBA --> Kafka
    Kafka --> Rules --> Kafka
    Agents --> Storage
    API --> Storage
    Web --> API
    MCP --> API

Loading

Full architecture (every service, every storage role, the v1.5 console workbench, and the Investigation Ledger contract) is in apps/docs/docs/architecture.md. The deeper system-design write-up — including ML fusion, the Neo4j-at-ingest schema, and the threat-intel pipeline — lives at docs/architecture/SYSTEM_DESIGN.md. The full monorepo layout is at apps/docs/docs/architecture/overview.md.

---

What's in the box

A handful of headline capabilities — the rest are catalogued in apps/docs/docs/features/ and indexed at the top of apps/docs/docs/intro.md:

• 69 click-and-connect data connectors (EDR/XDR, SIEM, cloud, CNAPP, identity, SaaS, VCS, K8s audit, network) with schema-driven config, live Test connection, and vault-encrypted secrets. Walkthrough: apps/docs/docs/connectors/index.md.
• Investigation Rail + replayable Investigation Ledger — every prompt, tool call, evidence chip, and rationale stored against a case, replayable in the UI. apps/docs/docs/console/investigation-rail.md.
• Detection-as-Code lifecycle — propose → review → eval-gate → promote; CI rejects any candidate that regresses MITRE accuracy. apps/docs/docs/concepts/detections.md — and the 800+ native Sigma rules live in detections/.
• L0–L4 automation maturity — gate every autonomous action on per-action confidence thresholds and blast-radius. apps/docs/docs/concepts/automation-maturity.md.
• Hunt-as-Code — YAML hypotheses with MITRE tags, cron schedules, and natural-language /hunt workbench. hunts/ + apps/docs/docs/console/rule-tuning.md.
• Public weekly benchmark scoreboard — the same harness that gates PRs, run weekly against main. apps/docs/docs/benchmark-scoreboard.mdx.

---

Use it from Claude, Cursor, or Cody

AiSOC ships an MCP server (services/mcp/) so analysts can query alerts, run agent investigations, and replay every step the agent took without leaving the IDE or chat. The server exposes 13 tools — discovery, deep-dive, governed lake query, and the action / replay set that walks the agent decision ledger step-by-step.

Status — monorepo source build today; npm publish lands in v8.0. Full setup is in apps/docs/docs/integrations/mcp.md, which shows the today-vs-v8.0 invocations side by side.

---

Extend it

Three contribution surfaces; each is one file plus optional fixtures, and CI validates every PR.

• Detection rule. Drop a Sigma YAML under detections/ with a positive / negative fixture in detections/fixtures/. The validate-detections workflow tests it on every PR. Spec: docs/connectors/.
• Connector. Subclass BaseConnector in services/connectors/app/connectors/, register it in _CONNECTOR_CLASSES, and add a plugins/<id>/plugin.yaml manifest. The marketplace picks it up automatically. Walkthrough: apps/docs/docs/connectors/.
• Playbook. Drop a YAML under playbooks/; validate-playbooks gates the PR. Schema: playbook.schema.json.

Plugin and detection SDK (Python · TypeScript · Go) — see apps/docs/docs/plugins/overview.md. The CLI (aisoc-cli) is in packages/aisoc-cli/; PyPI publish lands in v8.0.

---

Roadmap & releases

• Latest GitHub release with downloads: https://github.com/beenuar/AiSOC/releases/latest
• Per-release narrative: RELEASES.md (mirrors what used to live in this README)
• Machine-readable inventory with file paths, env-var diffs, test counts: CHANGELOG.md
• v8.0 wave-2 in flight ([~] items): docs/roadmap/v8-progress.md
• Bigger-picture roadmap (BYOC multi-cloud, MSSP rollups, federated search): ROADMAP.md

---

Contributing

PRs of every size are welcome. Read CONTRIBUTING.md for the workflow and the Code of Conduct before opening a PR.

First-time contributors: pick a good first issue. Need help? Open a Q&A discussion.

---

Credits

AiSOC is built and improved by a growing community of contributors, security researchers, and operators. The full attribution — including bug reporters and security researchers — lives in .github/CREDITS.md. The always-up-to-date code-contribution graph is on the GitHub contributors page.

---

Security

For security issues, please do not open a public issue. Use GitHub's private vulnerability reporting. Full policy in SECURITY.md. AiSOC follows coordinated disclosure.

---

License

MIT — © 2024–present AiSOC contributors.

Report a bug · Request a feature · Contribute · Read the docs · Reproduce the benchmark