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
/**
* 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) {
// A fixed sentence, not the thrown message. The only error reachable
// here is this module's own size refusal or a JSON parse failure, and
// a parse failure's message quotes the offending input back to whoever
// sent it — which is both useless to them and an information-exposure
// finding (`js/stack-trace-exposure`). The bound is the actionable
// fact, so the bound is what is returned; the detail goes to stderr.
log.info(`rejected a request body: ${String(err instanceof Error ? err.message : err)}`);
rpcError(
res,
413,
`The request body could not be read. It must be JSON and at most ${options.maxBodyBytes} bytes.`,
);
return;
}
const gate: GateOptions = {
aisocUrl: cfg.aisocUrl,
bearer,
timeoutMs: cfg.timeoutMs,
userAgent: cfg.userAgent,
log,
};
// A per-request config carrying the caller's own credential.
//
// Written field by field rather than as a spread with an override. The
// spread form is correct today and becomes a credential fallback the day
// somebody reorders the literal, and the thing it would fall back to is
// the server operator's own key against somebody else's tenant. Listing
// the fields means the key can only ever be the one that arrived in this
// request; `scripts/check_mcp_over_http.py` refuses the spread too.
const requestCfg: ServerConfig = {
aisocUrl: cfg.aisocUrl,
apiKey: bearer.replace(/^Bearer\s+/i, ""),
timeoutMs: cfg.timeoutMs,
verbose: cfg.verbose,
userAgent: cfg.userAgent,
};
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());
});
}