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
/**
* AiSOCClient — typed HTTP client built on top of openapi-fetch.
*
* The client is structured around resource namespaces that mirror the REST API:
* client.alerts.* – alert management
* client.cases.* – case management
* client.detections.* – detection rule management
* client.connectors.* – connector management
* client.playbooks.* – playbook management
* client.apiKeys.* – API key management
* client.approvals.* – action approvals awaiting a human decision
* client.push.* – Web Push subscription management
* client.onCall.* – on-call rota
* client.liveActions.* – what this deployment can actually do to the estate
*
* The responder namespaces exist because a responder client — the PWA, the
* native app, or anything a user writes — needs approvals, push and on-call,
* and the hand-written client covered none of them. They were in
* docs/openapi.yaml the whole time, which is exactly why nobody noticed: the
* generated types were complete and the ergonomic surface was not.
*/
import type {
Alert,
AlertFilters,
ApiKey,
ApiKeyCreateRequest,
ApiKeyCreateResponse,
Approval,
ApprovalFilters,
Case,
CaseFilters,
Connector,
DetectionRule,
LiveActionDiscovery,
OnCallEntry,
Page,
PaginationParams,
Playbook,
PlaybookRun,
PushSubscriptionPayload,
} from "./types.js";
export interface AiSOCClientOptions {
/** Base URL of the AiSOC API, e.g. https://soc.example.com */
baseUrl: string;
/**
* Authentication token. Accepts either:
* - A JWT bearer token (from POST /auth/login)
* - A scoped API key (aisoc_…)
*/
token: string;
/** Additional headers merged into every request. */
headers?: Record<string, string>;
/** Fetch implementation — defaults to global fetch. */
fetch?: typeof globalThis.fetch;
}
// ─── Error class ─────────────────────────────────────────────────────────────
export class AiSOCError extends Error {
constructor(
public readonly status: number,
public readonly body: string,
) {
super(`AiSOC API error ${status}: ${body}`);
this.name = "AiSOCError";
}
}
// ─── Resource sub-clients ─────────────────────────────────────────────────────
class ResourceClient {
constructor(
protected readonly baseUrl: string,
protected readonly token: string,
protected readonly extraHeaders: Record<string, string> = {},
/**
* `AiSOCClientOptions.fetch` was documented as "Fetch implementation —
* defaults to global fetch" and then never threaded through: every
* request called the global directly. So a caller could pass one and
* silently not get it, which matters most in the two places it exists
* for — a test double, and a React Native runtime whose fetch is not the
* same object the module closed over.
*
* Left undefined rather than defaulted, and resolved per call, so that
* replacing the global after construction still works.
*/
protected readonly fetchImpl?: typeof globalThis.fetch,
) {}
protected async request<T>(
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
path: string,
body?: unknown,
query?: Record<string, unknown>,
): Promise<T> {
const url = new URL(path, this.baseUrl);
if (query) {
for (const [k, v] of Object.entries(query)) {
if (v !== undefined && v !== null) {
url.searchParams.set(k, String(v));
}
}
}
const doFetch = this.fetchImpl ?? globalThis.fetch;
const res = await doFetch(url.toString(), {
method,
headers: {
Authorization: `Bearer ${this.token}`,
"Content-Type": "application/json",
...this.extraHeaders,
},
body: body !== undefined ? JSON.stringify(body) : undefined,
});
if (!res.ok) {
throw new AiSOCError(res.status, await res.text());
}
if (res.status === 204) return undefined as unknown as T;
return res.json() as Promise<T>;
}
}
class AlertsClient extends ResourceClient {
async list(filters?: AlertFilters): Promise<Page<Alert>> {
return this.request<Page<Alert>>("GET", "/api/v1/alerts", undefined, filters as Record<string, unknown>);
}
async get(id: string): Promise<Alert> {
return this.request<Alert>("GET", `/api/v1/alerts/${id}`);
}
async update(id: string, data: Partial<Alert>): Promise<Alert> {
return this.request<Alert>("PATCH", `/api/v1/alerts/${id}`, data);
}
}
class CasesClient extends ResourceClient {
async list(filters?: CaseFilters): Promise<Page<Case>> {
return this.request<Page<Case>>("GET", "/api/v1/cases", undefined, filters as Record<string, unknown>);
}
async get(id: string): Promise<Case> {
return this.request<Case>("GET", `/api/v1/cases/${id}`);
}
async create(data: Partial<Case>): Promise<Case> {
return this.request<Case>("POST", "/api/v1/cases", data);
}
async update(id: string, data: Partial<Case>): Promise<Case> {
return this.request<Case>("PATCH", `/api/v1/cases/${id}`, data);
}
// There is no `delete`. The API serves no DELETE on a case — a case is
// closed by patching its status, and the method that used to be here
// called a route `services/api` has never declared.
}
class DetectionsClient extends ResourceClient {
// The route is `/detection/rules`, singular, and this client asked for
// `/detections` — so every method here answered 404 against a real
// deployment while its mocked test passed.
async list(params?: PaginationParams): Promise<Page<DetectionRule>> {
return this.request<Page<DetectionRule>>("GET", "/api/v1/detection/rules", undefined, params as Record<string, unknown>);
}
async get(id: string): Promise<DetectionRule> {
return this.request<DetectionRule>("GET", `/api/v1/detection/rules/${id}`);
}
}
class ConnectorsClient extends ResourceClient {
async list(params?: PaginationParams): Promise<Page<Connector>> {
return this.request<Page<Connector>>("GET", "/api/v1/connectors", undefined, params as Record<string, unknown>);
}
async get(id: string): Promise<Connector> {
return this.request<Connector>("GET", `/api/v1/connectors/${id}`);
}
}
class PlaybooksClient extends ResourceClient {
async list(params?: PaginationParams): Promise<Page<Playbook>> {
return this.request<Page<Playbook>>("GET", "/api/v1/playbooks", undefined, params as Record<string, unknown>);
}
async get(id: string): Promise<Playbook> {
return this.request<Playbook>("GET", `/api/v1/playbooks/${id}`);
}
async create(data: Partial<Playbook>): Promise<Playbook> {
return this.request<Playbook>("POST", "/api/v1/playbooks", data);
}
// PUT, not PATCH: `playbooks.py` declares `@router.put("/{playbook_id}")`
// and no patch route, so the previous verb returned 405.
async update(id: string, data: Partial<Playbook>): Promise<Playbook> {
return this.request<Playbook>("PUT", `/api/v1/playbooks/${id}`, data);
}
async delete(id: string): Promise<void> {
return this.request<void>("DELETE", `/api/v1/playbooks/${id}`);
}
async run(id: string, triggerData?: Record<string, unknown>): Promise<PlaybookRun> {
return this.request<PlaybookRun>("POST", `/api/v1/playbooks/${id}/run`, { trigger_data: triggerData });
}
async getRun(runId: string): Promise<PlaybookRun> {
return this.request<PlaybookRun>("GET", `/api/v1/playbooks/runs/${runId}`);
}
}
class ApiKeysClient extends ResourceClient {
async list(): Promise<Page<ApiKey>> {
return this.request<Page<ApiKey>>("GET", "/api/v1/api-keys");
}
async create(data: ApiKeyCreateRequest): Promise<ApiKeyCreateResponse> {
return this.request<ApiKeyCreateResponse>("POST", "/api/v1/api-keys", data);
}
async revoke(id: string): Promise<void> {
return this.request<void>("DELETE", `/api/v1/api-keys/${id}`);
}
}
// ─── Responder namespaces ────────────────────────────────────────────────────
class ApprovalsClient extends ResourceClient {
/** Pending by default, because that is the whole point of the queue. */
async list(filters?: ApprovalFilters): Promise<Page<Approval>> {
return this.request<Page<Approval>>("GET", "/api/v1/approvals", undefined, filters as Record<string, unknown>);
}
async get(id: string): Promise<Approval> {
return this.request<Approval>("GET", `/api/v1/approvals/${id}`);
}
/**
* Approve or deny.
*
* Deciding carries the action through to the execution service, so a
* non-2xx here can mean "your decision was recorded and the action was
* refused" rather than "nothing happened". The thrown `AiSOCError` body
* says which.
*/
async decide(id: string, decision: "approve" | "deny", comment?: string): Promise<Approval> {
return this.request<Approval>("POST", `/api/v1/approvals/${id}/decide`, { decision, comment });
}
}
class PushClient extends ResourceClient {
/** VAPID public key. Required before a browser can subscribe at all. */
async publicKey(): Promise<{ public_key: string }> {
return this.request<{ public_key: string }>("GET", "/api/v1/push/public-key");
}
async subscribe(subscription: PushSubscriptionPayload): Promise<{ status: string }> {
return this.request<{ status: string }>("POST", "/api/v1/push/subscribe", subscription);
}
async unsubscribe(endpoint: string): Promise<{ status: string }> {
return this.request<{ status: string }>("POST", "/api/v1/push/unsubscribe", { endpoint });
}
/** Send yourself one, to prove delivery works before relying on it. */
async test(): Promise<{ status: string }> {
return this.request<{ status: string }>("POST", "/api/v1/push/test");
}
}
class OnCallClient extends ResourceClient {
async list(): Promise<Page<OnCallEntry>> {
return this.request<Page<OnCallEntry>>("GET", "/api/v1/oncall");
}
async me(): Promise<OnCallEntry> {
return this.request<OnCallEntry>("GET", "/api/v1/oncall/me");
}
}
class LiveActionsClient extends ResourceClient {
/** What this deployment can do to the estate, and with which vendor. */
async discover(filters?: { vendor_id?: string; capability?: string }): Promise<LiveActionDiscovery> {
return this.request<LiveActionDiscovery>("GET", "/api/v1/live-actions", undefined, filters);
}
async vendorsFor(capability: string): Promise<string[]> {
return this.request<string[]>("GET", `/api/v1/live-actions/by-capability/${encodeURIComponent(capability)}`);
}
async capabilitiesFor(vendorId: string): Promise<string[]> {
return this.request<string[]>("GET", `/api/v1/live-actions/by-vendor/${encodeURIComponent(vendorId)}`);
}
/**
* Preview an action. There is deliberately no `dispatch` here: a live
* containment goes through the approval path so an approver is bound to
* it, and the API exposes no un-approved dispatch route to proxy.
*/
async dryRun(request: Record<string, unknown>): Promise<unknown> {
return this.request<unknown>("POST", "/api/v1/live-actions/dry-run", request);
}
}
// ─── Main client ─────────────────────────────────────────────────────────────
export class AiSOCClient {
/** Alert management — list, get, update alerts. */
readonly alerts: AlertsClient;
/** Case management — full CRUD. */
readonly cases: CasesClient;
/** Detection rule management. */
readonly detections: DetectionsClient;
/** Connector management. */
readonly connectors: ConnectorsClient;
/** Playbook management and execution. */
readonly playbooks: PlaybooksClient;
/** Scoped API key management. */
readonly apiKeys: ApiKeysClient;
/** Action approvals awaiting a human decision. */
readonly approvals: ApprovalsClient;
/** Web Push subscription management. */
readonly push: PushClient;
/** On-call rota. */
readonly onCall: OnCallClient;
/** The live-action registry: discovery and dry-run. */
readonly liveActions: LiveActionsClient;
constructor(opts: AiSOCClientOptions) {
const args: [string, string, Record<string, string>, (typeof globalThis.fetch) | undefined] = [
opts.baseUrl,
opts.token,
opts.headers ?? {},
opts.fetch,
];
this.alerts = new AlertsClient(...args);
this.cases = new CasesClient(...args);
this.detections = new DetectionsClient(...args);
this.connectors = new ConnectorsClient(...args);
this.playbooks = new PlaybooksClient(...args);
this.apiKeys = new ApiKeysClient(...args);
this.approvals = new ApprovalsClient(...args);
this.push = new PushClient(...args);
this.onCall = new OnCallClient(...args);
this.liveActions = new LiveActionsClient(...args);
}
/**
* Send an introspection query to the GraphQL endpoint.
* Useful for verifying connectivity and auth.
*/
async graphql<T = unknown>(
query: string,
variables?: Record<string, unknown>,
): Promise<{ data: T; errors?: Array<{ message: string }> }> {
const sub = new ResourceClient(
(this.alerts as unknown as { baseUrl: string }).baseUrl,
(this.alerts as unknown as { token: string }).token,
);
return sub["request"]("POST", "/graphql", { query, variables });
}
}