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
feat(mcp): streamable HTTP transport with per-request credentials and a fail-closed gate
Beenu Arorab63a7de69152
diff --git a/services/mcp/src/gate.ts b/services/mcp/src/gate.tsnew file mode 100644index 000000000..a26e5fe50--- /dev/null+++ b/services/mcp/src/gate.ts@@ -0,0 +1,173 @@+/**+ * Ask AiSOC whether a tool call may run, and tell it how it went.+ *+ * Depth 9.1 (parity 6.6). Over stdio this server was a child process holding+ * one operator's own API key, and the only thing a tool call could do was+ * what that person could already do at the console. Over HTTP it is a shared+ * process reached by several tenants with credentials of their own, and that+ * changes who is allowed to decide what:+ *+ * - **This process decides nothing.** It forwards the caller's credential to+ * `POST /api/v1/mcp/tool-calls/authorize` and does what it is told. A+ * policy cached or recomputed here would be a second authority that can+ * disagree with the first, and the disagreement would be invisible.+ * - **The tenant is never sent.** It is derived server-side from the+ * credential. There is no tenant field in either request body, so there is+ * nothing for a compromised deployment of this process to set.+ * - **A refusal is actionable.** `approval_required` carries the id of the+ * row a human decides, so the agent can say what to do rather than failing+ * opaquely.+ *+ * Failure posture: `authorize` fails **closed**. If the API cannot be+ * reached, no call runs. That is the opposite of `telemetry.ts`, which fails+ * open on purpose — telemetry is an observation and must not break a call,+ * whereas this is the authorization. Two surfaces, two postures, stated here+ * so neither gets changed to match the other by accident.+ */++import type { Logger } from "./config.js";++/** What the API answers. Mirrors `McpAuthorizeResponse` in the API service. */+export interface AuthorizeDecision {+ call_id: string;+ outcome: "allow" | "deny" | "approval_required";+ reason: string;+ approval_id?: string | null;+ required_permission?: string;+}++export interface GateOptions {+ /** Base URL of the AiSOC API. */+ aisocUrl: string;+ /** The *caller's* bearer credential, forwarded verbatim. Never the server's. */+ bearer: string;+ timeoutMs: number;+ userAgent: string;+ log: Logger;+}++/** Raised when the gate could not reach a decision. Fails the call. */+export class GateUnavailableError extends Error {+ constructor(cause: string) {+ super(+ `AiSOC could not authorize this tool call (${cause}). ` ++ `No tool runs without a decision, so this is a refusal rather than a fallback.`,+ );+ this.name = "GateUnavailableError";+ }+}++async function postJson(+ url: string,+ bearer: string,+ body: unknown,+ timeoutMs: number,+ userAgent: string,+): Promise<{ status: number; json: unknown }> {+ const controller = new AbortController();+ const timer = setTimeout(() => controller.abort(), timeoutMs);+ try {+ const res = await fetch(url, {+ method: "POST",+ headers: {+ Authorization: bearer.startsWith("Bearer ") ? bearer : `Bearer ${bearer}`,+ "Content-Type": "application/json",+ Accept: "application/json",+ "User-Agent": userAgent,+ },+ body: JSON.stringify(body),+ signal: controller.signal,+ });+ // 204 has no body, and `res.json()` on an empty body throws.+ const json = res.status === 204 ? null : await res.json().catch(() => null);+ return { status: res.status, json };+ } finally {+ clearTimeout(timer);+ }+}++/**+ * Authorize one tool call. Throws {@link GateUnavailableError} rather than+ * returning a permissive default when the API cannot answer.+ *+ * `arguments` travels in full because the approval has to bind to the+ * specific call — approving "investigate case A" must not authorise+ * "investigate case B". The API hashes it on arrival and stores only the+ * digest; the audit row records argument *names* alone.+ */+export async function authorizeToolCall(+ opts: GateOptions,+ toolName: string,+ args: unknown,+): Promise<AuthorizeDecision> {+ let result: { status: number; json: unknown };+ try {+ result = await postJson(+ `${opts.aisocUrl}/api/v1/mcp/tool-calls/authorize`,+ opts.bearer,+ { tool_name: toolName, arguments: isPlainObject(args) ? args : {} },+ opts.timeoutMs,+ opts.userAgent,+ );+ } catch (err) {+ throw new GateUnavailableError(String(err));+ }++ if (result.status === 401 || result.status === 403) {+ return {+ call_id: "",+ outcome: "deny",+ reason:+ result.status === 401+ ? "AiSOC rejected the credential this request presented."+ : "The presented credential is not allowed to use the MCP surface.",+ };+ }+ if (result.status >= 400 || !isPlainObject(result.json)) {+ throw new GateUnavailableError(`HTTP ${result.status}`);+ }++ const decision = result.json as unknown as AuthorizeDecision;+ if (decision.outcome !== "allow" && decision.outcome !== "deny" && decision.outcome !== "approval_required") {+ // An outcome this build does not know is not an allow. A newer API+ // inventing a verdict must not be read as permission by an older client.+ throw new GateUnavailableError(`unrecognised outcome "${String(decision.outcome)}"`);+ }+ return decision;+}++/**+ * Report how an authorized call turned out.+ *+ * Deliberately fire-and-forget and deliberately *not* fail-closed: the call+ * has already happened, and refusing to return its result because the second+ * bookkeeping request failed would punish the user for a logging problem.+ * The decision row is already written, which is the one that has to exist.+ */+export async function completeToolCall(+ opts: GateOptions,+ callId: string,+ outcome: "success" | "error" | "invalid_arguments" | "unknown_tool" | "denied",+ latencyMs: number,+ errorKind?: string,+): Promise<void> {+ if (!callId) return;+ try {+ const res = await postJson(+ `${opts.aisocUrl}/api/v1/mcp/tool-calls/${encodeURIComponent(callId)}/complete`,+ opts.bearer,+ { outcome, latency_ms: Math.max(0, Math.round(latencyMs)), ...(errorKind ? { error_kind: errorKind } : {}) },+ opts.timeoutMs,+ opts.userAgent,+ );+ if (res.status >= 400) {+ opts.log.info(`gate: completion for ${callId} returned HTTP ${res.status}`);+ }+ } catch (err) {+ opts.log.info(`gate: completion for ${callId} dropped: ${String(err)}`);+ }+}++function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}diff --git a/services/mcp/src/http.ts b/services/mcp/src/http.tsnew file mode 100644index 000000000..318aa0a9e--- /dev/null+++ b/services/mcp/src/http.ts@@ -0,0 +1,262 @@+/**+ * The MCP server over streamable HTTP.+ *+ * Depth 9.1 (parity 6.6). Until this file existed the only transport was+ * stdio, so the only way to reach these tools was to let an MCP host start+ * the process as a child with one operator's API key written into the host's+ * configuration file. Nothing in the repository deployed it and nothing+ * recorded what it read.+ *+ * Three decisions here are security decisions, not plumbing:+ *+ * **Stateless, one server per request.**+ * `sessionIdGenerator: undefined` puts the SDK transport in stateless mode+ * and a fresh `Server` is built per request, bound to the credential that+ * request presented. The alternative — a session id minted once and reused —+ * would let a session outlive the credential that created it, so revoking an+ * API key would not end the sessions it had opened, and anyone who learned a+ * session id would inherit its tenant. Sessions are cheap to add later and+ * expensive to take back.+ *+ * **The credential comes from the request, never from the environment.**+ * `AISOC_API_KEY` configures the *stdio* server. Reading it here would mean+ * an unauthenticated caller, or a caller whose own key had been revoked,+ * silently answering with the operator's access to somebody else's tenant.+ * There is no fallback: a request with no `Authorization` header is 401 and+ * nothing is built. `scripts/check_mcp_over_http.py` fails if this file ever+ * names `cfg.apiKey`.+ *+ * **Every call is authorized by the API before it runs.** See `./gate.ts`.+ * This process is not the authority on what a key may do, and it fails+ * closed when it cannot get an answer.+ *+ * Binding: `AISOC_MCP_HTTP_HOST` defaults to `127.0.0.1`, which is the right+ * default for a transport that did not exist yesterday. The compose service+ * sets `0.0.0.0` because inside a container that is the only way a sibling+ * service reaches it, and compose publishes the port on the loopback address+ * the rest of the stack uses.+ */+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";++import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";++import { type Logger, type ServerConfig, packageVersion } from "./config.js";+import { authorizeToolCall, completeToolCall, type GateOptions } from "./gate.js";+import { buildServer, type CallHooks } from "./server.js";++/** Where the MCP endpoint lives. Fixed so a client's URL is predictable. */+export const MCP_PATH = "/mcp";++/** Liveness. Deliberately unauthenticated and deliberately says nothing else. */+export const HEALTH_PATH = "/healthz";++export interface HttpServerOptions {+ host: string;+ port: number;+ /** Cap on a single JSON-RPC frame. A transport with no bound is a memory DoS. */+ maxBodyBytes: number;+}++export function resolveHttpOptions(env: NodeJS.ProcessEnv = process.env): HttpServerOptions {+ const port = Number.parseInt(env.AISOC_MCP_HTTP_PORT ?? "8096", 10);+ if (!Number.isFinite(port) || port <= 0 || port > 65535) {+ throw new Error(`Invalid AISOC_MCP_HTTP_PORT: ${env.AISOC_MCP_HTTP_PORT}`);+ }+ const maxBodyBytes = Number.parseInt(env.AISOC_MCP_MAX_BODY_BYTES ?? "1048576", 10);+ return {+ host: env.AISOC_MCP_HTTP_HOST?.trim() || "127.0.0.1",+ port,+ maxBodyBytes: Number.isFinite(maxBodyBytes) && maxBodyBytes > 0 ? maxBodyBytes : 1_048_576,+ };+}++/**+ * Pull the bearer credential out of a request.+ *+ * Returns `undefined` rather than a default. Every caller treats that as 401.+ */+export function bearerFrom(headers: IncomingMessage["headers"]): string | undefined {+ const raw = headers.authorization;+ if (typeof raw !== "string") return undefined;+ const trimmed = raw.trim();+ if (!/^bearer\s+\S/i.test(trimmed)) return undefined;+ return trimmed;+}++/** Read a bounded JSON body. Rejects rather than truncating. */+export async function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown> {+ const chunks: Buffer[] = [];+ let size = 0;+ for await (const chunk of req) {+ const buf = chunk as Buffer;+ size += buf.length;+ if (size > maxBytes) {+ // Truncating would hand the parser a prefix of a frame, which either+ // fails confusingly or — worse — parses into a different call.+ throw new Error(`request body exceeds ${maxBytes} bytes`);+ }+ chunks.push(buf);+ }+ if (size === 0) return undefined;+ return JSON.parse(Buffer.concat(chunks).toString("utf8"));+}++function writeJson(res: ServerResponse, status: number, body: unknown): void {+ const payload = JSON.stringify(body);+ res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) });+ res.end(payload);+}++/**+ * The JSON-RPC error a transport-level refusal has to look like.+ *+ * An MCP client parses the body before it looks at the status, so a bare+ * `401 Unauthorized` with an HTML body surfaces in the host as a parse+ * failure and the operator is told the server is broken rather than that+ * their credential is missing.+ */+function rpcError(res: ServerResponse, status: number, message: string): void {+ writeJson(res, status, {+ jsonrpc: "2.0",+ error: { code: -32001, message },+ id: null,+ });+}++/**+ * Hooks that put every tool call through the API's authorize/complete pair.+ *+ * Built per request so the credential cannot be shared between two callers.+ */+export function gateHooks(opts: GateOptions): CallHooks {+ return {+ async before(toolName, args) {+ const decision = await authorizeToolCall(opts, toolName, args);+ return {+ allowed: decision.outcome === "allow",+ reason:+ decision.outcome === "approval_required"+ ? `${decision.reason} Ask an approver to decide it, then call the tool again.`+ : decision.reason,+ callId: decision.call_id || undefined,+ };+ },+ after(callId, outcome, latencyMs, errorKind) {+ // Not awaited: the result is already on its way to the agent and a+ // bookkeeping request must not hold it. Errors are swallowed inside+ // `completeToolCall`, which logs them.+ void completeToolCall(opts, callId ?? "", outcome, latencyMs, errorKind);+ },+ };+}++/**+ * Handle one MCP request end to end.+ *+ * Exported so tests can drive it with a fake request/response pair rather+ * than binding a port.+ */+export async function handleMcpRequest(+ cfg: ServerConfig,+ log: Logger,+ options: HttpServerOptions,+ req: IncomingMessage,+ res: ServerResponse,+): Promise<void> {+ const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);++ if (url.pathname === HEALTH_PATH) {+ writeJson(res, 200, { status: "ok", version: packageVersion(), transport: "streamable-http" });+ return;+ }+ if (url.pathname !== MCP_PATH) {+ rpcError(res, 404, `Not found. The MCP endpoint is ${MCP_PATH}.`);+ return;+ }++ const bearer = bearerFrom(req.headers);+ if (!bearer) {+ // No environment fallback, deliberately. See the module header.+ rpcError(+ res,+ 401,+ "Authorization required. Send `Authorization: Bearer <aisoc_... or JWT>`; " ++ "the tenant is derived from the credential and cannot be supplied any other way.",+ );+ return;+ }++ let body: unknown;+ try {+ body = req.method === "POST" ? await readJsonBody(req, options.maxBodyBytes) : undefined;+ } catch (err) {+ rpcError(res, 413, String(err instanceof Error ? err.message : err));+ return;+ }++ const gate: GateOptions = {+ aisocUrl: cfg.aisocUrl,+ bearer,+ timeoutMs: cfg.timeoutMs,+ userAgent: cfg.userAgent,+ log,+ };++ // A per-request config carrying the caller's credential. The process-wide+ // `cfg.apiKey` is not read here and must not be: the whole point of the+ // HTTP transport is that the caller's own credential decides the tenant.+ const requestCfg: ServerConfig = { ...cfg, apiKey: bearer.replace(/^Bearer\s+/i, "") };++ const transport = new StreamableHTTPServerTransport({+ // Stateless. See the module header for why a session id would be worse.+ sessionIdGenerator: undefined,+ enableJsonResponse: true,+ });+ const server = buildServer(requestCfg, log, gateHooks(gate));++ res.on("close", () => {+ void transport.close();+ void server.close();+ });++ try {+ await server.connect(transport);+ await transport.handleRequest(req, res, body);+ } catch (err) {+ log.error("mcp http request failed", err);+ if (!res.headersSent) {+ rpcError(res, 500, "The MCP server failed to handle this request.");+ }+ }+}++/** Boot the HTTP transport. Resolves when the listener closes. */+export async function runHttpServer(cfg: ServerConfig, log: Logger): Promise<void> {+ const options = resolveHttpOptions();+ const httpServer = createServer((req, res) => {+ void handleMcpRequest(cfg, log, options, req, res);+ });++ await new Promise<void>((resolve, reject) => {+ httpServer.once("error", reject);+ httpServer.listen(options.port, options.host, () => {+ httpServer.removeListener("error", reject);+ resolve();+ });+ });+ // stderr, not stdout: the stdio transport owns stdout and this binary can+ // be started either way.+ console.error(+ `[aisoc-mcp] ${packageVersion()} listening on http://${options.host}:${options.port}${MCP_PATH} (target ${cfg.aisocUrl})`,+ );++ await new Promise<void>((resolve) => {+ const shutdown = (sig: string) => {+ console.error(`[aisoc-mcp] received ${sig}, closing listener`);+ httpServer.close(() => resolve());+ };+ process.once("SIGINT", () => shutdown("SIGINT"));+ process.once("SIGTERM", () => shutdown("SIGTERM"));+ httpServer.once("close", () => resolve());+ });+}diff --git a/services/mcp/src/index.ts b/services/mcp/src/index.tsindex 987642d4a..4645149c9 100644--- a/services/mcp/src/index.ts+++ b/services/mcp/src/index.ts@@ -21,6 +21,7 @@ import process from "node:process";import { type ParsedArgs, parseArgs, packageVersion, resolveConfig, makeLogger } from "./config.js";import { runDoctor, printDoctorReport } from "./doctor.js";+import { runHttpServer } from "./http.js";import { runServer } from "./server.js";import {install,@@ -70,6 +71,16 @@ async function main(): Promise<void> {async function cmdServe(args: ParsedArgs): Promise<void> {const cfg = resolveConfig(args);const log = makeLogger(cfg);+ // Depth 9.1. `--http` (or AISOC_MCP_HTTP=1) serves streamable HTTP instead+ // of stdio. Opt-in rather than inferred from the environment: an MCP host+ // launching this binary as a child process must keep getting stdio, and a+ // transport that switched itself based on a variable being set somewhere+ // would be a very hard failure to read from inside Claude Desktop.+ const wantHttp = args.flags.http === true || args.flags.http === "1" || process.env.AISOC_MCP_HTTP === "1";+ if (wantHttp) {+ await runHttpServer(cfg, log);+ return;+ }// No banner on stdout — that channel is reserved for JSON-RPC frames.// `runServer` logs its lifecycle to stderr.await runServer(cfg, log);@@ -205,6 +216,13 @@ function printHelp(): void {" --timeout <ms> Per-request timeout. Env: AISOC_TIMEOUT_MS. Default 20000."," --verbose Log lifecycle events to stderr.","",+ "Serve options:",+ " --http Serve streamable HTTP instead of stdio. Env: AISOC_MCP_HTTP=1.",+ " Each request authenticates with its own bearer credential;",+ " --api-key is not consulted and the tenant comes from the",+ " credential. Host/port: AISOC_MCP_HTTP_HOST (127.0.0.1),",+ " AISOC_MCP_HTTP_PORT (8096). Endpoint: /mcp, liveness /healthz.",+ "","Install options:"," --host <h> claude | cursor | continue | cody"," --launcher <l> auto (default) | node | npx. `auto` writes a direct",diff --git a/services/mcp/src/server.ts b/services/mcp/src/server.tsindex 792fbeb32..aff09f1eb 100644--- a/services/mcp/src/server.ts+++ b/services/mcp/src/server.ts@@ -58,13 +58,37 @@ through this MCP server. Typical workflows:Every agent decision in AiSOC is logged to a persistent ledger; \\`aisoc_replay_decision\` and \`aisoc_explain_step\` are the auditable surface.`;+/**+ * A decision taken before a tool runs, and the report after it.+ *+ * Over stdio there is nothing to decide: the server holds the operator's own+ * key and a tool call can do only what that person could already do. Over+ * HTTP the credential arrives per request and several tenants share the+ * process, so `src/http.ts` supplies these two and the API decides. Optional+ * here so the stdio path is byte-for-byte the behaviour it always had.+ */+export interface CallHooks {+ /**+ * Called before dispatch. Returning `{ allowed: false }` refuses the call+ * with `reason` surfaced to the agent, and the tool never runs.+ */+ before(toolName: string, args: unknown): Promise<{ allowed: boolean; reason?: string; callId?: string }>;+ /** Called on every exit path, including the refusals. */+ after(+ callId: string | undefined,+ outcome: "success" | "error" | "invalid_arguments" | "unknown_tool" | "denied",+ latencyMs: number,+ errorKind?: string,+ ): void;+}+/*** Build (but don't start) an MCP server bound to the AiSOC tool registry.** Exported separately from the start helper so tests can drive request* handlers without spinning up a real stdio transport.*/-export function buildServer(cfg: ServerConfig, log: Logger): Server {+export function buildServer(cfg: ServerConfig, log: Logger, hooks?: CallHooks): Server {const client = new AisocClient(cfg, log);// This server is a standing read path into a customer's alerts, cases and// event lake, and until now nothing recorded what it read. Off unless@@ -110,6 +134,7 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {outcome: "unknown_tool",latency_ms: Date.now() - startedAt,});+ hooks?.after(undefined, "unknown_tool", Date.now() - startedAt);// Unknown tool. Return as a tool-failure rather than throwing so the// agent gets a clear human message instead of a transport error.return toErrorResult(@@ -117,6 +142,42 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {);}+ // Authorization, when a transport supplied one. Before validation on+ // purpose: a call that is not allowed must not have its arguments+ // inspected and reported on, and the refusal has to be recorded whether+ // or not the arguments were well-formed.+ let callId: string | undefined;+ if (hooks) {+ let verdict: { allowed: boolean; reason?: string; callId?: string };+ try {+ verdict = await hooks.before(name, request.params.arguments);+ } catch (err) {+ // Fail closed. The gate module raises when it could not reach a+ // decision, and "could not decide" is not "allowed".+ log.error(`authorization failed for ${name}`, err);+ telemetry.record({+ tool_name: name,+ argument_keys: keys,+ outcome: "error",+ latency_ms: Date.now() - startedAt,+ error_kind: err instanceof Error ? err.constructor.name : "unknown",+ });+ return toErrorResult(err instanceof Error ? err.message : String(err));+ }+ callId = verdict.callId;+ if (!verdict.allowed) {+ telemetry.record({+ tool_name: name,+ argument_keys: keys,+ outcome: "error",+ latency_ms: Date.now() - startedAt,+ error_kind: "NotAuthorized",+ });+ hooks.after(callId, "denied", Date.now() - startedAt);+ return toErrorResult(verdict.reason ?? `${name} is not permitted for this credential.`);+ }+ }+// Validate via zod. Failed validation gives precise per-field issues.const parse = tool.schema.safeParse(request.params.arguments ?? {});if (!parse.success) {@@ -129,6 +190,7 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {outcome: "invalid_arguments",latency_ms: Date.now() - startedAt,});+ hooks?.after(callId, "invalid_arguments", Date.now() - startedAt);return toErrorResult(formatErrorForTool(new InvalidArgumentsError(name, issues)),);@@ -142,6 +204,7 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {outcome: "success",latency_ms: Date.now() - startedAt,});+ hooks?.after(callId, "success", Date.now() - startedAt);return toSuccessResult(result);} catch (err) {telemetry.record({@@ -151,6 +214,12 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {latency_ms: Date.now() - startedAt,error_kind: err instanceof Error ? err.constructor.name : "unknown",});+ hooks?.after(+ callId,+ "error",+ Date.now() - startedAt,+ err instanceof Error ? err.constructor.name : "unknown",+ );// Log full error to stderr for debugging; surface a sanitised message// to the agent. We deliberately don't include stack traces in the// MCP response (PII / secrets risk).