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): 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.pyindex 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 / CATALOGUEpath.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.pyindex 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.pyindex 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.pyindex 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[sreturn 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.sqlindex 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.pyindex 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.asyncioasync 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.asyncioasync 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.asyncioasync 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.mdindex 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 doctorThe 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