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
/**
* AiSOC API Client
*
* Typed HTTP client that talks to the Core API service and a few sibling
* microservices (agents, fusion, threatintel, enrichment).
*
* Conventions:
* - Every public function returns a typed `Promise<T>`. Callers should
* wrap with SWR / React Query for caching + retries.
* - Errors are thrown as native `Error` with the HTTP status + body so
* UI components can catch and render `<ErrorState error={e} />`.
* - Base URLs default to "" (same-origin) so the browser hits whatever
* host it loaded the page from. Next.js `rewrites()` then proxies the
* `/api/v1/*`, `/api/v1/contextual/*`, `/ws/*` and `/sse` paths to the
* right downstream service. This makes the bundle host-agnostic — the
* same image works on `localhost:3000`, behind nginx, or behind a
* Cloudflare Tunnel pointed at `tryaisoc.com`.
* - `NEXT_PUBLIC_*_URL` env vars are still honoured if you want to bypass
* the proxy (e.g. point the bundle at a different API origin during
* local debugging).
*/
/**
* Returns `url` unchanged when running server-side or when `url` is already
* same-origin. In the browser, if `url` is cross-origin relative to the page,
* we fall back to `''` (same-origin) so Next.js rewrites can proxy the request.
*
* This prevents a misconfigured NEXT_PUBLIC_*_URL (e.g. pointing directly at
* api.tryaisoc.com) from bypassing the proxy and triggering CORS blocks.
*/
function safeBase(url: string): string {
if (!url) return "";
if (typeof window === "undefined") return url; // SSR — let Next.js rewrites decide
try {
const envOrigin = new URL(url).origin;
if (envOrigin !== window.location.origin) {
// Cross-origin base detected. Fall back to same-origin so the Next.js
// rewrite proxy can handle the request without CORS issues.
return "";
}
} catch {
// Relative URL or invalid — use as-is (same-origin path is fine)
}
return url;
}
export const API_BASE = safeBase(process.env.NEXT_PUBLIC_API_URL || "");
const AGENTS_BASE = safeBase(process.env.NEXT_PUBLIC_AGENTS_URL || "");
const ACTIONS_BASE = safeBase(process.env.NEXT_PUBLIC_ACTIONS_URL || "");
const FUSION_BASE = safeBase(process.env.NEXT_PUBLIC_FUSION_URL || "");
const THREATINTEL_BASE = safeBase(process.env.NEXT_PUBLIC_THREATINTEL_URL || "");
const ENRICHMENT_BASE = safeBase(process.env.NEXT_PUBLIC_ENRICHMENT_URL || "");
const REALTIME_BASE = safeBase(process.env.NEXT_PUBLIC_REALTIME_URL || "");
const WS_BASE = process.env.NEXT_PUBLIC_WS_URL || ""; // WS handled separately by wsOrigin()
/**
* Compute the WebSocket origin at call time.
*
* If the bundle was built with `NEXT_PUBLIC_WS_URL` set, use that verbatim.
* Otherwise, derive `wss://<current-host>` from `window.location` so the WS
* connection lands on the same host the page was loaded from (the Next.js
* rewrites then proxy `/ws/*` to the realtime gateway).
*
* SSR fallback: returns `''` so the resulting URL is path-only; nothing on
* the server actually opens WebSockets.
*/
function wsOrigin(): string {
if (WS_BASE) return WS_BASE;
if (typeof window !== "undefined") {
const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
return `${proto}//${window.location.host}`;
}
return "";
}
const TENANT_ID = process.env.NEXT_PUBLIC_TENANT_ID || "00000000-0000-0000-0000-000000000001";
export const API_BASES = {
api: API_BASE,
agents: AGENTS_BASE,
actions: ACTIONS_BASE,
fusion: FUSION_BASE,
threatintel: THREATINTEL_BASE,
enrichment: ENRICHMENT_BASE,
realtime: REALTIME_BASE,
ws: WS_BASE,
} as const;
export const DEFAULT_TENANT_ID = TENANT_ID;
// ─── Active tenant (W5 — tenant switcher) ───────────────────────────────────
//
// The console used to ship every request with the env-derived TENANT_ID. With
// the tenant switcher, MSSP parents and analysts who carry credentials for
// multiple tenants need a way to flip the `X-Tenant-Id` header at runtime.
// We expose three building blocks the TenantContext + switcher consume:
//
// - ACTIVE_TENANT_KEY: localStorage key for the override
// - getActiveTenantId(): read precedence — override → cached user → env
// - setActiveTenantId(): persist (or clear) the override
//
// `request()` calls `getActiveTenantId()` on every call so a tenant flip
// applies to the very next fetch without needing a page reload. The env var
// `NEXT_PUBLIC_TENANT_ID` remains the floor so demo and SSR contexts keep
// working when no user is logged in.
export const ACTIVE_TENANT_KEY = "aisoc.activeTenantId";
export function getActiveTenantId(): string {
if (typeof window === "undefined") return TENANT_ID;
try {
const override = window.localStorage.getItem(ACTIVE_TENANT_KEY);
if (override) return override;
const raw = window.localStorage.getItem(AUTH_USER_KEY);
if (raw) {
const user = JSON.parse(raw) as { tenant_id?: string };
if (user.tenant_id) return user.tenant_id;
}
} catch {
/* localStorage unavailable / malformed payload — fall through */
}
return TENANT_ID;
}
export function setActiveTenantId(tenantId: string | null): void {
if (typeof window === "undefined") return;
try {
if (tenantId) {
window.localStorage.setItem(ACTIVE_TENANT_KEY, tenantId);
} else {
window.localStorage.removeItem(ACTIVE_TENANT_KEY);
}
} catch {
/* private-mode quota errors — surface choice is in-memory only */
}
}
interface FetchOptions extends RequestInit {
params?: Record<string, string | number | boolean | undefined>;
baseUrl?: string;
}
export class ApiError extends Error {
status: number;
body: string;
constructor(message: string, status: number, body: string) {
super(message);
this.name = "ApiError";
this.status = status;
this.body = body;
}
}
/**
* The headers every console call to an AiSOC API must carry.
*
* Exported because not every call can go through {@link apiRequest}: the
* NDJSON and SSE endpoints need the raw `Response` so the caller can read
* `response.body`. Those five call sites used to build their own header
* object, and every one of them sent `X-Tenant-Id` and no token — which
* reads like an identity and is not one. The API authenticates a bearer
* token; a tenant header is a caller-supplied claim.
*
* `X-Tenant-Id` resolves at call time so the tenant switcher applies to the
* very next request without a page reload.
*/
export function apiHeaders(extra?: HeadersInit): Record<string, string> {
const headers: Record<string, string> = {
"Content-Type": "application/json",
"X-Tenant-Id": getActiveTenantId(),
...(extra as Record<string, string> | undefined),
};
if (typeof window !== "undefined") {
try {
if (!headers.Authorization && !headers.authorization) {
const token = window.localStorage.getItem(AUTH_TOKEN_KEY);
if (token) headers.Authorization = `Bearer ${token}`;
}
} catch {
/* localStorage unavailable; ignore */
}
}
return headers;
}
/**
* Whether a JWT's `exp` has passed. True when it cannot be read.
*
* Deliberately does not verify the signature: the browser cannot, and
* this is a usability check rather than a security one. The API verifies
* for real, and a forged token simply 401s there.
*/
export function isTokenExpired(token: string, nowSeconds?: number): boolean {
const parts = token.split(".");
if (parts.length !== 3) return true;
try {
const payload = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/"))) as {
exp?: number;
};
if (typeof payload.exp !== "number") return false;
// A small skew, so a token that expires mid-request does not bounce
// the user out of a page that was working a second ago.
const now = nowSeconds ?? Math.floor(Date.now() / 1000);
return payload.exp <= now - 5;
} catch {
return true;
}
}
/**
* Routes that must not trigger the 401 self-heal.
*
* Signing in is where a 401 means "wrong password", not "your session
* died" — redirecting there would replace the form's error message with a
* reload of the same form.
*
* `/auth/register` was listed here for one commit and the console
* route-contract gate rejected it: the API serves `login`, `refresh`,
* `me` and `me/preferences`, and nothing else under `/auth`. An exemption
* for a route that does not exist is dead weight that reads like a
* promise.
*/
const AUTH_EXEMPT_PATHS = ["/api/v1/auth/login", "/api/v1/auth/refresh"];
/**
* Clear a dead session and send the user to sign in again.
*
* Called on a 401 from any route that is not itself part of signing in.
* Without this a user whose token expired mid-session saw every panel
* fail with no explanation and no way to recover.
*/
function handleUnauthorized(path: string): void {
if (typeof window === "undefined") return;
if (AUTH_EXEMPT_PATHS.some((exempt) => path.startsWith(exempt))) return;
// Already on the sign-in page: clearing is right, navigating would loop.
const onLogin = window.location.pathname.startsWith("/login");
try {
window.localStorage.removeItem(AUTH_TOKEN_KEY);
window.localStorage.removeItem(AUTH_REFRESH_KEY);
window.localStorage.removeItem(AUTH_USER_KEY);
} catch {
/* localStorage unavailable; the redirect below still helps */
}
if (!onLogin) {
const next = encodeURIComponent(window.location.pathname + window.location.search);
window.location.assign(`/login?next=${next}`);
}
}
async function request<T>(path: string, options: FetchOptions = {}): Promise<T> {
const { params, baseUrl, ...fetchOptions } = options;
let url = `${baseUrl ?? API_BASE}${path}`;
if (params) {
const searchParams = new URLSearchParams();
Object.entries(params).forEach(([key, value]) => {
if (value !== undefined && value !== null && value !== "") {
searchParams.set(key, String(value));
}
});
const qs = searchParams.toString();
if (qs) url += `?${qs}`;
}
const headers = apiHeaders(fetchOptions.headers);
let response: Response;
try {
response = await fetch(url, {
...fetchOptions,
headers,
cache: "no-store",
});
} catch (err) {
throw new ApiError(`Network error talking to ${url}: ${(err as Error).message}`, 0, "");
}
if (!response.ok) {
const errorText = await response.text().catch(() => "");
if (response.status === 401) {
// Self-heal rather than leaving the user on a page where every
// panel fails silently and nothing offers a way back.
handleUnauthorized(path);
}
throw new ApiError(
`API ${response.status} ${response.statusText} — ${path}`,
response.status,
errorText
);
}
if (response.status === 204) return {} as T;
// Some endpoints (the agent stream, NDJSON) might not be JSON. Callers that
// need streams should use fetch() with apiHeaders(). Here we assume JSON.
return (await response.json()) as T;
}
/**
* The credentialed JSON client, for calls with no typed wrapper yet.
*
* Sixty-one console call sites reached the API with no `Authorization`
* header, forty-five of them through a bare `fetch(url)`. They worked only
* because the API resolved a credential-free request to a demo administrator
* in a development-class environment. Prefer a typed namespace below when one
* covers the route; reach for this when none does, rather than for `fetch`.
*
* `scripts/check_console_auth_headers.py` keeps the class closed.
*/
export async function apiRequest<T>(path: string, options: FetchOptions = {}): Promise<T> {
return request<T>(path, options);
}
/**
* SWR fetcher that carries a credential.
*
* SWR calls a fetcher as `f(key)`, so a fetcher has nowhere to put options
* and every single-argument fetcher in this console was anonymous by
* construction. This one routes through {@link request}, so it also throws
* {@link ApiError} with the status intact, which `describeApiFailure` needs
* to tell a console bug from an outage.
*/
export async function authedFetcher<T>(url: string): Promise<T> {
return request<T>(url);
}
/**
* A credentialed `fetch` that returns the raw `Response`.
*
* For the endpoints whose body is not JSON: NDJSON streams, SSE, PDF and
* Markdown downloads. Identical to `fetch` except that the credential and
* tenant headers are not optional.
*/
export async function apiFetch(path: string, options: FetchOptions = {}): Promise<Response> {
const { params, baseUrl, ...fetchOptions } = options;
let url = `${baseUrl ?? API_BASE}${path}`;
if (params) {
const searchParams = new URLSearchParams();
Object.entries(params).forEach(([key, value]) => {
if (value !== undefined && value !== null && value !== "") {
searchParams.set(key, String(value));
}
});
const qs = searchParams.toString();
if (qs) url += `?${qs}`;
}
return fetch(url, {
...fetchOptions,
headers: apiHeaders(fetchOptions.headers),
cache: "no-store",
});
}
// ─── Onboarding ──────────────────────────────────────────────────────────────
export interface SetupStep {
key: string;
label: string;
done: boolean;
why: string;
href: string | null;
detail: string | null;
}
export interface OnboardingStatus {
first_run: boolean;
steps: SetupStep[];
connectors: number;
alerts: number;
sample_data_loaded: boolean;
}
export interface SampleDataResult {
accepted: number;
rejected: number;
scenarios: { key: string; title: string; severity: string; why: string }[];
note: string;
}
/**
* What a tenant still has to set up, and the one button that gives an
* evaluator something to look at.
*
* `first_run` is derived from the tenant's own data server-side rather
* than from a stored flag, so it stays true if somebody connects a source
* through the API or deletes their last one.
*/
export const onboardingApi = {
status: () => request<OnboardingStatus>("/api/v1/onboarding/status"),
loadSampleData: () =>
request<SampleDataResult>("/api/v1/onboarding/sample-data", { method: "POST" }),
};
// ─── Auth ────────────────────────────────────────────────────────────────────
export const AUTH_TOKEN_KEY = "aisoc.responder.accessToken";
export const AUTH_REFRESH_KEY = "aisoc.responder.refreshToken";
export const AUTH_USER_KEY = "aisoc.responder.user";
export interface AuthUser {
id: string;
email: string;
username?: string | null;
role: string;
tenant_id: string;
is_active?: boolean;
preferences?: Record<string, unknown>;
}
export interface TokenResponse {
access_token: string;
refresh_token: string;
token_type: string;
expires_in: number;
}
export interface LoginResult extends TokenResponse {
user: AuthUser;
}
/**
* What `POST /auth/login` answers when the password was right and a second
* factor is outstanding (HTTP 202). Two distinct cases, and conflating them
* sends the user to the wrong screen: `mfa_required` means "type a code",
* `mfa_enrollment_required` means "your tenant now requires a factor you
* have never set up".
*/
export interface MfaChallenge {
mfa_token: string;
mfa_required?: boolean;
mfa_enrollment_required?: boolean;
methods?: string[];
}
export function isMfaChallenge(result: LoginResult | MfaChallenge): result is MfaChallenge {
return "mfa_token" in result && !("user" in result);
}
function persistAuth(tokens: TokenResponse, user: AuthUser): void {
if (typeof window === "undefined") return;
try {
window.localStorage.setItem(AUTH_TOKEN_KEY, tokens.access_token);
if (tokens.refresh_token) {
window.localStorage.setItem(AUTH_REFRESH_KEY, tokens.refresh_token);
}
window.localStorage.setItem(AUTH_USER_KEY, JSON.stringify(user));
} catch {
/* localStorage unavailable; ignore */
}
}
export const authApi = {
/**
* Public SSO availability for the login screen: whether SSO is offered,
* under what label, and whether password sign-in remains open. Reveals
* no provider internals; a failure reads as "no SSO" rather than an
* error state, so a status outage never blocks the password form.
*/
ssoStatus: async (): Promise<{
sso_enabled: boolean;
provider: string;
login_label: string;
local_login_enabled: boolean;
}> => {
try {
return await request("/api/v1/auth/sso/status");
} catch {
return {
sso_enabled: false,
provider: "oidc",
login_label: "Continue with SSO",
local_login_enabled: true,
};
}
},
/**
* Email + password login against ``POST /api/v1/auth/login``.
*
* The backend returns access + refresh tokens only, so we follow up with
* ``GET /api/v1/auth/me`` to fetch the user record. On success, persist
* everything under the same localStorage keys the responder PWA uses
* (``aisoc.responder.accessToken`` etc.) so the existing ``request()``
* helper attaches the JWT automatically and a single login covers desktop
* + mobile.
*/
async login(email: string, password: string): Promise<LoginResult | MfaChallenge> {
const tokens = await request<TokenResponse & Partial<MfaChallenge>>("/api/v1/auth/login", {
method: "POST",
body: JSON.stringify({ email, password }),
});
// HTTP 202: the password was accepted and no session was issued. The
// caller has to run the second factor; storing anything here would
// persist a token that does not exist.
if (!tokens.access_token && tokens.mfa_token) {
return {
mfa_token: tokens.mfa_token,
mfa_required: tokens.mfa_required,
mfa_enrollment_required: tokens.mfa_enrollment_required,
methods: tokens.methods,
};
}
// Stash the access token now so the `me` request flows through the
// standard `Authorization: Bearer …` path in `request()`.
if (typeof window !== "undefined") {
try {
window.localStorage.setItem(AUTH_TOKEN_KEY, tokens.access_token);
} catch {
/* ignore */
}
}
const user = await request<AuthUser>("/api/v1/auth/me");
persistAuth(tokens, user);
return { ...tokens, user };
},
logout(): void {
if (typeof window === "undefined") return;
try {
window.localStorage.removeItem(AUTH_TOKEN_KEY);
window.localStorage.removeItem(AUTH_REFRESH_KEY);
window.localStorage.removeItem(AUTH_USER_KEY);
} catch {
/* ignore */
}
},
currentUser(): AuthUser | null {
if (typeof window === "undefined") return null;
try {
const raw = window.localStorage.getItem(AUTH_USER_KEY);
return raw ? (JSON.parse(raw) as AuthUser) : null;
} catch {
return null;
}
},
/**
* Whether there is a session that can still make a request.
*
* This used to answer "is a token stored", which is a different
* question and produced an inescapable lockout: `/login` saw a stored
* token, redirected to `/dashboard`, every call there 401'd, and
* nothing sent the user back. The only way out was clearing browser
* storage, which is not a thing to ask of an operator.
*
* An unreadable or unparseable token counts as **not** authenticated:
* the pessimistic answer costs a sign-in, the optimistic one costs the
* lockout.
*/
isAuthenticated(): boolean {
if (typeof window === "undefined") return false;
try {
const token = window.localStorage.getItem(AUTH_TOKEN_KEY);
if (!token) return false;
return !isTokenExpired(token);
} catch {
return false;
}
},
/**
* Complete an SSO handoff that the IdP redirected back into the URL
* fragment (`#access_token=...&refresh_token=...`). Browsers never send
* fragments to servers, so the tokens appear in no access log or Referer
* header; this consumes them the moment the login screen mounts, verifies
* the access token against `/auth/me`, persists the session exactly like
* a password login would, and scrubs the fragment from history so the
* tokens do not linger in the address bar or browser session history.
*/
async completeSsoHandoff(): Promise<boolean> {
if (typeof window === "undefined") return false;
try {
const hash = window.location.hash;
if (!hash.includes("access_token=")) return false;
const params = new URLSearchParams(hash.replace(/^#/, ""));
const accessToken = params.get("access_token");
if (!accessToken) return false;
const refreshToken = params.get("refresh_token") || "";
window.history.replaceState(null, "", window.location.pathname + window.location.search);
const res = await fetch(`${API_BASE}/api/v1/auth/me`, {
headers: { Authorization: `Bearer ${accessToken}` },
});
if (!res.ok) return false;
const user = await res.json();
persistAuth(
{
access_token: accessToken,
refresh_token: refreshToken,
token_type: "bearer",
expires_in: 0,
},
user
);
return true;
} catch {
return false;
}
},
/**
* Finish a sign-in that `POST /auth/login` answered with 202.
*
* Takes a TOTP code or a recovery code — the API decides which by trying
* the authenticator first, so the user types whichever they have without
* telling the console which it is.
*/
async completeMfa(mfaToken: string, code: string): Promise<LoginResult> {
const tokens = await request<TokenResponse>("/api/v1/auth/mfa/verify", {
method: "POST",
body: JSON.stringify({ mfa_token: mfaToken, code }),
});
if (typeof window !== "undefined") {
try {
window.localStorage.setItem(AUTH_TOKEN_KEY, tokens.access_token);
} catch {
/* ignore */
}
}
const user = await request<AuthUser>("/api/v1/auth/me");
persistAuth(tokens, user);
return { ...tokens, user };
},
/**
* Adopt a session handed back by a non-login endpoint.
*
* `POST /auth/mfa/enroll/confirm` returns a token pair when the
* enrolment completed from a sign-in challenge, so the user is not made
* to authenticate a second time with a code they just proved.
*/
async adoptSession(accessToken: string, refreshToken: string): Promise<AuthUser> {
if (typeof window !== "undefined") {
try {
window.localStorage.setItem(AUTH_TOKEN_KEY, accessToken);
} catch {
/* ignore */
}
}
const user = await request<AuthUser>("/api/v1/auth/me");
persistAuth(
{
access_token: accessToken,
refresh_token: refreshToken,
token_type: "bearer",
expires_in: 0,
},
user
);
return user;
},
/** Merge user preferences on the server (theme, layout, etc.). */
async updateUserPreferences(preferences: Record<string, unknown>): Promise<AuthUser> {
const response = await fetch(`${API_BASE}/api/v1/auth/me/preferences`, {
method: "PATCH",
headers: apiHeaders(),
body: JSON.stringify({ preferences }),
});
if (!response.ok) throw new Error("Failed to update preferences");
const user = (await response.json()) as AuthUser;
// Keep locally-cached user in sync
try {
window.localStorage.setItem(AUTH_USER_KEY, JSON.stringify(user));
} catch {
/* ignore */
}
return user;
},
};
// ─── Multi-factor authentication ─────────────────────────────────────────────
//
// Every call takes an optional `mfaToken`. It is how a user whose tenant
// has just started requiring a second factor enrols: they hold a correct
// password and no session, so there is no bearer credential to send and
// the challenge stands in for one. With a session, omit it.
export interface MfaStatus {
enrolled: boolean;
tenant_requires_totp: boolean;
recovery_codes_remaining: number;
/** Which factor, not just whether there is one: a holder of only a
* security key must not be offered "enter the code from your app". */
has_totp: boolean;
has_webauthn: boolean;
/** Roles the tenant enforces, and whether the caller's own is one. */
require_for_roles: string[];
required_for_me: boolean;
}
export interface MfaEnrollment {
secret: string;
otpauth_uri: string;
}
export interface MfaConfirmed {
recovery_codes: string[];
access_token?: string | null;
refresh_token?: string | null;
}
export const mfaApi = {
status: (): Promise<MfaStatus> => request("/api/v1/auth/mfa/status"),
enrollBegin: (mfaToken?: string): Promise<MfaEnrollment> =>
request("/api/v1/auth/mfa/enroll/begin", {
method: "POST",
body: JSON.stringify(mfaToken ? { mfa_token: mfaToken } : {}),
}),
enrollConfirm: (code: string, mfaToken?: string): Promise<MfaConfirmed> =>
request("/api/v1/auth/mfa/enroll/confirm", {
method: "POST",
body: JSON.stringify(mfaToken ? { code, mfa_token: mfaToken } : { code }),
}),
/** Remove your own factor. The API requires a current code, so a stolen
* session cannot strip the thing protecting it. */
disable: (code: string): Promise<void> =>
request("/api/v1/auth/mfa", { method: "DELETE", body: JSON.stringify({ code }) }),
/** Administrative reset for a colleague who lost their phone. Audited
* with the reason, which is why the reason is required here too. */
reset: (userId: string, reason: string): Promise<{ status: string }> =>
request(`/api/v1/auth/mfa/reset/${encodeURIComponent(userId)}`, {
method: "POST",
body: JSON.stringify({ reason }),
}),
policy: (): Promise<MfaPolicy> => request("/api/v1/auth/mfa/policy"),
/** The whole policy, both halves at once. The role list is *replaced*,
* not merged, so clearing a role here actually clears it. */
setPolicy: (requireTotp: boolean, requireForRoles: string[] = []): Promise<MfaPolicy> =>
request("/api/v1/auth/mfa/policy", {
method: "PUT",
body: JSON.stringify({ require_totp: requireTotp, require_for_roles: requireForRoles }),
}),
/** Assertion options for a sign-in that owes a second factor. The user
* comes from the signed challenge, never from this call. */
webauthnChallenge: (mfaToken: string): Promise<WebAuthnChallenge> =>
request("/api/v1/auth/mfa/webauthn/challenge", {
method: "POST",
body: JSON.stringify({ mfa_token: mfaToken }),
}),
webauthnVerify: (
mfaToken: string,
challenge: string,
credential: Record<string, unknown>
): Promise<{ access_token: string; refresh_token: string }> =>
request("/api/v1/auth/mfa/webauthn/verify", {
method: "POST",
body: JSON.stringify({ mfa_token: mfaToken, challenge, credential }),
}),
};
export interface MfaPolicy {
require_totp: boolean;
require_for_roles: string[];
}
export interface WebAuthnChallenge {
publicKey: Record<string, unknown>;
challenge: string;
}
// ─── Tenants & MSSP ─────────────────────────────────────────────────────────
//
// The W5 tenant switcher needs to know:
// - which tenant the user is currently authenticated against
// (`tenants/me` — single canonical source of truth, includes display name)
// - what other tenants they can flip to
// (`mssp/children` for MSSP parents — returns *real* child tenants from
// the DB, not the mock list used by the parent dashboard)
//
// Failures are caught by the caller — the switcher gracefully degrades to a
// single-tenant role badge when these endpoints 401/404 (e.g. a tenant user
// who isn't an MSSP parent will not have any children but still has /me).
export interface MyTenant {
id: string;
name: string;
// mssp_role and parent_tenant_id come from the lightweight identity
// endpoint and are present for any tenant (null for standalone tenants).
mssp_role?: "parent" | "child" | null;
parent_tenant_id?: string | null;
}
export interface ChildTenant {
id: string;
name: string;
mssp_role: string;
created_at?: string;
}
// Full tenant record from `GET /api/v1/tenants/me` (requires `settings:read`).
// See services/api/app/api/v1/endpoints/tenants.py, class TenantResponse.
export interface FullTenant {
id: string;
name: string;
slug: string;
plan: string;
is_active: boolean;
settings: Record<string, unknown>;
limits: Record<string, unknown>;
mssp_role?: "parent" | "child" | null;
parent_tenant_id?: string | null;
created_at: string;
}
// Tenant member from `GET /api/v1/tenants/me/users` (requires `users:read`).
// See services/api/app/api/v1/endpoints/tenants.py, class UserResponse.
export interface TenantUser {
id: string;
tenant_id: string;
email: string;
username: string;
role: string;
is_active: boolean;
last_login: string | null;
created_at: string;
}
/**
* What the product is called and what it looks like, for this tenant.
*
* Resolved server-side from the organisation the tenant belongs to, so the
* console never has to know whether a deployment is white-labelled: an
* unbranded one gets the platform defaults from the same endpoint. One code
* path rather than a branded one and an unbranded one that drift.
*/
export interface Branding {
product_name: string;
primary_color: string;
accent_color: string;
support_email: string | null;
support_url: string | null;
sender_name: string;
footer_text: string;
/** A path on this deployment, never a third-party address. */
logo_url: string | null;
org_id: string | null;
is_white_labelled: boolean;
}
export const brandingApi = {
/** Readable by any authenticated member; the console calls it per page load. */
async get(): Promise<Branding> {
return request<Branding>("/api/v1/branding");
},
/**
* The logo bytes, fetched with the caller's credential.
*
* `logo_url` cannot be handed to an `<img src>`. The route authenticates a
* bearer token, and the only credential a browser attaches to an image
* request is a cookie — so the sidebar logo answered 401 on every
* deployment not running the development auth shim, which is every
* deployment a customer has. Fetched here and handed to the DOM as an
* object URL instead.
*/
async logo(path: string): Promise<Blob> {
const headers = apiHeaders();
// A GET for image bytes; the JSON content type `apiHeaders` sets by
// default describes a body this request does not have.
delete headers["Content-Type"];
const response = await fetch(`${API_BASE}${path}`, { headers });
if (!response.ok) {
throw new ApiError(`branding logo request failed`, response.status, "");
}
return response.blob();
},
};
export interface RetroHuntSettings {
enabled: boolean;
lookback_days: number;
include_federated: boolean;
max_sweeps_per_hour: number;
max_sweeps_per_day: number;
sweeps_this_hour: number;
sweeps_today: number;
sweeps_skipped_budget: number;
}
export const retroHuntsApi = {
/**
* This tenant's answer to "may AiSOC sweep my history".
*
* A tenant that has never opted in has no settings row, and the API returns
* the column defaults rather than a 404 -- "you have not opted in" is a
* state with a correct answer.
*/
async getSettings(): Promise<RetroHuntSettings> {
return request<RetroHuntSettings>("/api/v1/retro-hunts/settings");
},
/**
* Opt in or out. The budget fields are read-only here by design: they are
* the operator's ceiling on what one tenant can cost the deployment.
*/
async putSettings(body: {
enabled: boolean;
lookback_days: number;
include_federated: boolean;
}): Promise<RetroHuntSettings> {
return request<RetroHuntSettings>("/api/v1/retro-hunts/settings", {
method: "PUT",
body: JSON.stringify(body),
});
},
};
export interface RbacPermission {
id: string;
name: string;
description: string | null;
category: string | null;
}
export interface RbacRole {
id: string;
tenant_id: string;
name: string;
label?: string | null;
description: string | null;
is_system: boolean;
permissions: RbacPermission[];
user_count: number;
is_sso_default: boolean;
}
export interface UserRoleOut {
user_id: string;
role_id: string;
role_name: string;
}
export interface RbacPermissionLite {
name: string;
description?: string | null;
category?: string | null;
}
export interface AdminUserRow {
id: string;
email: string;
username?: string | null;
is_active: boolean;
role: string;
roles: string[];
provider: string;
last_login: string | null;
created_at: string;
effective_permissions: string[];
}
export interface AdminUserPage {
items: AdminUserRow[];
total: number;
limit: number;
offset: number;
}
/**
* RBAC console surface. All endpoints are admin-gated server-side
* (`roles:read` / `roles:write`); a 403 here means the signed-in operator
* is not a platform admin, and the screens must render read-only or hide
* management controls accordingly — never pretend success.
*/
export const rbacApi = {
async listRoles(): Promise<RbacRole[]> {
return request<RbacRole[]>("/api/v1/rbac/roles");
},
async listPermissions(): Promise<RbacPermissionLite[]> {
return request<RbacPermissionLite[]>("/api/v1/rbac/permissions");
},
async seedRoles(): Promise<{
seeded: boolean;
permissions: number;
roles: number;
role_permissions: number;
user_roles: number;
}> {
return request("/api/v1/rbac/roles/seed", { method: "POST" });
},
async createRole(body: {
name: string;
label?: string;
description?: string | null;
permission_names: string[];
}): Promise<RbacRole> {
return request<RbacRole>("/api/v1/rbac/roles", { method: "POST", body: JSON.stringify(body) });
},
/** Update label/description and (optionally) replace the permission set. */
async updateRole(
roleId: string,
body: { label?: string; description?: string | null; permission_names?: string[] }
): Promise<RbacRole> {
return request<RbacRole>(`/api/v1/rbac/roles/${roleId}`, {
method: "PATCH",
body: JSON.stringify(body),
});
},
async deleteRole(roleId: string): Promise<void> {
await apiFetch(`/api/v1/rbac/roles/${roleId}`, { method: "DELETE" });
},
/** Replace a user's primary role. Takes effect on their next request. */
async setPrimaryRole(userId: string, roleName: string, reason: string): Promise<UserRoleOut> {
return request<UserRoleOut>(`/api/v1/rbac/users/${userId}/role`, {
method: "PUT",
body: JSON.stringify({ role_name: roleName, reason }),
});
},
};
/**
* Admin Users screen. Server-gated to `roles:write` (admin) on every route;
* role changes revoke the target's sessions and take effect immediately.
*/
export const adminUsersApi = {
async listUsers(
params: {
search?: string;
role?: string;
status?: "active" | "disabled";
sort?: "name" | "email" | "status" | "created" | "last_login";
order?: "asc" | "desc";
limit?: number;
offset?: number;
} = {}
): Promise<AdminUserPage> {
const qs = new URLSearchParams();
Object.entries(params).forEach(([k, v]) => {
if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
});
const suffix = qs.toString();
return request<AdminUserPage>(`/api/v1/admin/users${suffix ? `?${suffix}` : ""}`);
},
async getUser(userId: string): Promise<AdminUserRow> {
return request<AdminUserRow>(`/api/v1/admin/users/${userId}`);
},
async setRoles(userId: string, roleNames: string[], reason: string): Promise<AdminUserRow> {
return request<AdminUserRow>(`/api/v1/admin/users/${userId}/roles`, {
method: "PUT",
body: JSON.stringify({ role_names: roleNames, reason }),
});
},
async addRole(userId: string, roleName: string, reason: string): Promise<AdminUserRow> {
return request<AdminUserRow>(`/api/v1/admin/users/${userId}/roles`, {
method: "POST",
body: JSON.stringify({ role_name: roleName, reason }),
});
},
async removeRole(userId: string, roleName: string, reason: string): Promise<AdminUserRow> {
const qs = reason ? `?reason=${encodeURIComponent(reason)}` : "";
return request<AdminUserRow>(
`/api/v1/admin/users/${userId}/roles/${encodeURIComponent(roleName)}${qs}`,
{
method: "DELETE",
}
);
},
async setStatus(userId: string, isActive: boolean, reason: string): Promise<AdminUserRow> {
return request<AdminUserRow>(`/api/v1/admin/users/${userId}`, {
method: "PATCH",
body: JSON.stringify({ is_active: isActive, reason }),
});
},
async deleteUser(userId: string, reason: string): Promise<void> {
await request<void>(`/api/v1/admin/users/${userId}?reason=${encodeURIComponent(reason)}`, {
method: "DELETE",
});
},
};
export const tenantsApi = {
/**
* Lightweight tenant identity for the SOC console TopBar.
*
* Uses `/api/v1/tenants/me/identity` (any authenticated user) instead of
* `/api/v1/tenants/me` (requires `settings:read`) so analyst/viewer roles
* can render the tenant pill and role badge without leaking plan or
* settings configuration.
*/
async me(): Promise<MyTenant> {
return request<MyTenant>("/api/v1/tenants/me/identity");
},
/** Full tenant record (plan, limits, settings) for the Workspace settings panel. */
async getFull(): Promise<FullTenant> {
return request<FullTenant>("/api/v1/tenants/me");
},
/** All users in the current tenant, for the Workspace settings panel. */
async listUsers(): Promise<TenantUser[]> {
return request<TenantUser[]>("/api/v1/tenants/me/users");
},
};
// The managed-portfolio read surface. Every figure below is counted from the
// tenant's own rows by `services/api/app/services/mssp_portfolio.py`; there is
// no revenue, risk-score or analyst-allocation data anywhere in this product,
// so the console does not have columns for them.
export interface PortfolioConnectorHealth {
total: number;
healthy: number;
stale: number;
error: number;
}
export interface PortfolioLimitHeadroom {
key: string;
label: string;
used: number;
limit: number | null;
remaining: number | null;
pct_used: number | null;
/** unlimited | ok | warning | exhausted */
state: string;
}
export interface PortfolioTenant {
tenant_id: string;
name: string;
slug: string;
relationship: string;
is_active: boolean;
open_alerts: number;
critical_alerts: number;
high_alerts: number;
untriaged_alerts: number;
/** Seeded demo rows, counted apart from the figures above. */
synthetic_alerts: number;
open_cases: number;
sla_breached_cases: number;
/** Null when this tenant closed no cases in the trailing window. */
mttr_minutes: number | null;
connectors: PortfolioConnectorHealth;
last_event_at: string | null;
limits: PortfolioLimitHeadroom[];
limits_exhausted: number;
limits_warning: number;
}
export interface PortfolioSummary {
tenants: number;
tenants_active: number;
open_alerts: number;
critical_alerts: number;
high_alerts: number;
untriaged_alerts: number;
synthetic_alerts: number;
open_cases: number;
sla_breached_cases: number;
mttr_minutes: number | null;
connectors_total: number;
connectors_healthy: number;
connectors_stale: number;
connectors_error: number;
tenants_with_exhausted_limits: number;
tenants_with_limit_warnings: number;
tenants_without_connectors: number;
}
export interface Portfolio {
org_id: string | null;
org_slug: string | null;
org_name: string | null;
org_role: string | null;
/** True when the caller's role reaches the whole portfolio rather than explicit grants. */
portfolio_wide: boolean;
/**
* How many tenants the caller is scoped to. Distinguishes "your organisation
* manages none" from "you were granted none" — different problems, and a bare
* zero row count tells them apart for nobody.
*/
scoped_tenants: number;
summary: PortfolioSummary;
tenants: PortfolioTenant[];
}
export interface PortfolioAlert {
alert_id: string;
tenant_id: string;
tenant_name: string;
title: string;
severity: string;
status: string;
category: string | null;
created_at: string | null;
event_time: string | null;
case_id: string | null;
is_synthetic: boolean;
}
export const msspApi = {
async listChildren(): Promise<ChildTenant[]> {
return request<ChildTenant[]>("/api/v1/mssp/children");
},
/**
* Managed portfolio: per-tenant posture plus derived totals.
*
* Throws `ApiError` with status 403 when the caller belongs to no operator
* organisation. That is not an error state in the console — cross-tenant
* reads simply are not theirs to make — so callers should branch on it.
*/
async getPortfolio(): Promise<Portfolio> {
return request<Portfolio>("/api/v1/mssp/portfolio");
},
/** Open alerts across the portfolio. Excludes seeded demo rows by default. */
async listPortfolioAlerts(
params: { severity?: string; limit?: number } = {}
): Promise<PortfolioAlert[]> {
return request<PortfolioAlert[]>("/api/v1/mssp/portfolio/alerts", {
params: { severity: params.severity, limit: params.limit ?? 25 },
});
},
};
// ─── Alerts ─────────────────────────────────────────────────────────────────
export type AlertSeverity = "critical" | "high" | "medium" | "low" | "info";
export type AlertStatus = "new" | "triaged" | "investigating" | "resolved" | "false_positive";
export interface MitreAttack {
tactic: string;
technique: string;
techniqueId: string;
}
export interface AlertIOC {
type: string;
value: string;
malicious?: boolean;
}
export type ConfidenceLabel = "high" | "medium" | "low";
/**
* The closed set of anonymizer and hosting classes ingest can stamp.
* Mirrors `ALL_CLASSES` in `scripts/ip_class_dataset.py` and the dataset
* manifest; a value outside it is dropped rather than rendered, because an
* unrecognised class on a security surface reads as a finding nobody can
* explain.
*/
export type IpClass =
| "vpn"
| "tor_exit"
| "public_proxy"
| "residential_proxy"
| "hosting_provider";
const IP_CLASSES: readonly IpClass[] = [
"vpn",
"tor_exit",
"public_proxy",
"residential_proxy",
"hosting_provider",
];
function asIpClass(value: unknown): IpClass | undefined {
return typeof value === "string" && (IP_CLASSES as readonly string[]).includes(value)
? (value as IpClass)
: undefined;
}
export interface ConfidenceFactor {
factor: string;
label: string;
value: number;
contribution: number;
weight: number;
}
/**
* One pivotable entity from the Investigation Rail (W6).
*
* The API groups these by ``kind`` — *principal* (user, host, asset),
* *network* (ip, domain, fqdn), *workflow* (case_id, run_id, ledger),
* *tenant* (tenant_id) — so the rail can render each group with its
* own affordances. ``value`` is always renderable as text; ``label``
* is an optional human-friendly override. ``pivotPath`` is an
* internal href (e.g. ``/graph?node=ip:10.0.0.1``) when the entity
* can be opened in the AttackGraphView.
*/
export interface RelatedEntity {
kind: "principal" | "network" | "workflow" | "tenant";
type: string;
value: string;
label?: string | null;
pivotPath?: string | null;
}
/**
* One row in the Investigation Rail's mini-timeline (W6).
*
* Reuses the shape of ``InvestigationLedger`` so the existing
* renderer can be lifted. Sourced from the case timeline and audit
* log; capped at the six most recent events on the server.
*/
export interface MiniTimelineEvent {
id: string;
timestamp: string;
type: string;
title: string;
description?: string | null;
actor?: string | null;
/** ``case_timeline`` or ``audit_log`` — surfaced as a small badge. */
source: "case_timeline" | "audit_log";
}
/**
* One row in the rail's "Recommended actions" list (W6).
*
* Generated by the ResponderAgent and normalised server-side so the
* UI can render legacy list-of-strings payloads and the structured
* shape uniformly.
*/
export interface RecommendedAction {
priority: "critical" | "high" | "medium" | "low" | "info";
action: string;
rationale?: string | null;
risk?: string | null;
}
/**
* What the tenant's business-context rules did to this alert before triage,
* plus the verdict's cited impact statement — read from the auto-triage
* ledger event. Absent (not empty) when no rule fired: the backend writes
* the keys only on a match, so absence is honest absence.
*/
export interface BusinessContextRail {
matchedRuleIds: string[];
severityBefore?: string | null;
severityAfter?: string | null;
impactStatement?: string | null;
impactCitations: string[];
}
export interface Alert {
id: string;
title: string;
description: string;
severity: AlertSeverity;
status: AlertStatus;
source: string;
sourceRef?: string;
tenantId: string;
/** Normalised 0-100 integer. Absent when nothing scored the alert — do not
* render a `0` in its place, that is a measurement nobody made. */
riskScore?: number;
mitreAttack?: MitreAttack[];
iocs?: AlertIOC[];
rawEvent?: Record<string, unknown>;
/** Where-in-the-source-console coordinates (rule id, agent, original alert id) parsed
* server-side from the ingested payload - search the source console with these. */
wazuhLocator?: Record<string, unknown>;
assignee?: string;
caseId?: string;
tags?: string[];
createdAt: string;
updatedAt: string;
resolvedAt?: string;
confidenceLabel?: ConfidenceLabel;
/**
* Fusion detection confidence as an integer 0-100, normalised by
* `normalizeAlert` regardless of which key and scale the payload used.
* Render it as `N/100` — it is not a probability that the verdict is
* correct, and it is independent of severity.
*/
confidenceScore?: number;
confidenceRationale?: ConfidenceFactor[];
/**
* Anonymizer or hosting class of the source address, stamped at ingest
* from a pinned local dataset. Absent means the dataset had no entry,
* which is the ordinary case: three of the five classes ship with no
* records because no redistributable source for them exists. Render
* absence as nothing at all, never as a reassuring "not an anonymizer".
*/
srcIpClass?: IpClass;
/** Version of the dataset that produced `srcIpClass`. Shown beside the
* chip because the dataset is refreshed and a class has to be datable. */
srcIpClassDatasetVersion?: string;
ledgerRunId?: string;
/** Analyst-corrected verdict (Tier 1.5 override loop). */
disposition?: "true_positive" | "false_positive" | "benign" | "escalate" | null;
// ─── Investigation Rail envelope (W6) ─────────────────────────────────────
//
// The list endpoint never populates these — they're only present
// on ``GET /api/v1/alerts/{id}``. The rail component checks for
// their presence before rendering each section, so it degrades
// gracefully when the backend predates v1.5.
narrative?: string | null;
relatedEntities?: RelatedEntity[];
miniTimeline?: MiniTimelineEvent[];
recommendedActions?: RecommendedAction[];
businessContext?: BusinessContextRail | null;
// ─── Automated triage ────────────────────────────────────────────────────
//
// `services/agents` auto-triages every fused alert and writes the verdict
// back onto the row (`ledger.persist_auto_triage`). The API has returned
// `ai_score` / `ai_summary` / `triage_groundedness` on every alert since,
// and this mapper dropped all three — so the one output of the AI the
// product leads with was metered, persisted, and rendered nowhere.
/** 0–1 confidence the triage run reported. Distinct from `confidenceScore`,
* which is fusion's detection confidence and has nothing to do with the
* agent. */
aiScore?: number;
/** The verdict's rationale, as written by whichever path produced it. The
* model's own text is prefixed `LLM auto-triage verdict:`; the
* deterministic fallback reads as a description of the signals it matched.
* Rendered verbatim so the reader can tell them apart. */
aiSummary?: string;
/** Fraction of the verdict's cited indicators that appear in the evidence.
* `null`/absent means *not assessed* — the deterministic path never scores
* groundedness, and rendering that as 0 would read as "wholly unsupported".
*/
triageGroundedness?: number | null;
/** Indicators the verdict cited that the evidence never contained. */
triageUngrounded?: string[];
}
/**
* Normalize an alert payload coming back from the API.
*
* The Postgres-backed API speaks ``snake_case`` (``tenant_id``,
* ``risk_score``, ``confidence_label``, …) while the web console's
* ``Alert`` type uses ``camelCase``. We map the keys explicitly so
* the UI can rely on the documented shape and the new Investigation
* Rail fields (W6 — ``narrative``, ``related_entities``,
* ``mini_timeline``, ``recommended_actions``) flow through one
* predictable boundary.
*
* Unknown / missing keys are tolerated — older API builds simply
* don't carry the new fields and the rail renders empty sections.
*/
function normalizeAlert(raw: unknown): Alert {
const r = (raw ?? {}) as Record<string, unknown>;
const pickStr = (snake: string, camel: string): string | undefined => {
const v = r[snake] ?? r[camel];
return typeof v === "string" ? v : undefined;
};
const pickNum = (snake: string, camel: string): number | undefined => {
const v = r[snake] ?? r[camel];
return typeof v === "number" ? v : undefined;
};
const pickArr = <T = unknown>(snake: string, camel: string): T[] | undefined => {
const v = r[snake] ?? r[camel];
return Array.isArray(v) ? (v as T[]) : undefined;
};
// Tags arrive either as a bare array (legacy) or as the JSONB
// ``{labels: [...]}`` shape the cases endpoint uses. Normalise to
// a plain string[] so the rail and grid can map without a guard.
const tagsRaw = r.tags;
let tags: string[] | undefined;
if (Array.isArray(tagsRaw)) {
tags = tagsRaw.map((t) => String(t));
} else if (
tagsRaw &&
typeof tagsRaw === "object" &&
Array.isArray((tagsRaw as Record<string, unknown>).labels)
) {
tags = ((tagsRaw as Record<string, unknown>).labels as unknown[]).map((t) => String(t));
}
// MITRE: the API can return either ``mitre_attack`` (already
// structured) or the split ``mitre_tactics`` / ``mitre_techniques``
// arrays. Prefer structured; otherwise zip the two parallel lists.
let mitreAttack: MitreAttack[] | undefined;
const mitreStructured = r.mitre_attack ?? r.mitreAttack;
if (Array.isArray(mitreStructured)) {
mitreAttack = (mitreStructured as Array<Record<string, unknown>>).map((m) => ({
tactic: String(m.tactic ?? ""),
technique: String(m.technique ?? ""),
techniqueId: String(m.technique_id ?? m.techniqueId ?? ""),
}));
} else {
const techniques = pickArr<string>("mitre_techniques", "mitreTechniques");
const tactics = pickArr<string>("mitre_tactics", "mitreTactics");
if (techniques && techniques.length > 0) {
mitreAttack = techniques.map((t, i) => ({
tactic: tactics?.[i] ? String(tactics[i]) : "",
technique: String(t),
techniqueId: String(t),
}));
}
}
const rationaleRaw = r.confidence_rationale ?? r.confidenceRationale;
const confidenceRationale = Array.isArray(rationaleRaw)
? (rationaleRaw as Array<Record<string, unknown>>).map((f) => ({
factor: String(f.factor ?? ""),
label: String(f.label ?? ""),
value: Number(f.value ?? 0),
contribution: Number(f.contribution ?? 0),
weight: Number(f.weight ?? 0),
}))
: undefined;
// Confidence arrives on two keys at two different scales, and this field
// used to accept whichever showed up first: the API surfaces `confidence`
// as an integer 0-100, while fusion's `confidence_score` is the raw
// [0.0, 1.0] float the band was derived from. One field carrying two
// scales meant every consumer had to guess, and they guessed differently —
// `AlertDetailView` multiplied by 100 and rendered a real confidence of 21
// as "2100%", while `AttackStory` rendered the same value as "21/100".
// Both passed their tests because each mock used the scale its own view
// assumed.
//
// Normalised here, once, to the canonical 0-100 integer. The scale is
// decided by the *key*, never by the magnitude: a genuine confidence of 1
// is indistinguishable from a raw score of 1.0 by value alone.
const canonicalConfidence = pickNum("confidence", "confidence");
const rawConfidenceScore = pickNum("confidence_score", "confidenceScore");
const confidenceScore =
canonicalConfidence !== undefined
? canonicalConfidence
: rawConfidenceScore !== undefined
? Math.round(rawConfidenceScore * 100)
: undefined;
// ── Investigation Rail envelope (W6) ────────────────────────────────────
// `alert_rail.RelatedEntity` serialises as `{group, kind, value, label,
// pivot}`. This mapper read `e.type` and `e.pivot_path`, which the API has
// never sent, and passed `e.kind` ("host") into the client's `kind`, which
// is the rail *column* ("principal"). All three were wrong in the same
// direction: `pivotPath` was always null so no chip was ever a link, `type`
// was always empty, and `ENTITY_KIND_CONFIG[kind]` missed on every row — so
// the section rendered its header with a count and no chips beneath it. The
// `/graph?entity=…` route fix and its URL encoding were therefore
// unreachable from the console on every deployment.
//
// `group`/`kind` are read first and the old spellings kept as fallbacks, so
// a console pointed at an older API still renders.
const relatedRaw = r.related_entities ?? r.relatedEntities;
const relatedEntities = Array.isArray(relatedRaw)
? (relatedRaw as Array<Record<string, unknown>>).map((e) => ({
kind: (e.group ?? e.kind ?? "principal") as RelatedEntity["kind"],
// `type` prefers its own spelling so a legacy `{kind: 'principal',
// type: 'host'}` payload still reports the concrete type, and falls
// back to `kind` for the current `{group, kind}` shape.
type: String(e.type ?? e.kind ?? ""),
value: String(e.value ?? ""),
label: (e.label as string | null | undefined) ?? null,
pivotPath:
(e.pivot as string | null | undefined) ??
(e.pivot_path as string | null | undefined) ??
(e.pivotPath as string | null | undefined) ??
null,
}))
: undefined;
const timelineRaw = r.mini_timeline ?? r.miniTimeline;
const miniTimeline = Array.isArray(timelineRaw)
? (timelineRaw as Array<Record<string, unknown>>).map((e) => ({
id: String(e.id ?? ""),
timestamp: String(e.timestamp ?? ""),
type: String(e.type ?? ""),
title: String(e.title ?? ""),
description: (e.description as string | null | undefined) ?? null,
actor: (e.actor as string | null | undefined) ?? null,
source: (e.source ?? "audit_log") as MiniTimelineEvent["source"],
}))
: undefined;
// Business-context rail leg. Snake-case is what the API sends; camel kept
// as a fallback for the same reason the other envelope fields keep one.
const bcRaw = (r.business_context ?? r.businessContext) as Record<string, unknown> | null | undefined;
const businessContext: BusinessContextRail | null =
bcRaw && typeof bcRaw === "object"
? {
matchedRuleIds: Array.isArray(bcRaw.matched_rule_ids ?? bcRaw.matchedRuleIds)
? ((bcRaw.matched_rule_ids ?? bcRaw.matchedRuleIds) as unknown[]).map(String)
: [],
severityBefore: (bcRaw.severity_before ?? bcRaw.severityBefore ?? null) as string | null,
severityAfter: (bcRaw.severity_after ?? bcRaw.severityAfter ?? null) as string | null,
impactStatement: (bcRaw.impact_statement ?? bcRaw.impactStatement ?? null) as string | null,
impactCitations: Array.isArray(bcRaw.impact_citations ?? bcRaw.impactCitations)
? ((bcRaw.impact_citations ?? bcRaw.impactCitations) as unknown[]).map(String)
: [],
}
: null;
const recommendedRaw =
r.recommended_actions ?? r.recommendedActions ?? r.ai_recommendations ?? r.aiRecommendations;
let recommendedActions: RecommendedAction[] | undefined;
if (Array.isArray(recommendedRaw)) {
recommendedActions = (recommendedRaw as unknown[]).map((item) => {
if (typeof item === "string") {
return { priority: "medium", action: item };
}
const o = (item ?? {}) as Record<string, unknown>;
return {
priority: (o.priority ?? "medium") as RecommendedAction["priority"],
action: String(o.action ?? ""),
rationale: (o.rationale as string | null | undefined) ?? null,
risk: (o.risk as string | null | undefined) ?? null,
};
});
}
// Risk has the same two-scales-one-field problem confidence had above, and
// it resolved across three keys: `risk_score ?? ai_score ?? confidence ?? 0`.
// `risk_score` and `ai_score` are [0,1] floats (fusion documents the first
// as "0-1, vendor-provided"; `metrics.py` buckets the second "across
// [0, 1]"), while `confidence` is the canonical 0-100 integer. The live
// path is `ai_score` — the `alerts` table has no `risk_score` column — so a
// real alert scoring 0.85 reached the console as 0.85, and the two surfaces
// reading it disagreed: the rail printed `Math.round(0.85)` as "risk 1"
// while the detail view printed "0.85".
//
// Normalised here, once, to the canonical 0-100 integer, with the scale
// decided by the *key*: a genuine confidence of 1 is indistinguishable from
// a model score of 1.0 by value alone. The camelCase `riskScore` is this
// function's own output name, so it is already on the 0-100 scale and is
// passed through — re-normalising an alert must not multiply it again.
//
// The `?? 0` that used to close the chain is gone too: an alert carrying
// none of these keys is unscored, and "nobody scored this" is not "scored
// zero risk". The rail already guards on `typeof riskScore === 'number'` to
// omit the chip, and the default made that guard unreachable.
const unitScaleRisk = pickNum("risk_score", "risk_score") ?? pickNum("ai_score", "aiScore");
const alreadyNormalisedRisk = pickNum("riskScore", "riskScore");
const riskScore =
unitScaleRisk !== undefined
? Math.round(unitScaleRisk * 100)
: (alreadyNormalisedRisk ?? canonicalConfidence);
return {
id: String(r.id ?? ""),
title: String(r.title ?? ""),
description: String(r.description ?? ""),
severity: ((r.severity as string) ?? "medium") as AlertSeverity,
status: ((r.status as string) ?? "new") as AlertStatus,
source: pickStr("source", "source") ?? pickStr("connector_type", "connectorType") ?? "unknown",
sourceRef: pickStr("source_ref", "sourceRef"),
tenantId: pickStr("tenant_id", "tenantId") ?? "",
riskScore,
mitreAttack,
iocs: pickArr<AlertIOC>("iocs", "iocs"),
rawEvent:
(r.raw_event as Record<string, unknown> | undefined) ??
(r.rawEvent as Record<string, unknown> | undefined),
wazuhLocator:
(r.wazuh_locator as Record<string, unknown> | undefined) ??
(r.wazuhLocator as Record<string, unknown> | undefined),
assignee: pickStr("assignee", "assignee"),
caseId: pickStr("case_id", "caseId"),
tags,
createdAt:
pickStr("created_at", "createdAt") ??
pickStr("first_seen", "firstSeen") ??
new Date().toISOString(),
updatedAt:
pickStr("updated_at", "updatedAt") ??
pickStr("last_seen", "lastSeen") ??
new Date().toISOString(),
resolvedAt: pickStr("resolved_at", "resolvedAt"),
confidenceLabel: (r.confidence_label ?? r.confidenceLabel) as ConfidenceLabel | undefined,
confidenceScore,
confidenceRationale,
srcIpClass: asIpClass(r.src_ip_class ?? r.srcIpClass),
srcIpClassDatasetVersion: pickStr(
"src_ip_class_dataset_version",
"srcIpClassDatasetVersion",
),
ledgerRunId: pickStr("ledger_run_id", "ledgerRunId"),
disposition: (r.disposition ?? null) as Alert["disposition"],
narrative: (r.narrative as string | null | undefined) ?? null,
relatedEntities,
miniTimeline,
recommendedActions,
businessContext,
aiScore: pickNum("ai_score", "aiScore"),
aiSummary: pickStr("ai_summary", "aiSummary"),
// `?? null` and not `?? undefined`: the column is nullable because NULL
// means "not assessed", and collapsing that into absent loses the
// distinction the schema comment exists to preserve.
triageGroundedness:
typeof (r.triage_groundedness ?? r.triageGroundedness) === "number"
? ((r.triage_groundedness ?? r.triageGroundedness) as number)
: null,
triageUngrounded: pickArr<string>("triage_ungrounded", "triageUngrounded"),
};
}
export interface AlertsResponse {
alerts: Alert[];
total: number;
page: number;
pageSize: number;
/** Absent when the server did not send them — see `AlertFacets`. */
facets?: AlertFacets;
}
/**
* Counts over the whole filtered result set, from `AlertListResponse.facets`.
*
* The stat strip used to derive these in the browser from the loaded page, so
* they were capped at `pageSize` and sat beside a server-side `total` in the
* hundreds. The server computes them off the same `WHERE` clause as `total`.
*
* A missing key inside `bySeverity` / `byStatus` means the server counted and
* found none. The whole object being absent means the server told us nothing,
* which is a different thing and must not render as a zero.
*/
export interface AlertFacets {
bySeverity: Record<string, number>;
byStatus: Record<string, number>;
/** Uses the API's shared unresolved vocabulary (`new | triaging | in_progress`). */
unresolved: number;
}
function countMap(raw: unknown): Record<string, number> {
if (!raw || typeof raw !== "object") return {};
return Object.fromEntries(
Object.entries(raw as Record<string, unknown>).filter(
(entry): entry is [string, number] => typeof entry[1] === "number"
)
);
}
/**
* Reads `AlertListResponse.facets`, or returns `undefined` when the server
* sent none. Returning an empty-but-present object here would be the same
* mistake as a `?? 0`: the strip could not tell "no criticals" from "nobody
* counted".
*/
function normalizeAlertFacets(raw: unknown): AlertFacets | undefined {
if (!raw || typeof raw !== "object") return undefined;
const r = raw as Record<string, unknown>;
const unresolved = r.unresolved;
return {
bySeverity: countMap(r.by_severity ?? r.bySeverity),
byStatus: countMap(r.by_status ?? r.byStatus),
unresolved: typeof unresolved === "number" ? unresolved : 0,
};
}
export interface AlertFilters {
severity?: string;
status?: string;
source?: string;
assignee?: string;
startTime?: string;
endTime?: string;
search?: string;
page?: number;
pageSize?: number;
tenantId?: string;
/**
* `newest` (created_at descending) or `priority` (severity first, then
* created_at). The API defaults to `newest` to keep its published contract;
* the console asks for `priority` so a noisy low-severity source cannot
* push a critical off page one.
*/
sort?: "newest" | "priority";
}
/**
* The five fields `PATCH /api/v1/alerts/{id}` can actually apply.
*
* This was `Partial<Alert>`, which let the console send any of the row's
* ~40 columns. The server ignored everything outside this set and still
* answered 200, so `{ disposition }` or `{ severity }` compiled, ran and
* changed nothing (issue #1280). The server now refuses them; narrowing
* the type here makes the rejected call fail to compile instead, and
* `AlertUpdateRequest` on the Python side is the one definition this
* mirrors.
*
* Severity goes through `POST /alerts/{id}/escalate`, a disposition
* through `POST /feedback/alert-override`, and a snooze through
* `POST /alerts/{id}/snooze`.
*/
export interface AlertUpdate {
status?: AlertStatus;
priority?: number;
tags?: string[];
/** `null` releases the alert back to the pool. */
assignee?: string | null;
case_id?: string | null;
}
export const alertsApi = {
list: async (filters: AlertFilters = {}) => {
const raw = await request<{
items?: unknown[];
alerts?: unknown[];
total?: number;
page?: number;
page_size?: number;
pageSize?: number;
facets?: unknown;
}>("/api/v1/alerts", {
params: filters as Record<string, string>,
});
// `AlertListResponse` puts the rows under `items`, not `alerts`
// (services/api/app/api/v1/endpoints/alerts.py). Reading only `alerts`
// resolved every page to [] while `total` reported the real count, so
// the queue rendered "1,247 alerts" above an empty table. `alerts` is
// still accepted because the mobile responder routes emit that shape.
const rows = Array.isArray(raw.items) ? raw.items : Array.isArray(raw.alerts) ? raw.alerts : [];
return {
alerts: rows.map(normalizeAlert),
total: typeof raw.total === "number" ? raw.total : 0,
page: typeof raw.page === "number" ? raw.page : 1,
pageSize:
typeof raw.pageSize === "number"
? raw.pageSize
: typeof raw.page_size === "number"
? raw.page_size
: 50,
facets: normalizeAlertFacets(raw.facets),
} satisfies AlertsResponse;
},
get: async (id: string) => {
const raw = await request<unknown>(`/api/v1/alerts/${id}`);
return normalizeAlert(raw);
},
update: async (id: string, data: AlertUpdate) => {
const raw = await request<unknown>(`/api/v1/alerts/${id}`, {
method: "PATCH",
body: JSON.stringify(data),
});
return normalizeAlert(raw);
},
bulkAction: (ids: string[], action: string, data?: Record<string, unknown>) =>
request<{ updated: number }>("/api/v1/alerts/bulk", {
method: "POST",
body: JSON.stringify({ ids, action, ...data }),
}),
/**
* Structured AI explanation for one alert (Stage 2 #6).
*
* `POST /api/v1/alerts/{id}/explain` returns a single JSON envelope
* with rule lineage, contributing events, MITRE technique cards, the
* live false-positive rate for the matched rule, suggested next
* steps, and a deterministic-or-LLM summary. Counterpart to the
* agents service's NDJSON token stream — use this when you want
* the *whole* answer in one shot (PDF builder, mobile app, the
* console drawer's first paint) instead of typing it out.
*
* The endpoint is rate-limited per tenant (token bucket; default
* burst 20, refill 0.2/s) and returns 429 with `Retry-After` when
* the bucket is empty. 404 means either the alert doesn't exist or
* the backend predates this endpoint — both are signals to fall
* back to the streaming explainer.
*/
explain: (alertId: string, signal?: AbortSignal) =>
request<AlertExplanation>(`/api/v1/alerts/${alertId}/explain`, {
method: "POST",
signal,
}),
};
// ─── Investigation Queue (W7) ───────────────────────────────────────────────
//
// The Investigation Queue is the analyst's working surface: one ranked list
// of "what should I work on next?" sourced from the canonical alerts table.
// The backend computes a virtual ``sla_due_at`` per row (``first_seen +
// mttd_target`` for the alert's severity) and orders the queue by
//
// 1. assignment bucket (mine before unassigned), and
// 2. ``sla_due_at`` ascending within each bucket.
//
// Snoozed and closed alerts are excluded server-side. Unassigned ``medium``
// and below are also excluded — those are triaged in bulk on /alerts, not
// one-by-one on the queue. See ``services/api/app/services/alert_queue.py``
// for the full contract.
export type QueueOwner = "me" | "unassigned" | "all";
export type QueuePeriod = "24h" | "7d" | "30d" | "all";
export type QueueBucket = "mine" | "unassigned";
export type QueueRisk = "low" | "medium" | "high";
export interface QueueAsset {
/** ``host`` | ``user`` | ``ip`` | ``asset`` — chosen by the backend. */
kind: string;
value: string;
label?: string | null;
}
export interface QueueAction {
/** 1-indexed priority; lower is more urgent. */
priority: number;
action: string;
risk: QueueRisk;
}
export interface QueueItem {
id: string;
tenant_id: string;
title: string;
severity: AlertSeverity;
status: AlertStatus;
priority: number;
category?: string | null;
connector_type?: string | null;
assigned_to_id?: string | null;
case_id?: string | null;
first_seen: string;
sla_due_at: string;
/** Seconds until ``sla_due_at`` — negative once breached. */
sla_remaining_seconds: number;
sla_breached: boolean;
age_seconds: number;
asset?: QueueAsset | null;
suggested_action?: QueueAction | null;
bucket: QueueBucket;
}
export interface QueueCounts {
mine: number;
unassigned: number;
all: number;
}
export interface QueueResponse {
items: QueueItem[];
total: number;
counts: QueueCounts;
period: QueuePeriod;
owner: QueueOwner;
page: number;
page_size: number;
pages: number;
/** Server's authoritative ``now`` — the UI drifts its countdowns from this. */
generated_at: string;
}
export interface QueueFilters {
owner?: QueueOwner;
period?: QueuePeriod;
page?: number;
page_size?: number;
}
export const queueApi = {
/**
* Fetch the Investigation Queue.
*
* Returns up to ``page_size`` items (capped server-side at 200) plus
* the live ``counts`` for all buckets — that's what the sidebar badge
* polls. The endpoint is cheap because the server only projects the
* columns the queue actually renders; do *not* fan out to ``alertsApi.get``
* for every row.
*/
list: (filters: QueueFilters = {}) =>
request<QueueResponse>("/api/v1/alerts/queue", {
params: filters as Record<string, string | number>,
}),
/**
* Atomically claim an unassigned alert for the current user.
*
* Returns ``409`` if another analyst grabbed the row first — the UI
* should surface that as "claimed by Sam · refresh" rather than a
* generic error. Idempotent if the caller already owns the alert.
*/
claim: (alertId: string) =>
request<Alert>(`/api/v1/alerts/${alertId}/claim`, {
method: "POST",
}),
/**
* Reassign or unassign an alert. Pass ``assignee = null`` to release.
*
* Reuses the existing ``PATCH /alerts/{id}`` endpoint — the server
* already accepts ``assignee`` updates. We add a thin wrapper here so
* the queue view doesn't have to re-derive the URL.
*/
assign: (alertId: string, assignee: string | null) =>
request<Alert>(`/api/v1/alerts/${alertId}`, {
method: "PATCH",
body: JSON.stringify({ assignee }),
}),
/**
* Snooze an alert for ``duration_minutes`` (1 → 43200 / 30d) or until
* a specific timestamp. The alert re-enters the queue automatically
* once ``snoozed_until`` passes.
*/
snooze: (alertId: string, body: { duration_minutes?: number; until?: string; reason?: string }) =>
request<Alert>(`/api/v1/alerts/${alertId}/snooze`, {
method: "POST",
body: JSON.stringify(body),
}),
};
// ─── Risk-Based Alerting (entity rollup) ─────────────────────────────────────
//
// Wave 1 of the AiSOC v6 capability roadmap: alerts contribute time-decayed
// risk *points* onto the entities they touch (user / host / src_ip / domain).
// Once an entity crosses ``rba_promotion_threshold`` it becomes the primary
// unit of triage in the UI — so the analyst opens "the user fox.beach" with
// 47 contributing alerts attached, not 47 separate alert rows. The endpoints
// live on the fusion service (port 8082) and are proxied same-origin via
// next.config.js → ``/api/v1/fusion/*``.
export type EntityType = "user" | "host" | "ip" | "domain";
/** A single alert that contributed risk to an entity. */
export interface EntityRiskContribution {
alert_id: string;
severity: AlertSeverity;
/** Points contributed *at the moment of observation* — not decayed. */
raw_points: number;
/** ISO-8601 timestamp the alert was observed. */
observed_at: string;
title?: string | null;
source?: string | null;
}
/** A rolled-up entity with its current decayed risk score. */
export interface EntityRiskRecord {
tenant_id: string;
entity_type: EntityType;
entity_value: string;
/** Time-decayed score (0 → ∞ in theory, capped in practice by the engine). */
score: number;
/** Same as ``score`` rounded — convenience for the UI's badge. */
display_score: number;
/** Promotion threshold the engine was configured with at observation time. */
threshold: number;
/** True if ``score`` has crossed ``threshold`` at least once. */
promoted: boolean;
/** ID of the incident the entity was promoted into, if any. */
promoted_incident_id?: string | null;
/** ISO-8601 timestamp of the last contributing alert. */
last_seen: string;
/** ISO-8601 timestamp the entity first picked up any risk. */
first_seen: string;
/** Top contributing alerts, newest first, capped to ~25. */
contributions: EntityRiskContribution[];
/** Count by severity over the decay window — drives the queue badge. */
severity_histogram: Record<AlertSeverity, number>;
/** Convenience: total alert count in the decay window. */
alert_count: number;
}
export interface EntityRiskQueueResponse {
tenant_id: string;
threshold: number;
entities: EntityRiskRecord[];
}
export interface EntityRiskStats {
tenant_id: string;
/** Promotion threshold (mirrored from the engine). */
threshold: number;
/** Total active entities in the window. */
total: number;
/** Entities currently at or above ``threshold``. */
promoted: number;
/** Banded counts for the queue header chips. */
bands: {
critical: number;
high: number;
medium: number;
low: number;
};
/** Total alerts contributing across all entities in the window. */
alert_count: number;
/** Convenience: alert-to-incident ratio observed in the current window. */
alert_to_incident_ratio?: number | null;
}
/**
* Path namespace served by the fusion service. Goes through Next.js
* rewrites (`/api/v1/fusion/*` → ``${FUSION_HOST}/*``) so the bundle
* stays same-origin.
*/
const FUSION_PATH = "/api/v1/fusion";
// The tenant is no longer sent by default. It used to be, resolved from the
// build-time `NEXT_PUBLIC_TENANT_ID` when nothing better was cached — and the
// server took whatever arrived, because the entity-risk routes had no auth
// dependency at all. Now the server derives the tenant from the bearer token
// and treats the parameter as a filter it intersects with that scope, so
// sending a stale build-time value would turn into a 403 for a perfectly
// legitimate session. Omitting it is both safer and more correct: an explicit
// `tenantId` is still honoured for an operator narrowing to one managed
// customer, and naming a tenant outside their scope is refused server-side.
export const entityRiskApi = {
/** Top-N entities by current decayed risk score. */
queue: (
params: {
tenantId?: string;
limit?: number;
promotedOnly?: boolean;
} = {}
) =>
request<EntityRiskQueueResponse>(`${FUSION_PATH}/entity-risk/queue`, {
params: {
tenant_id: params.tenantId,
limit: params.limit ?? 25,
promoted_only: params.promotedOnly ? "true" : undefined,
},
}),
/** Tenant-scoped queue stats for dashboards (banding, totals, threshold). */
stats: (tenantId?: string) =>
request<EntityRiskStats>(`${FUSION_PATH}/entity-risk/stats`, {
params: { tenant_id: tenantId },
}),
/** Full risk record for a single entity (drawer detail). */
get: (entityType: EntityType, entityValue: string, tenantId?: string) => {
const pathType = entityType === "ip" ? "src_ip" : entityType;
return request<EntityRiskRecord>(
`${FUSION_PATH}/entity-risk/${pathType}/${encodeURIComponent(entityValue)}`,
{ params: { tenant_id: tenantId } }
);
},
};
// ─── Cases ───────────────────────────────────────────────────────────────────
/**
* The six states a case can hold, matching the `aisoc_cases` CHECK and
* `services/api/app/services/case_status.py`.
*
* This read `open | in_progress | pending | resolved | closed`, which shares
* exactly two members with the real vocabulary. Three of its values the
* database rejects outright, and the four states a case is actually *in* for
* most of its life -- new, triaged, investigating, contained -- were absent.
* Every `Record<CaseStatus, …>` keyed off this union was therefore complete
* by the type checker and missing an entry for most real rows, so the case
* workspace rendered an undefined label and the status dropdown offered three
* values the API refuses.
*/
export const CASE_STATUSES = [
"new",
"triaged",
"investigating",
"contained",
"resolved",
"closed",
] as const;
export type CaseStatus = "new" | "triaged" | "investigating" | "contained" | "resolved" | "closed";
export type CaseSeverity = "critical" | "high" | "medium" | "low";
export interface CaseTimelineEvent {
id: string;
type: string;
timestamp: string;
title: string;
description?: string;
actor?: string;
}
export interface CaseTask {
id: string;
title: string;
status: "todo" | "in_progress" | "done";
assignee?: string;
dueAt?: string;
createdAt: string;
}
export interface Case {
id: string;
/**
* Short, human-friendly case identifier (e.g. ``INC-001``).
* Returned by the backend as ``case_number`` and used by demo deeplinks.
*/
caseNumber?: string;
title: string;
description?: string;
status: CaseStatus;
severity: CaseSeverity;
/** Display alias for severity used by some UIs. */
priority?: CaseSeverity;
assignee?: string;
tenantId?: string;
alertIds?: string[];
/** Cached count from the backend so the UI doesn't have to re-aggregate. */
alertCount?: number;
tags?: string[];
mitre?: string[];
resolution?: string;
createdBy?: string;
createdAt: string;
updatedAt: string;
closedAt?: string;
dueAt?: string;
timeline?: CaseTimelineEvent[];
tasks?: CaseTask[];
}
// The console speaks the backend vocabulary directly.
//
// There were two translation maps here, and the round trip through them was
// **destructive**: `contained` came in as `in_progress`, and `in_progress`
// went back out as `investigating`. So opening a contained case and saving
// any edit -- a title, an assignee -- silently moved it backwards and
// discarded the containment an analyst had recorded. The lossiness is
// structural: six states cannot round-trip through five.
//
// The UI simplification they existed for is not worth that. Four of the six
// states now have their own label and colour, which is more information
// than the collapsed model carried anyway.
function toUiStatus(raw: unknown): CaseStatus {
if (typeof raw !== "string") return "new";
const known: readonly string[] = CASE_STATUSES;
return known.includes(raw) ? (raw as CaseStatus) : "new";
}
export interface CasesResponse {
cases: Case[];
total: number;
page: number;
pageSize: number;
}
// ─── WS-D2 — Per-case auto-summary artifact ─────────────────────────────────
//
// Mirrors the Pydantic schemas in ``services/api/app/services/case_summary.py``.
// We keep these as a flat block of ``snake_case`` interfaces (matching the
// JSON over the wire) so consumers don't pay a transformation cost — the
// backend is the source of truth for shape, the UI just renders.
export interface CaseSummaryHeader {
case_id: string;
case_number: string | null;
title: string;
description: string | null;
severity: string;
status: string;
assignee: string | null;
created_by: string | null;
tags: Record<string, unknown>;
}
export interface CaseLifecycleTimings {
opened_at: string;
triaged_at: string | null;
resolved_at: string | null;
closed_at: string | null;
sla_due_at: string | null;
time_to_triage_hours: number | null;
time_to_resolve_hours: number | null;
time_to_close_hours: number | null;
sla_breached: boolean;
}
export interface CaseSummaryTaskBreakdown {
total: number;
todo: number;
in_progress: number;
done: number;
overdue: number;
}
export interface CaseSummaryCommentBreakdown {
total: number;
analyst: number;
system: number;
distinct_authors: string[];
}
export interface CaseSummaryCoverage {
mitre_techniques: string[];
mitre_tactic_buckets: Record<string, number>;
compliance_frameworks: string[];
}
export interface CaseSummaryObservables {
total_nodes: number;
total_edges: number;
node_kind_counts: Record<string, number>;
distinct_kinds: string[];
}
export interface CaseSummaryEvidence {
total_items: number;
distinct_kinds: string[];
}
export interface CaseSummaryTimelineEntry {
ts: string;
kind: string; // "case" | "comment" | "task"
label: string;
detail: string | null;
}
export interface CaseSummaryRecommendation {
severity: string; // "info" | "warning" | "critical"
title: string;
body: string;
}
export interface CaseAutoSummary {
generated_at: string;
headline: string;
case: CaseSummaryHeader;
lifecycle: CaseLifecycleTimings;
coverage: CaseSummaryCoverage;
alerts: { count?: number; ids?: string[] } & Record<string, unknown>;
observables: CaseSummaryObservables;
evidence: CaseSummaryEvidence;
tasks: CaseSummaryTaskBreakdown;
comments: CaseSummaryCommentBreakdown;
timeline: CaseSummaryTimelineEntry[];
recommendations: CaseSummaryRecommendation[];
}
export interface CaseFilters {
status?: string;
priority?: string;
severity?: string;
assignee?: string;
search?: string;
page?: number;
pageSize?: number;
}
/**
* Normalize a case payload from the backend API.
*
* The Postgres-backed API returns snake_case fields and stores `tags` as a
* JSONB object (`{labels: string[]}`). The web console's `Case` type uses
* camelCase and expects `tags: string[]`. Without this normalization the
* detail page crashes with a runtime TypeError when components call
* `.map()` on `tags` directly.
*/
function normalizeCase(raw: unknown): Case {
const r = (raw ?? {}) as Record<string, unknown>;
const tagsRaw = r.tags;
let tags: string[] | undefined;
if (Array.isArray(tagsRaw)) {
tags = tagsRaw.map((t) => String(t));
} else if (
tagsRaw &&
typeof tagsRaw === "object" &&
Array.isArray((tagsRaw as Record<string, unknown>).labels)
) {
tags = ((tagsRaw as Record<string, unknown>).labels as unknown[]).map((t) => String(t));
}
const alertIds = Array.isArray(r.alert_ids)
? (r.alert_ids as unknown[]).map((x) => String(x))
: Array.isArray(r.alertIds)
? (r.alertIds as unknown[]).map((x) => String(x))
: undefined;
const mitre = Array.isArray(r.mitre_techniques)
? (r.mitre_techniques as unknown[]).map((x) => String(x))
: Array.isArray(r.mitre)
? (r.mitre as unknown[]).map((x) => String(x))
: undefined;
const createdAt =
(r.created_at as string | undefined) ??
(r.createdAt as string | undefined) ??
(r.opened_at as string | undefined) ??
new Date().toISOString();
const updatedAt =
(r.updated_at as string | undefined) ?? (r.updatedAt as string | undefined) ?? createdAt;
const caseNumber =
(r.case_number as string | undefined) ?? (r.caseNumber as string | undefined) ?? undefined;
return {
id: String(r.id ?? ""),
caseNumber,
title: String(r.title ?? ""),
description: (r.description as string | undefined) ?? undefined,
status: toUiStatus(r.status),
severity: (r.severity as Case["severity"]) ?? "medium",
priority:
(r.priority as Case["severity"] | undefined) ?? (r.severity as Case["severity"] | undefined),
assignee: (r.assignee as string | null | undefined) ?? undefined,
tenantId: (r.tenant_id as string | undefined) ?? (r.tenantId as string | undefined),
alertIds,
alertCount:
(r.alert_count as number | undefined) ??
(r.alertCount as number | undefined) ??
(alertIds ? alertIds.length : undefined),
tags,
mitre,
resolution: (r.resolution as string | undefined) ?? undefined,
createdBy: (r.created_by as string | undefined) ?? (r.createdBy as string | undefined),
createdAt,
updatedAt,
closedAt:
(r.closed_at as string | null | undefined) ??
(r.closedAt as string | null | undefined) ??
undefined,
dueAt:
(r.sla_due_at as string | null | undefined) ??
(r.dueAt as string | null | undefined) ??
undefined,
timeline: Array.isArray(r.timeline) ? (r.timeline as CaseTimelineEvent[]) : undefined,
tasks: Array.isArray(r.tasks) ? (r.tasks as CaseTask[]) : undefined,
};
}
export function normalizeCasesResponse(raw: unknown, filters: CaseFilters = {}): CasesResponse {
// The API may return either a bare array of cases or an envelope shape.
if (Array.isArray(raw)) {
const cases = raw.map(normalizeCase);
return {
cases,
total: cases.length,
page: filters.page ?? 1,
pageSize: filters.pageSize ?? cases.length,
};
}
const r = (raw ?? {}) as Record<string, unknown>;
const list = Array.isArray(r.cases) ? (r.cases as unknown[]).map(normalizeCase) : [];
return {
cases: list,
total: typeof r.total === "number" ? (r.total as number) : list.length,
page: typeof r.page === "number" ? (r.page as number) : (filters.page ?? 1),
pageSize:
typeof r.pageSize === "number"
? (r.pageSize as number)
: typeof r.page_size === "number"
? (r.page_size as number)
: (filters.pageSize ?? list.length),
};
}
export const casesApi = {
/** Explicit reopen — the sanctioned backwards status move (PATCH is
* forward-only and answers 422 on backwards transitions). */
async reopen(
caseId: string,
opts: { reason: string; status?: "new" | "triaged" | "investigating" }
): Promise<Case> {
const raw = await request<unknown>(`/api/v1/cases/${encodeURIComponent(caseId)}/reopen`, {
method: "POST",
body: JSON.stringify(opts),
});
return normalizeCase(raw);
},
list: async (filters: CaseFilters = {}) => {
// The status filter is passed through unchanged. It used to be rewritten
// through a five-state UI vocabulary, which could not express `contained`
// at all and mapped it onto `investigating` on the way back.
const params: Record<string, string> = {};
for (const [key, value] of Object.entries(filters)) {
if (value === undefined || value === null || value === "") continue;
params[key] = String(value);
}
const raw = await request<unknown>("/api/v1/cases", { params });
return normalizeCasesResponse(raw, filters);
},
get: async (id: string) => {
const raw = await request<unknown>(`/api/v1/cases/${id}`);
return normalizeCase(raw);
},
create: async (data: Partial<Case>) => {
// The backend CreateCaseRequest speaks snake_case and does NOT enable
// populate_by_name, so a raw camelCase Case payload silently drops fields
// like alertIds (the alert→case promotion never linked the alert). Map the
// UI fields the create flow uses onto the API schema explicitly.
const body: Record<string, unknown> = {};
if (data.title !== undefined) body.title = data.title;
if (data.description !== undefined) body.description = data.description;
if (data.severity !== undefined) body.severity = data.severity;
if (data.assignee !== undefined) body.assignee = data.assignee;
if (data.alertIds !== undefined) body.alert_ids = data.alertIds;
if (data.mitre !== undefined) body.mitre_techniques = data.mitre;
if (data.dueAt !== undefined) body.sla_due_at = data.dueAt;
const raw = await request<unknown>("/api/v1/cases", {
method: "POST",
body: JSON.stringify(body),
});
return normalizeCase(raw);
},
update: async (id: string, data: Partial<Case>) => {
const raw = await request<unknown>(`/api/v1/cases/${id}`, {
method: "PATCH",
body: JSON.stringify(data),
});
return normalizeCase(raw);
},
addComment: (id: string, comment: string) =>
request<{ id: string; comment: string; createdAt: string }>(`/api/v1/cases/${id}/comments`, {
method: "POST",
body: JSON.stringify({ comment }),
}),
linkAlerts: async (id: string, alertIds: string[]) => {
// Backend AddAlertsRequest expects snake_case `alert_ids`; sending
// `alertIds` raised a 422 and the alert was never attached to the case.
const raw = await request<unknown>(`/api/v1/cases/${id}/alerts`, {
method: "POST",
body: JSON.stringify({ alert_ids: alertIds }),
});
return normalizeCase(raw);
},
getTimeline: (id: string) =>
request<{ events: CaseTimelineEvent[] }>(`/api/v1/cases/${id}/timeline`),
addTask: (id: string, task: Partial<CaseTask>) =>
request<CaseTask>(`/api/v1/cases/${id}/tasks`, {
method: "POST",
body: JSON.stringify(task),
}),
updateTask: (caseId: string, taskId: string, task: Partial<CaseTask>) =>
request<CaseTask>(`/api/v1/cases/${caseId}/tasks/${taskId}`, {
method: "PATCH",
body: JSON.stringify(task),
}),
investigate: (caseId: string, alertSummary?: string) =>
request<{ run_id: string; case_id: string; status: string; message: string }>(
`/api/v1/cases/${caseId}/investigate`,
{
method: "POST",
body: JSON.stringify({ alert_summary: alertSummary ?? "" }),
}
),
getInvestigation: (caseId: string, runId: string) =>
request<{
run_id: string;
case_id: string;
status: string;
audit_log?: Array<{ kind: string; agent: string; summary: string; ts: string }>;
recon?: Record<string, unknown>;
forensic?: Record<string, unknown>;
responder?: Record<string, unknown>;
error?: string;
}>(`/api/v1/cases/${caseId}/investigations/${runId}`),
/**
* Attack-chain timeline visualization (T3.3 — v8.0).
*
* Backed by `/api/v1/cases/{id}/attack-chain` which runs a graph BFS over
* the case's seed alert and returns a ranked, time-ordered chain of
* related alerts plus a side-by-side entity graph. Severity stays as a
* lowercase string (info|low|medium|high|critical) to round-trip the
* five-tier ladder cleanly.
*
* Window defaults to 24h; the backend rejects unknown windows with 400.
* Returns `null` when the case has no linked alerts (the seed cannot be
* resolved). All other failures throw so SWR can surface them.
*/
getAttackChain: async (
caseId: string,
options: { window?: AttackChainWindow } = {}
): Promise<AttackChainTimeline | null> => {
const params: Record<string, string> = {};
if (options.window) params.window = options.window;
const raw = await request<BackendAttackChainResponse>(
`/api/v1/cases/${encodeURIComponent(caseId)}/attack-chain`,
{ params }
);
if (!raw.seed_alert_id) return null;
return {
caseId: raw.case_id,
tenantId: raw.tenant_id,
window: raw.window,
seedAlertId: raw.seed_alert_id,
chainSignature: raw.chain_signature ?? null,
confidence: typeof raw.confidence === "number" ? raw.confidence : 0,
generatedAt: raw.generated_at ?? new Date().toISOString(),
chain: (raw.chain ?? []).map((link) => ({
alertId: link.alert_id,
title: link.title,
severity: link.severity,
eventTime: link.event_time,
score: link.score,
distance: link.distance,
dtSeconds: link.dt_seconds,
sharedEntities: link.shared_entities ?? [],
mitreTechniques: link.mitre_techniques ?? [],
connectorType: link.connector_type ?? null,
sourceEventIds: link.source_event_ids ?? [],
})),
entityGraph: {
nodes: raw.entity_graph?.nodes ?? [],
edges: raw.entity_graph?.edges ?? [],
},
};
},
/** Trigger a browser download of the PDF report. */
downloadReportPdf: async (caseId: string, runId: string): Promise<void> => {
const resp = await fetch(
`${API_BASE}/api/v1/cases/${caseId}/investigations/${runId}/report.pdf`,
{
headers: apiHeaders(),
}
);
if (!resp.ok) {
const err = await resp.text().catch(() => resp.statusText);
throw new Error(err);
}
const blob = await resp.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = `aisoc-report-${runId}.pdf`;
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
URL.revokeObjectURL(url);
},
// WS-D2 — auto-summary at investigation close.
// The backend renders both the structured payload (json) and a print-ready
// page (html). We expose JSON for callers that want to drive their own UI
// (e.g. an inline drawer) and an "open in new tab" helper for the HTML
// artifact so operators can Cmd/Ctrl-P → Save as PDF for case-file archival.
/** Fetch the structured per-case auto-summary payload. */
getAutoSummary: (caseId: string) =>
request<CaseAutoSummary>(`/api/v1/cases/${caseId}/summary`, {
params: { format: "json" },
}),
/**
* Open the per-case auto-summary HTML artifact in a new tab.
*
* We deliberately fetch with the auth headers (instead of a plain
* ``window.open(url)``) because the backend requires the bearer token and
* tenant header — direct anchor navigation would drop them and 401.
* Mirrors the WS-G2 ``reportsApi.weeklyDigestHtml`` pattern so both
* report surfaces behave consistently in the PWA.
*/
openAutoSummaryHtml: async (caseId: string): Promise<void> => {
const headers = apiHeaders({ Accept: "text/html" });
const url = `${API_BASE}/api/v1/cases/${caseId}/summary?format=html`;
const response = await fetch(url, { headers, cache: "no-store" });
if (!response.ok) {
const detail = await response.text().catch(() => "");
throw new ApiError(
`API ${response.status} ${response.statusText} — /cases/${caseId}/summary`,
response.status,
detail
);
}
const blob = await response.blob();
const objectUrl = URL.createObjectURL(blob);
// Use a transient anchor so the print-ready page lands in its own tab.
const a = document.createElement("a");
a.href = objectUrl;
a.target = "_blank";
a.rel = "noopener";
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
// Hold the blob URL long enough for the new tab to read it, then release.
setTimeout(() => URL.revokeObjectURL(objectUrl), 60_000);
},
};
// ─── Investigation Ledger (persistent agent decision log) ───────────────────
//
// Backed by /v1/investigations endpoints. Every event the agent emits during
// an investigation is durably stored and replayable forever. The ledger UI
// renders this as a per-step timeline + side-panel "explain" view.
export interface LedgerRunSummary {
id: string;
case_id: string;
status: "running" | "completed" | "failed" | string;
model_used: string | null;
iterations: number;
total_tokens: number;
/** Measured (gateway-reported) spend; 0 with a 0 count means unmeasured. */
total_cost_usd: number;
measured_call_count: number;
estimated_cost_usd: number;
estimated_call_count: number;
unpriced_call_count: number;
started_at: string;
completed_at: string | null;
error: string | null;
}
export interface LedgerModelCost {
model: string;
/** What the gateway resolved ``model`` to; ``model`` is often an alias. */
resolved_model: string | null;
total_prompt_tokens: number;
total_completion_tokens: number;
total_cost_usd: number;
measured_call_count: number;
estimated_cost_usd: number;
estimated_call_count: number;
unpriced_call_count: number;
total_latency_ms: number;
call_count: number;
}
export interface LedgerRunDetail extends LedgerRunSummary {
alert_summary: string | null;
event_count: number;
artifact_count: number;
/**
* Per-model token/spend/latency breakdown. Empty list when the run pre-dates
* the cost-telemetry rollout or used no LLM models.
*/
model_costs: LedgerModelCost[];
}
export interface LedgerEvent {
id: string;
run_id: string;
seq: number;
ts: string;
kind: string;
agent: string;
summary: string;
payload: Record<string, unknown> | null;
input_hash: string | null;
output_hash: string | null;
duration_ms: number;
}
export interface LedgerEventList {
items: LedgerEvent[];
total: number;
since: number | null;
next_seq: number | null;
}
export interface LedgerArtifactSummary {
id: string;
kind: string;
sha256: string;
size_bytes: number;
event_id: string | null;
created_at: string;
}
export interface LedgerArtifactDetail extends LedgerArtifactSummary {
content: string | null;
blob_ref: string | null;
}
export interface LedgerExplain {
run: LedgerRunSummary;
previous: LedgerEvent | null;
focus: LedgerEvent;
next: LedgerEvent | null;
artifacts: LedgerArtifactDetail[];
}
export const ledgerApi = {
/** List investigation runs for the current tenant (optionally scoped to a case). */
listRuns: (params?: { caseId?: string; status?: string; limit?: number }) =>
request<LedgerRunSummary[]>("/api/v1/investigations", {
params: {
case_id: params?.caseId,
status: params?.status,
limit: params?.limit,
},
}),
/** Run summary + counts of attached events/artifacts. */
getRun: (runId: string) => request<LedgerRunDetail>(`/api/v1/investigations/${runId}`),
/** Paginated event timeline. Use `since` to tail. */
listEvents: (runId: string, params?: { since?: number; limit?: number }) =>
request<LedgerEventList>(`/api/v1/investigations/${runId}/events`, {
params: { since: params?.since, limit: params?.limit },
}),
/** Full ordered event list (bounded). */
replay: (runId: string, maxEvents = 10000) =>
request<LedgerEvent[]>(`/api/v1/investigations/${runId}/replay`, {
params: { max_events: maxEvents },
}),
/** "Why did the agent do this?" — previous → focus → next plus inlined artifacts. */
explain: (runId: string, step: number) =>
request<LedgerExplain>(`/api/v1/investigations/${runId}/explain`, {
params: { step },
}),
/** Artifact list for a run. */
listArtifacts: (runId: string) =>
request<LedgerArtifactSummary[]>(`/api/v1/investigations/${runId}/artifacts`),
/** Single artifact (full inlined content). */
getArtifact: (runId: string, artifactId: string) =>
request<LedgerArtifactDetail>(`/api/v1/investigations/${runId}/artifacts/${artifactId}`),
};
// ─── Metrics / Dashboard ─────────────────────────────────────────────────────
export interface DashboardMetrics {
period?: "1h" | "24h" | "7d" | "30d";
alerts: {
total: number;
new: number;
critical: number;
high: number;
medium: number;
low: number;
info?: number;
resolvedToday: number;
/** Unresolved alerts only (excludes resolved/closed). */
active?: number;
/** Unresolved critical alerts only. */
criticalActive?: number;
/** Alerts in resolved state (all time). */
resolved?: number;
/** Mean time to resolve, in **hours**, from closed cases. */
mttr: number;
/** Cases the mean was taken over. Zero means unmeasured, not zero hours. */
mttr_sample_count?: number;
};
cases: {
open: number;
inProgress: number;
resolvedThisWeek: number;
/** Created within the rolling 7d window. */
openedThisWeek?: number;
/** Closed (closed_at set) within the rolling 7d window. */
closedThisWeek?: number;
};
sources: Array<{ name: string; count: number; status: string }>;
topMitre: Array<{ tactic: string; count: number }>;
alertsTrend: Array<{ timestamp: string; count: number; severity: string }>;
threatsBySource: Array<{ source: string; count: number }>;
}
/**
* Funnel KPI metrics (PR-3 / W1).
*
* Mirrors ``FunnelMetrics`` Pydantic model in
* ``services/api/app/api/v1/endpoints/metrics.py``. Drives the
* ``FunnelKpiBar`` and ``EfficiencyReport`` widgets on the dashboard.
*/
export interface FunnelMetrics {
period: "1h" | "24h" | "7d" | "30d";
events_of_interest: number;
correlation_instances: number;
alerts_generated: number;
/** 0..1 ratio: 1 − (FP / total dispositioned alerts). */
signal_to_noise: number;
/** Mean time-to-detect in seconds (Alert.created_at → first_seen_at). */
mttd_seconds: number;
/** Active alerts owned by analysts (`status in new/triaging/in_progress`). */
analyst_queue_depth: number;
/** Alerts produced per correlation instance, clamped to [0, 1]. */
correlation_efficiency: number;
/** Alerts produced per event-of-interest, clamped to [0, 1]. */
alert_yield: number;
mitre_coverage: { covered: number; total: number; ratio: number };
/**
* Period-over-period deltas as **percentages**, e.g. `5.0` = +5%.
*
* This said "fraction, e.g. 0.05 = +5%", which is backwards: the
* backend's `_pct_delta` multiplies by 100 before returning, and
* `test_funnel_and_pipeline.py` pins `_pct_delta(150.0, 100.0) == 50.0`.
* The renderer believed the comment and scaled a second time.
*/
deltas: {
events_of_interest: number | null;
correlation_instances: number | null;
alerts_generated: number | null;
signal_to_noise: number | null;
mttd_seconds: number | null;
analyst_queue_depth: number | null;
};
/** ISO-8601 server timestamp. */
generated_at: string;
}
/**
* Pipeline health (PR-3 / W9).
*
* Mirrors ``PipelineHealth`` Pydantic model. Drives the
* ``PipelineHealth`` strip on /dashboard.
*/
export interface PipelineStage {
stage: "ingest" | "normalize" | "fuse" | "correlate" | "alert";
backlog: number;
p95_latency_ms: number;
error_rate: number;
status: "unknown" | "green" | "yellow" | "red";
/**
* Numeric fields above that this stage could not measure. They still carry
* `0` on the wire; render them as `n/a`, never as a value. Optional because
* an older API will not send it -- treat absent as "nothing declared",
* which is the pre-existing behaviour rather than a silent claim of
* full instrumentation.
*/
unmeasured?: string[];
}
export interface PipelineHealth {
/** Worst stage status, surfaced at the top of the pipeline rail. */
overall_status: "unknown" | "green" | "yellow" | "red";
stages: PipelineStage[];
/** ISO-8601 server timestamp. */
generated_at: string;
}
/**
* SOC Performance metrics (PR-3 / W2).
*
* Mirrors ``SOCMetrics`` Pydantic model in
* ``services/api/app/api/v1/endpoints/metrics.py``. Drives the SOC
* Performance panel + ATT&CK heatmap on /dashboard.
*/
export interface SOCKpis {
mttd_hours: number;
mttr_hours: number;
mttc_hours: number;
false_positive_rate: number;
escalation_rate: number;
alert_volume_7d: number;
cases_opened_7d: number;
cases_closed_7d: number;
analyst_overrides_7d: number;
/**
* How many rows each mean above was averaged over. Zero means the figure is
* unmeasured rather than zero — render "not measured", not "0.0 hrs".
* Optional so the console still works against an API that predates them.
*/
mttd_sample_count?: number;
mttr_sample_count?: number;
mttc_sample_count?: number;
/**
* The denominator each rate above was computed over. Zero means the rate is
* undefined rather than 0% — a tenant that has resolved nothing has not
* achieved a 0% false-positive rate. Optional for the same reason as the
* sample counts.
*/
false_positive_rate_sample_count?: number;
escalation_rate_sample_count?: number;
}
export interface AttackHeatmapCell {
tactic: string;
technique: string;
count: number;
}
export interface CalibrationBucket {
predicted_lower: number;
predicted_upper: number;
sample_count: number;
actual_tp_rate: number;
}
export interface SOCMetrics {
kpis: SOCKpis;
attack_heatmap: AttackHeatmapCell[];
calibration_curve: CalibrationBucket[];
}
/**
* Investigation cost telemetry (PR-3 / cost panel).
*
* Mirrors ``CostAggregate`` Pydantic model in
* ``services/api/app/api/v1/endpoints/investigations.py``.
*/
export interface CostAggregateRow {
model: string;
runs: number;
calls: number;
total_prompt_tokens: number;
total_completion_tokens: number;
total_cost_usd: number;
measured_call_count: number;
estimated_cost_usd: number;
estimated_call_count: number;
unpriced_call_count: number;
total_latency_ms: number;
/** Read with ``measured_call_count``: zero there means this is not a mean. */
avg_cost_per_run: number;
avg_latency_per_call_ms: number;
}
export interface CostAggregate {
window_days: number;
by_model: CostAggregateRow[];
totals: CostAggregateRow | null;
}
/**
* The windows every metrics route accepts, matching `_PERIOD_QUERY`'s pattern
* server-side and `TIME_WINDOWS` in `lib/timeWindow.ts`. Named once so the
* four call sites below cannot drift apart from each other.
*/
export type TimeWindowParam = "1h" | "24h" | "7d" | "30d";
export const metricsApi = {
/**
* Dashboard tiles for a time window.
*
* `period` was not a parameter: the console shipped a global time-window
* selector whose only consumer was itself, so changing it re-rendered a
* header and fetched nothing. Defaulted rather than required so no existing
* caller changes behaviour by omission.
*/
getDashboard: (period: TimeWindowParam = "24h") =>
request<DashboardMetrics>("/api/v1/metrics/dashboard", { params: { period } }),
getAlertTrend: (period: TimeWindowParam) =>
request<{ data: Array<{ timestamp: string; count: number }> }>(`/api/v1/metrics/alerts/trend`, {
params: { period },
}),
/** Funnel KPIs (events → correlations → alerts) with deltas. */
getFunnel: (period: TimeWindowParam = "24h") =>
request<FunnelMetrics>("/api/v1/metrics/funnel", { params: { period } }),
/** Per-stage pipeline health (ingest → normalize → fuse → correlate → alert). */
getPipelineHealth: () => request<PipelineHealth>("/api/v1/health/pipeline"),
/**
* SOC Performance KPIs + ATT&CK heatmap + calibration curve.
*
* Tenant-scoped server-side; the client just needs the bearer token
* and X-Tenant-Id header that `request()` already attaches.
*/
getSOC: (period: TimeWindowParam = "24h") =>
request<SOCMetrics>("/api/v1/metrics/soc", { params: { period } }),
};
// ─── Operational health: connector fleet, rejected events, alert posture ─────
//
// Three endpoints that existed server-side with no client. They answer the
// question the alert-centric dashboards structurally cannot: whether the
// absence of alerts means the estate is quiet or the pipeline stopped.
/** How a connector is doing against *its own* configured poll cadence. */
export type FleetHealthState = "healthy" | "degraded" | "failed" | "unproven" | "disabled";
export interface FleetConnectorHealth {
connector_id: string;
name: string;
connector_type: string;
state: FleetHealthState;
/** Operator-actionable wording from the server. Never bare "unhealthy". */
reason: string;
last_sync: string | null;
seconds_since_sync: number | null;
poll_interval_seconds: number;
/** How many poll cycles have been missed. Fractional. */
missed_intervals: number | null;
error_count: number;
events_ingested: number;
oauth_refresh_failures: number;
schema_drift_at: string | null;
}
export interface FleetHealth {
generated_at: string;
/** Worst enabled connector's state — deliberately not an average. */
state: FleetHealthState;
counts: Record<FleetHealthState, number>;
connectors: FleetConnectorHealth[];
}
export interface DeadLetterEntry {
id: string;
topic: string;
reason: string;
schema_version: string | null;
payload_excerpt: string | null;
source_event_id: string | null;
occurred_at: string | null;
acknowledged: boolean;
}
export interface DeadLetters {
window_hours: number;
total: number;
by_reason: Array<{ reason: string; count: number }>;
truncated: boolean;
dead_letters: DeadLetterEntry[];
}
export interface AlertStats {
total: number;
by_severity: Record<string, number>;
by_status: Record<string, number>;
new_last_24h: number;
critical_open: number;
}
export const operationsApi = {
/**
* Which connectors have quietly stopped working.
*
* Staleness is judged per connector against its own cadence, so a daily
* connector is not reported as failing eleven hours in.
*/
fleetHealth: () => request<FleetHealth>("/api/v1/health/fleet"),
/** Events the pipeline refused, and why. */
deadLetters: (params: { hours?: number; limit?: number } = {}) =>
request<DeadLetters>("/api/v1/health/dead-letters", {
params: params as Record<string, string>,
}),
/** Severity / status distribution plus the two counters worth paging on. */
alertStats: () => request<AlertStats>("/api/v1/alerts/stats"),
};
// ─── Investigations ─────────────────────────────────────────────────────────
export const investigationsApi = {
/**
* Investigation cost telemetry aggregated over the last `windowDays`.
* Backs the Cost Telemetry panel on /dashboard.
*/
getCostAggregate: (windowDays: number = 30) =>
request<CostAggregate>("/api/v1/investigations/costs/aggregate", {
params: { window_days: windowDays },
}),
};
// ─── SOC Insights (T3.1) ─────────────────────────────────────────────────────
//
// Backs the SOC Insights dashboard at /dashboards/soc-insights. The payload is
// intentionally flat — 7 tiles, each with a value, previous-window value,
// optional delta_pct (null when there's no prior data), and a 24-bucket
// sparkline. The page re-fetches on every `insights_updated` WebSocket poke.
export type InsightsWindow = "24h" | "7d" | "30d";
export interface InsightSparkline {
points: number[];
}
export interface InsightTile {
key: string;
label: string;
value: number;
/**
* Rows the mean was averaged over. `0` means the window measured
* nothing, so `value` is a placeholder rather than a result — the
* console renders "not measured" instead. Optional so a server that
* predates the field is handled without a cast.
*/
sample_count?: number;
unit: "hours" | "pct" | "count" | "usd" | "hours_saved";
previous_value: number;
delta_pct: number | null;
sparkline: InsightSparkline;
}
export interface SOCInsightsResponse {
window: InsightsWindow;
generated_at: string;
tenant_id: string;
tiles: InsightTile[];
manual_investigation_minutes: number;
}
export const insightsApi = {
/**
* Fetches the SOC Insights aggregate payload for the given window.
*
* The endpoint is tenant-scoped server-side; the client only needs to
* pick a window. SWR keys should include the window so flipping the
* filter doesn't show stale numbers from the previous range.
*/
getSOC: (window: InsightsWindow) =>
request<SOCInsightsResponse>("/api/v1/insights/soc", {
params: { window },
}),
};
// ─── Connectors ──────────────────────────────────────────────────────────────
export type ConnectorStatus = "active" | "inactive" | "error" | "configuring";
export interface Connector {
id: string;
name: string;
type: string;
status: ConnectorStatus;
/** `true` when the connector is enabled (separate from runtime status). */
enabled?: boolean;
tenantId?: string;
category?: string;
config?: Record<string, unknown>;
lastSync?: string;
/** Number of alerts ingested through this connector. */
alertCount?: number;
alertsIngested?: number;
errorMessage?: string;
description?: string;
createdAt?: string;
updatedAt?: string;
/** SHA-256 fingerprint of the most recent normalized event schema. */
schemaFingerprint?: string;
/** Timestamp of the most recent schema-drift event (null/undef if never). */
lastSchemaDriftAt?: string;
/** Human-readable diff for the most recent drift event. */
lastDriftDetails?: {
added?: string[];
removed?: string[];
previous_fingerprint?: string;
};
/** Cumulative count of events the pre-ingest filter dropped. */
eventsDropped?: number;
/**
* Timestamp of the most recently *ingested* normalized event.
*
* Distinct from `lastSync`, which advances on every poll cycle.
* `lastEventAt` only advances when an event actually lands — it's
* what feeds the freshness-SLO badge in the connectors list and
* the onboarding "verify data flowing" screen.
*/
lastEventAt?: string;
/** Short label for the most recent event source (e.g. "alert", "audit"). */
lastEventKind?: string;
/**
* Live freshness SLO verdict for the connector instance (Workstream 5).
*
* The server computes this from ``lastEventAt`` against a per-category
* cadence table (5 min for EDR, 15 min for SIEM, etc.) so a single
* Splunk that polls slowly doesn't drag the whole fleet to yellow. The
* UI badge renders directly from ``status`` — no client-side rule
* duplication so a future cadence change ships in one place.
*/
freshness?: {
status: "green" | "yellow" | "red" | "unknown";
expected_cadence_seconds: number;
seconds_since_last_event: number | null;
category: string;
};
}
export interface ConnectorsResponse {
connectors: Connector[];
total: number;
}
/** A single config field surfaced by ``BaseConnector.schema()`` on the backend. */
export interface ConnectorSchemaField {
name: string;
type: "string" | "secret" | "select" | "textarea" | "boolean" | "number";
label: string;
required?: boolean;
default?: string | number | boolean | null;
placeholder?: string;
help_text?: string;
options?: Array<{ value: string; label: string }>;
}
/** Forward-looking OAuth hints; rendered as "Hosted OAuth coming soon". */
export interface ConnectorOAuthHints {
supported_in_hosted?: boolean;
authorize_url?: string;
token_url?: string;
scopes?: string[];
}
/** A catalog entry: one available connector type with its config schema. */
export interface ConnectorCatalogEntry {
connector_id: string;
connector_name: string;
category: string;
description: string;
fields: ConnectorSchemaField[];
docs_url?: string;
oauth?: ConnectorOAuthHints;
}
export interface ConnectorCatalogResponse {
connectors: ConnectorCatalogEntry[];
}
/** Result of a "Test connection" call (pre-save or against a saved instance). */
export interface ConnectorTestResult {
success: boolean;
message?: string;
error?: string;
latency_ms?: number;
latencyMs?: number;
details?: Record<string, unknown>;
}
/** Raw shape returned by the API for a connector instance row. */
interface BackendConnectorResponse {
id: string;
tenant_id: string;
name: string;
connector_type: string;
category: string;
is_enabled: boolean;
connector_config: Record<string, unknown>;
health_status: string;
last_health_check: string | null;
last_sync: string | null;
events_ingested: number;
error_count: number;
tags: string[];
created_at: string;
updated_at: string;
schema_fingerprint?: string | null;
last_schema_drift_at?: string | null;
last_drift_details?: {
added?: string[];
removed?: string[];
previous_fingerprint?: string;
} | null;
events_dropped?: number | null;
// Workstream 1: distinct from `last_sync` — only advances when a
// normalized event actually lands. The verify-data-flowing screen
// and freshness-SLO badge both read from here.
last_event_at?: string | null;
last_event_kind?: string | null;
// Workstream 5: freshness SLO computed server-side from ``last_event_at``
// against a per-category cadence table. Optional because the API may
// omit it for connectors that haven't ingested yet (the server still
// emits an ``unknown`` verdict, but defensive null-handling lets the
// UI degrade gracefully if the field is ever stripped).
freshness?: {
status: "green" | "yellow" | "red" | "unknown";
expected_cadence_seconds: number;
seconds_since_last_event: number | null;
category: string;
} | null;
}
/** Aggregated health summary for the connectors fleet (a single tenant). */
export interface ConnectorHealthSummary {
total: number;
healthy: number;
unhealthy: number;
unknown: number;
/** Connectors whose schema has ever drifted. */
drifted: number;
/** Connectors whose schema drifted in the last 24h. */
driftedRecently: number;
/** Most-recent drift timestamp across the fleet. */
lastDriftAt?: string;
/** Cumulative events ingested across all enabled connectors. */
totalEventsIngested: number;
/** Cumulative events dropped by pre-ingest filter rules. */
totalEventsDropped: number;
}
/**
* Map the backend ``health_status`` enum (``healthy``/``unhealthy``/``unknown``)
* to the frontend ``ConnectorStatus`` (``active``/``inactive``/``error``/
* ``configuring``). The mapping also folds in ``is_enabled`` because a disabled
* connector should always render as ``inactive`` in the UI regardless of its
* last health check.
*/
function deriveConnectorStatus(row: BackendConnectorResponse): ConnectorStatus {
if (!row.is_enabled) return "inactive";
switch (row.health_status) {
case "healthy":
return "active";
case "unhealthy":
case "error":
return "error";
case "unknown":
case "":
return "configuring";
default:
return "configuring";
}
}
function mapBackendConnector(row: BackendConnectorResponse): Connector {
return {
id: row.id,
name: row.name,
type: row.connector_type,
category: row.category,
status: deriveConnectorStatus(row),
enabled: row.is_enabled,
tenantId: row.tenant_id,
config: row.connector_config,
lastSync: row.last_sync ?? undefined,
alertCount: row.events_ingested,
alertsIngested: row.events_ingested,
createdAt: row.created_at,
updatedAt: row.updated_at,
schemaFingerprint: row.schema_fingerprint ?? undefined,
lastSchemaDriftAt: row.last_schema_drift_at ?? undefined,
lastDriftDetails: row.last_drift_details ?? undefined,
eventsDropped: row.events_dropped ?? 0,
lastEventAt: row.last_event_at ?? undefined,
lastEventKind: row.last_event_kind ?? undefined,
freshness: row.freshness ?? undefined,
};
}
export interface CreateConnectorPayload {
name: string;
connector_type: string;
category?: string;
auth_config?: Record<string, unknown>;
connector_config?: Record<string, unknown>;
tags?: string[];
}
export interface UpdateConnectorPayload {
name?: string;
is_enabled?: boolean;
auth_config?: Record<string, unknown>;
connector_config?: Record<string, unknown>;
tags?: string[];
}
export interface TestConnectorPayload {
connector_type: string;
auth_config?: Record<string, unknown>;
connector_config?: Record<string, unknown>;
}
/**
* Watermark response polled by the wizard's "verify data flowing" panel.
*
* The shape mirrors ``LastEventResponse`` from the API service. Note
* the field is intentionally distinct from ``last_sync``: ``last_sync``
* advances on every poll cycle (including empty polls), while
* ``last_event_at`` only advances when a normalized event actually
* lands in ``raw_events``. ``data_flowing`` is the server's own
* answer to "is data live?" so every client agrees on the rule.
*/
export interface ConnectorLastEvent {
connector_id: string;
last_event_at: string | null;
last_event_kind: string | null;
events_ingested: number;
last_sync: string | null;
health_status: string;
data_flowing: boolean;
}
/**
* Input to the AI troubleshooter. We intentionally send only the
* **keys** of ``auth_config`` (not values) so the backend can hint
* about which field to revisit without ever seeing the credential.
*/
export interface TroubleshootRequest {
connector_type: string;
error: string;
auth_config_keys?: string[];
}
/** Structured fix suggestion the wizard renders next to a failed test. */
export interface TroubleshootResponse {
likely_cause: string;
fix_steps: string[];
doc_link?: string | null;
}
/** Push-token reveal response. */
export interface IngestTokenResponse {
connector_id: string;
ingest_token: string;
inbox_url: string;
}
export const connectorsApi = {
/**
* List connector instances for the current tenant.
*
* The backend returns a raw ``list[ConnectorResponse]``; we wrap it in a
* ``ConnectorsResponse`` envelope and map each row from snake_case to the
* camelCase frontend shape so views never have to reach into raw API rows.
*/
list: async (): Promise<ConnectorsResponse> => {
const rows = await request<BackendConnectorResponse[]>("/api/v1/connectors");
const connectors = rows.map(mapBackendConnector);
return { connectors, total: connectors.length };
},
/** Catalog of available connector types (one entry per registered class). */
catalog: () => request<ConnectorCatalogResponse>("/api/v1/connectors/catalog"),
get: async (id: string): Promise<Connector> => {
const row = await request<BackendConnectorResponse>(`/api/v1/connectors/${id}`);
return mapBackendConnector(row);
},
create: async (data: CreateConnectorPayload): Promise<Connector> => {
const row = await request<BackendConnectorResponse>("/api/v1/connectors", {
method: "POST",
body: JSON.stringify(data),
});
return mapBackendConnector(row);
},
update: async (id: string, data: UpdateConnectorPayload): Promise<Connector> => {
const row = await request<BackendConnectorResponse>(`/api/v1/connectors/${id}`, {
method: "PATCH",
body: JSON.stringify(data),
});
return mapBackendConnector(row);
},
/** Run "Test connection" against a saved instance. */
test: (id: string) =>
request<ConnectorTestResult>(`/api/v1/connectors/${id}/test`, {
method: "POST",
}),
/** Run "Test connection" with un-saved credentials from the wizard. */
testInline: (payload: TestConnectorPayload) =>
request<ConnectorTestResult>("/api/v1/connectors/test", {
method: "POST",
body: JSON.stringify(payload),
}),
/**
* Ask the AI troubleshooter to classify a failed test.
*
* Used by the AddConnector wizard immediately after `test` or
* `testInline` returns ``success=false``. Renders into the
* "Likely cause / fix steps / docs" callout in the modal.
*/
troubleshoot: (payload: TroubleshootRequest) =>
request<TroubleshootResponse>("/api/v1/connectors/troubleshoot", {
method: "POST",
body: JSON.stringify(payload),
}),
/**
* Poll the verify-data-flowing watermark for a connector.
*
* Distinct from `lastSync`: this only advances when an actual
* normalized event lands. Returned even when no event has ever
* landed (with `data_flowing=false`) so the polling loop can have
* stable shape rather than a 404.
*/
lastEvent: (id: string) => request<ConnectorLastEvent>(`/api/v1/connectors/${id}/last_event_at`),
/**
* Generate or rotate the per-connector push-ingest token.
*
* Used by the wizard's "Push (any vendor)" path to surface a
* `curl` example. Calling this rotates the token; the previous
* one is invalidated immediately.
*/
refreshIngestToken: (id: string) =>
request<IngestTokenResponse>(`/api/v1/connectors/${id}/push/refresh`, {
method: "POST",
}),
delete: (id: string) => request<void>(`/api/v1/connectors/${id}`, { method: "DELETE" }),
/**
* Aggregated health summary for the connectors fleet.
*
* Surfaces healthy/degraded/error counts, schema-drift events seen in the
* last 24h, and the cumulative count of events the pre-ingest filter
* dropped. Used by the Connectors page header strip and the new
* "Connector Health" widget on the dashboard.
*/
health: async (): Promise<ConnectorHealthSummary> => {
const raw = await request<{
total: number;
healthy: number;
unhealthy: number;
unknown: number;
drifted: number;
drifted_recently: number;
last_drift_at: string | null;
total_events_ingested: number;
total_events_dropped: number;
}>("/api/v1/connectors/health");
return {
total: raw.total,
healthy: raw.healthy,
unhealthy: raw.unhealthy,
unknown: raw.unknown,
drifted: raw.drifted,
driftedRecently: raw.drifted_recently,
lastDriftAt: raw.last_drift_at ?? undefined,
totalEventsIngested: raw.total_events_ingested,
totalEventsDropped: raw.total_events_dropped,
};
},
};
// ─── Universal capture / inbox tokens (Workstream 6) ───────────────────────
/**
* Catalog entry for a vendor template the operator can pick when minting
* an inbox URL. Mirrors `InboxTemplateInfo` on the API side; the wizard
* groups by `category` to keep the picker scannable.
*/
export interface InboxTemplate {
template_id: string;
label: string;
description: string;
category: string;
}
/** Existing inbox token row — list view, plaintext token NOT included. */
export interface InboxTokenListItem {
fingerprint: string;
template_id: string;
label: string | null;
has_hmac_secret: boolean;
created_at: string;
revoked_at: string | null;
last_used_at: string | null;
}
/**
* Mint / rotate response. `token` is the plaintext (returned exactly once
* at mint or rotate time); `inbox_url` is the absolute URL the operator
* pastes into the vendor's webhook config.
*/
export interface InboxTokenSecret {
token: string;
inbox_url: string;
template_id: string;
label: string | null;
has_hmac_secret: boolean;
created_at: string;
revoked_at: string | null;
last_used_at: string | null;
}
/** Body for `POST /api/v1/inbox/tokens`. */
export interface MintInboxTokenPayload {
template_id: string;
label?: string | null;
hmac_secret?: string | null;
}
export const inboxApi = {
/** List vendor templates the operator can mint inbox URLs for. */
templates: () => request<InboxTemplate[]>("/api/v1/inbox/templates"),
/** List the calling tenant's inbox tokens (revoked filtered out). */
list: (params?: { include_revoked?: boolean }) => {
const qs = params?.include_revoked ? "?include_revoked=true" : "";
return request<InboxTokenListItem[]>(`/api/v1/inbox/tokens${qs}`);
},
/** Mint a new inbox token. Plaintext returned exactly once. */
mint: (payload: MintInboxTokenPayload) =>
request<InboxTokenSecret>("/api/v1/inbox/tokens", {
method: "POST",
body: JSON.stringify(payload),
}),
/**
* Rotate an existing token: mints a new one with the same template / label
* / HMAC, revokes the old. Returns the new plaintext exactly once.
*/
rotate: (fingerprint: string) =>
request<InboxTokenSecret>(`/api/v1/inbox/tokens/${encodeURIComponent(fingerprint)}/rotate`, {
method: "POST",
}),
/** Permanently revoke an inbox token. */
revoke: (fingerprint: string) =>
request<void>(`/api/v1/inbox/tokens/${encodeURIComponent(fingerprint)}`, { method: "DELETE" }),
};
// ─── Hosted OAuth (Workstream 2) ──────────────────────────────────────────────
/**
* Per-tenant OAuth client registration, returned by GET / PUT
* `/api/v1/oauth/app/{connector_type}`.
*
* The secret is *never* round-tripped to the browser — only `has_secret`
* lets the UI render a "credential present" badge. To rotate the
* client_secret, call `oauthApi.upsertApp()` with a fresh value.
*/
export interface OAuthAppView {
connector_type: string;
client_id: string;
has_secret: boolean;
authorize_url: string | null;
token_url: string | null;
scopes: string[] | null;
created_at: string;
updated_at: string;
}
/**
* Payload accepted by `PUT /api/v1/oauth/app/{connector_type}`.
*
* `authorize_url`, `token_url`, and `scopes` are optional — when omitted,
* the backend falls back to the connector class's `OAuthHints` defaults
* (e.g. Okta / Azure AD / GitHub).
*/
export interface OAuthAppRegistrationPayload {
client_id: string;
client_secret: string;
authorize_url?: string | null;
token_url?: string | null;
scopes?: string[] | null;
}
/**
* Response from `GET /api/v1/oauth/start?response_mode=json`.
*
* The default `response_mode=redirect` returns a 302; SPAs that want to
* handle the redirect themselves (e.g. open the consent screen in a
* popup) call with `response_mode=json` and use this shape.
*/
export interface OAuthStartResponse {
authorize_url: string;
state: string;
}
/**
* Options for `oauthApi.startUrl()` — the helper that builds the
* canonical `/api/v1/oauth/start?...` URL the browser navigates to.
*
* `connector_id` is set when the operator is *re-authing* an existing
* connector instance (token expired, scope upgrade); otherwise omit it
* and the callback will INSERT a fresh `connectors` row.
*
* `extras` ride along in the state row and end up in the connector's
* `connector_config` after callback (e.g. `organization` for GitHub,
* `cloud_id` for Atlassian).
*/
export interface OAuthStartOptions {
connectorType: string;
connectorId?: string;
returnTo?: string;
name?: string;
extras?: Record<string, unknown>;
}
export const oauthApi = {
/**
* Fetch the registered OAuth app for a connector class. Returns 404
* until the operator has called `upsertApp()` at least once.
*/
getApp: (connectorType: string) =>
request<OAuthAppView>(`/api/v1/oauth/app/${encodeURIComponent(connectorType)}`),
/**
* Register or rotate the tenant's OAuth client for a connector class.
* The backend encrypts `client_secret` at rest via the credential vault.
*/
upsertApp: (connectorType: string, payload: OAuthAppRegistrationPayload) =>
request<OAuthAppView>(`/api/v1/oauth/app/${encodeURIComponent(connectorType)}`, {
method: "PUT",
body: JSON.stringify(payload),
}),
/** Unregister the tenant's OAuth client for a connector class. */
deleteApp: (connectorType: string) =>
request<void>(`/api/v1/oauth/app/${encodeURIComponent(connectorType)}`, { method: "DELETE" }),
/**
* Build the `/api/v1/oauth/start?...` URL. The caller does
* `window.location.assign(oauthApi.startUrl({...}))` to kick off the
* hosted OAuth dance — we don't fetch this ourselves because the
* server response is a 302 to the provider, not JSON the SPA wants
* to parse.
*
* Returns a same-origin URL so Next.js rewrites can proxy to the API.
*/
startUrl: (opts: OAuthStartOptions): string => {
const params = new URLSearchParams();
params.set("connector_type", opts.connectorType);
if (opts.connectorId) params.set("connector_id", opts.connectorId);
if (opts.returnTo) params.set("return_to", opts.returnTo);
if (opts.name) params.set("name", opts.name);
if (opts.extras && Object.keys(opts.extras).length > 0) {
params.set("extras", JSON.stringify(opts.extras));
}
return `${API_BASE}/api/v1/oauth/start?${params.toString()}`;
},
/**
* JSON variant of `startUrl()`: instead of redirecting, the API
* returns `{ authorize_url, state }` so a popup-based UX can drive
* the consent screen itself.
*/
startJson: (opts: OAuthStartOptions) => {
const params: Record<string, string> = {
connector_type: opts.connectorType,
response_mode: "json",
};
if (opts.connectorId) params.connector_id = opts.connectorId;
if (opts.returnTo) params.return_to = opts.returnTo;
if (opts.name) params.name = opts.name;
if (opts.extras && Object.keys(opts.extras).length > 0) {
params.extras = JSON.stringify(opts.extras);
}
return request<OAuthStartResponse>("/api/v1/oauth/start", { params });
},
};
// ─── Threat Intel ─────────────────────────────────────────────────────────────
export type IndicatorType = "ip" | "domain" | "hash" | "url" | "email";
/**
* A canonical threat indicator surfaced by the threatintel service.
*
* Carries the analyst-facing fields used by the IOC inbox (severity,
* confidence, tags) plus the raw lookup data (sources, geo, ASN).
*/
export interface ThreatIndicator {
id: string;
type: IndicatorType;
value: string;
/** 0-100 confidence score blended across providers. */
confidence: number;
severity: AlertSeverity;
malicious: boolean;
tags?: string[];
sources: string[];
firstSeen?: string;
lastSeen?: string;
description?: string;
country?: string;
asn?: string;
mitre?: string[];
}
export interface IOCLookup extends ThreatIndicator {
/** Free-form provider blob (kept around for power users). */
raw?: Record<string, unknown>;
}
/**
* The outcome of one IOC lookup. Three states, deliberately — "the store
* answered and holds nothing on this indicator" and "the store did not
* answer" are different facts, and only the first of them is good news.
*
* Collapsing them is what the console used to do: the lookup `catch` set a
* `notFound` flag that rendered a green **CLEAN — no threat indicators found
* for this IOC**, so a transport error, a 5xx, or a route that did not exist
* all read to an analyst as an all-clear on the indicator they were checking.
* It called `/api/v1/enrichment/lookup`, which the API does not serve, so
* every lookup took that branch and the panel had only ever said "clean".
*/
export type IOCLookupOutcome =
| { status: "match"; indicator: ThreatIndicator }
| { status: "clean" }
| { status: "failed"; reason: string };
export const threatIntelApi = {
/**
* Look one indicator up in the tenant's threat-intel store.
*
* Goes to `/api/v1/threat-intel/indicators`, the route that serves the
* page's own list — so the lookup reads the same store the table does, and
* a match here is an indicator the deployment actually holds. The response
* carries `degraded`/`reason`, which the backend already sets when it
* answered from a fallback or could not reach its index; that is treated as
* a failed lookup rather than a clean one, because a partial store cannot
* support "we hold nothing on this".
*/
lookup: async (ioc: string): Promise<IOCLookupOutcome> => {
let response: {
indicators?: ThreatIndicator[];
degraded?: boolean;
reason?: string;
};
try {
response = await request("/api/v1/threat-intel/indicators", { params: { q: ioc } });
} catch (err) {
const status = err instanceof ApiError ? err.status : undefined;
// status 0 is `request`'s own marker for "never reached the server".
const detail =
status === undefined || status === 0
? "the threat-intel service could not be reached"
: `the threat-intel service answered HTTP ${status}`;
return { status: "failed", reason: detail };
}
if (response.degraded) {
return {
status: "failed",
reason: response.reason?.trim() || "the threat-intel store answered from a degraded source",
};
}
const match = (response.indicators ?? []).find(
(candidate) => candidate.value?.toLowerCase() === ioc.toLowerCase()
);
return match ? { status: "match", indicator: match } : { status: "clean" };
},
// `bulkLookup` used to live here. It posted `{ iocs: [...] }` to
// `/api/v1/enrichment/bulk` and had **zero callers**. That path is not
// served by the API — measured against a running stack, 404 — and the
// request shape was not the one the enrichment service reads either
// (`POST /enrich/bulk` takes `{ items: [...] }`). It is deleted rather
// than repointed: an exported helper aimed at a route that does not exist
// is a loaded gun, because whoever wires it up first gets a rejected
// promise and, following the shape `lookup` used to have, renders it as a
// clean verdict. A bulk lookup can be written against
// `/api/v1/threat-intel/indicators` — the route `lookup` uses — when
// something needs one.
// `total` is the store's count of indicators in scope; `shown` is how many
// this response carries. They are different numbers and the console renders
// both — it used to render the page length as the catalogue size.
//
// `degraded`/`reason` are on the type because the route sets them and the
// list path was throwing them away. Measured against a running stack with
// no threat-intel service, this route answers **HTTP 200** with
// `{"indicators":[],"total":0,"degraded":true,"reason":"the threat-intel
// service did not answer (ConnectError); no indicators can be listed"}` —
// so a consumer keying only on "did the request succeed" reads an explicit
// non-measurement as a measurement of zero. `lookup` above already treats
// the same flag as a failed lookup.
list: (filters: { type?: IndicatorType; tag?: string; q?: string } = {}) =>
request<{
indicators: ThreatIndicator[];
total: number;
shown?: number;
bounded?: boolean;
degraded?: boolean;
reason?: string;
}>("/api/v1/threat-intel/indicators", { params: filters as Record<string, string> }),
};
// ─── AI Agents ────────────────────────────────────────────────────────────────
export interface AgentInvestigation {
id: string;
alertId: string;
status: "pending" | "running" | "completed" | "failed";
findings?: string;
recommendations?: string[];
actions?: Array<{ type: string; target: string; status: string }>;
startedAt: string;
completedAt?: string;
}
export const agentsApi = {
/**
* Stream a structured "Explain this alert" walkthrough as NDJSON.
*
* Each line in `response.body` is one {@link ExplainStreamFrame}.
* Returns the raw `Response` because the drawer renders frames as
* they arrive — see `ExplainDrawer.tsx` for the consumer.
*/
explainStream: (
payload: { alert: Record<string, unknown>; alertId?: string },
signal?: AbortSignal
) =>
fetch(`${AGENTS_BASE}/api/v1/explain`, {
method: "POST",
headers: apiHeaders(),
body: JSON.stringify({
alert: payload.alert,
alert_id: payload.alertId,
tenant_id: getActiveTenantId(),
}),
signal,
}),
};
// ─── Explain endpoint frames ─────────────────────────────────────────────────
//
// One frame per NDJSON line. The drawer routes each frame by `kind` and
// appends to the matching section, so order matters: `section` opens a
// section, subsequent typed frames fill it, and `done` closes the stream.
export interface ExplainSectionFrame {
kind: "section";
id: "summary" | "ocsf" | "mitre" | "evidence" | "next";
title: string;
}
export interface ExplainDeltaFrame {
kind: "delta";
section: "summary";
text: string;
}
export interface ExplainOcsfFrame {
kind: "ocsf";
category: string;
category_uid: number;
class: string;
class_uid: number;
activity: string;
fields: Record<string, unknown>;
}
export interface ExplainMitreFrame {
kind: "mitre";
id: string;
name: string;
tactic_names: string[];
description: string;
url: string;
found: boolean;
}
export interface ExplainEvidenceFrame {
kind: "evidence";
label: string;
value: string;
annotation: string;
}
export interface ExplainNextStepFrame {
kind: "next_step";
title: string;
rationale: string;
playbook_id: string | null;
}
export interface ExplainDoneFrame {
kind: "done";
alert_id: string;
}
export interface ExplainErrorFrame {
kind: "error";
error: string;
}
export type ExplainStreamFrame =
| ExplainSectionFrame
| ExplainDeltaFrame
| ExplainOcsfFrame
| ExplainMitreFrame
| ExplainEvidenceFrame
| ExplainNextStepFrame
| ExplainDoneFrame
| ExplainErrorFrame;
// ─── Structured Alert Explanation (POST /api/v1/alerts/{id}/explain) ────────
//
// Stage 2 #6 added a *structured* one-shot explainer alongside the agents
// service's NDJSON streaming explainer. Where the stream emits tokens for
// a typewriter UX, this endpoint returns the *whole* answer in one JSON
// envelope — including richer context the streaming endpoint doesn't have:
//
// * `rule_lineage` — which detection rule fired (best-effort,
// with a confidence band on the match itself)
// * `historical_fp_rate` — live false-positive rate over the last 30
// days, scoped to rule, technique, category,
// or tenant (whichever has enough samples)
// * deterministic-or-LLM `summary` (with `llm_used` + `llm_reason` so
// the UI can disclose when the prose was generated vs. fallback)
//
// The dataclass shape mirrors `services/api/app/services/alert_explain.py`.
// Keep the two in sync; the backend serializes via `dataclasses.asdict`.
/** Lineage of the detection rule that produced an alert. */
export interface RuleLineage {
rule_id: string | null;
rule_name: string | null;
rule_description: string | null;
rule_status: string | null;
rule_severity: string | null;
rule_confidence: number | null;
rule_language: string | null;
is_builtin: boolean;
/** Confidence in the lineage *match itself*, not the rule's own confidence. */
confidence: "high" | "medium" | "low";
/**
* How the lineage was resolved. `none` means we couldn't match any rule.
* `raw_event` / `tags` are deterministic; `mitre_overlap` and `category`
* are best-effort guesses.
*/
match_method: "raw_event" | "tags" | "mitre_overlap" | "category" | "none";
}
/** Live false-positive rate for the matched rule (or fallback scope). */
export interface HistoricalFpRate {
fp_rate: number;
sample_size: number;
false_positives: number;
lookback_days: number;
/** Which scope was used. Narrower = more relevant; broader = more samples. */
scope: "rule" | "category" | "technique" | "tenant";
/** Human-readable description of which scope was used and why. */
notes: string;
}
/** A deterministic, hand-curated suggested next step. */
export interface SuggestedAction {
title: string;
rationale: string;
/** ID of a playbook the user can launch directly, or null if N/A. */
playbook_id: string | null;
priority: "immediate" | "soon" | "fyi";
}
/** A single signal from the raw event that contributed to the alert. */
export interface ContributingEvent {
label: string;
value: string;
/** Optional hint about why this signal mattered (e.g. "matched rule pattern"). */
annotation?: string;
}
/** Resolved MITRE ATT&CK technique card (id, name, tactics, link). */
export interface MitreTechniqueCard {
id: string;
name: string;
tactic_names: string[];
description: string;
url: string;
}
/** Top-level structured explanation envelope. */
export interface AlertExplanation {
alert_id: string;
summary: string;
rule_lineage: RuleLineage;
contributing_events: ContributingEvent[];
mitre_techniques: MitreTechniqueCard[];
historical_fp_rate: HistoricalFpRate;
suggested_actions: SuggestedAction[];
/** True when the summary was LLM-generated; false → deterministic fallback. */
llm_used: boolean;
/** Source of the summary: `tenant_byok`, `platform_default`, `deterministic`, etc. */
llm_source: string;
/** When `llm_used=false`, why we fell back (e.g. `airgap_blocked`, `no_credential`). */
llm_reason: string;
/** ISO-8601 timestamp the explanation was generated. */
generated_at: string;
}
// ─── Hunt / Search ───────────────────────────────────────────────────────────
export interface HuntQuery {
query: string;
language?: "kql" | "lucene" | "sql" | "esql";
startTime?: string;
endTime?: string;
limit?: number;
}
export interface HuntResult {
id: string;
timestamp: string;
source: string;
severity?: AlertSeverity;
fields: Record<string, unknown>;
highlight?: string;
}
export interface HuntResponse {
total: number;
took: number;
hits: HuntResult[];
}
export interface SavedSearch {
id: string;
name: string;
query: string;
language: string;
createdAt: string;
pinned?: boolean;
}
/** What `POST /api/v1/agents/hunt` answers. */
export interface AgentHuntResponse {
hypothesis: string;
/**
* Whether the hunt *ran*. Not the same as `matches.length > 0`: a hunt
* that could not run is not a hunt that found nothing, and collapsing
* the two is how a console shows a reassuring empty result for a search
* that never happened. False always carries an `unavailable_reason`.
*/
checked: boolean;
matches: Record<string, unknown>[];
/** Plans the validator would not run. Shown, not swallowed. */
refusals: string[];
unavailable_reason: string | null;
}
export const huntApi = {
/**
* Natural-language hunting through the agent (parity 6.1).
*
* The agent plans; the planner validates every attempt against the
* allowed shape. The model never writes a query directly. The tenant
* comes from the caller's token server-side and is deliberately not a
* parameter here.
*/
runAgentHunt: (hypothesis: string) =>
request<AgentHuntResponse>("/api/v1/agents/hunt", {
method: "POST",
body: JSON.stringify({ hypothesis }),
}),
search: (query: HuntQuery) =>
request<HuntResponse>("/api/v1/hunt/search", {
method: "POST",
body: JSON.stringify(query),
}),
listSaved: () => request<{ searches: SavedSearch[] }>("/api/v1/hunt/saved"),
saveSearch: (data: Pick<SavedSearch, "name" | "query" | "language">) =>
request<SavedSearch>("/api/v1/hunt/saved", {
method: "POST",
body: JSON.stringify(data),
}),
deleteSaved: (id: string) => request<void>(`/api/v1/hunt/saved/${id}`, { method: "DELETE" }),
};
// ─── Event lake (Phase A1/C1) ────────────────────────────────────────────────
//
// Wraps `services/api/app/api/v1/endpoints/lake.py`. `/lake/sql` runs a
// tenant-scoped SELECT against the ClickHouse warm tier (the server injects the
// `tenant_id` predicate before execution); `/lake/schema` returns the
// allowlisted tables + columns the Explore surface renders as a schema helper.
export interface LakeQueryRequest {
sql: string;
row_cap?: number;
timeout_seconds?: number;
}
export interface LakeQueryResponse {
columns: string[];
rows: unknown[][];
row_count: number;
row_cap: number;
referenced_tables: string[];
elapsed_ms: number;
executed_at: string;
}
export interface LakeColumnInfo {
name: string;
type: string;
comment: string;
}
export interface LakeTableInfo {
table: string;
columns: LakeColumnInfo[];
}
export interface LakeSchemaResponse {
tables: LakeTableInfo[];
}
export const lakeApi = {
sql: (body: LakeQueryRequest) =>
request<LakeQueryResponse>("/api/v1/lake/sql", {
method: "POST",
body: JSON.stringify(body),
}),
schema: () => request<LakeSchemaResponse>("/api/v1/lake/schema"),
};
// ─── Federated SIEM search ───────────────────────────────────────────────────
//
// Client for `services/api/app/api/v1/endpoints/federated.py`, which fans one
// `UnifiedQuery` out to every federated-capable connector the tenant has
// enabled (Splunk, Microsoft Sentinel, Elastic, QRadar) using that tenant's
// own vault-encrypted credentials, and merges the rows.
//
// The shape worth preserving through the client is `sources[]`. The endpoint
// deliberately never fails the whole call because one backend is slow, 401s or
// 5xxs — it returns a per-backend verdict instead. Collapsing that into a
// single throw would discard exactly the information an analyst needs to tell
// "Sentinel has nothing" from "Sentinel did not answer", so nothing here
// treats a per-source error as a request error.
/** Operator vocabulary accepted by `Indicator` in the connectors service. */
export type FederatedOperator =
"eq" | "ne" | "contains" | "starts_with" | "ends_with" | "gt" | "gte" | "lt" | "lte" | "in";
export const FEDERATED_OPERATORS: readonly FederatedOperator[] = [
"eq",
"ne",
"contains",
"starts_with",
"ends_with",
"gt",
"gte",
"lt",
"lte",
"in",
] as const;
/** One `field <op> value` triple. Stacking indicators implies AND. */
export interface FederatedIndicator {
field: string;
operator: FederatedOperator;
value: unknown;
}
export interface FederatedSearchRequest {
free_text?: string;
indicators?: FederatedIndicator[];
since_seconds?: number;
limit?: number;
connector_ids?: string[] | null;
per_backend_timeout_seconds?: number | null;
}
/**
* Per-backend outcome.
*
* `status` is `ok` (rows returned, possibly zero), `error` (this backend
* failed and `error` carries the message; others may have succeeded), or
* `unsupported` (the connector type does not speak federated search).
*/
export interface FederatedSourceVerdict {
connector_id: string;
connector_name: string;
connector_type: string;
status: "ok" | "error" | "unsupported";
row_count: number;
duration_ms: number;
error: string | null;
}
/** Source tag the API stamps onto every merged row. */
export interface FederatedRowSource {
connector_id: string;
connector_name: string;
connector_type: string;
}
export type FederatedRow = Record<string, unknown> & {
_aisoc_source?: FederatedRowSource;
};
export interface FederatedSearchResponse {
rows: FederatedRow[];
row_count: number;
sources: FederatedSourceVerdict[];
truncated: boolean;
}
export interface FederatedBackend {
connector_id: string;
connector_type: string;
name: string;
health_status: string;
is_enabled: boolean;
}
export interface FederatedBackendsResponse {
backends: FederatedBackend[];
}
/**
* Thrown when the deployment has `AISOC_FEATURE_FED_SEARCH=false`.
*
* The endpoint answers 404 for that case, which is indistinguishable from a
* routing mistake unless the client names it. A disabled feature is a
* configuration fact the operator can act on; a generic "not found" is not.
*/
export class FederatedSearchDisabledError extends Error {
constructor() {
super("Federated search is disabled on this deployment (AISOC_FEATURE_FED_SEARCH).");
this.name = "FederatedSearchDisabledError";
}
}
function asFederatedError(err: unknown): never {
// `_ensure_feature_enabled` answers 404 with this detail. The same endpoint
// also 404s for an unknown `connector_ids` entry, so match on the body
// rather than the status alone — misreporting a typo'd connector id as a
// disabled feature would send the operator to the wrong config file.
if (
err instanceof ApiError &&
err.status === 404 &&
/AISOC_FEATURE_FED_SEARCH|federated search is disabled/i.test(err.body)
) {
throw new FederatedSearchDisabledError();
}
throw err;
}
export const federatedApi = {
/** Connector instances `search()` would fan out to, with their health. */
listBackends: async (): Promise<FederatedBackendsResponse> => {
try {
const raw = await request<Partial<FederatedBackendsResponse>>("/api/v1/federated/backends");
return { backends: Array.isArray(raw.backends) ? raw.backends : [] };
} catch (err) {
return asFederatedError(err);
}
},
search: async (body: FederatedSearchRequest): Promise<FederatedSearchResponse> => {
try {
const raw = await request<Partial<FederatedSearchResponse>>("/api/v1/federated/search", {
method: "POST",
body: JSON.stringify(body),
});
const rows = Array.isArray(raw.rows) ? raw.rows : [];
return {
rows,
row_count: typeof raw.row_count === "number" ? raw.row_count : rows.length,
sources: Array.isArray(raw.sources) ? raw.sources : [],
truncated: raw.truncated === true,
};
} catch (err) {
return asFederatedError(err);
}
},
};
// ─── Natural-language query translator (T3.4) ────────────────────────────────
//
// Wraps `services/api/app/api/v1/endpoints/nl_query.py`. The translator
// itself never mutates state — it just maps an English question to an
// ES|QL / SPL / KQL triple plus a human-readable explanation. The /hunt
// page calls this when an analyst clicks an example-query pill or hits
// "Translate" in the NL input.
export interface NlQueryTranslateRequest {
question: string;
index_pattern?: string;
time_range_hours?: number;
}
export interface NlQueryTranslateResponse {
request_id: string;
question: string;
esql: string;
spl: string;
kql: string;
explanation: string;
created_at: string;
engine: "deterministic" | "llm";
grammar_validated: boolean;
}
export const nlQueryApi = {
translate: (data: NlQueryTranslateRequest) =>
request<NlQueryTranslateResponse>("/api/v1/nl-query/translate", {
method: "POST",
body: JSON.stringify(data),
}),
};
// ─── Saved natural-language hunts (T3.4) ─────────────────────────────────────
//
// Backs the /hunt page's NL hero block + saved-hunts sidebar. Distinct from
// `huntApi` above (legacy SIEM-style query bar, demo-data fallback) and from
// the hypothesis-driven `/hunts` workbench (heavyweight, detection-engineer
// authored, separate page). Wire shape mirrors
// `services/api/app/api/v1/endpoints/saved_hunts.py`.
export type HuntLanguage = "esql" | "kql" | "spl";
export interface TranslatedQueryEnvelope {
esql: string;
kql: string;
spl: string;
explanation: string;
}
export interface SavedHunt {
id: string;
name: string;
nl_query: string;
translated_query: TranslatedQueryEnvelope;
language: HuntLanguage;
schedule: string | null;
last_run_at: string | null;
created_at: string;
updated_at: string;
created_by: string | null;
}
export interface CreateSavedHuntRequest {
name: string;
nl_query: string;
language?: HuntLanguage;
schedule?: string | null;
}
export interface RunSavedHuntResponse {
id: string;
name: string;
nl_query: string;
translated_query: TranslatedQueryEnvelope;
last_run_at: string;
}
export const savedHuntsApi = {
list: () => request<SavedHunt[]>("/api/v1/saved-hunts"),
get: (id: string) => request<SavedHunt>(`/api/v1/saved-hunts/${id}`),
create: (data: CreateSavedHuntRequest) =>
request<SavedHunt>("/api/v1/saved-hunts", {
method: "POST",
body: JSON.stringify(data),
}),
remove: (id: string) => request<void>(`/api/v1/saved-hunts/${id}`, { method: "DELETE" }),
/**
* Re-translate the saved NL question and stamp `last_run_at`. The endpoint
* does not execute the underlying ES|QL — that path is the job of
* `/api/v1/nl-query/execute` (which requires a configured Elasticsearch
* URL). We use the returned `translated_query` to populate the editor.
*/
run: (id: string) =>
request<RunSavedHuntResponse>(`/api/v1/saved-hunts/${id}/run`, {
method: "POST",
}),
};
// ─── Attack Graph (Neo4j) ────────────────────────────────────────────────────
export type GraphNodeKind =
| "host"
| "user"
| "ip"
| "domain"
| "hash"
| "process"
| "technique"
| "tactic"
| "alert"
| "asset";
export interface GraphNode {
id: string;
label: string;
kind: GraphNodeKind;
riskScore?: number;
severity?: AlertSeverity;
attributes?: Record<string, unknown>;
}
export interface GraphEdge {
id: string;
source: string;
target: string;
label: string;
weight?: number;
attributes?: Record<string, unknown>;
}
export interface AttackGraph {
nodes: GraphNode[];
edges: GraphEdge[];
generatedAt: string;
/**
* The response was cut at the server's ceiling, so paths are missing.
*
* Optional because `/graph/blast-radius` and the case attack-path route
* reuse this shape and bound differently. A consumer must treat `undefined`
* as "this endpoint does not say" and not as "complete" — the two are only
* the same for a response that was never bounded.
*/
truncated?: boolean;
/** The node ceiling the service applied, when it reports one. */
nodeLimit?: number;
/** The edge ceiling the service applied, when it reports one. */
edgeLimit?: number;
}
export interface AttackPath {
id: string;
nodes: GraphNode[];
edges: GraphEdge[];
totalRisk: number;
hops: number;
}
export interface MitreCoverageCell {
techniqueId: string;
techniqueName: string;
tactic: string;
detections: number;
alerts: number;
/** 0-1 normalized coverage for heatmap shading. */
intensity: number;
}
export interface MitreCoverage {
tactics: string[];
cells: MitreCoverageCell[];
generatedAt: string;
}
/**
* Case-scoped attack path graph as returned by the Attack-Path Investigation
* Agent backend (`/api/v1/graph/attack-path/{case_id}`). Distinct from the
* tenant-level `AttackGraph` overview because the backend payload schema is
* leaner: each node carries a `properties` dict and edges carry a relationship
* `type` instead of label/weight metadata.
*/
export interface CaseAttackPathNode {
id: string;
label: string;
properties: Record<string, unknown>;
}
export interface CaseAttackPathEdge {
source: string;
target: string;
type: string;
}
export interface CaseAttackPath {
caseId: string;
nodes: CaseAttackPathNode[];
edges: CaseAttackPathEdge[];
nodeCount: number;
edgeCount: number;
}
interface BackendCaseAttackPathResponse {
case_id: string;
nodes: CaseAttackPathNode[];
edges: CaseAttackPathEdge[];
node_count: number;
edge_count: number;
}
// ─── Attack chain timeline (T3.3 — v8.0) ──────────────────────────────────────
// The attack-chain endpoint returns a ranked, time-ordered chain of related
// alerts starting from the seed alert anchored to a case. It's distinct from
// the case attack-path graph above: this view is *temporal* (a timeline of
// alerts) while the path view is *topological* (a graph of entities). Both
// power different tabs in the case workspace.
/** Severity ladder mirrors the backend five-tier scale exactly. */
export type AttackChainSeverity = "info" | "low" | "medium" | "high" | "critical";
/** Allowed lookback windows. The backend rejects anything else with 400. */
export type AttackChainWindow = "1h" | "6h" | "24h" | "72h" | "7d" | "30d";
/**
* A single link in the chain — one related alert plus the metadata that
* makes it readable in a timeline: how far it is from the seed (graph
* distance), how it scored relative to other candidates, the entities it
* shares with the seed, and which MITRE techniques it tagged.
*/
export interface AttackChainLink {
alertId: string;
title: string;
severity: AttackChainSeverity | string;
/** ISO-8601. The chain is ordered by this field. */
eventTime: string;
/** Ranking score the BFS uses to pick the top chain candidates. */
score: number;
/** Hops from the seed alert in the entity graph. 0 == seed itself. */
distance: number;
/** Time gap from the previous link, in seconds. Always >= 0. */
dtSeconds: number;
/** Entities that bridge this link to the rest of the chain. */
sharedEntities: Array<{ kind: string; value: string }>;
mitreTechniques: string[];
connectorType: string | null;
sourceEventIds: string[];
}
/** Entity nodes & edges rendered side-by-side with the timeline.
*
* Node shape from the backend is `{id, kind, label, ...extras}` where extras
* depend on the kind: Alert nodes also carry `severity` and `event_time`.
* Edges are `{source, target, kind}` — the relationship label (e.g. TOUCHES).
*/
export interface AttackChainEntityNode {
id: string;
kind: string;
label?: string;
severity?: string;
event_time?: string;
[key: string]: unknown;
}
export interface AttackChainEntityEdge {
source: string;
target: string;
kind: string;
}
export interface AttackChainTimeline {
caseId: string;
tenantId: string;
window: string;
seedAlertId: string;
chainSignature: string | null;
/** 0..1 — substrate-level confidence in the chain reconstruction. */
confidence: number;
generatedAt: string;
chain: AttackChainLink[];
entityGraph: {
nodes: AttackChainEntityNode[];
edges: AttackChainEntityEdge[];
};
}
/** Raw shape returned by `/api/v1/cases/{id}/attack-chain`. */
interface BackendAttackChainResponse {
case_id: string;
tenant_id: string;
window: string;
seed_alert_id: string | null;
chain_signature: string | null;
confidence: number;
generated_at: string;
chain: Array<{
alert_id: string;
title: string;
severity: string;
event_time: string;
score: number;
distance: number;
dt_seconds: number;
shared_entities: Array<{ kind: string; value: string }>;
mitre_techniques: string[];
connector_type: string | null;
source_event_ids: string[];
}>;
entity_graph: {
nodes: AttackChainEntityNode[];
edges: AttackChainEntityEdge[];
};
// Empty-chain responses include a `reason` breadcrumb the UI can show.
reason?: string;
}
export const graphApi = {
getOverview: (filters: { entity?: string; depth?: number } = {}) =>
request<AttackGraph>("/api/v1/graph", {
params: filters as Record<string, string | number>,
}),
getMitreCoverage: () => request<MitreCoverage>("/api/v1/graph/mitre/coverage"),
/**
* Fetch the reconstructed attack-path graph for a single case.
* Backed by the Attack-Path Investigation Agent endpoint
* `/api/v1/graph/attack-path/{case_id}`.
* Returns `null` when the case has no linked graph entities (404 from API).
*/
getCaseAttackPath: async (
caseId: string,
options: { maxDepth?: number } = {}
): Promise<CaseAttackPath | null> => {
try {
const raw = await request<BackendCaseAttackPathResponse>(
`/api/v1/graph/attack-path/${encodeURIComponent(caseId)}`,
{
params: options.maxDepth ? { max_depth: options.maxDepth } : {},
}
);
return {
caseId: raw.case_id,
nodes: raw.nodes ?? [],
edges: raw.edges ?? [],
nodeCount: raw.node_count ?? 0,
edgeCount: raw.edge_count ?? 0,
};
} catch (err) {
const apiErr = err as { status?: number };
if (apiErr?.status === 404) return null;
throw err;
}
},
};
// ─── Detection Rules ─────────────────────────────────────────────────────────
export type DetectionLanguage =
| "sigma"
| "yara"
| "kql"
| "eql"
| "lucene"
| "regex"
/**
* The compiled ``match_when`` spec the fusion detection engine evaluates.
* Deliberately not one of the six the rule IDE can execute: the body is
* read-only and the engine, not the API, is what runs it.
*/
| "aisoc-match";
export interface DetectionRule {
id: string;
name: string;
description?: string;
language: DetectionLanguage;
body: string;
enabled: boolean;
tags?: string[];
mitre?: string[];
severity?: AlertSeverity;
createdAt: string;
updatedAt: string;
lastTriggeredAt?: string;
hitCount?: number;
/**
* True when the fusion detection engine loads this rule from the compiled
* corpus and evaluates it against live telemetry. A tenant's own rule is
* not loaded by the engine, so "disabled" means different things for the
* two and the card says which.
*/
isBuiltin?: boolean;
/** The engine's rule id (``det-cloud-063``) — what an alert carries. */
sourceId?: string | null;
/** Whether this tenant has stored any decision about the rule. */
tuned?: boolean;
/**
* ``createdAt``/``updatedAt`` on an untuned built-in are the timestamp of
* the compiled artefact this deployment ships, not an authoring date.
*/
timestampsFromArtefact?: boolean;
}
export interface DetectionRuleListResult {
rules: DetectionRule[];
/** Rules matching the request's filters — not the number returned. */
total: number;
/** The library before filters, split by origin. */
builtinTotal: number;
customTotal: number;
returned: number;
offset: number;
limit: number;
/**
* Set when the compiled corpus could not be read at all. Rendered as a
* failure, never as "no rules exist": telling an operator their coverage
* is zero when a file is merely unreachable is the defect this surface was
* reported for.
*/
catalogError: string | null;
/** Artefacts that resolved nowhere while others did. */
missingArtefacts: string[];
}
export interface DetectionRuleListParams {
search?: string;
severity?: string;
category?: string;
mitre?: string;
enabled?: boolean;
source?: "all" | "builtin" | "custom";
limit?: number;
offset?: number;
}
// ─── Detection management UI (WS-B3) ─────────────────────────────────────────
//
// Rule-centric MITRE coverage, bulk enable/disable, and the drift inbox are
// powered by ``services/api/app/api/v1/endpoints/detection_compat.py``.
// Schemas are mirrored here field-for-field so the UI gets autocomplete and
// the compiler catches drift if the backend payload ever changes shape.
export interface DetectionCoverageCell {
techniqueId: string;
tactic: string | null;
techniqueName?: string | null;
totalRules: number;
activeRules: number;
inactiveRules: number;
}
export interface DetectionCoverageSummary {
totalRules: number;
activeRules: number;
inactiveRules: number;
techniques: number;
/** Techniques with at least one *active* rule. */
coveredTechniques: number;
}
export interface DetectionCoverage {
tactics: string[];
cells: DetectionCoverageCell[];
summary: DetectionCoverageSummary;
generatedAt: string;
}
export interface DetectionDriftEntry {
ruleId: string;
name: string;
severity: string;
enabled: boolean;
confidence: number;
fpRate: number;
lastTriggeredAt: string | null;
daysSinceTriggered: number | null;
/** ``high_fp_rate``, ``low_confidence``, ``stale``. */
issues: string[];
}
export interface DetectionDriftSummary {
total: number;
highFpRate: number;
lowConfidence: number;
stale: number;
/**
* Rules the drift heuristics cannot judge. Every one of them reads a
* column only operator review and the rule IDE write, and the compiled
* corpus records none, so built-ins are counted here rather than filed as
* "low confidence, stale".
*/
unscored?: number;
}
export interface DetectionDrift {
entries: DetectionDriftEntry[];
summary: DetectionDriftSummary;
generatedAt: string;
}
export interface DetectionBulkToggleResult {
updated: number;
/** Rule IDs the backend refused (not tenant-owned, malformed, missing). */
skipped: string[];
}
/** One bar in the confidence histogram. */
export interface ConfidenceBucket {
/** Display label, e.g. ``"0–25"``. */
label: string;
floor: number;
ceil: number;
count: number;
activeCount: number;
}
/** Per-MITRE-tactic confidence average. */
export interface TacticConfidence {
tactic: string;
rules: number;
activeRules: number;
avgConfidence: number;
avgConfidenceActive: number;
}
/** Compact rule reference for the lowest/highest tables. */
export interface ConfidenceRuleEntry {
ruleId: string;
name: string;
severity: string;
enabled: boolean;
confidence: number;
fpRate: number;
primaryTactic: string | null;
}
export interface ConfidenceSummary {
totalRules: number;
activeRules: number;
avgConfidence: number;
avgConfidenceActive: number;
medianConfidence: number;
/** Rules below the drift low-confidence threshold (server side: 60). */
lowConfidence: number;
/**
* Rules excluded from every figure above because no confidence has ever
* been recorded for them. Rendered beside the averages so a mean over
* three rules is not read as a mean over the whole library.
*/
unscored?: number;
}
export interface DetectionConfidence {
summary: ConfidenceSummary;
buckets: ConfidenceBucket[];
tactics: TacticConfidence[];
lowest: ConfidenceRuleEntry[];
highest: ConfidenceRuleEntry[];
generatedAt: string;
}
export interface DetectionBacktestResult {
rule_id: string;
rule_language: string;
window_days: number;
events_scanned: number;
would_fire: number;
hit_rate: number;
sample_matches: Record<string, unknown>[];
error: string | null;
}
export const detectionApi = {
/**
* The tenant's effective rule library: the compiled corpus the engine runs
* plus whatever this tenant has tuned. Filters and paging are server-side
* because the library is 2,614 rules on a default install and serialising
* all of it is several megabytes.
*/
list: (params: DetectionRuleListParams = {}) => {
const query = new URLSearchParams();
for (const [key, value] of Object.entries(params)) {
if (value !== undefined && value !== null && value !== "") {
query.set(key, String(value));
}
}
const suffix = query.toString() ? `?${query.toString()}` : "";
return request<DetectionRuleListResult>(`/api/v1/detection/rules${suffix}`);
},
get: (id: string) => request<DetectionRule>(`/api/v1/detection/rules/${id}`),
// Wave 2 (W2.3) — backtest a saved rule over the last N days of real lake
// events. Returns exactly how many events would have fired + sample matches.
backtest: (id: string, body: { window_days?: number; limit?: number; source?: string | null }) =>
request<DetectionBacktestResult>(`/api/v1/rules/${id}/backtest`, {
method: "POST",
body: JSON.stringify(body),
}),
create: (rule: Partial<DetectionRule>) =>
request<DetectionRule>("/api/v1/detection/rules", {
method: "POST",
body: JSON.stringify(rule),
}),
update: (id: string, rule: Partial<DetectionRule>) =>
request<DetectionRule>(`/api/v1/detection/rules/${id}`, {
method: "PATCH",
body: JSON.stringify(rule),
}),
delete: (id: string) => request<void>(`/api/v1/detection/rules/${id}`, { method: "DELETE" }),
test: (rule: Pick<DetectionRule, "language" | "body"> & { sample?: string }) =>
request<{ matches: number; preview: HuntResult[] }>("/api/v1/detection/test", {
method: "POST",
body: JSON.stringify(rule),
}),
// ─── WS-B3 management endpoints ──────────────────────────────────────────
coverage: () => request<DetectionCoverage>("/api/v1/detection/coverage"),
drift: () => request<DetectionDrift>("/api/v1/detection/drift"),
/**
* Confidence distribution + per-tactic averages + worst/best rules.
* The plan calls this "confidence trends"; we surface it as a
* snapshot histogram + ranked tables since rule confidence isn't
* captured historically yet.
*/
confidence: () => request<DetectionConfidence>("/api/v1/detection/confidence"),
/**
* Enable or disable many rules in one round-trip. Built-in /
* cross-tenant rules are silently skipped server-side and reported in
* the ``skipped`` array of the response so the UI can surface them.
*/
bulkToggle: (ruleIds: string[], enabled: boolean) =>
request<DetectionBulkToggleResult>("/api/v1/detection/rules/bulk-toggle", {
method: "POST",
body: JSON.stringify({ ruleIds, enabled }),
}),
};
// ─── Detection-as-code proposals (Wave 2 — w2-dac) ──────────────────────────
//
// Mirrors `services/api/app/api/v1/endpoints/detection_proposals.py`. Backed
// by `DetectionRuleProposal` + `DetectionEvalBaseline` tables. The eval
// verdict is computed server-side from a `scripts/run_evals.py` JSON report
// and the most recent active MITRE accuracy baseline; ≥ 1pp regression
// blocks approval / merge.
export type DetectionProposalStatus =
"proposed" | "in_review" | "eval_passed" | "eval_failed" | "approved" | "rejected" | "promoted";
export interface DetectionProposalEvalVerdict {
ran_at?: string;
candidate?: { mitre_accuracy?: number; all_passed?: boolean };
baseline?: { mitre_accuracy?: number };
drop_pp?: number;
max_regression_pp?: number;
regressed?: boolean;
passed?: boolean;
/**
* Written only by `POST /{id}/evaluate-rule`. `/decide` answers HTTP
* 412 without it, which is why the Approve button could not succeed
* before the console had a caller for that route.
*/
candidate_rule?: { passed?: boolean; ran_at?: string };
}
export interface DetectionProposal {
id: string;
tenant_id: string | null;
base_rule_id: string | null;
promoted_rule_id: string | null;
name: string;
description: string | null;
rule_language: string;
rule_body: string;
category: string;
severity: string;
confidence: number;
mitre_tactics: string[];
mitre_techniques: string[];
tags: string[];
status: DetectionProposalStatus;
eval_result: DetectionProposalEvalVerdict | Record<string, never>;
/** What this rule claims to catch, carried so the approval gate can replay it. */
positive_fixtures?: Array<Record<string, unknown>>;
/** What it claims to ignore. Empty means the proposal makes no such claim. */
negative_fixtures?: Array<Record<string, unknown>>;
review_comments: Array<{
actor_id: string;
actor_email?: string;
comment: string;
at: string;
}>;
proposed_by_id: string | null;
decided_by_id: string | null;
decision_comment: string | null;
decided_at: string | null;
/** WS-B4: git PR path — URL of the GitHub PR created on promotion. Author: Beenu - [email protected] */
github_pr_url: string | null;
created_at: string;
updated_at: string;
}
export interface DetectionEvalBaseline {
id: string;
tenant_id: string | null;
suite: string;
score: number;
payload: Record<string, unknown>;
is_active: boolean;
recorded_by_id: string | null;
created_at: string;
}
export const detectionProposalsApi = {
list: (params?: { status?: DetectionProposalStatus; limit?: number }) => {
const qs = new URLSearchParams();
if (params?.status) qs.set("status", params.status);
if (params?.limit !== undefined) qs.set("limit", String(params.limit));
const suffix = qs.toString() ? `?${qs.toString()}` : "";
return request<DetectionProposal[]>(`/api/v1/detection-proposals${suffix}`);
},
get: (id: string) => request<DetectionProposal>(`/api/v1/detection-proposals/${id}`),
create: (proposal: {
name: string;
description?: string | null;
rule_language: string;
rule_body: string;
category: string;
severity?: string;
confidence?: number;
mitre_tactics?: string[];
mitre_techniques?: string[];
tags?: string[];
base_rule_id?: string | null;
}) =>
request<DetectionProposal>("/api/v1/detection-proposals", {
method: "POST",
body: JSON.stringify(proposal),
}),
comment: (id: string, comment: string) =>
request<DetectionProposal>(`/api/v1/detection-proposals/${id}/comment`, {
method: "POST",
body: JSON.stringify({ comment }),
}),
attachEval: (
id: string,
body: { eval_report: Record<string, unknown>; max_regression_pp?: number }
) =>
request<DetectionProposal>(`/api/v1/detection-proposals/${id}/eval`, {
method: "POST",
body: JSON.stringify(body),
}),
/**
* Run the candidate rule body against its own fixtures.
*
* This had no web client at all, and it is the gate `/decide` requires:
* approving returns HTTP 412 unless `eval_result.candidate_rule` exists,
* and this route is the only thing that writes that key. So the console
* rendered an Approve button that could not succeed, and the gate was
* reachable only by calling the API directly.
*/
evaluateRule: (
id: string,
body: {
positive_fixtures: Array<Record<string, unknown>>;
negative_fixtures: Array<Record<string, unknown>>;
}
) =>
request<DetectionProposal>(`/api/v1/detection-proposals/${id}/evaluate-rule`, {
method: "POST",
body: JSON.stringify(body),
}),
/** Replay a candidate rule over real tenant events in the lake. */
backtestProposal: (id: string, body?: { days?: number; limit?: number }) =>
request<Record<string, unknown>>(`/api/v1/detection-proposals/${id}/backtest`, {
method: "POST",
body: JSON.stringify(body ?? {}),
}),
// Triggers a synchronous run of `scripts/run_evals.py` server-side and
// returns the JSON report plus runner metadata. The rule editor calls this
// from "Propose for review" so the eval gate runs before the proposal is
// visible for approval. Subprocess takes ~5–15s on the 200-incident corpus.
runEval: (body?: {
use_active_baseline?: boolean;
max_regression_pp?: number;
timeout_seconds?: number;
}) =>
request<{
report: Record<string, unknown>;
exit_code: number;
duration_seconds: number;
ran_at: string;
script: string;
}>("/api/v1/detection-proposals/run-eval", {
method: "POST",
body: JSON.stringify(body ?? {}),
}),
decide: (id: string, body: { decision: "approve" | "reject"; comment?: string | null }) =>
request<DetectionProposal>(`/api/v1/detection-proposals/${id}/decide`, {
method: "POST",
body: JSON.stringify(body),
}),
promote: (id: string) =>
request<DetectionProposal>(`/api/v1/detection-proposals/${id}/promote`, { method: "POST" }),
listBaselines: (suite?: string) => {
const suffix = suite ? `?suite=${encodeURIComponent(suite)}` : "";
return request<DetectionEvalBaseline[]>(`/api/v1/detection-proposals/baselines${suffix}`);
},
recordBaseline: (body: { suite: string; score: number; payload?: Record<string, unknown> }) =>
request<DetectionEvalBaseline>("/api/v1/detection-proposals/baselines", {
method: "POST",
body: JSON.stringify(body),
}),
};
// ─── Detection Rule Tuning Workbench (PR-6 / v1.5 §W8) ───────────────────────
//
// The tuning workbench replaces the static /noise-tuning prototype with a live
// projection of ``DetectionRule`` rows into analyst-actionable suggestions.
// The backend is intentionally cheap — every projection is derived from
// already-materialised fields (``fp_rate``, ``total_hits``, ``confidence``,
// ``last_triggered``, ``status``) so a tenant with thousands of imported Sigma
// rules can still triage without hammering the alerts table.
//
// Three verbs ship here:
// • ``list`` / ``summary`` — read-only projection (``rules:read``).
// • ``apply`` — mechanically tighten a rule (``rules:write``), bumps version.
// • ``dismiss`` / ``autoTune`` — record analyst intent (``rules:write``).
//
// See ``services/api/app/services/rule_tuning.py`` for the authoritative
// wire shape; the types below mirror its Pydantic models 1:1.
export type TuningSuggestion =
| "disable"
| "add_suppression"
| "raise_threshold"
| "tune_confidence"
| "review_stale"
| "healthy";
export type TuningAction = "raise_threshold" | "add_suppression" | "disable" | "acknowledge";
export interface TuningEntry {
rule_id: string;
name: string;
description: string | null;
category: string;
severity: string;
status: string;
enabled: boolean;
confidence: number;
/** Materialised false-positive rate in ``[0, 1]``. */
fp_rate: number;
total_hits: number;
/** ISO-8601 timestamp of the rule's last hit; ``null`` if it has never fired. */
last_triggered_at: string | null;
tags: string[];
mitre_tactics: string[];
mitre_techniques: string[];
version: number;
updated_at: string;
suggestion: TuningSuggestion;
/** Server-side ordering weight — already sorted descending in ``entries``. */
score: number;
reasons: string[];
auto_tune: boolean;
/** Set when an analyst has dismissed the rule from the default view. */
dismissed_at: string | null;
/** Most recent tuning action applied to this rule (``raise_threshold`` …). */
last_action: string | null;
last_action_at: string | null;
}
export interface TuningSummary {
total_rules: number;
actionable: number;
healthy: number;
disable_count: number;
add_suppression_count: number;
raise_threshold_count: number;
tune_confidence_count: number;
review_stale_count: number;
auto_tune_enabled: number;
/** Average ``fp_rate`` across classified rules, ``[0, 1]``. */
average_fp_rate: number;
/** Count of rules whose ``fp_rate`` is at or above the noisy threshold. */
high_fp_count: number;
}
export interface TuningFilters {
severity: string | null;
suggestion: string | null;
search: string | null;
enabled_only: boolean;
include_dismissed: boolean;
page: number;
page_size: number;
}
export interface TuningResponse {
entries: TuningEntry[];
summary: TuningSummary;
/** Echo of the filters that built this response. */
filters: TuningFilters;
total: number;
generated_at: string;
}
export interface TuningListParams {
severity?: string;
suggestion?: TuningSuggestion;
search?: string;
enabled_only?: boolean;
include_dismissed?: boolean;
page?: number;
page_size?: number;
}
export interface ApplyTuningRequest {
action: TuningAction;
note?: string | null;
/** Override threshold to set when ``action === 'raise_threshold'``. */
threshold?: number | null;
/** Free-text reason recorded with the suppression placeholder. */
suppression_reason?: string | null;
}
export interface DismissTuningRequest {
reason?: string | null;
}
export interface AutoTuneRequest {
enabled: boolean;
}
export const tuningApi = {
/**
* Fetch the rule tuning workbench feed.
*
* The ``summary`` block is computed across the *entire classified
* population* (not the current page), so the header tiles stay stable
* as analysts paginate. Dismissed rules are excluded by default — pass
* ``include_dismissed: true`` when auditing what's been hidden.
*/
list: (params: TuningListParams = {}) =>
request<TuningResponse>("/api/v1/detection/tuning", {
params: params as Record<string, string | number | boolean>,
}),
/**
* Cheap summary-only endpoint. Used by the sidebar badge and the
* upcoming /console dashboard tile so they don't have to fetch the
* full feed just to render counts.
*/
summary: () => request<TuningSummary>("/api/v1/detection/tuning/summary"),
/**
* Mechanically apply a tuning suggestion. ``raise_threshold``,
* ``add_suppression``, and ``disable`` mutate the rule and bump
* ``DetectionRule.version``; ``acknowledge`` is a no-op + audit. The
* server returns the re-projected entry so the UI can refresh in place.
*/
apply: (ruleId: string, body: ApplyTuningRequest) =>
request<TuningEntry>(`/api/v1/detection/tuning/${ruleId}/apply`, {
method: "POST",
body: JSON.stringify(body),
}),
/**
* Hide a rule from the default workbench view without touching its
* semantics. Dismissed rules reappear with ``include_dismissed: true``.
*/
dismiss: (ruleId: string, body: DismissTuningRequest = {}) =>
request<TuningEntry>(`/api/v1/detection/tuning/${ruleId}/dismiss`, {
method: "POST",
body: JSON.stringify(body),
}),
/**
* Flip the per-rule ``auto_tune`` opt-in flag. Stored under
* ``suppression_config.auto_tune`` so future automated tuners know
* they're allowed to touch the rule. Flipping does *not* trigger any
* immediate mutation.
*/
autoTune: (ruleId: string, enabled: boolean) =>
request<TuningEntry>(`/api/v1/detection/tuning/${ruleId}/auto_tune`, {
method: "POST",
body: JSON.stringify({ enabled } satisfies AutoTuneRequest),
}),
};
// ─── AI Copilot ──────────────────────────────────────────────────────────────
export type CopilotRole = "user" | "assistant" | "system";
export interface CopilotMessage {
id: string;
role: CopilotRole;
content: string;
/** When the message was created (ISO string). */
createdAt: string;
/** Optional citations to backend resources the assistant referenced. */
citations?: Array<{
label: string;
href?: string;
kind?: "alert" | "case" | "rule" | "asset" | "doc";
}>;
/** Optional structured suggestions the UI can render as buttons. */
suggestions?: string[];
}
export interface CopilotConversation {
id: string;
title: string;
updatedAt: string;
messageCount: number;
}
export interface CopilotChatRequest {
conversationId?: string;
message: string;
/** Optional context the user is currently looking at. */
context?: {
alertId?: string;
caseId?: string;
entity?: string;
page?: string;
};
}
export interface CopilotChatResponse {
conversationId: string;
reply: CopilotMessage;
}
export const copilotApi = {
listConversations: () =>
request<{ conversations: CopilotConversation[] }>("/api/v1/copilot/conversations"),
getConversation: (id: string) =>
request<{ id: string; title: string; messages: CopilotMessage[] }>(
`/api/v1/copilot/conversations/${id}`
),
/** One-shot chat call. UI should support optimistic append + rollback. */
chat: (req: CopilotChatRequest) =>
request<CopilotChatResponse>("/api/v1/copilot/chat", {
method: "POST",
body: JSON.stringify(req),
}),
/**
* Stream a chat response as NDJSON (one JSON object per line, with
* `{ delta?: string, done?: boolean, citations?, suggestions? }`).
* Callers should consume via `Response.body.getReader()`.
*/
streamChat: (req: CopilotChatRequest, signal?: AbortSignal) =>
fetch(`${API_BASE}/api/v1/copilot/chat/stream`, {
method: "POST",
headers: apiHeaders(),
body: JSON.stringify(req),
signal,
}),
};
// ─── Ambient Copilot (contextual actions) ───────────────────────────────────
//
// Phase 4A. Each page (alerts/cases/detections/playbooks) renders a small
// row of buttons that call into `services/agents` with a tightly-scoped
// system prompt. The result is rendered inline next to the entity the user
// is looking at — no full Copilot conversation required.
//
// Endpoints live on the agents service (port 8001 / AGENTS_BASE), not on
// the main API, because they share the same LangChain/MITRE plumbing as the
// investigation orchestrator.
export type ContextualPage = "alerts" | "cases" | "detections" | "playbooks";
export interface ContextualSuggestion {
label: string;
action?: string | null;
href?: string | null;
}
export interface ContextualActionDescriptor {
key: string;
label: string;
description: string;
icon?: string | null;
}
export interface ContextualActionsCatalogue {
pages: Record<ContextualPage, ContextualActionDescriptor[]>;
}
export interface ContextualActionRequest {
page: ContextualPage;
action: string;
entity_id: string;
entity?: Record<string, unknown> | null;
question?: string | null;
case_id?: string | null;
}
export interface ContextualActionResponse {
id: string;
page: ContextualPage;
action: string;
entity_id: string;
title: string;
/** Markdown body. */
content: string;
/** 0-1 confidence. `0` when the LLM was not configured. */
confidence: number;
suggestions: ContextualSuggestion[];
citations: Array<Record<string, unknown>>;
model: string;
elapsed_ms: number;
fallback: boolean;
created_at: string;
}
/**
* One streamed NDJSON frame from `/action/stream`. The first frame is a
* header (no `delta`/`done`), subsequent frames carry `delta`, and the
* final frame has `done: true` plus suggestions + confidence.
*/
export interface ContextualStreamFrame {
/** Header frame fields. */
title?: string;
page?: ContextualPage;
action?: string;
entity_id?: string;
model?: string;
fallback?: boolean;
/** Body frame fields. */
delta?: string;
/** Footer frame fields. */
done?: boolean;
suggestions?: ContextualSuggestion[];
confidence?: number;
/** Error frame. */
error?: string;
}
export const contextualApi = {
/** Catalogue of supported (page, action) pairs. */
listActions: () =>
request<ContextualActionsCatalogue>("/api/v1/contextual/actions", {
baseUrl: AGENTS_BASE,
}),
/** One-shot contextual call. Returns a fully-formed Markdown response. */
run: (req: ContextualActionRequest) =>
request<ContextualActionResponse>("/api/v1/contextual/action", {
method: "POST",
body: JSON.stringify(req),
baseUrl: AGENTS_BASE,
}),
/**
* Streaming variant. Returns the raw `Response` so the caller can read
* NDJSON frames via `response.body.getReader()`. See
* {@link ContextualStreamFrame} for the per-line shape.
*/
stream: (req: ContextualActionRequest, signal?: AbortSignal) =>
fetch(`${AGENTS_BASE}/api/v1/contextual/action/stream`, {
method: "POST",
headers: apiHeaders(),
body: JSON.stringify(req),
signal,
}),
};
// Re-export base URLs so dev tooling and tests can introspect them.
// Production callers should prefer the typed functions above.
export const __apiBases = {
api: API_BASE,
agents: AGENTS_BASE,
actions: ACTIONS_BASE,
fusion: FUSION_BASE,
threatintel: THREATINTEL_BASE,
enrichment: ENRICHMENT_BASE,
realtime: REALTIME_BASE,
ws: WS_BASE,
} as const;
// ─── Web Push & Responder PWA ────────────────────────────────────────────────
//
// Phase 4B. The mobile responder PWA subscribes to Web Push so on-call
// engineers get paged for P0 alerts and "agent needs your approval"
// events without keeping the browser tab open. Subscriptions are stored
// per-tenant on the realtime gateway, which fans events out from Kafka.
export interface PushSubscriptionPayload {
endpoint: string;
keys: {
p256dh: string;
auth: string;
};
expirationTime?: number | null;
}
export interface PushSubscribeRequest {
subscription: PushSubscriptionPayload;
user_agent?: string;
user_id?: string | null;
topics?: string[];
}
export interface PushSubscribeResponse {
id: string;
vapid_public_key: string;
topics: string[];
}
export interface PushPublicKeyResponse {
/** VAPID public key as a URL-safe base64 string. */
public_key: string;
enabled: boolean;
}
export type OnCallStatus = "available" | "busy" | "snoozed" | "offline";
export interface OnCallSnapshot {
user_id: string;
user_email: string | null;
user_name: string | null;
status: OnCallStatus;
rotation: string | null;
schedule_ref: string | null;
note: string | null;
/** ISO-8601 timestamp the current snooze ends (null otherwise). */
until: string | null;
updated_at: string;
}
export type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
export interface ApprovalRequest {
id: string;
tenant_id: string;
run_id: string | null;
case_id: string | null;
alert_id: string | null;
requested_by: string;
required_user_id: string | null;
required_topic: string | null;
title: string;
summary: string;
risk_level: "low" | "medium" | "high" | "critical";
action: Record<string, unknown>;
status: ApprovalStatus;
decided_by_id: string | null;
decided_at: string | null;
decision_comment: string | null;
expires_at: string | null;
created_at: string;
updated_at: string;
}
export const responderApi = {
/** Fetch the VAPID public key the SW will subscribe with. */
getPublicKey: () => request<PushPublicKeyResponse>("/api/v1/push/public-key"),
/** Register a new Web Push subscription for this device. */
subscribe: (req: PushSubscribeRequest) =>
request<PushSubscribeResponse>("/api/v1/push/subscribe", {
method: "POST",
body: JSON.stringify(req),
}),
/** Tear down an existing subscription (e.g. on sign-out). */
unsubscribe: (endpoint: string) =>
request<{ removed: boolean }>("/api/v1/push/unsubscribe", {
method: "POST",
body: JSON.stringify({ endpoint }),
}),
/** Send a test page to all of the caller's registered devices. */
testNotify: () =>
request<{ sent: number }>("/api/v1/push/test", {
method: "POST",
}),
/** Snapshot of every user's on-call status (admin view). */
listOnCall: () => request<{ items: OnCallSnapshot[] }>("/api/v1/oncall"),
/** Current caller's on-call snapshot. */
getOnCall: () => request<OnCallSnapshot>("/api/v1/oncall/me"),
/** Toggle the caller's own on-call status (optionally for a window).
*
* Pass ``snooze_minutes`` together with ``status: 'snoozed'`` to defer
* paging temporarily — the backend computes ``until`` from that window.
*/
setOnCall: (
status: OnCallStatus,
options?: {
snooze_minutes?: number | null;
note?: string | null;
rotation?: string | null;
schedule_ref?: string | null;
}
) =>
request<OnCallSnapshot>("/api/v1/oncall/me", {
method: "PUT",
body: JSON.stringify({
status,
snooze_minutes: options?.snooze_minutes ?? null,
note: options?.note ?? null,
rotation: options?.rotation ?? null,
schedule_ref: options?.schedule_ref ?? null,
}),
}),
/** Pending agent approval requests visible to me. */
listApprovals: (params?: {
status?: ApprovalStatus;
mine?: boolean;
risk_level?: ApprovalRequest["risk_level"];
page?: number;
page_size?: number;
}) =>
request<{
items: ApprovalRequest[];
total: number;
page: number;
page_size: number;
pages: number;
}>("/api/v1/approvals", {
params: {
status: params?.status ?? "pending",
...(params?.mine ? { mine: "true" } : {}),
...(params?.risk_level ? { risk_level: params.risk_level } : {}),
...(params?.page ? { page: params.page } : {}),
...(params?.page_size ? { page_size: params.page_size } : {}),
},
}),
/** Single approval (for the deep-linked notification view). */
getApproval: (id: string) => request<ApprovalRequest>(`/api/v1/approvals/${id}`),
/** Approve a pending agent action. */
approve: (id: string, comment?: string) =>
request<ApprovalRequest>(`/api/v1/approvals/${id}/decide`, {
method: "POST",
body: JSON.stringify({ decision: "approve", comment: comment ?? null }),
}),
/** Deny a pending agent action with a required reason. */
deny: (id: string, reason: string) =>
request<ApprovalRequest>(`/api/v1/approvals/${id}/decide`, {
method: "POST",
body: JSON.stringify({ decision: "deny", comment: reason }),
}),
/** Snooze an alert for the on-call rotation.
*
* Pass either ``durationMinutes`` (relative window) or ``until`` (absolute
* ISO-8601 timestamp). The alert re-surfaces in the queue once the window
* elapses.
*/
snoozeAlert: (
alertId: string,
options: { durationMinutes?: number; until?: string; reason?: string }
) =>
request<Alert>(`/api/v1/alerts/${alertId}/snooze`, {
method: "POST",
body: JSON.stringify({
duration_minutes: options.durationMinutes ?? null,
until: options.until ?? null,
reason: options.reason ?? null,
}),
}),
};
// ─── WebAuthn / Passkey authentication (Phase 4B) ───────────────────────────
//
// The mobile responder uses passkeys instead of passwords. The flow is the
// standard WebAuthn registration + authentication ceremony backed by
// services/api/app/api/v1/endpoints/passkeys.py. Browsers handle the
// platform UI; the helpers below just shuttle JSON between the SimpleWebAuthn
// browser library and our backend.
export interface PasskeyCredential {
id: string;
device_name: string;
created_at: string;
last_used_at: string | null;
transports: string[];
}
export const passkeyApi = {
/** Begin registration for the currently logged-in user. */
registerBegin: (deviceName: string) =>
request<{
publicKey: Record<string, unknown>;
challenge: string;
device_name_default: string;
}>("/api/v1/passkeys/register/begin", {
method: "POST",
body: JSON.stringify({ device_name: deviceName }),
}),
/** Submit the platform attestation to persist the new credential. */
registerFinish: (challenge: string, credential: Record<string, unknown>) =>
request<PasskeyCredential>("/api/v1/passkeys/register/finish", {
method: "POST",
body: JSON.stringify({ challenge, credential }),
}),
/** Begin a passwordless login (email is optional / hint only). */
authenticateBegin: (email?: string) =>
request<{ publicKey: Record<string, unknown>; challenge: string }>(
"/api/v1/passkeys/authenticate/begin",
{
method: "POST",
body: JSON.stringify({ email: email ?? null }),
}
),
/** Verify the assertion and return a JWT pair. */
authenticateFinish: (challenge: string, credential: Record<string, unknown>) =>
request<{
access_token: string;
refresh_token: string;
token_type: string;
expires_in: number;
}>("/api/v1/passkeys/authenticate/finish", {
method: "POST",
body: JSON.stringify({ challenge, credential }),
}),
/** Active credentials for the current user. */
list: () => request<{ items: PasskeyCredential[] }>("/api/v1/passkeys/credentials"),
/** Soft-revoke one of my credentials. */
delete: (id: string) => request<void>(`/api/v1/passkeys/credentials/${id}`, { method: "DELETE" }),
};
// ─── Autonomy policy (Tier 1.3 — configurable autonomy guardrails) ──────────
//
// Three-tier confidence cutoffs per agent action: at or above ``auto`` the
// agent executes silently, between ``auto`` and ``review`` it queues for an
// analyst, between ``review`` and ``escalation`` it pages on-call, and below
// ``escalation`` it refuses. The admin UI in
// ``apps/web/src/components/settings/AutonomyPolicy.tsx`` reads + writes
// these thresholds; the agent re-reads them on the next investigation.
export interface AutonomyThresholdTriple {
auto: number;
review: number;
escalation: number;
}
export type AutonomyBlastRadius =
"read" | "low" | "medium" | "high" | "critical" | "custom" | "unknown";
export interface AutonomyActionPolicy {
action: string;
blast_radius: AutonomyBlastRadius;
thresholds: AutonomyThresholdTriple;
default_thresholds: AutonomyThresholdTriple;
overridden: boolean;
override_source?: string | null;
last_updated_at?: string | null;
last_updated_by?: string | null;
last_reason?: string | null;
/**
* Whether this verb reaches a vendor without a human, resolved by the API
* from the autonomy tier and the capability contract — the control that
* actually gates execution. Optional so an older API blanks the posture
* rather than letting the console infer one from the thresholds, which is
* the defect this field exists to retire.
*/
effective_auto_execute?: boolean;
/** The same question at the top of the tier ladder. */
auto_executes_at_any_tier?: boolean;
/** Capability it resolves to in the action registry, null when none does. */
capability?: string | null;
executable?: boolean;
effective_tier?: string;
effective_reason?: string;
}
/** The control that gates execution, as reported by the API. */
export interface AutonomyEffective {
tier: string;
tier_label: string;
tier_source: string;
max_automatic_impact: string | null;
auto_executing_actions: string[];
high_blast_auto_executing: string[];
unimplemented_actions: string[];
thresholds_are_advisory: boolean;
advisory_note: string;
}
export interface AutonomyPolicyResponse {
tenant_id: string;
actions: AutonomyActionPolicy[];
effective?: AutonomyEffective;
}
export interface AutonomyThresholdUpdate {
auto: number;
review: number;
escalation: number;
reason?: string | null;
}
export interface AutonomyThresholdUpdateResponse {
action: string;
thresholds: AutonomyThresholdTriple;
updated_at: string;
updated_by: string;
}
export const autonomyPolicyApi = {
/** Effective policy (defaults + DB overrides) for the calling tenant. */
list: () => request<AutonomyPolicyResponse>("/api/v1/autonomy-policy"),
/** Upsert one action's three-tier thresholds. */
update: (action: string, payload: AutonomyThresholdUpdate) =>
request<AutonomyThresholdUpdateResponse>(
`/api/v1/autonomy-policy/${encodeURIComponent(action)}`,
{
method: "PUT",
body: JSON.stringify(payload),
}
),
/** Clear a tenant override and revert the action to the hard-coded default. */
reset: (action: string) =>
request<void>(`/api/v1/autonomy-policy/${encodeURIComponent(action)}`, { method: "DELETE" }),
/** Which alert classes this tenant is measuring rather than acting on. */
shadowMode: () => request<ShadowModeResponse>("/api/v1/autonomy-policy/shadow-mode"),
/** Start or stop measuring one alert class. */
setShadowMode: (alertClass: string, enabled: boolean) =>
request<ShadowModeEntry>(
`/api/v1/autonomy-policy/shadow-mode/${encodeURIComponent(alertClass)}`,
{ method: "PUT", body: JSON.stringify({ enabled }) }
),
/** Capabilities this tenant has earned, or that an operator overruled into place. */
grants: () => request<GrantListResponse>("/api/v1/autonomy-policy/grants"),
/**
* Ask for a capability. A refusal is a 200 with `granted: false` and the
* reasons: being told no by a safety control is the control working, and
* surfacing it as an error invites a client to retry it.
*/
requestGrant: (payload: PromotionRequestBody) =>
request<PromotionResponse>("/api/v1/autonomy-policy/grants", {
method: "POST",
body: JSON.stringify(payload),
}),
/** Hand a capability back. Audited as a revocation, not as a demotion. */
revokeGrant: (params: { scope_kind: string; scope_key: string; capability: string }) =>
request<void>(`/api/v1/autonomy-policy/grants?${new URLSearchParams(params).toString()}`, {
method: "DELETE",
}),
/** Rolling agreement between the agent and this tenant's own analysts. */
agreement: (params?: { scope_kind?: string; scope_key?: string }) => {
const query = new URLSearchParams();
if (params?.scope_kind) query.set("scope_kind", params.scope_kind);
if (params?.scope_key) query.set("scope_key", params.scope_key);
const suffix = query.toString();
return request<AgreementResponse>(
`/api/v1/autonomy-policy/agreement${suffix ? `?${suffix}` : ""}`
);
},
};
// ─── Shadow mode and rolling agreement (gap-closure Phase 2.1 / 2.2) ─────────
//
// Every rate below is `number | null`, and `null` means there was no
// denominator. It renders as "not measured", never as 0: a zero in the
// agreement column says the agent was wrong every time, and "it was never
// asked" is a different fact calling for a different response. The counts
// travel with the rates for the same reason — 100% over four answers is not
// the claim 100% over four hundred is.
export interface ShadowModeEntry {
alert_class: string;
enabled: boolean;
enabled_at?: string | null;
updated_at?: string | null;
updated_by?: string | null;
}
export interface ShadowModeResponse {
tenant_id: string;
entries: ShadowModeEntry[];
}
export interface AgreementWindow {
resolved: number;
labelled: number;
unlabeled: number;
answered: number;
abstained: number;
agreed: number;
malicious_support: number;
malicious_caught: number;
agreement_rate: number | null;
malicious_recall: number | null;
abstention_rate: number | null;
}
export interface AgreementScope {
key: string;
window: AgreementWindow;
}
export interface AgreementThresholds {
min_decisions: number;
min_malicious: number;
min_agreement: number;
min_malicious_recall: number;
max_abstention_rate: number;
window_days: number;
demotion_agreement: number;
demotion_malicious_recall: number;
drift_sample: number;
drift_min_answered: number;
}
// ─── Evidence-gated autonomy (gap-closure Phase 2.3) ────────────────────────
//
// `source` and `is_override` are both carried because the distinction has to
// survive without anyone inferring it. An override is autonomy a human
// overruled a refusal to grant, and six months later "was this earned" must
// be answerable from the row rather than reconstructed from the numbers.
export type GrantState = "shadow" | "granted" | "demoted";
export type GrantSource = "earned" | "operator_override";
export interface AutonomyGrant {
id: string;
scope_kind: string;
scope_key: string;
capability: string;
state: GrantState;
source: GrantSource;
is_override: boolean;
evidence?: Record<string, unknown> | null;
granted_at?: string | null;
demoted_at?: string | null;
demoted_reason?: string | null;
override_reason?: string | null;
}
export interface GrantListResponse {
tenant_id: string;
grants: AutonomyGrant[];
/** Grants this request's reconciliation pass demoted. */
demoted_now: Array<Record<string, unknown>>;
}
export interface PromotionRequestBody {
scope_kind: string;
scope_key: string;
capability: string;
override?: boolean;
override_reason?: string | null;
}
export interface PromotionResponse {
granted: boolean;
state: GrantState;
source: GrantSource;
is_override: boolean;
/** What to fix on a refusal; what was waived on an override. */
refusals: string[];
evidence: Record<string, unknown>;
changed: boolean;
}
export interface AgreementResponse {
tenant_id: string;
scope_kind: string;
scope_key: string;
window: AgreementWindow;
/**
* The trailing slice of the most recent decisions, scored on its own. A
* window average is where a gradual decline hides, so any surface showing
* one has to show both or it is showing the flattering half.
*/
recent: AgreementWindow;
window_start: string;
window_end: string;
thresholds: AgreementThresholds;
reconciled: number;
by_alert_class: AgreementScope[];
by_rule: AgreementScope[];
by_source: AgreementScope[];
by_model: AgreementScope[];
}
// ─── Analyst override feedback loop (Tier 1.5) ───────────────────────────────
//
// When an analyst corrects an AI verdict, the API:
// 1. updates the alert's ``disposition``
// 2. writes the lesson into ``aisoc_institutional_memory`` (so future
// investigations of similar alerts pull this up)
// 3. surfaces *retroactive candidates* — past alerts in the same tenant
// sharing the same coarse signature that would now flip disposition.
//
// The analyst can then bulk-apply the new disposition to those candidates
// via ``POST /api/v1/feedback/redisposition/apply``.
export type AnalystVerdict = "true_positive" | "false_positive" | "benign" | "escalate";
export interface AlertOverrideRequest {
alert_id: string;
/** The AI-generated verdict being overridden. */
original_verdict: string;
/** Analyst's corrected verdict. */
corrected_verdict: AnalystVerdict;
/** Optional free-text justification surfaced in institutional memory. */
reason?: string;
}
export interface RedispositionCandidate {
alert_id: string;
title: string;
severity: string;
current_disposition: string | null;
proposed_disposition: AnalystVerdict;
event_time: string;
}
export interface AlertOverrideResponse {
alert_id: string;
corrected_verdict: AnalystVerdict;
recorded_at: string;
/** Stable institutional-memory key, only present when a signature was derivable. */
memory_key: string | null;
redisposition_candidates: RedispositionCandidate[];
}
export interface RedispositionApplyRequest {
alert_ids: string[];
new_disposition: AnalystVerdict;
/**
* Blast-radius control: sha256 over the exact alert set + disposition,
* mirroring the server's compute_confirmation_token. Required — apply
* fails validation without it.
*/
confirmation_token: string;
}
/** Mirror of the server's canonical token (sorted ids joined, hashed).
* Uses WebCrypto when available (secure context) and a pure-JS SHA-256
* fallback otherwise — the console is often served over plain HTTP on a
* LAN address, where crypto.subtle is undefined. */
export async function computeRedispositionToken(
alertIds: string[],
newDisposition: string
): Promise<string> {
const canonical = [...alertIds].sort().join("|") + "=>" + newDisposition;
if (globalThis.crypto?.subtle) {
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
return Array.from(new Uint8Array(digest))
.map((b) => b.toString(16).padStart(2, "0"))
.join("");
}
return sha256Hex(canonical);
}
/* Compact SHA-256 (public-domain style), fallback for insecure contexts. */
function sha256Hex(ascii: string): string {
const K = [
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
];
const rotr = (x: number, n: number) => (x >>> n) | (x << (32 - n));
const bytes = Array.from(new TextEncoder().encode(ascii));
const bitLen = bytes.length * 8;
bytes.push(0x80);
while (bytes.length % 64 !== 56) bytes.push(0);
const hi = Math.floor(bitLen / 0x100000000);
const lo = bitLen >>> 0;
bytes.push((hi >>> 24) & 0xff, (hi >>> 16) & 0xff, (hi >>> 8) & 0xff, hi & 0xff);
bytes.push((lo >>> 24) & 0xff, (lo >>> 16) & 0xff, (lo >>> 8) & 0xff, lo & 0xff);
let h = [
0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
];
const w = new Array<number>(64);
for (let i = 0; i < bytes.length; i += 64) {
for (let j = 0; j < 16; j++) {
w[j] =
(bytes[i + j * 4] << 24) |
(bytes[i + j * 4 + 1] << 16) |
(bytes[i + j * 4 + 2] << 8) |
bytes[i + j * 4 + 3];
}
for (let j = 16; j < 64; j++) {
const s0 = rotr(w[j - 15], 7) ^ rotr(w[j - 15], 18) ^ (w[j - 15] >>> 3);
const s1 = rotr(w[j - 2], 17) ^ rotr(w[j - 2], 19) ^ (w[j - 2] >>> 10);
w[j] = (w[j - 16] + s0 + w[j - 7] + s1) >>> 0;
}
let [a, b, c, d, e, f, g, hh] = h;
for (let j = 0; j < 64; j++) {
const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
const ch = (e & f) ^ (~e & g);
const t1 = (hh + S1 + ch + K[j] + w[j]) >>> 0;
const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
const maj = (a & b) ^ (a & c) ^ (b & c);
const t2 = (S0 + maj) >>> 0;
hh = g;
g = f;
f = e;
e = (d + t1) >>> 0;
d = c;
c = b;
b = a;
a = (t1 + t2) >>> 0;
}
h = h.map((x, k) => (x + [a, b, c, d, e, f, g, hh][k]) >>> 0);
}
return h.map((x) => x.toString(16).padStart(8, "0")).join("");
}
export interface RedispositionApplyResponse {
updated: number;
new_disposition: AnalystVerdict;
}
export interface OverrideEntry {
key: string;
tags: string[];
reason: string | null;
created_at: string | null;
value: Record<string, unknown>;
}
export interface OverrideSummary {
total_overrides: number;
false_positive_corrections: number;
true_positive_corrections: number;
benign_corrections: number;
escalate_corrections: number;
}
export const feedbackApi = {
/** Persist an analyst correction and get retroactive re-disposition candidates back. */
submitOverride: (payload: AlertOverrideRequest) =>
request<AlertOverrideResponse>("/api/v1/feedback/alert-override", {
method: "POST",
body: JSON.stringify(payload),
}),
/** Bulk-apply a new disposition to past alerts the analyst confirmed. */
applyRedisposition: (payload: RedispositionApplyRequest) =>
request<RedispositionApplyResponse>("/api/v1/feedback/redisposition/apply", {
method: "POST",
body: JSON.stringify(payload),
}),
/** List analyst overrides the agent has 'learned' from for this tenant. */
listOverrides: (limit = 100) =>
request<OverrideEntry[]>("/api/v1/feedback/overrides", {
params: { limit: String(limit) },
}),
/** Counts of dispositions for the FPR card on the SOC dashboard. */
summary: () => request<OverrideSummary>("/api/v1/feedback/summary"),
};
// ─── Deployment & AI (air-gap + LLM provider snapshot) ───────────────────────
//
// Read-only operator visibility for "where will my AI calls actually go?" and
// "is air-gap actually engaged on this pod?". Both endpoints are unauthenticated
// snapshots that mirror the same code paths the runtime uses to gate egress
// (``app.core.airgap.is_host_allowed_for_airgap``) and pick the LLM transport
// (``services/agents/app/api/explain.py``), so the indicator the operator sees
// in the Settings → "Deployment & AI" panel cannot drift from runtime behaviour.
export interface AirgapStatus {
/** True when AISOC_AIRGAPPED is set; the egress gate is enforcing. */
enabled: boolean;
/** Operator-supplied AISOC_AIRGAP_ALLOWLIST entries. */
allowlist: string[];
/** Always-allowed private/internal suffixes (.local, .internal, ...). */
implicit_private_suffixes: string[];
/** Human-readable summary suitable for audit reports. */
policy: string;
}
export type LlmProvider =
| "openai"
| "anthropic"
| "azure-openai"
| "local-ollama"
| "local-vllm"
| "local-litellm"
| "custom"
| "none";
export type LlmEffectivePath = "live" | "fallback";
export type LlmRecentHealth = "healthy" | "degraded" | "unknown";
export interface LlmStatus {
/** Stable provider id classified from the configured base URL. */
provider: LlmProvider;
/** LLM_MODEL / OPENAI_MODEL / AISOC_LLM_MODEL — empty string when unset. */
model: string;
/** Configured base URL (LLM_BASE_URL or OPENAI_BASE_URL). Empty when unset. */
base_url: string;
/** Hostname extracted from base_url (lowercased), or "" when no base_url. */
host: string;
/**
* Whether ``OPENAI_API_KEY`` / ``LLM_API_KEY`` is set. The key itself is
* never returned — even partially redacted.
*/
key_set: boolean;
/** Mirrors AirgapStatus.enabled. */
airgap_enabled: boolean;
/**
* Whether the configured LLM host would be permitted by the egress gate at
* request time. Always true when air-gap is OFF or no LLM is configured.
*/
airgap_compliant: boolean;
/** Best-effort "this is clearly a local LLM" hint for the UI badge. */
is_local: boolean;
/**
* Which branch the Explain endpoint would actually take right now:
* ``live`` = real LLM call, ``fallback`` = deterministic OCSF/MITRE summary.
*/
effective_path: LlmEffectivePath;
/** Operator-readable explanation of the current state. */
policy_note: string;
/**
* Whether the provider is actually *answering*, from the outcomes of the
* calls this pod already made — not a probe, and not a latency figure.
*
* Everything above describes configuration, which is why a deployment
* timing out on every call used to render the emerald "Live" pill. Three
* states, and ``unknown`` is a real one: a pod that has observed no call
* has not earned a green badge.
*/
recent_health: LlmRecentHealth;
/** Observed chat-completions calls in the recent window (this pod only). */
recent_calls: number;
/** How many of those failed. */
recent_failures: number;
/** Operator-readable summary of the window, including what to do about it. */
recent_note: string;
}
// ─── BYOK per-tenant LLM credentials (WS-H2) ────────────────────────────────
//
// Mirrors ``services/api/app/api/v1/endpoints/llm_credentials.py``. The
// plaintext API key is *write-only*; the server stores it vault-encrypted
// and only ever returns ``has_api_key: bool`` so the UI can render
// "credential set / not set" without round-tripping the secret.
//
// Provider invariants enforced server-side and surfaced in the UI:
// - ``local-ollama`` / ``local-vllm`` / ``local-litellm`` / ``custom``
// require a ``base_url``.
// - ``openai`` / ``anthropic`` / ``azure-openai`` require an ``api_key``
// (on first write; rotation-only PUTs may pass ``api_key: null``).
//
// The provider list is a *strict subset* of the read-side ``LlmProvider``
// — ``none`` is never a writable choice.
export type LlmWritableProvider =
| "openai"
| "anthropic"
| "azure-openai"
| "local-ollama"
| "local-vllm"
| "local-litellm"
| "custom";
export interface LlmCredentialUpsert {
provider: LlmWritableProvider;
/** Required for local + custom providers. Optional for hosted SaaS. */
base_url?: string | null;
/** Optional model override (e.g. "gpt-4o-mini"). */
model?: string | null;
/**
* Plaintext API key. Server vault-encrypts before persistence. Pass
* ``null`` (or omit) on a rotation-only PUT to keep the existing
* ciphertext untouched.
*/
api_key?: string | null;
/** Free-form provider-specific settings (e.g. ``{ "temperature": 0.2 }``). */
settings?: Record<string, unknown> | null;
enabled?: boolean;
}
export interface LlmCredentialView {
provider: LlmWritableProvider;
base_url: string | null;
model: string | null;
/** True iff a vault-encrypted ciphertext is currently stored. */
has_api_key: boolean;
settings: Record<string, unknown>;
enabled: boolean;
created_at: string;
updated_at: string;
/** Last time the API key was rotated (set/changed). Null if never. */
last_rotated_at: string | null;
}
/**
* Where the local model is actually running, as Ollama reports it.
*
* Distinct from `LlmStatus`, which describes *configuration*. A GPU
* reservation is a request: a model can still land on the CPU for want of
* VRAM or a usable driver, so this is the outcome rather than the intent.
*/
export interface LlmRuntime {
placement: "gpu" | "partial" | "cpu" | "unknown" | "unreachable" | "not_local";
detail: string;
base_url: string;
/** What an operator can do about the answer. Never empty for a CPU verdict. */
options: string[];
/** Absent, not zero, when nothing is loaded — "not measured" is not "zero". */
model?: string;
vram_bytes?: number;
total_bytes?: number;
}
export const llmApi = {
/** Ask the model where it is running. Reports, never changes. */
runtime: () => request<LlmRuntime>("/api/v1/llm/runtime"),
};
export interface LlmCredentialTestResult {
outcome: "ok" | "refused" | "unreachable" | "unverified";
detail: string;
provider: string;
model?: string;
latency_ms?: number;
}
/**
* The chat models a custom OpenAI-compatible endpoint listed at ``/models``.
*
* ``listed`` is every distinct id the endpoint returned and ``excluded`` the
* ones judged not chat-capable (image, audio, embedding and similar), so the
* selector can say how much it filtered. Any outcome other than ``ok`` comes
* with an empty ``models``: the hand-typed id is the fallback, never a guess.
*/
export interface LlmModelDiscoveryResult {
outcome: "ok" | "refused" | "unreachable" | "unverified";
detail: string;
models: { id: string; name?: string | null }[];
listed: number;
excluded: number;
truncated: boolean;
}
export const deploymentApi = {
/** Live air-gap policy snapshot for this pod. Safe to poll. */
getAirgapStatus: () => request<AirgapStatus>("/api/v1/airgap/status"),
/** Live LLM provider snapshot. Mirrors the egress gate's classification. */
getLlmStatus: () => request<LlmStatus>("/api/v1/llm/status"),
/**
* Read the tenant's BYOK credential. Returns ``null`` when no credential
* is configured (the platform falls back to env-var defaults in that case).
*/
getLlmCredential: () => request<LlmCredentialView | null>("/api/v1/llm/credentials"),
/** Create or update the tenant's BYOK credential. */
upsertLlmCredential: (payload: LlmCredentialUpsert) =>
request<LlmCredentialView>("/api/v1/llm/credentials", {
method: "PUT",
body: JSON.stringify(payload),
}),
/** Hard-delete the credential. Returns 204 on success. */
deleteLlmCredential: () => request<void>("/api/v1/llm/credentials", { method: "DELETE" }),
/**
* Make one real call with the saved credential and report what happened.
*
* The routes above validate shape and never talk to the provider, so a
* revoked key used to surface as triage quietly falling back. `unverified`
* is a success-adjacent outcome: an air-gapped deployment refuses the
* egress rather than attempting it, which is the policy working.
*/
testLlmCredential: () =>
request<LlmCredentialTestResult>("/api/v1/llm/credentials/test", {
method: "POST",
}),
/**
* List the chat models a ``custom`` endpoint serves.
*
* Works before the form is saved: ``base_url`` and ``api_key`` are used for
* this one request and never stored. Omit ``api_key`` to use the stored key,
* which the server sends only to the stored base URL.
*/
discoverLlmModels: (payload: { base_url?: string | null; api_key?: string | null }) =>
request<LlmModelDiscoveryResult>("/api/v1/llm/credentials/models", {
method: "POST",
body: JSON.stringify(payload),
}),
};
// ─── Reports / Executive digest (WS-G2) ─────────────────────────────────────
export interface DigestPeriod {
start: string;
end: string;
label: string;
}
export interface SeveritySplit {
critical: number;
high: number;
medium: number;
low: number;
info: number;
}
export interface AlertSummary {
total: number;
new: number;
resolved: number;
open_at_period_end: number;
severity: SeveritySplit;
}
export interface CaseSummary {
opened: number;
closed: number;
open_at_period_end: number;
sla_breached: number;
}
export interface MttSummary {
mttd_hours: number | null;
mttr_hours: number | null;
mttc_hours: number | null;
}
export interface TacticHighlight {
tactic: string;
count: number;
delta_from_prior: number;
}
export interface TopSourceHighlight {
connector_type: string;
count: number;
}
export interface HighRiskAlertHighlight {
alert_id: string;
title: string;
severity: string;
ai_score: number | null;
mitre_tactics: string[];
event_time: string;
}
export interface AutomationSummary {
total_decisions: number;
auto_executed: number;
escalated: number;
review_pending: number;
}
export interface DigestRecommendation {
severity: "info" | "warning" | "critical" | string;
title: string;
body: string;
}
export interface ExecutiveDigest {
tenant_id: string;
period: DigestPeriod;
headline: string;
alerts: AlertSummary;
cases: CaseSummary;
mtt: MttSummary;
top_tactics: TacticHighlight[];
top_sources: TopSourceHighlight[];
high_risk_alerts: HighRiskAlertHighlight[];
automation: AutomationSummary;
recommendations: DigestRecommendation[];
}
export interface WeeklyDigestParams {
/** ISO timestamp for the start of the window. Defaults to now-7d on the API. */
period_start?: string;
/** ISO timestamp for the end of the window. Defaults to now on the API. */
period_end?: string;
}
export const reportsApi = {
/**
* Fetch the executive weekly digest for the current tenant as structured
* JSON suitable for rendering an interactive panel in the web UI.
*/
weeklyDigest: (params: WeeklyDigestParams = {}) =>
request<ExecutiveDigest>("/api/v1/reports/digest/weekly", {
params: { format: "json", ...params },
}),
/**
* Fetch the print-ready HTML representation of the weekly digest as a string.
* Pairs naturally with `URL.createObjectURL(new Blob([html], …))` so the UI
* can pop a new tab and let the browser's native "Save as PDF" produce the
* board-ready document — no server-side PDF dependency required.
*
* Goes through the shared `request()` plumbing so it inherits the same auth
* (cookie + optional localStorage bearer) and tenant header treatment as the
* JSON variant.
*/
weeklyDigestHtml: async (params: WeeklyDigestParams = {}): Promise<string> => {
const search = new URLSearchParams({ format: "html" });
if (params.period_start) search.set("period_start", params.period_start);
if (params.period_end) search.set("period_end", params.period_end);
const headers = apiHeaders({ Accept: "text/html" });
const url = `${API_BASE}/api/v1/reports/digest/weekly?${search.toString()}`;
const response = await fetch(url, { headers, cache: "no-store" });
if (!response.ok) {
const detail = await response.text().catch(() => "");
throw new ApiError(
`API ${response.status} ${response.statusText} — /reports/digest/weekly`,
response.status,
detail
);
}
return response.text();
},
};
// ─── Cost dashboard (WS-H1) ─────────────────────────────────────────────────
export interface DashboardPeriod {
/** ISO timestamp marking the start of the rolling window (inclusive). */
start: string;
/** ISO timestamp marking the end of the window (exclusive, i.e. now()). */
end: string;
/** Width of the window in days, derived from start/end. */
window_days: number;
/** Human-readable label, e.g. "Apr 9 – May 9, 2026". */
label: string;
}
export interface CostHeadline {
/**
* **Measured** LLM cost in USD — what the gateway reported it charged.
* Only meaningful when ``measured_call_count > 0``: a zero there means
* nothing measured this window, which is not the same as a free one.
*/
total_cost_usd: number;
/** Calls the measured sum was computed over. 0 ⇒ render "not measured". */
measured_call_count: number;
/** List-price estimate for calls the gateway did not price. Label it. */
estimated_cost_usd: number;
estimated_call_count: number;
/** Calls nothing could price at all. */
unpriced_call_count: number;
/** Sum of prompt + completion tokens. */
total_tokens: number;
/** Total LLM API call count (one row in aisoc_run_costs ≈ one call). */
total_calls: number;
/** Distinct investigation_runs that produced cost in the window. */
total_runs: number;
/** Mean measured cost per run; null when nothing was measured. */
avg_cost_per_run_usd: number | null;
}
export interface CostBucket {
/** Calendar day in UTC, ISO ``YYYY-MM-DD``. */
day: string;
/** Measured cost for the day; see ``measured_call_count``. */
total_cost_usd: number;
measured_call_count: number;
estimated_cost_usd: number;
estimated_call_count: number;
unpriced_call_count: number;
total_tokens: number;
call_count: number;
}
export interface ModelBreakdown {
/** Lowercased model id as requested — usually an ``aisoc-<role>`` alias. */
model: string;
/** What the gateway resolved that alias to, e.g. ``ollama/qwen2:1.5b``. */
resolved_model: string | null;
runs: number;
calls: number;
total_prompt_tokens: number;
total_completion_tokens: number;
/** Measured cost; see ``measured_call_count``. */
total_cost_usd: number;
measured_call_count: number;
estimated_cost_usd: number;
estimated_call_count: number;
unpriced_call_count: number;
/**
* What this volume would have cost on the public list price. Read it with
* ``imputed_is_estimable``: false means the model has no published price
* and this is 0 because there is nothing to compute, not because it is free.
*/
imputed_public_cost_usd: number;
imputed_is_estimable: boolean;
/** Tokens the imputation had to skip, so partial coverage is visible. */
unpriced_tokens: number;
avg_latency_ms: number | null;
}
export interface TopCostCase {
case_id: string;
runs: number;
total_cost_usd: number;
measured_call_count: number;
estimated_cost_usd: number;
estimated_call_count: number;
total_tokens: number;
}
export interface ActionCount {
/** ``cases:read``, ``alerts:write``, etc. — straight from audit_log.action. */
action: string;
count: number;
}
export interface ByokSavings {
/** True iff the current LLM provider is loopback / private (BYOK active). */
is_byok_active: boolean;
/** Provider id from /llm/status (e.g. ``openai``, ``local-ollama``). */
provider: string;
/** Measured cost — what the gateway reported. See ``recorded_is_measured``. */
recorded_cost_usd: number;
/** False when nothing in the window was measured, so 0 means "unknown". */
recorded_is_measured: boolean;
/**
* Re-priced using public list pricing (BYOK-neutral baseline). There is no
* default rate: applying one to a gateway alias is what produced savings
* figures for spend that never happened.
*/
imputed_public_cost_usd: number;
/** False => no model in the window has a published price; render "—". */
imputed_is_estimable: boolean;
/** Tokens excluded from the imputation because nothing prices them. */
unpriced_tokens: number;
/**
* Estimated savings vs hosted: equals imputed_public_cost on BYOK,
* ``max(imputed - recorded, 0)`` otherwise. Meaningless unless
* ``imputed_is_estimable``.
*/
savings_usd: number;
}
export interface StorageTierProjection {
tier: string;
retention_days: number;
resident_gb: number;
rate_usd_per_gb_month: number;
monthly_usd: number;
}
/**
* ADR-0005 / 6b — projected storage cost beside the measured LLM spend.
*
* A projection, never a bill: it runs the committed storage cost model over
* one measurement (the uncompressed bytes this tenant's events occupied in
* the lake) at reference list prices. `measured` is the field that matters —
* when it is false every money field is `null`, not `0`, because the lake
* runs in the `full` profile and a confident zero for a tenant nobody
* measured reads as free storage.
*/
export interface StorageCostProjection {
measured: boolean;
/** Why there is no projection. Null when there is one. */
unmeasured_reason: string | null;
raw_bytes_measured: number | null;
events_measured: number | null;
raw_tb_per_day: number | null;
monthly_usd: number | null;
usd_per_raw_tb_ingested: number | null;
tiers: StorageTierProjection[];
compression_ratio: number;
disclaimer: string;
}
export interface CostDashboard {
tenant_id: string;
period: DashboardPeriod;
headline: CostHeadline;
daily_costs: CostBucket[];
by_model: ModelBreakdown[];
top_cases: TopCostCase[];
action_counts: ActionCount[];
byok_savings: ByokSavings;
storage: StorageCostProjection;
}
/**
* Query parameters for the cost-dashboard endpoint. Declared as a `type`
* (not interface) so it satisfies the request helper's
* `Record<string, string | number | boolean | undefined>` constraint.
*/
export type CostDashboardParams = {
/**
* Rolling window in days. The API clamps to ``[1, 365]`` and defaults
* to 30 — leaving this unset is the right call for the default view.
*/
window_days?: number;
};
export const costsApi = {
/**
* WS-H1 — fetch the cost dashboard snapshot for the current tenant.
*
* Backs the admin cost dashboard at ``apps/web/src/app/(admin)/costs``.
* Requires the ``reports:read`` permission server-side (granted to
* tenant_admin / soc_lead / soc_analyst / threat_hunter / viewer), so
* the page is gated by the same role bar that protects the executive
* digest.
*/
dashboard: (params: CostDashboardParams = {}) =>
request<CostDashboard>("/api/v1/costs/dashboard", { params }),
};
// ─── Audit log / compliance bundle helpers ──────────────────────────────────
/**
* Filters accepted by the audit-log export endpoint. Mirrors the query
* parameters supported by ``GET /api/v1/audit/export`` so the UI layer can
* forward whatever the analyst is currently filtering on without translation.
*/
export type AuditExportFilters = {
action?: string;
resource?: string;
actor_id?: string;
search?: string;
/** Hard cap to keep a single export bounded — defaults to API max (10 000). */
limit?: number;
};
function buildAuditExportSearch(
filters: AuditExportFilters,
format: "csv" | "html"
): URLSearchParams {
const search = new URLSearchParams({ format });
if (filters.action) search.set("action", filters.action);
if (filters.resource) search.set("resource", filters.resource);
if (filters.actor_id) search.set("actor_id", filters.actor_id);
if (filters.search) search.set("search", filters.search);
if (typeof filters.limit === "number" && filters.limit > 0) {
search.set("limit", String(filters.limit));
}
return search;
}
function buildAuditExportHeaders(accept: string): Record<string, string> {
const headers = apiHeaders({ Accept: accept });
return headers;
}
export const auditApi = {
/**
* WS-H3 — download the (filtered) audit trail as RFC 4180 CSV. Returns the
* raw CSV body so the UI can wrap it in a Blob and trigger a download via
* an anchor click. Going through ``fetch`` (instead of a plain anchor) lets
* us forward the bearer token from localStorage and surface an
* ``ApiError`` if the export is rejected (e.g. missing audit_log:read).
*/
exportCsv: async (
filters: AuditExportFilters = {}
): Promise<{ body: string; filename: string }> => {
const url = `${API_BASE}/api/v1/audit/export?${buildAuditExportSearch(filters, "csv").toString()}`;
const response = await fetch(url, {
headers: buildAuditExportHeaders("text/csv"),
cache: "no-store",
});
if (!response.ok) {
const detail = await response.text().catch(() => "");
throw new ApiError(
`API ${response.status} ${response.statusText} — /audit/export?format=csv`,
response.status,
detail
);
}
const filename = parseFilenameFromContentDisposition(
response.headers.get("Content-Disposition"),
`aisoc-audit-${timestampSlug()}.csv`
);
const body = await response.text();
return { body, filename };
},
/**
* WS-H3 — fetch the print-ready HTML bundle of the (filtered) audit trail.
* Mirrors ``reportsApi.weeklyDigestHtml``: pop the result into a new tab and
* let the browser's native "Save as PDF" produce the compliance binder, no
* server-side weasyprint dependency required.
*/
exportHtml: async (
filters: AuditExportFilters = {}
): Promise<{ html: string; filename: string }> => {
const url = `${API_BASE}/api/v1/audit/export?${buildAuditExportSearch(filters, "html").toString()}`;
const response = await fetch(url, {
headers: buildAuditExportHeaders("text/html"),
cache: "no-store",
});
if (!response.ok) {
const detail = await response.text().catch(() => "");
throw new ApiError(
`API ${response.status} ${response.statusText} — /audit/export?format=html`,
response.status,
detail
);
}
const filename = parseFilenameFromContentDisposition(
response.headers.get("Content-Disposition"),
`aisoc-audit-${timestampSlug()}.html`
);
const html = await response.text();
return { html, filename };
},
};
/** Parse ``filename="…"`` out of a Content-Disposition header. */
function parseFilenameFromContentDisposition(header: string | null, fallback: string): string {
if (!header) return fallback;
// Match RFC 6266 filename="…" — quoted form is what FastAPI emits for us.
const match = header.match(/filename="([^"]+)"/i);
return match ? match[1] : fallback;
}
/** ``20260509T234501Z`` style slug for client-side filenames. */
function timestampSlug(): string {
const now = new Date();
const pad = (n: number) => n.toString().padStart(2, "0");
return (
`${now.getUTCFullYear()}` +
`${pad(now.getUTCMonth() + 1)}` +
`${pad(now.getUTCDate())}` +
`T${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}Z`
);
}
// ─── Saved views (per-user filter + column presets) ──────────────────────────
//
// Workstream F3 — analyst quality-of-life. Lets each user park a filter +
// column preset on a list page (alerts, cases, investigations, playbooks)
// and reload it with one click. One preset per ``(user, view_type)`` can be
// flagged ``is_default``; the UI auto-applies it on first load.
//
// The wire format mirrors ``services/api/app/api/v1/endpoints/saved_views.py``
// 1:1: opaque ``filters`` and ``columns`` blobs are owned by the page
// rendering them, so callers cast to whatever shape they need (e.g.
// ``AlertFilters`` for the alerts page) without round-tripping through this
// type. That keeps the saved-views API a *generic* preset store rather than
// a tight coupling between every list page and this client.
/** Pages that support saved views — must match the backend allowlist. */
export type SavedViewType = "alerts" | "cases" | "investigations" | "playbooks";
/** A saved-view row as returned by the API. */
export interface SavedView {
id: string;
view_type: SavedViewType;
name: string;
/** Page-specific filter blob — opaque to this client. */
filters: Record<string, unknown>;
/** Optional column override. ``null`` means "use page defaults". */
columns: unknown[] | Record<string, unknown> | null;
is_default: boolean;
created_at: string;
updated_at: string;
}
/** Body for ``POST /saved-views``. */
export interface SavedViewCreateRequest {
view_type: SavedViewType;
name: string;
filters?: Record<string, unknown>;
columns?: unknown[] | Record<string, unknown> | null;
is_default?: boolean;
}
/** Body for ``PATCH /saved-views/{id}`` — every field is optional. */
export interface SavedViewUpdateRequest {
name?: string;
filters?: Record<string, unknown>;
/** Pass ``null`` to clear a previously-saved column override. */
columns?: unknown[] | Record<string, unknown> | null;
is_default?: boolean;
}
export const savedViewsApi = {
/**
* List the caller's presets for one list page. Sorted by
* ``is_default DESC, updated_at DESC`` server-side, so the default
* preset (if any) lands first.
*/
list: (viewType: SavedViewType) =>
request<SavedView[]>("/api/v1/saved-views", {
params: { view_type: viewType },
}),
/** Create a new preset. Returns the freshly-stamped row. */
create: (payload: SavedViewCreateRequest) =>
request<SavedView>("/api/v1/saved-views", {
method: "POST",
body: JSON.stringify(payload),
}),
/** Patch a preset in place — rename, retune filters, toggle default. */
update: (id: string, payload: SavedViewUpdateRequest) =>
request<SavedView>(`/api/v1/saved-views/${id}`, {
method: "PATCH",
body: JSON.stringify(payload),
}),
/** Delete a preset. Returns ``{}`` on the 204 response. */
delete: (id: string) =>
request<Record<string, never>>(`/api/v1/saved-views/${id}`, {
method: "DELETE",
}),
};
// ─── Realtime / WebSocket helpers ────────────────────────────────────────────
export interface RealtimeTicket {
token: string;
expires_in: number;
tenant_id: string;
}
export const realtimeApi = {
/**
* Mint a short-lived (≤60s), audience-scoped HS256 ticket for the realtime
* WS/SSE edge (Issue #239). This authenticated call uses the caller's session
* Bearer token (attached automatically by `request`); the API derives the
* tenant server-side, so the browser never chooses its own tenant. The
* returned `token` is appended as `?token=` to the WS/SSE URL immediately
* before connecting and re-fetched on every (re)connect since it expires fast.
*/
ticket: () => request<RealtimeTicket>("/api/v1/realtime/ticket", { method: "POST" }),
/**
* Returns a ready-to-open WebSocket URL for the given channel, with a freshly
* minted ticket attached as `?token=`. Async because it must authenticate
* (mint a ticket) first — the realtime service rejects tokenless upgrades.
* The tenant is derived from the verified ticket claim server-side, so we no
* longer pass (untrusted) `tenant_id` in the query string.
*/
async channelUrl(channel: "alerts" | "cases" | "agents" | "insights" | "all"): Promise<string> {
const { token } = await realtimeApi.ticket();
return `${wsOrigin()}/ws/${channel}?token=${encodeURIComponent(token)}`;
},
/**
* Returns a ready-to-open SSE URL with a freshly minted ticket attached as
* `?token=`. Mirrors `channelUrl` for the EventSource transport.
*/
async sseUrl(): Promise<string> {
const { token } = await realtimeApi.ticket();
const base = REALTIME_BASE || "";
return `${base}/sse?token=${encodeURIComponent(token)}`;
},
/**
* Health endpoint of the realtime gateway, useful for status pages.
* Uses the dedicated `/api/v1/realtime/healthz` proxy path so it works
* same-origin behind the Cloudflare Tunnel.
*/
health: () =>
request<{ status: string; clients: number }>("/api/v1/realtime/healthz", {
baseUrl: REALTIME_BASE,
}),
};
export default {
alerts: alertsApi,
entityRisk: entityRiskApi,
cases: casesApi,
metrics: metricsApi,
connectors: connectorsApi,
inbox: inboxApi,
oauth: oauthApi,
threatIntel: threatIntelApi,
agents: agentsApi,
hunt: huntApi,
savedHunts: savedHuntsApi,
nlQuery: nlQueryApi,
graph: graphApi,
detection: detectionApi,
detectionProposals: detectionProposalsApi,
tuning: tuningApi,
copilot: copilotApi,
contextual: contextualApi,
ledger: ledgerApi,
realtime: realtimeApi,
responder: responderApi,
passkey: passkeyApi,
autonomyPolicy: autonomyPolicyApi,
feedback: feedbackApi,
deployment: deploymentApi,
reports: reportsApi,
costs: costsApi,
savedViews: savedViewsApi,
};
// ─── API keys ────────────────────────────────────────────────────────────────
//
// The settings panel used to mint an `aisoc_live_…` secret in the browser with
// `crypto.getRandomValues` and report "API key created". That string
// authenticated nothing, so a user would wire it into a CI pipeline or a
// forwarder and get silent 401s — while believing they held a working
// credential. The real CRUD backend has existed at `/api/v1/api-keys` all
// along; it simply had no client binding.
export interface ApiKeyRecord {
id: string;
name: string;
prefix: string;
scopes: string[];
is_active: boolean;
expires_at: string | null;
last_used_at: string | null;
created_at: string;
}
/** Create response. `key` is the raw secret and is returned exactly once. */
export interface CreatedApiKey extends Omit<ApiKeyRecord, "is_active" | "last_used_at"> {
key: string;
}
export interface CreateApiKeyInput {
name: string;
scopes?: string[];
expires_in_days?: number | null;
}
export const apiKeysApi = {
list: () => request<ApiKeyRecord[]>("/api/v1/api-keys"),
create: (data: CreateApiKeyInput) =>
request<CreatedApiKey>("/api/v1/api-keys", {
method: "POST",
body: JSON.stringify(data),
}),
update: (id: string, data: Partial<CreateApiKeyInput>) =>
request<ApiKeyRecord>(`/api/v1/api-keys/${id}`, {
method: "PATCH",
body: JSON.stringify(data),
}),
revoke: (id: string) => request<void>(`/api/v1/api-keys/${id}`, { method: "DELETE" }),
};
// ─── SCIM credentials ────────────────────────────────────────────────────────
//
// `apps/docs/docs/operations/scim.md` told administrators to "mint one from
// the console". The CRUD backend at `/api/v1/scim-tokens` had existed since
// the SCIM surface shipped and the console had no binding to it at all — not
// a panel, not a client function, not a string containing "scim" anywhere
// under `apps/web/src` — so the only way to obtain a credential was the curl
// command two paragraphs further down.
export interface ScimTokenRecord {
id: string;
name: string;
/** Display prefix. The secret itself is stored as a digest and never returned. */
prefix: string;
org_id: string | null;
created_at: string;
last_used_at: string | null;
expires_at: string | null;
revoked_at: string | null;
rotated_from_id: string | null;
active: boolean;
}
/** Create and rotate both return the raw secret, exactly once. */
export interface CreatedScimToken extends ScimTokenRecord {
token: string;
}
export const scimTokensApi = {
list: () => request<ScimTokenRecord[]>("/api/v1/scim-tokens"),
create: (data: { name: string; expires_in_days?: number | null }) =>
request<CreatedScimToken>("/api/v1/scim-tokens", {
method: "POST",
body: JSON.stringify(data),
}),
/**
* Both secrets work for `grace_hours`, so the replacement can be pasted
* into the identity provider without a failed sync in between. Zero
* revokes the old one at once, which is the right trade after a
* disclosure and the wrong one otherwise.
*/
rotate: (id: string, grace_hours: number) =>
request<CreatedScimToken>(`/api/v1/scim-tokens/${id}/rotate`, {
method: "POST",
body: JSON.stringify({ grace_hours }),
}),
revoke: (id: string) => request<void>(`/api/v1/scim-tokens/${id}`, { method: "DELETE" }),
};
// ─── Replay evaluation (gap-closure Phase 1.4) ───────────────────────────────
//
// Wraps `services/api/app/api/v1/endpoints/evaluations.py`: measure triage
// against a tenant's own analysts, on their own closed findings.
//
// Every field the console needs to show sample sizes beside the headline is
// on the summary, not buried in `score`. That is deliberate on both sides: a
// headline accuracy rendered without the count behind it is the single most
// misleading thing this surface could print, so the two travel together
// through the wire shape rather than by a convention the UI has to remember.
//
// `headline_accuracy` is `null` when the window held too few malicious cases
// for a headline to mean anything, and `headline_withheld_reason` carries the
// sentence explaining that. Null is not zero: a zero in an accuracy column
// says the agent got every answer wrong, which is a different fact with a
// different remedy.
export type ReplayEvaluationStatus = "queued" | "running" | "completed" | "failed";
export interface ReplayEvaluationSummary {
id: string;
status: ReplayEvaluationStatus;
error: string | null;
connector_id: string;
vendor: string;
window_start: string;
window_end: string;
train_fraction: number;
bootstrap_seed: number;
bootstrap_resamples: number;
findings_read: number;
findings_labelled: number;
decisions_recorded: number;
graded: number;
malicious_support: number;
headline_accuracy: number | null;
headline_withheld_reason: string | null;
malicious_recall: number | null;
created_at: string;
started_at: string | null;
completed_at: string | null;
is_terminal: boolean;
}
export interface ReplayEvaluationDetail extends ReplayEvaluationSummary {
/** The full `ReplayScore.as_dict()`. */
score: Record<string, unknown> | null;
/** Split point, frozen-context provenance, attempted writes, envelope gaps. */
method: Record<string, unknown> | null;
/** The artefact stored when the run completed, not a re-render. */
report_markdown: string | null;
}
export interface ReplayableConnectorInfo {
connector_type: string;
vendor: string;
label: string;
}
export interface ReplayCapabilities {
connectors: ReplayableConnectorInfo[];
default_window_days: number;
default_train_fraction: number;
default_bootstrap_seed: number;
default_bootstrap_resamples: number;
/** Below this many malicious cases no headline accuracy is printed. */
min_malicious_for_headline: number;
max_findings: number;
}
export interface StartReplayInput {
connector_id: string;
since?: string;
until?: string;
train_fraction?: number;
limit?: number;
}
export type ReplayExportFormat = "markdown" | "json" | "pdf";
export const evaluationsApi = {
capabilities: () => request<ReplayCapabilities>("/api/v1/evaluations/replay/capabilities"),
list: (limit = 50) =>
request<ReplayEvaluationSummary[]>("/api/v1/evaluations/replay", {
params: { limit },
}),
get: (id: string) => request<ReplayEvaluationDetail>(`/api/v1/evaluations/replay/${id}`),
decisions: (id: string, limit = 2000) =>
request<Array<Record<string, unknown>>>(`/api/v1/evaluations/replay/${id}/decisions`, {
params: { limit },
}),
start: (data: StartReplayInput) =>
request<ReplayEvaluationSummary>("/api/v1/evaluations/replay", {
method: "POST",
body: JSON.stringify(data),
}),
/**
* Where a download points. Built rather than fetched because the browser
* does the download, and the route already sets `Content-Disposition`.
*
* `exclude_latency` is offered on every format: the two wall-clock figures
* are the only part of the report that does not reproduce between runs, so
* an operator diffing two exports wants them gone.
*/
exportUrl: (id: string, format: ReplayExportFormat, excludeLatency = false): string =>
`${API_BASE}/api/v1/evaluations/replay/${id}/export` +
`?format=${format}&exclude_latency=${excludeLatency ? "true" : "false"}`,
};
// ─── Case depth (depth 9.3 / parity 5.6 remainder) ───────────────────────────
export interface BulkTriageChange {
set_status?: string;
set_severity?: string;
assign_to?: string;
unassign?: boolean;
}
export interface BulkTriageResult {
matched_count: number;
updated_count: number;
changes: Record<string, unknown>;
}
export interface AnalystWorkloadRow {
analyst: string;
total: number;
open_cases: number;
closed_cases: number;
open_high_or_critical: number;
overdue: number;
/**
* `null` when the analyst has closed nothing in the window. The console
* must render that as "no data" and never as `0.0`, which reads as
* "instant" — the exact confusion that left two console figures wrong for
* months.
*/
mean_hours_to_close: number | null;
/** How many closed cases the mean above was taken over. */
mean_over_cases: number;
}
export interface AnalystWorkload {
since: string;
computed_at: string;
analysts: AnalystWorkloadRow[];
unassigned: { open_cases: number; open_high_or_critical: number };
}
/**
* One war room row, as `GET /api/v1/war-rooms/cases/{id}` returns it.
*
* `last_synced_at: null` means the sweep has never run for this room — a
* different fact from "ran and had nothing to say", and the panel renders
* them differently. `last_error` is empty on success; a room that has
* silently stopped mirroring is worse than one that was never opened, so
* the reason is surfaced rather than swallowed.
*/
export interface WarRoom {
id: string;
case_id: string;
provider: string;
channel_id: string;
channel_name: string;
channel_url: string;
state: string;
opened_by: string;
last_synced_at: string | null;
last_error: string;
}
// Depth 9.4 — case war rooms. #1315 shipped WarRoomPanel importing this
// client without adding it, so the component could not typecheck; added by
// the merge train against the server's own response models.
export const warRoomApi = {
forCase: (caseId: string) => request<WarRoom[]>(`/api/v1/war-rooms/cases/${encodeURIComponent(caseId)}`),
/** Open fails loudly by design: the analyst pressed a button, so a vendor
* refusal surfaces as the vendor's own sentence rather than a quiet retry. */
open: (caseId: string, provider: 'slack' | 'teams') =>
request<WarRoom>(`/api/v1/war-rooms/cases/${encodeURIComponent(caseId)}`, {
method: 'POST',
body: JSON.stringify({ provider }),
}),
};
export const caseDepthApi = {
/**
* Apply one triage decision to many alerts.
*
* `maxCount` is a preflight the caller states: a larger match is refused
* with a 409 carrying the real figure and **nothing is written**, so the
* first call is a dry run. The bar surfaces that count and asks again
* rather than retrying silently with a bigger number.
*/
bulkTriage: (alertIds: string[], change: BulkTriageChange, maxCount: number, comment = '') =>
request<BulkTriageResult>('/api/v1/case-depth/alerts/bulk-triage', {
method: 'POST',
body: JSON.stringify({ alert_ids: alertIds, max_count: maxCount, comment, ...change }),
}),
mergeAlerts: (primaryId: string, duplicateIds: string[], reason = '') =>
request<{ primary_id: string; merged_ids: string[]; case_id: string | null }>(
'/api/v1/case-depth/alerts/merge',
{
method: 'POST',
body: JSON.stringify({ primary_id: primaryId, duplicate_ids: duplicateIds, reason }),
},
),
mergeCases: (primaryId: string, duplicateIds: string[], reason = '') =>
request<{ primary_id: string; merged_ids: string[]; case_id: string | null }>(
'/api/v1/case-depth/cases/merge',
{
method: 'POST',
body: JSON.stringify({ primary_id: primaryId, duplicate_ids: duplicateIds, reason }),
},
),
workload: (days = 30) =>
request<AnalystWorkload>('/api/v1/case-depth/workload', { params: { days: String(days) } }),
customFields: () =>
request<
Array<{
id: string;
key: string;
label: string;
help_text: string;
field_type: string;
choices: string[];
required: boolean;
position: number;
active: boolean;
}>
>('/api/v1/case-depth/custom-fields'),
caseCustomValues: (caseId: string) =>
request<
Array<{
key: string;
label: string;
field_type: string;
value: string;
required: boolean;
updated_by: string;
updated_at: string | null;
}>
>(`/api/v1/case-depth/cases/${caseId}/custom-values`),
setCaseCustomValues: (caseId: string, values: Record<string, string>) =>
request<unknown>(`/api/v1/case-depth/cases/${caseId}/custom-values`, {
method: 'PUT',
body: JSON.stringify({ values }),
}),
};
// ── Access review (depth plan wave 2, 1.2) ─────────────────────────────────
//
// Read-only. Every route below computes or reads findings; none of them
// changes a vendor object, and the only write is a reviewer acknowledging a
// finding, which is state about the review rather than about the estate.
export interface AccessReviewFinding {
id: string;
run_id: string;
kind: string;
provider: string;
principal_id: string;
severity: "info" | "low" | "medium" | "high" | "critical";
title: string;
detail: string;
/** The object a person should go and change. Never empty. */
object_hint: string;
recommendation: string;
/** Null when usage was not measured, or when no built-in role is smaller. */
best_fit_role: string | null;
evidence: Record<string, unknown>;
/**
* False when no usage data backed this finding. Usage-dependent kinds are
* suppressed entirely in that case, so a false here marks the weaker
* non-usage findings for what they are.
*/
usage_measured: boolean;
acknowledged_at: string | null;
acknowledged_by: string | null;
acknowledged_note: string | null;
first_seen: string | null;
last_seen: string | null;
}
export interface AccessReviewProviderState {
provider: string;
run_state: "nothing_reviewed" | "no_findings" | "findings" | "failed";
reviewed_principals: number;
usage_measured_for: number;
finding_count: number;
window_start: string | null;
window_end: string | null;
note: string | null;
last_run_at: string | null;
}
export interface AccessReviewSummary {
/**
* `never_run` is a distinct state from a run that found nothing, and the
* page renders them differently on purpose: an estate nobody looked at
* must not read as an estate with nothing wrong.
*/
state: "never_run" | "reviewed";
open_findings: number;
providers: AccessReviewProviderState[];
note?: string;
}
export interface AccessReviewKind {
kind: string;
title: string;
severity: string;
object_hint: string;
recommendation: string;
needs_usage: boolean;
}
export const accessReviewApi = {
async kinds(): Promise<{ kinds: AccessReviewKind[] }> {
return request<{ kinds: AccessReviewKind[] }>("/api/v1/access-review/kinds");
},
async summary(provider?: string): Promise<AccessReviewSummary> {
const query = provider ? `?provider=${encodeURIComponent(provider)}` : "";
return request<AccessReviewSummary>(`/api/v1/access-review/summary${query}`);
},
async findings(params: {
provider?: string;
kind?: string;
includeAcknowledged?: boolean;
} = {}): Promise<{ items: AccessReviewFinding[]; count: number }> {
const search = new URLSearchParams();
if (params.provider) search.set("provider", params.provider);
if (params.kind) search.set("kind", params.kind);
if (params.includeAcknowledged) search.set("include_acknowledged", "true");
const query = search.toString();
return request<{ items: AccessReviewFinding[]; count: number }>(
`/api/v1/access-review/findings${query ? `?${query}` : ""}`,
);
},
async run(provider: string): Promise<AccessReviewSummary & { run_id: string }> {
return request<AccessReviewSummary & { run_id: string }>(
`/api/v1/access-review/run?provider=${encodeURIComponent(provider)}`,
{ method: "POST" },
);
},
async acknowledge(findingId: string, note: string): Promise<AccessReviewFinding> {
return request<AccessReviewFinding>(
`/api/v1/access-review/findings/${encodeURIComponent(findingId)}/acknowledge`,
{ method: "POST", body: JSON.stringify({ note }) },
);
},
};