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): record the HTTP transport, and correct the audit claim per transport

Beenu Arora37c81d129f8d
diff --git a/scripts/check_mcp_over_http.py b/scripts/check_mcp_over_http.py
index 429c05e79..db39bec90 100644
--- a/scripts/check_mcp_over_http.py
+++ b/scripts/check_mcp_over_http.py
@@ -161,9 +161,7 @@ def _registry_sources(root: Path) -> str:
if not tools_dir.is_dir():
return ""
return "\n".join(
- path.read_text(encoding="utf-8")
- for path in sorted(tools_dir.glob("*.ts"))
- if path.name not in {"index.ts", "types.ts"}
+ path.read_text(encoding="utf-8") for path in sorted(tools_dir.glob("*.ts")) if path.name not in {"index.ts", "types.ts"}
)
@@ -255,8 +253,7 @@ def violations(root: Path) -> list[str]:
drifted = sorted(n for n in set(registry) & set(declared) if registry[n] != declared[n])
if missing:
found.append(
- f"catalogue-parity: {CATALOGUE} does not know about {', '.join(missing)}. "
- "An unknown tool is authorised by nothing."
+ f"catalogue-parity: {CATALOGUE} does not know about {', '.join(missing)}. An unknown tool is authorised by nothing."
)
if extra:
found.append(f"catalogue-parity: {CATALOGUE} lists {', '.join(extra)}, which the registry does not export.")
@@ -305,10 +302,7 @@ def write_catalogue(root: Path) -> int:
"services/mcp/src/tools/. Do not hand-edit: the same script fails CI "
"when this file and the registry disagree."
),
- "tools": [
- {"name": name, "read_only": registry[name], "default_enabled": registry[name]}
- for name in sorted(registry)
- ],
+ "tools": [{"name": name, "read_only": registry[name], "default_enabled": registry[name]} for name in sorted(registry)],
}
path = root / CATALOGUE
path.parent.mkdir(parents=True, exist_ok=True)
@@ -334,7 +328,9 @@ def main() -> int:
print(f"\n{len(problems)} problem(s).", file=sys.stderr)
return 1
- print("check_mcp_over_http: OK — streamable HTTP, per-request credentials, authorized and audited per call, deployed in compose and Helm")
+ print(
+ "check_mcp_over_http: OK — streamable HTTP, per-request credentials, authorized and audited per call, deployed in compose and Helm"
+ )
return 0
@@ -383,7 +379,10 @@ def _rule_self_test() -> list[tuple[str, bool]]:
checks.append(
(
"removing the HTTP transport is reported",
- any("transport:" in v for v in _with_edit(root, {HTTP_MODULE: http_src.replace("StreamableHTTPServerTransport", "StdioServerTransport")})),
+ any(
+ "transport:" in v
+ for v in _with_edit(root, {HTTP_MODULE: http_src.replace("StreamableHTTPServerTransport", "StdioServerTransport")})
+ ),
)
)
checks.append(
@@ -424,8 +423,7 @@ def _rule_self_test() -> list[tuple[str, bool]]:
checks.append(
(
"a write tool relabelled read-only in the catalogue is reported",
- catalogue != flipped
- and any("catalogue-parity:" in v for v in _with_edit(root, {CATALOGUE: json.dumps(flipped, indent=2)})),
+ catalogue != flipped and any("catalogue-parity:" in v for v in _with_edit(root, {CATALOGUE: json.dumps(flipped, indent=2)})),
)
)
checks.append(
diff --git a/services/api/app/api/v1/endpoints/mcp_access.py b/services/api/app/api/v1/endpoints/mcp_access.py
index 3d0fe8c25..cfac61e08 100644
--- a/services/api/app/api/v1/endpoints/mcp_access.py
+++ b/services/api/app/api/v1/endpoints/mcp_access.py
@@ -75,9 +75,7 @@ router = APIRouter(prefix="/mcp", tags=["mcp"])
#: Outcomes the MCP server may report. Closed on purpose: a free-text
#: outcome column is one nobody can aggregate, and "success" spelled three
#: ways is how a usage meter reads zero.
-COMPLETION_OUTCOMES: frozenset[str] = frozenset(
- {"success", "error", "invalid_arguments", "unknown_tool", "denied"}
-)
+COMPLETION_OUTCOMES: frozenset[str] = frozenset({"success", "error", "invalid_arguments", "unknown_tool", "denied"})
# ---------------------------------------------------------------------------
diff --git a/services/api/app/models/mcp_access.py b/services/api/app/models/mcp_access.py
index 8a5c2aeee..6583da69e 100644
--- a/services/api/app/models/mcp_access.py
+++ b/services/api/app/models/mcp_access.py
@@ -43,12 +43,8 @@ class McpToolGrant(Base):
tool_name: Mapped[str] = mapped_column(Text, nullable=False)
enabled: Mapped[bool] = mapped_column(Boolean, nullable=False)
decided_by: Mapped[str] = mapped_column(Text, nullable=False, default="")
- created_at: Mapped[datetime] = mapped_column(
- DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC)
- )
- updated_at: Mapped[datetime] = mapped_column(
- DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC)
- )
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC))
+ updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC))
class McpToolApproval(Base):
@@ -77,6 +73,4 @@ class McpToolApproval(Base):
decided_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
decision_note: Mapped[str] = mapped_column(Text, nullable=False, default="")
expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
- created_at: Mapped[datetime] = mapped_column(
- DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC)
- )
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC))
diff --git a/services/api/app/services/mcp_access.py b/services/api/app/services/mcp_access.py
index 090740955..3b6d86423 100644
--- a/services/api/app/services/mcp_access.py
+++ b/services/api/app/services/mcp_access.py
@@ -170,9 +170,7 @@ async def effective_tools(db: AsyncSession, tenant_id: uuid.UUID) -> list[dict[s
return out
-async def _live_approval(
- db: AsyncSession, tenant_id: uuid.UUID, tool_name: str, fingerprint: str
-) -> McpToolApproval | None:
+async def _live_approval(db: AsyncSession, tenant_id: uuid.UUID, tool_name: str, fingerprint: str) -> McpToolApproval | None:
"""An approved, unexpired, unspent approval for exactly this call."""
now = datetime.now(UTC)
stmt = (
diff --git a/services/api/migrations/104_mcp_access.sql b/services/api/migrations/104_mcp_access.sql
index 75f5f4b7c..f4c6b13d3 100644
--- a/services/api/migrations/104_mcp_access.sql
+++ b/services/api/migrations/104_mcp_access.sql
@@ -51,7 +51,7 @@ CREATE TABLE IF NOT EXISTS aisoc_mcp_tool_grants (
-- Matches `name` in app/data/mcp_tool_catalog.json. Not an FK: the
-- catalogue is a generated file held in parity with the TypeScript
- -- registry by scripts/check_mcp_tool_catalog.py, and a row for a tool
+ -- registry by scripts/check_mcp_over_http.py, and a row for a tool
-- that has since been removed should survive as history rather than
-- block the removal.
tool_name TEXT NOT NULL,
diff --git a/services/api/tests/test_mcp_access.py b/services/api/tests/test_mcp_access.py
index ef3984acc..c6fbb3e85 100644
--- a/services/api/tests/test_mcp_access.py
+++ b/services/api/tests/test_mcp_access.py
@@ -108,9 +108,7 @@ async def client(session_factory):
app = FastAPI()
app.include_router(mcp_router, prefix="/api/v1")
- state: dict[str, CurrentUser] = {
- "user": _principal(user_id=ANALYST, scopes=["*"], key_prefix="aisoc_analyst")
- }
+ state: dict[str, CurrentUser] = {"user": _principal(user_id=ANALYST, scopes=["*"], key_prefix="aisoc_analyst")}
async def _db():
async with session_factory() as session:
@@ -176,9 +174,7 @@ async def test_a_refused_call_is_recorded_too(client, session_factory) -> None:
@pytest.mark.asyncio
async def test_the_outcome_is_a_second_row_because_audit_rows_are_immutable(client, session_factory) -> None:
- authorized = client.post(
- "/api/v1/mcp/tool-calls/authorize", json={"tool_name": READ_TOOL, "arguments": {}}
- ).json()
+ authorized = client.post("/api/v1/mcp/tool-calls/authorize", json={"tool_name": READ_TOOL, "arguments": {}}).json()
res = client.post(
f"/api/v1/mcp/tool-calls/{authorized['call_id']}/complete",
json={"outcome": "success", "latency_ms": 42},
@@ -209,9 +205,7 @@ async def test_an_outcome_outside_the_closed_set_is_refused(client) -> None:
@pytest.mark.asyncio
async def test_a_tenant_can_turn_a_tool_off_against_a_wildcard_key(client, session_factory) -> None:
- assert client.post("/api/v1/mcp/tool-calls/authorize", json={"tool_name": READ_TOOL, "arguments": {}}).json()[
- "outcome"
- ] == "allow"
+ assert client.post("/api/v1/mcp/tool-calls/authorize", json={"tool_name": READ_TOOL, "arguments": {}}).json()["outcome"] == "allow"
off = client.put(f"/api/v1/mcp/tools/{READ_TOOL}", json={"enabled": False})
assert off.status_code == 200, off.text
@@ -232,7 +226,7 @@ async def test_a_tenant_can_turn_a_tool_off_against_a_wildcard_key(client, sessi
@pytest.mark.asyncio
async def test_no_row_means_default_not_denied_and_the_console_can_tell(client) -> None:
- """"Nobody decided" and "somebody turned it off" must not render the same."""
+ """ "Nobody decided" and "somebody turned it off" must not render the same."""
listed = {entry["name"]: entry for entry in client.get("/api/v1/mcp/tools").json()}
assert listed[READ_TOOL]["source"] == "default"
assert listed[READ_TOOL]["enabled"] is True
@@ -323,16 +317,22 @@ async def test_an_approval_is_spent_by_the_call_it_authorised(client) -> None:
user_id=ANALYST, scopes=["*"], key_prefix="aisoc_analyst"
)
- assert client.post(
- "/api/v1/mcp/tool-calls/authorize",
- json={"tool_name": WRITE_TOOL, "arguments": {"case_id": "case-a"}},
- ).json()["outcome"] == "allow"
+ assert (
+ client.post(
+ "/api/v1/mcp/tool-calls/authorize",
+ json={"tool_name": WRITE_TOOL, "arguments": {"case_id": "case-a"}},
+ ).json()["outcome"]
+ == "allow"
+ )
# Second use of the same approval: a grant that outlives the call it was
# given for is a permission, and nobody granted a permission.
- assert client.post(
- "/api/v1/mcp/tool-calls/authorize",
- json={"tool_name": WRITE_TOOL, "arguments": {"case_id": "case-a"}},
- ).json()["outcome"] == "approval_required"
+ assert (
+ client.post(
+ "/api/v1/mcp/tool-calls/authorize",
+ json={"tool_name": WRITE_TOOL, "arguments": {"case_id": "case-a"}},
+ ).json()["outcome"]
+ == "approval_required"
+ )
@pytest.mark.asyncio
@@ -386,21 +386,20 @@ async def test_an_expired_approval_is_not_a_live_one(client, session_factory) ->
client.post(f"/api/v1/mcp/approvals/{pending['approval_id']}/decide", json={"approve": True})
async with session_factory() as session:
- row = (
- await session.execute(
- select(McpToolApproval).where(McpToolApproval.id == uuid.UUID(pending["approval_id"]))
- )
- ).scalar_one()
+ row = (await session.execute(select(McpToolApproval).where(McpToolApproval.id == uuid.UUID(pending["approval_id"])))).scalar_one()
row.expires_at = datetime.now(UTC) - timedelta(seconds=1)
await session.commit()
client.state_holder["user"] = _principal( # type: ignore[attr-defined]
user_id=ANALYST, scopes=["*"], key_prefix="aisoc_analyst"
)
- assert client.post(
- "/api/v1/mcp/tool-calls/authorize",
- json={"tool_name": WRITE_TOOL, "arguments": {"case_id": "case-a"}},
- ).json()["outcome"] == "approval_required"
+ assert (
+ client.post(
+ "/api/v1/mcp/tool-calls/authorize",
+ json={"tool_name": WRITE_TOOL, "arguments": {"case_id": "case-a"}},
+ ).json()["outcome"]
+ == "approval_required"
+ )
# ---------------------------------------------------------------------------
@@ -431,8 +430,7 @@ def test_a_permission_is_one_a_key_can_actually_be_minted_with() -> None:
policy.tool_catalogue.cache_clear()
missing = sorted(
- {spec.required_permission for spec in policy.tool_catalogue().values() if spec.required_permission}
- - set(VALID_SCOPES)
+ {spec.required_permission for spec in policy.tool_catalogue().values() if spec.required_permission} - set(VALID_SCOPES)
)
assert missing == [], f"not mintable into an API key: {missing}"
diff --git a/services/mcp/README.md b/services/mcp/README.md
index 63d0ba7f7..4b7a8784c 100644
--- a/services/mcp/README.md
+++ b/services/mcp/README.md
@@ -146,9 +146,47 @@ Every flag has an environment-variable equivalent. The CLI flag wins when both a
| `--api-key` | `AISOC_API_KEY` | _(none)_ | API key (`aisoc_pat_…`) or JWT. Required for non-public endpoints. |
| `--timeout` | `AISOC_TIMEOUT_MS` | `20000` | Per-request timeout in ms. |
| `--verbose` | `AISOC_MCP_VERBOSE=1` | off | Lifecycle logs to stderr. Stdout stays JSON-RPC clean. |
+| `--http` | `AISOC_MCP_HTTP=1` | off | Serve streamable HTTP instead of stdio. See below. |
+| — | `AISOC_MCP_HTTP_HOST` | `127.0.0.1` | Bind address for the HTTP transport. |
+| — | `AISOC_MCP_HTTP_PORT` | `8096` | Port for the HTTP transport. |
+| — | `AISOC_MCP_MAX_BODY_BYTES` | `1048576` | Largest JSON-RPC frame accepted over HTTP. |
Two further env vars control telemetry, described under [Security notes](#security-notes): `AISOC_MCP_TELEMETRY_URL` and `AISOC_MCP_AGENT_ID`.
+## Over the network (streamable HTTP)
+
+`--http` serves the same tools over MCP's streamable HTTP transport at
+`POST /mcp`, with an unauthenticated liveness probe at `GET /healthz`.
+`docker compose --profile mcp up` runs it; the Helm chart has an `mcp`
+component, off by default.
+
+Three things are different over HTTP, and they are differences in who decides
+what rather than in plumbing:
+
+- **The credential comes from the request.** Send
+ `Authorization: Bearer aisoc_…` (or a JWT) on every call. `--api-key` /
+ `AISOC_API_KEY` configure the *stdio* server and are not consulted here, so a
+ request without a credential is `401` rather than being answered with the
+ operator's own access. The tenant is derived from the credential; there is no
+ tenant parameter anywhere in the protocol or the authorize request.
+- **Every call is authorized by AiSOC before it runs.** The server posts to
+ `POST /api/v1/mcp/tool-calls/authorize` and does what it is told. It fails
+ **closed**: if the API cannot be reached, no tool runs.
+- **A tool that is not read-only needs a human.** `aisoc_run_investigation` is
+ the only one today. The first call creates an approval bound to those exact
+ arguments and answers with its id; somebody other than the requester decides
+ it at `POST /api/v1/mcp/approvals/{id}/decide`, and the approval is spent by
+ the call it authorised.
+
+A tenant administrator can switch any individual tool off for the whole tenant
+at `PUT /api/v1/mcp/tools/{tool_name}`, independently of what scopes a key
+carries. `GET /api/v1/mcp/tools` lists the effective state and says whether it
+came from a tenant decision or from the tool's default.
+
+Sessions are deliberately not implemented: the transport is stateless and a
+fresh server is built per request, so revoking a key ends every conversation
+it had opened rather than leaving a session id that outlives it.
+
## Verify before you fly
```bash
@@ -174,11 +212,44 @@ node dist/index.js doctor
The host launches us over stdio. Stdout carries JSON-RPC frames only; logs go to stderr. We translate MCP `tools/call` into AiSOC REST calls. `aisoc_run_investigation` emits progressive content blocks so the assistant can show intermediate steps.
+With `--http` the left-hand arrow is streamable HTTP rather than stdio, the
+host supplies its own bearer credential per request, and one extra hop sits in
+front of every dispatch:
+
+```
+┌──────────────┐ HTTP POST /mcp ┌──────────────┐ authorize ┌──────────────┐
+│ any MCP │ ─────────────────► │ @aisoc/mcp │ ───────────► │ AiSOC API │
+│ client │ Authorization: │ --http │ ◄─────────── │ decides + │
+│ │ Bearer aisoc_… │ │ allow / │ writes audit │
+└──────────────┘ └──────┬───────┘ deny / └──────────────┘
+ │ approval
+ ▼ (only if allowed)
+ the tool's own AiSOC REST call
+```
+
## Security notes
-- **Your API key never leaves the machine** running this server. It is read from the environment or from the host's local config file (written mode `0600`) and used to sign requests to your own AiSOC instance.
+- **Your API key never leaves the machine** running this server, on the stdio transport. It is read from the environment or from the host's local config file (written mode `0600`) and used to sign requests to your own AiSOC instance. Over HTTP there is no stored key at all: the credential arrives with each request, is used for that request, and is not retained.
- **Read-only unless the key says otherwise.** `aisoc_run_investigation` requires `cases:write`; `aisoc_preview_action` requires `actions:execute` but only ever calls the dry-run; every other tool needs only read scopes.
-- **Audit trail — read this before relying on it.** The API's `audit_middleware` records only mutating methods carrying a valid JWT, so the ten read tools (`aisoc_list_*`, `aisoc_get_*`, `aisoc_lake_query`) produce **no server-side audit row**, and what it does record is an HTTP path rather than a tool name. Per-tool attribution comes instead from this server's own `mcp.tool_call` records: tool name, calling key's subject, argument *keys* (never values), latency, and outcome. Set `AISOC_MCP_TELEMETRY_URL` to an AiSOC inbox token using the `ai-runtime` template to collect them. Unset, nothing is emitted. `AISOC_MCP_AGENT_ID` names this server in the AI-estate inventory.
+- **Audit trail — and it differs by transport, so read which one you run.**
+ - **Over HTTP:** AiSOC writes an `mcp:tool_call` row to the tenant's
+ append-only, hash-chained `audit_log` for **every** call including the
+ reads, before the tool runs, carrying the tool name, the argument *names*
+ (never the values), the decision and the calling key's prefix. A second
+ `mcp:tool_result` row carries the outcome and latency — a second row
+ rather than an update because those rows are immutable by trigger. Revoke
+ the key and the history survives the revocation.
+ - **Over stdio:** that path does not exist, and the old caveat still holds.
+ The API's `audit_middleware` records only mutating methods carrying a
+ valid JWT, so the read tools (`aisoc_list_*`, `aisoc_get_*`,
+ `aisoc_lake_query`) produce **no server-side audit row**, and what it does
+ record is an HTTP path rather than a tool name. Attribution then comes
+ only from this server's own telemetry, below.
+ - Either way, `AISOC_MCP_TELEMETRY_URL` collects this server's own
+ `mcp.tool_call` records into an AiSOC inbox token using the `ai-runtime`
+ template. Unset, nothing is emitted. `AISOC_MCP_AGENT_ID` names this
+ server in the AI-estate inventory. That is a self-report, which is a
+ weaker artefact than the audit row above and is not a substitute for it.
- **Outbound destinations** are your `AISOC_URL`, plus `AISOC_MCP_TELEMETRY_URL` when you configure one, plus the npm registry on `npx` cold-start if you launch that way.
## Troubleshooting