Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

docs(mcp): correct tool count from 11 to 13 across all surfaces (Issue #36) (#199)

Beenu Arora83c420dbcd7a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.md
index 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** (one
real 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.md
index 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:
```mermaid
graph LR
@@ -70,6 +70,7 @@ graph LR
A2[aisoc_list_cases]
A3[aisoc_query_detections]
A4[aisoc_list_investigations]
+ A5[aisoc_lake_schema]
end
subgraph Deep-dive
B1[aisoc_get_alert]
@@ -77,12 +78,16 @@ graph LR
B3[aisoc_get_detection_rule]
B4[aisoc_get_investigation]
end
+ subgraph Lake query
+ D1[aisoc_lake_query]
+ end
subgraph Action / replay
C1[aisoc_run_investigation]
C2[aisoc_replay_decision]
C3[aisoc_explain_step]
end
A2 --> 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.md
index 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 Overview
diff --git a/apps/web/src/components/landing/sections/FeatureGrid.tsx b/apps/web/src/components/landing/sections/FeatureGrid.tsx
index 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.md
index 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.md
index 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.md
index 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. |