Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
docs(mcp): correct tool count from 11 to 13 across all surfaces (Issue #36) (#199)
Beenu Arora83c420dbcd7a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4ef69fbff..12d7bf9f0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fix MCP tool count in docs and landing copy (Issue #36)++Closes the documentation-vs-reality drift on the MCP server's tool surface.+`services/mcp/src/tools/index.ts` registers **13** tools — five discovery+(`aisoc_list_alerts`, `aisoc_list_cases`, `aisoc_query_detections`,+`aisoc_list_investigations`, `aisoc_lake_schema`), four deep-dive+(`aisoc_get_alert`, `aisoc_get_case`, `aisoc_get_detection_rule`,+`aisoc_get_investigation`), one warm-tier lake query+(`aisoc_lake_query`, gated server-side by the `lake:query` permission),+and three action/replay (`aisoc_run_investigation`, `aisoc_replay_decision`,+`aisoc_explain_step`) — but eight public-facing surfaces still claimed+"11 tools" and most tables omitted both lake tools entirely.++Fixed in this PR:++* `README.md` — both the MCP section copy and the services table now say+ 13 tools and call out the lake query pair.+* `services/mcp/README.md` — count corrected; `aisoc_lake_schema` and+ `aisoc_lake_query` added to the tool table with the same wording the+ registry uses (discovery-before-query ordering).+* `apps/docs/docs/integrations/mcp.md` — count corrected; the Mermaid+ graph gained a `Lake query` subgraph wired `aisoc_lake_schema →+ aisoc_lake_query` so the recommended call order is visible at a glance.+* `apps/docs/docs/intro.md`, `apps/docs/docs/architecture.md` (two+ references), `docs/architecture/SYSTEM_DESIGN.md`,+ `docs/design/landing-page-brief.md` — all updated.+* `apps/web/src/components/landing/sections/FeatureGrid.tsx` — the+ marketing card "Use AiSOC from Claude, Cursor, Continue, Cody — 11+ tools." now reads "13 tools." This is the landing-page surface most+ visitors actually see.++No tool implementation changed — the count and tables in+`services/mcp/src/tools/index.ts` were already correct. This is a+documentation-only fix so analysts and self-hosters don't see a smaller+surface area than the server actually exposes, and so the lake query+governance story is discoverable from every doc that lists tools.++### Wire `DetectAgent.process` to `FusionEngine` via cross-service HTTP (Issue #190)++Closes [#190](https://github.com/beenuar/AiSOC/issues/190).++Closes the missing edge in the four-agent façade: `DetectAgent` previously+self-described as the public detection surface but had no synchronous entry+point into the fusion pipeline. Existing callers had to push to Kafka and wait+for the consumer path to run dedup → correlation → ML scoring → confidence+labelling → RBA, which is fine for the streaming case but unusable for+interactive use (e.g. an investigation that needs to fuse one ad-hoc alert).++Three changes, all purely additive:++* `services/fusion/app/api/router.py` exposes `POST /process`, which accepts a+ `RawAlert`, runs it through the live `FusionEngine` instance owned by the+ fusion worker, and returns the `FusedAlert` envelope. Returns `503` if the+ worker has not finished bootstrapping its engine — better to fail loudly than+ to invent a synthetic verdict. Schema validation is delegated to FastAPI /+ Pydantic, so a malformed payload still fails with `422`.+* `services/agents/app/tools/fusion.py` is a thin async `httpx` client that+ posts to `{FUSION_SERVICE_URL}/process` (default+ `http://fusion:8003/process` inside the docker-compose network — fusion+ mounts its router at the root path, *not* under `/api/fusion`). The client+ forwards an optional bearer token and **raises** on any non-2xx or transport+ failure. The module docstring contrasts this with `app.tools.graph`, which+ intentionally degrades gracefully: fusion is the primary detection path, and+ swallowing its errors would make alerts disappear silently.+* `DetectAgent.process(raw_alert, api_token=None)` now delegates to the client+ with no transformation. The class docstring is updated to point at the+ correct endpoint. The same `FusionEngine` instance services both the Kafka+ consumer and the new HTTP path, so behaviour is identical regardless of how+ an alert arrives.++Tests (`services/fusion/tests/test_process_endpoint.py`,+`services/agents/tests/test_fusion_client.py`) cover the happy path+(new-incident envelope), the duplicate path, both 503 modes (no worker,+no engine), 422 on malformed and on invalid severity, and that the endpoint+uses the same engine instance as the worker (no fresh `FusionEngine()` per+request). Client-side tests pin the URL to `/process` (regression guard+against the `/api/fusion/process` path mismatch we caught during initial+wiring), assert bearer-token forwarding, confirm `httpx.HTTPStatusError`+propagates on 503/422, and `httpx.HTTPError` propagates on transport+failures. A final trio of tests pins `DetectAgent.process` as a faithful+delegate to the client (args pass through unchanged, errors propagate, no+swallowed exceptions).++No feature flag and no env gate: the wiring is purely additive — no existing+caller of the fusion service or the agents service changes shape, and the new+endpoint/method only fire when something explicitly invokes them.+### Real ES|QL runner for saved-hunt scheduler (T3.4, v8.0)Replaces the `_execute_hunt` stub in `services/api/app/workers/hunt_scheduler.py`diff --git a/README.md b/README.mdindex c4c2621de..846e5c4c4 100644--- a/README.md+++ b/README.md@@ -186,7 +186,7 @@ npx -y @aisoc/mcp install --host claude \--api-key aisoc_pat_xxxxxxxxxxxx```-The server exposes 11 tools — discovery (`aisoc_list_alerts`, `aisoc_list_cases`, `aisoc_query_detections`), deep-dive (`aisoc_get_case`, `aisoc_get_investigation`), and the action/replay set (`aisoc_run_investigation`, `aisoc_replay_decision`, `aisoc_explain_step`) for walking the agent decision ledger step-by-step.+The server exposes 13 tools — discovery (`aisoc_list_alerts`, `aisoc_list_cases`, `aisoc_query_detections`, `aisoc_list_investigations`, `aisoc_lake_schema`), deep-dive (`aisoc_get_alert`, `aisoc_get_case`, `aisoc_get_detection_rule`, `aisoc_get_investigation`), lake query (`aisoc_lake_query` — warm-tier SELECT, gated by `lake:query` server-side), and the action/replay set (`aisoc_run_investigation`, `aisoc_replay_decision`, `aisoc_explain_step`) for walking the agent decision ledger step-by-step.Full guide: [docs/integrations/mcp](apps/docs/docs/integrations/mcp.md). Source: [`services/mcp/`](services/mcp/). npm: `@aisoc/mcp`.@@ -428,7 +428,7 @@ flowchart LR| `osquery-tls` | Python | 8091 | Native osquery TLS server — enroll nodes, distribute packs, stream FIM/process/network telemetry || `osquery-extensions` | Python | — | Custom osquery extensions (AI-powered threat intel table, ML anomaly score table) || `slack-bot` | Python | 8009 | ChatOps surface — interactive approvals for high-blast-radius actions, `/aisoc` slash command, HMAC-signed Slack signature verification |-| `mcp` | TypeScript | — (stdio) | Model Context Protocol server exposing 11 read-only AiSOC tools (case search, alert detail, IOC pivot, ledger query, DAC lookup, …) to IDE-side AI agents (Claude Code, Cursor, Continue, Cody) |+| `mcp` | TypeScript | — (stdio) | Model Context Protocol server exposing 13 AiSOC tools — discovery, deep-dive, action/replay, and warm-tier lake query (`aisoc_lake_query`, gated by `lake:query` server-side) — to IDE-side AI agents (Claude Code, Cursor, Continue, Cody) || `ingest` | Go | 8081 | OCSF normalization + Shodan/CVE || `enrichment` | Go | 8080 | IOC enrichment (VT, AbuseIPDB, GreyNoise) |diff --git a/apps/docs/docs/architecture.md b/apps/docs/docs/architecture.mdindex 6800b827c..c7a904de2 100644--- a/apps/docs/docs/architecture.md+++ b/apps/docs/docs/architecture.md@@ -48,9 +48,10 @@ step against a case and replayable in the UI), the **Ambient Copilot**playbooks), the **Responder PWA** (passkey-only mobile route at`/responder/*` with VAPID Web Push), the **public eval harness** (onereal measurement plus three substrate self-consistency gates, run in CI),-the **MCP server** (`@aisoc/mcp`, exposes 11 tools to Claude / Cursor /-Continue / Cody), and the **click-and-connect connector platform** (next-section).+the **MCP server** (`@aisoc/mcp`, exposes 13 tools to Claude / Cursor /+Continue / Cody — including the warm-tier `aisoc_lake_query` /+`aisoc_lake_schema` pair, gated by the `lake:query` permission), and the+**click-and-connect connector platform** (next section).Additional capabilities introduced in 2026 H2:@@ -226,7 +227,7 @@ AiSOC/| `purple-team` | 8006 | Python | ART YAML parser, Caldera executor, ATT&CK heatmap, **detection drift snapshots** || `connectors` | — | Python | Connector polling (APScheduler), credential vault (`CredentialVault`), registry-based discovery — **50 vendors shipped** across EDR / SIEM / cloud / IAM / SaaS / network / email || `demo-producer` | — | Python | Synthetic event generator for demos and evaluation |-| `mcp` | n/a | TypeScript | Model Context Protocol stdio server, 11 tools for IDE-side agents (Claude / Cursor / Continue / Cody) |+| `mcp` | n/a | TypeScript | Model Context Protocol stdio server, 13 tools for IDE-side agents (Claude / Cursor / Continue / Cody) — discovery, deep-dive, action/replay, and the warm-tier lake query pair || `osquery-tls` | 8443 | Go | TLS server implementing osquery's enrol/config/distributed/log endpoints; ships normalised host events into `ingest` || `osquery-extensions` | — | Go | Out-of-band osquery extensions registering custom virtual tables and decorators consumed by `osquery-tls` || `slack-bot` | — | Python | ChatOps surface: posts approval prompts, exposes `/aisoc` slash command, verifies inbound interactions with HMAC-signed Slack request signatures |diff --git a/apps/docs/docs/integrations/mcp.md b/apps/docs/docs/integrations/mcp.mdindex 3712419ed..92e55f44d 100644--- a/apps/docs/docs/integrations/mcp.md+++ b/apps/docs/docs/integrations/mcp.md@@ -61,7 +61,7 @@ If the assistant asks for permission to call `aisoc_*` tools, that's expected## Tools exposed-The server advertises **11 tools** to your assistant. Discovery tools list things, deep-dive tools fetch one thing, and the action / replay tools are what make AiSOC interesting:+The server advertises **13 tools** to your assistant. Discovery tools list things, deep-dive tools fetch one thing, the lake-query pair lets agents run governed SELECTs over the warm tier, and the action / replay tools are what make AiSOC interesting:```mermaidgraph LR@@ -70,6 +70,7 @@ graph LRA2[aisoc_list_cases]A3[aisoc_query_detections]A4[aisoc_list_investigations]+ A5[aisoc_lake_schema]endsubgraph Deep-diveB1[aisoc_get_alert]@@ -77,12 +78,16 @@ graph LRB3[aisoc_get_detection_rule]B4[aisoc_get_investigation]end+ subgraph Lake query+ D1[aisoc_lake_query]+ endsubgraph Action / replayC1[aisoc_run_investigation]C2[aisoc_replay_decision]C3[aisoc_explain_step]endA2 --> B2 --> C1 --> C2 --> C3+ A5 --> D1```| Tool | What it does |@@ -95,6 +100,8 @@ graph LR| `aisoc_get_detection_rule` | Inspect a single rule (logic, fixtures, FP notes). || `aisoc_list_investigations` | Page through agent investigation runs. || `aisoc_get_investigation` | Run summary (status, duration, agents involved, cost). |+| `aisoc_lake_schema` | Discover allowlisted tables and column names in the warm tier — call this *before* `aisoc_lake_query` so the agent doesn't guess column names. |+| `aisoc_lake_query` | Run a read-only SELECT against the warm tier (lake). Per-tenant RLS, row caps, and the `lake:query` permission are enforced server-side. || **`aisoc_run_investigation`** | Kick off the agent on a case and stream events back. || **`aisoc_replay_decision`** | Walk the agent ledger step-by-step (recon, forensic, responder, reporter). || **`aisoc_explain_step`** | Why-did-the-agent-do-this for a single step: prompt, response, tool I/O. |diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.mdindex 5f0231e20..1c76c4abf 100644--- a/apps/docs/docs/intro.md+++ b/apps/docs/docs/intro.md@@ -92,7 +92,7 @@ for the full list.- **AI-vs-AI adversary eval** — deterministic attacker-LLM mutator generates adversarial incidents to test detection resilience under synonym swap, leetspeak, zero-width injection, and fragmentation attacks.- **Marketplace** — 15 first-party plugins, 50+ playbooks, 6,900+ detections (filtered by tier: stable / beta / imported / community), surfaced in-app via [`marketplace/index.json`](https://github.com/beenuar/AiSOC/tree/main/marketplace).- **SDKs** — Python, TypeScript, and Go SDKs for client and plugin development; Ed25519-signed publishing.-- **Model Context Protocol** — `@aisoc/mcp` exposes 11 tools to Claude, Cursor, Continue, and Cody so analysts can replay agent decisions from inside their IDE ([MCP integration](./integrations/mcp)).+- **Model Context Protocol** — `@aisoc/mcp` exposes 13 tools to Claude, Cursor, Continue, and Cody so analysts can replay agent decisions and run governed warm-tier SELECTs from inside their IDE ([MCP integration](./integrations/mcp)).## Architecture Overviewdiff --git a/apps/web/src/components/landing/sections/FeatureGrid.tsx b/apps/web/src/components/landing/sections/FeatureGrid.tsxindex 8a8f3129f..9ee572388 100644--- a/apps/web/src/components/landing/sections/FeatureGrid.tsx+++ b/apps/web/src/components/landing/sections/FeatureGrid.tsx@@ -148,7 +148,7 @@ const BLOCKS: ReadonlyArray<FeatureBlock> = [{icon: DollarSign,title: 'MCP server.',- body: 'Use AiSOC from Claude, Cursor, Continue, Cody — 11 tools.',+ body: 'Use AiSOC from Claude, Cursor, Continue, Cody — 13 tools.',},{icon: TerminalSquare,diff --git a/docs/architecture/SYSTEM_DESIGN.md b/docs/architecture/SYSTEM_DESIGN.mdindex a5849ab69..93ac662ba 100644--- a/docs/architecture/SYSTEM_DESIGN.md+++ b/docs/architecture/SYSTEM_DESIGN.md@@ -102,7 +102,7 @@ This document describes the end-to-end architecture of the AiSOC platform after| `services/osquery-extensions` | Go 1.25 | Out-of-band osquery extensions (custom virtual tables + decorators) | Loaded by `osquery-tls`-managed agents || `services/slack-bot` | Python 3.11 | ChatOps surface: posts approval prompts, `/aisoc` slash command | Verifies inbound interactions with HMAC-signed Slack request signatures || `services/realtime` | Node 20 | WebSocket fan-out + Web Push for the web console + Responder PWA | n/a |-| `services/mcp` | Node 20 (TypeScript) | Model Context Protocol stdio server, 11 tools for IDE-side agents (Claude / Cursor / Continue / Cody) | n/a |+| `services/mcp` | Node 20 (TypeScript) | Model Context Protocol stdio server, 13 tools for IDE-side agents (Claude / Cursor / Continue / Cody) — discovery, deep-dive, action/replay, and the warm-tier lake query pair (`aisoc_lake_schema`, `aisoc_lake_query`) | n/a || `apps/web` | Next.js 14 | Server components + SWR + Responder PWA route group + benchmark scoreboard | n/a |---diff --git a/docs/design/landing-page-brief.md b/docs/design/landing-page-brief.mdindex d3628d1ea..9a81edc50 100644--- a/docs/design/landing-page-brief.md+++ b/docs/design/landing-page-brief.md@@ -889,7 +889,7 @@ Condensed teardown lives at `docs/design/landing-page-references.md`.| Marketplace (7,117 items) | `marketplace/index.json` · `scripts/build_marketplace.py` | Detection engineer | V4 | connectors | Shipped || Credential vault (Fernet + HMAC) | `services/api/app/services/vault.py` · `apps/docs/docs/operations/credentials.md` | CISO | V4, P3 | deploy, pillars (P3) | Shipped || Plugin SDKs (Python, TypeScript, Go) | `packages/plugin-sdk-py/` · `packages/plugin-sdk-ts/` · `packages/plugin-sdk-go/` | Detection engineer | V4 | features-operate | Shipped |-| MCP server (11 tools) | `services/mcp/` | Detection engineer | V4 | features-operate | Shipped |+| MCP server (13 tools) | `services/mcp/` | Detection engineer | V4 | features-operate | Shipped || Cursor extension | `services/mcp/cursor-extension/` (T7.1) | Detection engineer | V4 | features-operate | Shipped (scaffold) || Render one-click deploy | `render.yaml` · `infra/render/` | Analyst, manager | V5 (deploy) | deploy | Shipped || Fly.io deploy script | `infra/fly/` | Manager | V5 | deploy | Shipped |diff --git a/services/mcp/README.md b/services/mcp/README.mdindex de59a743a..34d71095d 100644--- a/services/mcp/README.md+++ b/services/mcp/README.md@@ -76,7 +76,7 @@ Print these as JSON any time with `npx @aisoc/mcp install --list-paths`.## Tools exposed-The server advertises **11 tools**. Discovery tools list things, deep-dive tools fetch one thing, and the action / replay tools are what make AiSOC interesting:+The server advertises **13 tools**. Discovery tools list things, deep-dive tools fetch one thing, the lake-query pair lets agents run governed SELECTs over the warm tier, and the action / replay tools are what make AiSOC interesting:| Tool | Purpose ||---|---|@@ -88,6 +88,8 @@ The server advertises **11 tools**. Discovery tools list things, deep-dive tools| `aisoc_get_detection_rule` | Inspect a single rule (logic, fixtures, FP notes). || `aisoc_list_investigations` | Page through agent investigation runs. || `aisoc_get_investigation` | Run summary (status, duration, agents involved, cost). |+| `aisoc_lake_schema` | Discover allowlisted tables and column names in the warm tier — call this *before* `aisoc_lake_query` so the agent doesn't guess column names. |+| `aisoc_lake_query` | Run a read-only SELECT against the warm tier (lake). Per-tenant RLS, row caps, and the `lake:query` permission are enforced server-side. || **`aisoc_run_investigation`** | Kick off the agent on a case and stream events back. || **`aisoc_replay_decision`** | Walk the agent ledger step-by-step (recon, forensic, responder, reporter). || **`aisoc_explain_step`** | Why-did-the-agent-do-this for a single step: prompt, response, tool I/O. |