Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

feat(alerts): structured POST /alerts/{id}/explain with rule lineage, FP rate, suggested actions (#90)

Beenu Arorafdd9f2b93d91
diff --git a/apps/web/src/components/alerts/ExplainDrawer.test.tsx b/apps/web/src/components/alerts/ExplainDrawer.test.tsx
index 357178113..900111a5c 100644
--- a/apps/web/src/components/alerts/ExplainDrawer.test.tsx
+++ b/apps/web/src/components/alerts/ExplainDrawer.test.tsx
@@ -1,16 +1,24 @@
-// WS-D1 — pin the ExplainDrawer streaming contract.
+// WS-D1 — pin the ExplainDrawer dual-backend contract.
//
-// The drawer is a thin renderer over the `agentsApi.explainStream` NDJSON
-// pipe, but it owns three things that the rest of the app depends on and
-// that have already broken once before: (1) the abort lifecycle so a closed
-// drawer doesn't keep an LLM call alive, (2) per-frame routing so a re-emitted
-// MITRE card doesn't double-render, and (3) graceful fallback when the
-// backend trips a rate limit or runs into a transport error.
+// The drawer is a thin renderer over two API calls and owns four things
+// the rest of the app depends on:
//
-// We test against a controllable `ReadableStream`: each test gets an
-// `enqueue(frame)` helper and chooses exactly when to close the body. That
-// keeps timing assertions deterministic without faking timers, which is the
-// only way React state batches behave consistently in jsdom.
+// 1. Backend preference — try the structured endpoint
+// (`alertsApi.explain`) first, fall back to the streaming endpoint
+// (`agentsApi.explainStream`) on 404/500/network errors but NOT on
+// 429 (which must surface directly).
+// 2. The abort lifecycle, so a closed drawer doesn't keep an LLM call
+// alive on either backend.
+// 3. Per-frame routing on the streaming path so a re-emitted MITRE
+// card doesn't double-render.
+// 4. Graceful fallback when the streaming backend trips a rate limit
+// or runs into a transport error.
+//
+// We test against a controllable `ReadableStream`: each streaming test
+// gets an `enqueue(frame)` helper and chooses exactly when to close the
+// body. That keeps timing assertions deterministic without faking
+// timers, which is the only way React state batches behave consistently
+// in jsdom.
import { describe, expect, it, vi, beforeEach } from 'vitest';
import { act, render, screen, waitFor } from '@testing-library/react';
@@ -19,16 +27,32 @@ import userEvent from '@testing-library/user-event';
// ─── Mocks ───────────────────────────────────────────────────────────────────
const explainStreamMock = vi.hoisted(() => vi.fn());
-vi.mock('@/lib/api', () => ({
- __esModule: true,
- agentsApi: {
- explainStream: explainStreamMock,
- },
-}));
-
-// Import AFTER the mock so the component picks up our stub.
+const explainStructuredMock = vi.hoisted(() => vi.fn());
+
+// We mock both API surfaces but keep the real `ApiError` class so
+// `instanceof ApiError` checks inside the drawer continue to work.
+vi.mock('@/lib/api', async () => {
+ const actual = await vi.importActual<typeof import('@/lib/api')>('@/lib/api');
+ return {
+ ...actual,
+ agentsApi: {
+ explainStream: explainStreamMock,
+ },
+ alertsApi: {
+ ...actual.alertsApi,
+ explain: explainStructuredMock,
+ },
+ };
+});
+
+// Import AFTER the mock so the component picks up our stubs.
import { ExplainDrawer } from './ExplainDrawer';
-import type { Alert, ExplainStreamFrame } from '@/lib/api';
+import {
+ ApiError,
+ type Alert,
+ type AlertExplanation,
+ type ExplainStreamFrame,
+} from '@/lib/api';
// ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -115,15 +139,27 @@ const ALERT: Alert = {
describe('ExplainDrawer', () => {
beforeEach(() => {
explainStreamMock.mockReset();
+ explainStructuredMock.mockReset();
+ // The drawer prefers the structured endpoint and only falls back to
+ // the stream on non-429 failures. The bulk of these tests pre-date
+ // that endpoint and want to exercise the streaming code path, so we
+ // default the structured mock to a 404 (i.e. backend doesn't have
+ // the route) which triggers the documented fallback. Tests that
+ // care about structured behavior override this in the test body.
+ explainStructuredMock.mockRejectedValue(
+ new ApiError('Not Found', 404, 'route not registered'),
+ );
});
it('returns null when closed', () => {
const { container } = render(
<ExplainDrawer open={false} onClose={vi.fn()} alert={ALERT} />,
);
- // When closed the component renders nothing — no overlay, no aside.
+ // When closed the component renders nothing — no overlay, no aside,
+ // and neither backend should be hit.
expect(container.firstChild).toBeNull();
expect(explainStreamMock).not.toHaveBeenCalled();
+ expect(explainStructuredMock).not.toHaveBeenCalled();
});
it('renders header + sections as frames arrive and closes on done', async () => {
@@ -571,4 +607,308 @@ describe('ExplainDrawer', () => {
expect(attempt).toBe(2);
expect(signalRefs).toHaveLength(2);
});
+
+ // ─── Structured-endpoint behavior ───────────────────────────────────
+ //
+ // These tests pin the dual-backend contract: the drawer must prefer
+ // the structured endpoint when it works, fall back to the stream on
+ // 404/500/network, and surface 429 as a terminal error (no fallback,
+ // because both backends share the tenant LLM budget).
+
+ describe('structured endpoint (POST /alerts/{id}/explain)', () => {
+ /** Build a representative structured payload — small but lifelike. */
+ function buildPayload(
+ overrides: Partial<AlertExplanation> = {},
+ ): AlertExplanation {
+ return {
+ alert_id: ALERT.id,
+ summary:
+ 'Two okta logins for alice from impossible geographic distance ' +
+ 'within 4 minutes — likely account takeover.',
+ rule_lineage: {
+ rule_id: 'rule-okta-impossible-travel-v2',
+ rule_name: 'Okta impossible travel',
+ rule_description:
+ 'Two successful logins from geographically distant locations ' +
+ 'within a window shorter than physical travel time.',
+ rule_severity: 'high',
+ rule_status: 'enabled',
+ rule_language: 'sigma',
+ rule_confidence: 92,
+ is_builtin: true,
+ // raw_event is the strongest deterministic match — what we'd
+ // expect when the alert carries the rule's own raw_event hash.
+ match_method: 'raw_event',
+ confidence: 'high',
+ },
+ historical_fp_rate: {
+ fp_rate: 0.0714,
+ sample_size: 84,
+ false_positives: 6,
+ lookback_days: 30,
+ scope: 'rule',
+ notes: '6 of 84 alerts marked false-positive in the last 30 days.',
+ },
+ mitre_techniques: [
+ {
+ id: 'T1078',
+ name: 'Valid Accounts',
+ tactic_names: ['Defense Evasion', 'Initial Access'],
+ description: 'Adversaries may obtain credentials.',
+ url: 'https://attack.mitre.org/techniques/T1078/',
+ },
+ ],
+ contributing_events: [
+ {
+ label: 'src_ip',
+ value: '203.0.113.42',
+ annotation: 'Frankfurt',
+ },
+ {
+ label: 'distance_km',
+ value: '9100',
+ // Note: annotation deliberately omitted to confirm the
+ // adapter defaults it cleanly.
+ },
+ ],
+ suggested_actions: [
+ {
+ title: 'Force re-authentication',
+ rationale:
+ 'Invalidate active sessions to block the suspicious actor.',
+ playbook_id: 'identity-compromise-v1',
+ priority: 'immediate',
+ },
+ ],
+ llm_used: true,
+ llm_source: 'tenant_byok:openai/gpt-4o-mini',
+ llm_reason: 'tenant has BYOK credentials, model available',
+ generated_at: '2026-05-12T18:30:00Z',
+ ...overrides,
+ };
+ }
+
+ it('renders the structured payload without ever calling the stream', async () => {
+ explainStructuredMock.mockResolvedValueOnce(buildPayload());
+
+ render(<ExplainDrawer open={true} onClose={vi.fn()} alert={ALERT} />);
+
+ // Structured endpoint is hit; stream is not.
+ await waitFor(() => {
+ expect(explainStructuredMock).toHaveBeenCalledTimes(1);
+ expect(explainStructuredMock).toHaveBeenCalledWith(
+ ALERT.id,
+ expect.any(AbortSignal),
+ );
+ });
+ expect(explainStreamMock).not.toHaveBeenCalled();
+
+ // Source badge surfaces "Structured" so QA can spot a fallback.
+ await waitFor(() => {
+ expect(screen.getByText('Structured')).toBeInTheDocument();
+ });
+
+ // Summary, rule lineage, FP rate, MITRE, evidence, and suggested
+ // actions all render together — this is the headline win of the
+ // structured endpoint over streaming.
+ expect(
+ screen.getByText(/likely account takeover/),
+ ).toBeInTheDocument();
+ expect(screen.getByText('Okta impossible travel')).toBeInTheDocument();
+ expect(
+ screen.getByText('rule-okta-impossible-travel-v2'),
+ ).toBeInTheDocument();
+ expect(screen.getByText(/Valid Accounts/)).toBeInTheDocument();
+ expect(screen.getByText('203.0.113.42')).toBeInTheDocument();
+ expect(screen.getByText('Force re-authentication')).toBeInTheDocument();
+
+ // LLM disclosure footer is structured-only and must surface
+ // whether prose is LLM-generated, with the source. This is what
+ // the "audit my AI decisions" workflow consumes.
+ expect(
+ screen.getByText(/tenant_byok:openai\/gpt-4o-mini/),
+ ).toBeInTheDocument();
+
+ // Status flips straight to Done — there's no streaming phase.
+ expect(screen.getByText('Done')).toBeInTheDocument();
+ });
+
+ it('surfaces 429 directly without falling back to the stream', async () => {
+ // Both backends share the LLM cost ledger. Falling back on 429
+ // would silently double-bill the tenant for no benefit, so the
+ // drawer must show the rate-limit message and stop.
+ explainStructuredMock.mockRejectedValueOnce(
+ new ApiError('Too Many Requests', 429, 'retry_after=30'),
+ );
+
+ render(<ExplainDrawer open={true} onClose={vi.fn()} alert={ALERT} />);
+
+ await waitFor(() => {
+ expect(
+ screen.getByText(/Rate limit reached for AI explanations/i),
+ ).toBeInTheDocument();
+ });
+
+ // The stream MUST NOT be tried as a back-channel.
+ expect(explainStreamMock).not.toHaveBeenCalled();
+ // Status reflects the failure and Retry is offered.
+ expect(screen.getByText('Error')).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', { name: 'Retry' }),
+ ).toBeInTheDocument();
+ // Source badge tells QA the failure came from the structured
+ // backend (helps distinguish from a stream-side rate limit).
+ expect(screen.getByText('Structured')).toBeInTheDocument();
+ });
+
+ it('falls back to the stream on 404 (older backend without the route)', async () => {
+ // 404 is the "this version of the API doesn't have the new
+ // endpoint" case — common during canary rollouts. We must not
+ // surface the 404 to the analyst; just transparently downgrade
+ // to the streaming UX.
+ explainStructuredMock.mockRejectedValueOnce(
+ new ApiError('Not Found', 404, 'route not registered'),
+ );
+
+ const signalRef: { current: AbortSignal | undefined } = {
+ current: undefined,
+ };
+ const { response, handle } = buildMockStream({ signalCapture: signalRef });
+ explainStreamMock.mockImplementation(
+ async (_payload: unknown, signal?: AbortSignal) => {
+ signalRef.current = signal;
+ return response;
+ },
+ );
+
+ render(<ExplainDrawer open={true} onClose={vi.fn()} alert={ALERT} />);
+
+ // Structured tried first, then stream — in that order.
+ await waitFor(() => {
+ expect(explainStructuredMock).toHaveBeenCalledTimes(1);
+ expect(explainStreamMock).toHaveBeenCalledTimes(1);
+ });
+
+ await handle.enqueue({
+ kind: 'delta',
+ section: 'summary',
+ text: 'Streaming fallback worked.',
+ });
+ await handle.enqueue({ kind: 'done', alert_id: ALERT.id });
+ await handle.close();
+
+ await waitFor(() => {
+ expect(
+ screen.getByText('Streaming fallback worked.'),
+ ).toBeInTheDocument();
+ // Source badge flips to "Stream" so the analyst (and QA) know
+ // the structured backend wasn't available this time.
+ expect(screen.getByText('Stream')).toBeInTheDocument();
+ });
+ });
+
+ it('falls back to the stream on 500 (backend error)', async () => {
+ // 500 is "the structured endpoint is broken right now" — same
+ // graceful downgrade as 404, but a different signal for ops.
+ explainStructuredMock.mockRejectedValueOnce(
+ new ApiError(
+ 'Internal Server Error',
+ 500,
+ 'rule lineage resolver crashed',
+ ),
+ );
+
+ const signalRef: { current: AbortSignal | undefined } = {
+ current: undefined,
+ };
+ const { response, handle } = buildMockStream({ signalCapture: signalRef });
+ explainStreamMock.mockImplementation(
+ async (_payload: unknown, signal?: AbortSignal) => {
+ signalRef.current = signal;
+ return response;
+ },
+ );
+
+ render(<ExplainDrawer open={true} onClose={vi.fn()} alert={ALERT} />);
+
+ await waitFor(() => {
+ expect(explainStreamMock).toHaveBeenCalledTimes(1);
+ });
+
+ await handle.enqueue({ kind: 'done', alert_id: ALERT.id });
+ await handle.close();
+
+ await waitFor(() => {
+ expect(screen.getByText('Stream')).toBeInTheDocument();
+ });
+ });
+
+ it('aborts the structured request when the drawer closes', async () => {
+ // Same lifecycle contract as the streaming path: closing the
+ // drawer mid-flight must abort the in-flight request so we
+ // don't keep an LLM call (and its cost) alive.
+ let capturedSignal: AbortSignal | undefined;
+ explainStructuredMock.mockImplementation(
+ async (_id: string, signal?: AbortSignal) => {
+ capturedSignal = signal;
+ // Never resolve — we want the abort to kill it.
+ return new Promise<AlertExplanation>(() => {});
+ },
+ );
+
+ const { rerender } = render(
+ <ExplainDrawer open={true} onClose={vi.fn()} alert={ALERT} />,
+ );
+
+ await waitFor(() => {
+ expect(explainStructuredMock).toHaveBeenCalled();
+ expect(capturedSignal).toBeDefined();
+ });
+ expect(capturedSignal?.aborted).toBe(false);
+
+ rerender(<ExplainDrawer open={false} onClose={vi.fn()} alert={ALERT} />);
+
+ await waitFor(() => {
+ expect(capturedSignal?.aborted).toBe(true);
+ });
+
+ // Stream must NOT have been invoked — the close happened before
+ // the structured request could fail and trigger fallback.
+ expect(explainStreamMock).not.toHaveBeenCalled();
+ });
+
+ it('renders structured payload even when llm_used is false (deterministic mode)', async () => {
+ // Air-gapped / no-BYOK path: structured endpoint returns the
+ // deterministic template instead of an LLM summary. The
+ // disclosure must say so plainly so analysts trust the output.
+ explainStructuredMock.mockResolvedValueOnce(
+ buildPayload({
+ llm_used: false,
+ llm_source: 'deterministic',
+ llm_reason:
+ 'tenant has no BYOK credentials and air-gapped mode is enabled',
+ summary:
+ 'Detection rule "Okta impossible travel" matched. Two ' +
+ 'logins from geographically distant locations.',
+ }),
+ );
+
+ render(<ExplainDrawer open={true} onClose={vi.fn()} alert={ALERT} />);
+
+ await waitFor(() => {
+ expect(screen.getByText('Done')).toBeInTheDocument();
+ });
+
+ // Summary still renders — deterministic prose is still useful.
+ expect(
+ screen.getByText(/Detection rule "Okta impossible travel" matched/),
+ ).toBeInTheDocument();
+ // Disclosure footer flags this clearly so the user knows nobody
+ // pinged an LLM for this one.
+ expect(screen.getByText(/deterministic/)).toBeInTheDocument();
+ expect(
+ screen.getByText(/no BYOK credentials and air-gapped/),
+ ).toBeInTheDocument();
+ });
+ });
});
diff --git a/apps/web/src/components/alerts/ExplainDrawer.tsx b/apps/web/src/components/alerts/ExplainDrawer.tsx
index 38a039038..5f6847324 100644
--- a/apps/web/src/components/alerts/ExplainDrawer.tsx
+++ b/apps/web/src/components/alerts/ExplainDrawer.tsx
@@ -4,9 +4,22 @@
* ExplainDrawer
* =============
*
- * Right-edge slide-over that streams an OCSF + MITRE-grounded explanation
- * of a single alert. Backed by `services/agents` ` POST /api/v1/explain`
- * (NDJSON stream).
+ * Right-edge slide-over that explains a single alert in OCSF + MITRE
+ * terms. The drawer has *two* backends and prefers the richer one:
+ *
+ * 1. Structured (preferred) — `POST /api/v1/alerts/{id}/explain` on the
+ * API service. Returns a single JSON envelope with rule lineage,
+ * historical false-positive rate, MITRE technique cards, contributing
+ * events, suggested actions, and a deterministic-or-LLM summary.
+ * Used for the "what *is* this alert" answer + sidebar context.
+ * 2. NDJSON stream (fallback) — `POST /api/v1/explain` on the agents
+ * service. Token-by-token typewriter. Used when (a) the structured
+ * endpoint 404s (older backend), (b) a non-429 error happens, or
+ * (c) the structured payload is missing a summary.
+ *
+ * 429 from the structured endpoint surfaces directly — both backends share
+ * tenant rate-limit budget for LLM calls, so silently retrying with the
+ * stream just doubles the spend and makes the rate-limit useless.
*
* Why a drawer instead of inline?
* -------------------------------
@@ -14,8 +27,8 @@
* intact while the analyst is still in the middle of reading the row, and
* gives us room for ATT&CK technique cards (which want their own width).
*
- * Streaming model
- * ---------------
+ * Streaming model (fallback path)
+ * --------------------------------
* Each line of the response body is one {@link ExplainStreamFrame}. The
* drawer routes by `kind`:
*
@@ -39,12 +52,20 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import {
agentsApi,
+ alertsApi,
+ ApiError,
type Alert,
+ type AlertExplanation,
+ type ContributingEvent,
type ExplainEvidenceFrame,
type ExplainMitreFrame,
type ExplainNextStepFrame,
type ExplainOcsfFrame,
type ExplainStreamFrame,
+ type HistoricalFpRate,
+ type MitreTechniqueCard,
+ type RuleLineage,
+ type SuggestedAction,
} from '@/lib/api';
import { clsx } from 'clsx';
@@ -71,19 +92,48 @@ export interface ExplainDrawerProps {
// without breaking the render. (The backend sends them in canonical order
// today, but treating order as a hint not a contract makes this resilient
// when we layer caching or replay later.)
+//
+// Both backends populate the same shape; structured-only fields
+// (`ruleLineage`, `historicalFpRate`, `suggestedActions`, `llm*`) are
+// optional and simply don't render when absent.
interface DrawerState {
status: 'idle' | 'loading' | 'streaming' | 'done' | 'error';
+ /**
+ * Which backend produced the data we're showing. Surfaced to the
+ * analyst so "why is this faster/slower than usual?" has an answer,
+ * and so QA can spot when the structured endpoint silently fell back.
+ */
+ source: 'structured' | 'stream' | null;
error?: string;
summary: string;
ocsf?: ExplainOcsfFrame;
mitre: ExplainMitreFrame[];
evidence: ExplainEvidenceFrame[];
nextSteps: ExplainNextStepFrame[];
+ // ─── Structured-only ──────────────────────────────────────────────
+ ruleLineage?: RuleLineage;
+ historicalFpRate?: HistoricalFpRate;
+ suggestedActions?: SuggestedAction[];
+ /**
+ * True when the structured endpoint actually called an LLM for the
+ * summary; false when it returned the deterministic template (e.g.
+ * because we're air-gapped or the tenant has no BYOK credentials).
+ */
+ llmUsed?: boolean;
+ llmSource?: string;
+ llmReason?: string;
+ /**
+ * ISO-8601 timestamp from the structured endpoint. Helps debug stale
+ * cached payloads — though we don't cache today, the stamp is free
+ * insurance for when we do.
+ */
+ generatedAt?: string;
}
const INITIAL: DrawerState = {
status: 'idle',
+ source: null,
summary: '',
mitre: [],
evidence: [],
@@ -110,17 +160,23 @@ export function ExplainDrawer({
return rest as unknown as Record<string, unknown>;
}, [alert]);
- const startStream = useCallback(async () => {
- abortRef.current?.abort();
- const ctrl = new AbortController();
- abortRef.current = ctrl;
-
- setState({ ...INITIAL, status: 'loading' });
+ /**
+ * Stream explanation tokens from the agents service (NDJSON fallback
+ * path). Mutates state in-place via the reducer so the UI gets a
+ * typewriter effect. Resolves true on a clean `done`, false on error.
+ *
+ * The signal argument is a *shared* AbortController so cancelling the
+ * drawer also cancels the in-flight `fetch` immediately — without it,
+ * closing the drawer mid-LLM-call would still rack up tokens until
+ * the model finished.
+ */
+ const runStream = useCallback(
+ async (signal: AbortSignal): Promise<void> => {
+ setState((s) => ({ ...s, status: 'loading', source: 'stream' }));
- try {
const response = await agentsApi.explainStream(
{ alert: alertPayload, alertId: alert.id },
- ctrl.signal,
+ signal,
);
if (!response.ok || !response.body) {
@@ -161,31 +217,91 @@ export function ExplainDrawer({
if (frame.kind === 'error' || frame.kind === 'done') return;
}
}
+ },
+ [alert.id, alertPayload],
+ );
+
+ /**
+ * Top-level loader. Tries the structured endpoint first, falls back
+ * to the stream if it 404s or fails (but NOT on 429 — that's a real
+ * answer the user needs to see). Always writes `INITIAL` first so a
+ * second open doesn't show stale data from the previous alert.
+ */
+ const loadExplanation = useCallback(async () => {
+ abortRef.current?.abort();
+ const ctrl = new AbortController();
+ abortRef.current = ctrl;
+
+ setState({ ...INITIAL, status: 'loading' });
+
+ // ── Attempt 1: structured endpoint ─────────────────────────────
+ try {
+ const payload = await alertsApi.explain(alert.id, ctrl.signal);
+ // The drawer might have been closed while the request was in
+ // flight — `request()` wraps AbortError into ApiError so we
+ // can't rely on the exception. Check the signal explicitly.
+ if (ctrl.signal.aborted) return;
+ setState((s) => applyStructured(s, payload));
+ return;
+ } catch (err) {
+ if (ctrl.signal.aborted) return;
+
+ // 429 = rate limit. Surface directly. Falling back to the
+ // streaming endpoint would (a) ignore the analyst's tenant
+ // budget and (b) still get rate-limited on the agents service
+ // anyway because both share LLM cost ledger.
+ if (err instanceof ApiError && err.status === 429) {
+ setState((s) => ({
+ ...s,
+ status: 'error',
+ source: 'structured',
+ error:
+ 'Rate limit reached for AI explanations. Please try again in a moment.',
+ }));
+ return;
+ }
+
+ // 404 / 500 / network → fall through to the stream. We log so
+ // ops can see when the structured backend is down (and keep a
+ // breadcrumb in the user's network tab if they peek).
+ // eslint-disable-next-line no-console
+ console.warn(
+ '[ExplainDrawer] Structured endpoint unavailable, falling back to stream:',
+ err,
+ );
+ }
+
+ // ── Attempt 2: NDJSON stream ───────────────────────────────────
+ try {
+ await runStream(ctrl.signal);
} catch (err) {
+ if (ctrl.signal.aborted) return;
if ((err as { name?: string })?.name === 'AbortError') return;
setState((s) => ({
...s,
status: 'error',
+ source: 'stream',
error:
err instanceof Error
? err.message
: 'Failed to load explanation.',
}));
}
- }, [alert.id, alertPayload]);
+ }, [alert.id, runStream]);
- // Open / close lifecycle. Restarts the stream on every open so the
- // drawer is always fresh — alert state changes between opens.
+ // Open / close lifecycle. Re-fetches on every open so the drawer is
+ // always fresh — alert state (severity, disposition, etc.) changes
+ // between opens, and the FP rate could drift even within a session.
useEffect(() => {
if (!open) {
abortRef.current?.abort();
return;
}
- void startStream();
+ void loadExplanation();
return () => {
abortRef.current?.abort();
};
- }, [open, startStream]);
+ }, [open, loadExplanation]);
// ESC to close.
useEffect(() => {
@@ -219,8 +335,9 @@ export function ExplainDrawer({
<DrawerHeader
alert={alert}
status={state.status}
+ source={state.source}
onClose={onClose}
- onRetry={state.status === 'error' ? startStream : undefined}
+ onRetry={state.status === 'error' ? loadExplanation : undefined}
/>
<div className="flex-1 overflow-y-auto px-6 py-4 space-y-6">
@@ -230,6 +347,15 @@ export function ExplainDrawer({
<SummarySection text={state.summary} status={state.status} />
+ {/* ── Structured-only sections ── */}
+ {state.ruleLineage && (
+ <RuleLineageSection lineage={state.ruleLineage} />
+ )}
+
+ {state.historicalFpRate && (
+ <FpRateSection fpr={state.historicalFpRate} />
+ )}
+
{state.ocsf && <OcsfSection frame={state.ocsf} />}
{state.mitre.length > 0 && (
@@ -240,6 +366,13 @@ export function ExplainDrawer({
<EvidenceSection items={state.evidence} />
)}
+ {state.suggestedActions && state.suggestedActions.length > 0 && (
+ <SuggestedActionsSection
+ actions={state.suggestedActions}
+ onRunPlaybook={onRunPlaybook}
+ />
+ )}
+
{state.nextSteps.length > 0 && (
<NextStepsSection
steps={state.nextSteps}
@@ -247,7 +380,20 @@ export function ExplainDrawer({
/>
)}
- {state.status === 'done' && (
+ {/* LLM disclosure footer (structured only). Tells the user
+ whether prose was actually LLM-generated, with the source
+ and (if not) the reason. Required for the "audit my AI
+ decisions" workflow. */}
+ {state.source === 'structured' && state.llmUsed !== undefined && (
+ <LlmDisclosure
+ used={state.llmUsed}
+ source={state.llmSource}
+ reason={state.llmReason}
+ generatedAt={state.generatedAt}
+ />
+ )}
+
+ {state.status === 'done' && state.source !== 'structured' && (
<div className="text-xs text-gray-500 text-center pt-2">
Generated by AiSOC. Always verify before taking action.
</div>
@@ -258,7 +404,7 @@ export function ExplainDrawer({
);
}
-// ─── Frame reducer ───────────────────────────────────────────────────────────
+// ─── Reducers ────────────────────────────────────────────────────────────────
function applyFrame(state: DrawerState, frame: ExplainStreamFrame): DrawerState {
switch (frame.kind) {
@@ -287,16 +433,82 @@ function applyFrame(state: DrawerState, frame: ExplainStreamFrame): DrawerState
}
}
+/**
+ * Hydrate the drawer state from a single structured response. We
+ * translate MITRE technique cards into the same shape the streaming
+ * code path produces (`ExplainMitreFrame`) so MitreSection doesn't need
+ * to know which backend served it. Same trick for evidence — a normal
+ * ContributingEvent maps cleanly onto an ExplainEvidenceFrame.
+ */
+function applyStructured(
+ state: DrawerState,
+ payload: AlertExplanation,
+): DrawerState {
+ return {
+ ...state,
+ status: 'done',
+ source: 'structured',
+ error: undefined,
+ summary: payload.summary,
+ // OCSF isn't part of the structured payload yet (it lives on the
+ // alert record itself; the stream synthesizes it). Leave undefined
+ // and let MitreSection/EvidenceSection carry the load.
+ ocsf: undefined,
+ mitre: payload.mitre_techniques.map(toMitreFrame),
+ evidence: payload.contributing_events.map(toEvidenceFrame),
+ // Suggested actions render in their own section — keep nextSteps
+ // empty so we don't double-show.
+ nextSteps: [],
+ ruleLineage: payload.rule_lineage,
+ historicalFpRate: payload.historical_fp_rate,
+ suggestedActions: payload.suggested_actions,
+ llmUsed: payload.llm_used,
+ llmSource: payload.llm_source,
+ llmReason: payload.llm_reason,
+ generatedAt: payload.generated_at,
+ };
+}
+
+/** Adapt a structured MITRE card into the streaming frame shape. */
+function toMitreFrame(card: MitreTechniqueCard): ExplainMitreFrame {
+ return {
+ kind: 'mitre',
+ id: card.id,
+ name: card.name,
+ tactic_names: card.tactic_names,
+ description: card.description,
+ url: card.url,
+ // Structured backend only emits cards it actually resolved, so
+ // `found` is implicitly true. The streaming backend uses this flag
+ // to flag stub cards when the corpus is missing.
+ found: true,
+ };
+}
+
+/** Adapt a structured contributing event into the streaming frame shape. */
+function toEvidenceFrame(ev: ContributingEvent): ExplainEvidenceFrame {
+ return {
+ kind: 'evidence',
+ label: ev.label,
+ value: ev.value,
+ // The streaming frame requires `annotation`; default to empty
+ // string so EvidenceSection can keep its `if (annotation)` guards.
+ annotation: ev.annotation ?? '',
+ };
+}
+
// ─── Subcomponents ───────────────────────────────────────────────────────────
function DrawerHeader({
alert,
status,
+ source,
onClose,
onRetry,
}: {
alert: Alert;
status: DrawerState['status'];
+ source: DrawerState['source'];
onClose: () => void;
onRetry?: () => void;
}) {
@@ -308,6 +520,7 @@ function DrawerHeader({
Explain
</span>
<StatusBadge status={status} />
+ {source && <SourceBadge source={source} />}
</div>
<h2 className="text-lg font-semibold text-gray-100 truncate">
{alert.title}
@@ -383,6 +596,33 @@ function StatusBadge({ status }: { status: DrawerState['status'] }) {
);
}
+/**
+ * Tiny badge showing which backend served the explanation. Useful for
+ * QA ("did the structured endpoint actually fire?") and for analysts
+ * who notice the structured payload is richer than the streamed one.
+ * Hidden in idle state so the chrome stays clean before the first call.
+ */
+function SourceBadge({ source }: { source: 'structured' | 'stream' }) {
+ if (source === 'structured') {
+ return (
+ <span
+ className="text-[10px] font-mono px-2 py-0.5 rounded ring-1 ring-inset bg-purple-500/10 text-purple-300 ring-purple-500/20"
+ title="Structured one-shot endpoint (richer context, no token streaming)"
+ >
+ Structured
+ </span>
+ );
+ }
+ return (
+ <span
+ className="text-[10px] font-mono px-2 py-0.5 rounded ring-1 ring-inset bg-amber-500/10 text-amber-300 ring-amber-500/20"
+ title="NDJSON streaming fallback (structured endpoint unavailable)"
+ >
+ Stream
+ </span>
+ );
+}
+
function ErrorBanner({ message }: { message: string }) {
return (
<div className="rounded-md border border-red-500/30 bg-red-500/5 px-4 py-3 text-sm text-red-300">
@@ -555,6 +795,258 @@ function NextStepsSection({
);
}
+// ─── Structured-only sections ────────────────────────────────────────────────
+
+/**
+ * Show which detection rule fired, with provenance. Confidence here is
+ * about *the lineage match itself* (did we identify the right rule?),
+ * not the rule's own confidence score. We split the two so analysts
+ * can trust the rule-card description even when the match is fuzzy.
+ *
+ * `match_method=none` (no match at all) renders a soft empty state
+ * rather than a missing section, so the absence is explicit.
+ */
+function RuleLineageSection({ lineage }: { lineage: RuleLineage }) {
+ const confColor = {
+ high: 'text-emerald-400 ring-emerald-500/20 bg-emerald-500/10',
+ medium: 'text-amber-400 ring-amber-500/20 bg-amber-500/10',
+ low: 'text-orange-400 ring-orange-500/20 bg-orange-500/10',
+ }[lineage.confidence];
+
+ if (lineage.match_method === 'none' || !lineage.rule_id) {
+ return (
+ <section>
+ <SectionHeading>Detection rule</SectionHeading>
+ <div className="rounded-md border border-gray-800 bg-gray-900/40 p-3 text-xs text-gray-500">
+ No matching rule could be identified for this alert. The signal
+ may have come from an ad-hoc query or a deprecated rule.
+ </div>
+ </section>
+ );
+ }
+
+ return (
+ <section>
+ <SectionHeading>Detection rule</SectionHeading>
+ <div className="rounded-md border border-gray-800 bg-gray-900/60 p-3 space-y-2">
+ <div className="flex items-start justify-between gap-2">
+ <div className="min-w-0">
+ <h4 className="text-sm font-medium text-gray-100 truncate">
+ {lineage.rule_name || 'Unnamed rule'}
+ </h4>
+ <div className="text-[10px] font-mono text-gray-500 mt-0.5 truncate">
+ {lineage.rule_id}
+ </div>
+ </div>
+ <span
+ className={clsx(
+ 'shrink-0 text-[10px] font-mono px-2 py-0.5 rounded ring-1 ring-inset',
+ confColor,
+ )}
+ title={`Match method: ${lineage.match_method}`}
+ >
+ {lineage.confidence} confidence
+ </span>
+ </div>
+ {lineage.rule_description && (
+ <p className="text-xs text-gray-300 leading-relaxed">
+ {lineage.rule_description}
+ </p>
+ )}
+ <div className="flex flex-wrap gap-3 text-[11px] pt-1 border-t border-gray-800/80">
+ {lineage.rule_severity && (
+ <Tag label="Severity" value={lineage.rule_severity} />
+ )}
+ {lineage.rule_status && (
+ <Tag label="Status" value={lineage.rule_status} />
+ )}
+ {lineage.rule_language && (
+ <Tag label="Language" value={lineage.rule_language} />
+ )}
+ {lineage.rule_confidence !== null && (
+ <Tag
+ label="Rule confidence"
+ value={`${lineage.rule_confidence}%`}
+ />
+ )}
+ <Tag
+ label="Source"
+ value={lineage.is_builtin ? 'built-in' : 'custom'}
+ />
+ <Tag label="Matched via" value={lineage.match_method} />
+ </div>
+ </div>
+ </section>
+ );
+}
+
+/**
+ * Render the live false-positive rate for the matched rule. The scope
+ * field tells the user *what slice* the rate covers — sometimes the
+ * rule itself doesn't have enough samples and we fall back to the
+ * category or technique. Showing this honestly prevents a 0/3 sample
+ * "0% FP rate!" misread.
+ */
+function FpRateSection({ fpr }: { fpr: HistoricalFpRate }) {
+ const pct = (fpr.fp_rate * 100).toFixed(1);
+ // Color the rate so high-FP rules pop. Thresholds chosen to match the
+ // alert-reduction benchmark page (≥30% = red, ≥10% = amber).
+ const rateColor =
+ fpr.fp_rate >= 0.3
+ ? 'text-red-400'
+ : fpr.fp_rate >= 0.1
+ ? 'text-amber-400'
+ : 'text-emerald-400';
+ // Sample size gating: <5 samples is statistically meaningless, warn.
+ const lowSample = fpr.sample_size < 5;
+ return (
+ <section>
+ <SectionHeading>Historical false-positive rate</SectionHeading>
+ <div className="rounded-md border border-gray-800 bg-gray-900/60 p-3 space-y-1.5">
+ <div className="flex items-baseline gap-3">
+ <span className={clsx('text-2xl font-semibold tabular-nums', rateColor)}>
+ {pct}%
+ </span>
+ <span className="text-xs text-gray-400">
+ {fpr.false_positives} of {fpr.sample_size} resolved as FP
+ </span>
+ {lowSample && (
+ <span className="text-[10px] text-amber-300 ml-auto">
+ low-sample
+ </span>
+ )}
+ </div>
+ <div className="text-[11px] text-gray-500">{fpr.notes}</div>
+ <div className="text-[10px] font-mono text-gray-600">
+ scope={fpr.scope} · last {fpr.lookback_days}d
+ </div>
+ </div>
+ </section>
+ );
+}
+
+/**
+ * Render deterministic suggested next steps from the structured
+ * endpoint. Mirrors NextStepsSection but uses the priority field to
+ * sort/color, since structured actions are hand-curated.
+ */
+function SuggestedActionsSection({
+ actions,
+ onRunPlaybook,
+}: {
+ actions: SuggestedAction[];
+ onRunPlaybook?: (playbookId: string) => void;
+}) {
+ const priorityOrder = { immediate: 0, soon: 1, fyi: 2 } as const;
+ const sorted = [...actions].sort(
+ (a, b) => priorityOrder[a.priority] - priorityOrder[b.priority],
+ );
+ const priorityChip: Record<SuggestedAction['priority'], string> = {
+ immediate: 'bg-red-500/15 text-red-300 ring-red-500/30',
+ soon: 'bg-amber-500/15 text-amber-300 ring-amber-500/30',
+ fyi: 'bg-gray-500/15 text-gray-400 ring-gray-500/30',
+ };
+ return (
+ <section>
+ <SectionHeading>Suggested actions</SectionHeading>
+ <div className="space-y-2">
+ {sorted.map((a, i) => (
+ <div
+ key={`${a.title}-${i}`}
+ className="rounded-md border border-gray-800 bg-gray-900/60 p-3"
+ >
+ <div className="flex items-start justify-between gap-2 mb-1">
+ <div className="flex items-center gap-2 min-w-0">
+ <span
+ className={clsx(
+ 'shrink-0 text-[10px] font-mono px-2 py-0.5 rounded ring-1 ring-inset uppercase',
+ priorityChip[a.priority],
+ )}
+ >
+ {a.priority}
+ </span>
+ <h4 className="text-sm font-medium text-gray-100 truncate">
+ {a.title}
+ </h4>
+ </div>
+ {a.playbook_id && onRunPlaybook && (
+ <button
+ type="button"
+ onClick={() => onRunPlaybook(a.playbook_id!)}
+ className="shrink-0 text-xs px-2.5 py-1 rounded bg-blue-500/15 text-blue-300 hover:bg-blue-500/25 ring-1 ring-inset ring-blue-500/30 transition"
+ >
+ Run playbook
+ </button>
+ )}
+ </div>
+ <p className="text-xs text-gray-300 leading-relaxed">
+ {a.rationale}
+ </p>
+ {a.playbook_id && (
+ <div className="text-[10px] font-mono text-gray-500 mt-1">
+ {a.playbook_id}
+ </div>
+ )}
+ </div>
+ ))}
+ </div>
+ </section>
+ );
+}
+
+/**
+ * Disclosure footer for the structured endpoint. Required for
+ * compliance: any LLM-generated text must be flagged as such, and
+ * non-LLM (deterministic fallback) text must be flagged so reviewers
+ * know it's templated. The reason field surfaces *why* the LLM was
+ * skipped (air-gap policy, no BYOK, budget exhausted, etc.).
+ */
+function LlmDisclosure({
+ used,
+ source,
+ reason,
+ generatedAt,
+}: {
+ used: boolean;
+ source?: string;
+ reason?: string;
+ generatedAt?: string;
+}) {
+ const ts = generatedAt
+ ? new Date(generatedAt).toLocaleString(undefined, {
+ dateStyle: 'medium',
+ timeStyle: 'short',
+ })
+ : null;
+ return (
+ <div className="text-[11px] text-gray-500 border-t border-gray-800/80 pt-3 space-y-0.5">
+ <div className="flex items-center gap-2">
+ <span
+ className={clsx(
+ 'inline-block w-1.5 h-1.5 rounded-full',
+ used ? 'bg-emerald-400' : 'bg-amber-400',
+ )}
+ />
+ {used ? (
+ <span>
+ Summary generated by LLM
+ {source ? ` (source: ${source})` : ''}.
+ </span>
+ ) : (
+ <span>
+ Summary is a deterministic template
+ {reason ? ` — ${reason}` : ''}.
+ </span>
+ )}
+ </div>
+ {ts && <div className="font-mono text-gray-600">Generated {ts}</div>}
+ <div className="pt-1">
+ Generated by AiSOC. Always verify before taking action.
+ </div>
+ </div>
+ );
+}
+
// ─── Tiny presentational atoms ───────────────────────────────────────────────
function Tag({ label, value }: { label: string; value: string }) {
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index f2ec68ae6..ae853b737 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -412,6 +412,29 @@ export const alertsApi = {
description: string;
}>;
}>(`/api/v1/alerts/${id}/timeline`),
+
+ /**
+ * 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,
+ }),
};
// ─── Risk-Based Alerting (entity rollup) ─────────────────────────────────────
@@ -2023,6 +2046,101 @@ export type ExplainStreamFrame =
| 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 {
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index e1bb22919..57a0b64c1 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -489,6 +489,48 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
+ /api/v1/alerts/{alert_id}/explain:
+ post:
+ tags:
+ - alerts
+ summary: Generate a structured AI explanation for an alert
+ description: 'Return a structured explanation for one alert.
+
+
+ This is the *single-shot* counterpart to the agent service''s
+
+ NDJSON stream. Use this when the client is a non-interactive
+
+ consumer (PDF builder, SOAR playbook, mobile app) or when the
+
+ UI just wants the final payload without rendering tokens.'
+ operationId: explain_alert_api_v1_alerts__alert_id__explain_post
+ security:
+ - HTTPBearer: []
+ parameters:
+ - name: alert_id
+ in: path
+ required: true
+ schema:
+ type: string
+ format: uuid
+ title: Alert Id
+ responses:
+ '200':
+ description: Structured explanation payload (rule lineage, MITRE, FPR, actions,
+ summary)
+ content:
+ application/json:
+ schema:
+ type: object
+ additionalProperties: true
+ title: Response Explain Alert Api V1 Alerts Alert Id Explain Post
+ '422':
+ description: Validation Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/HTTPValidationError'
/api/v1/cases:
get:
tags:
diff --git a/services/api/app/api/v1/endpoints/alert_explain.py b/services/api/app/api/v1/endpoints/alert_explain.py
new file mode 100644
index 000000000..649de5f05
--- /dev/null
+++ b/services/api/app/api/v1/endpoints/alert_explain.py
@@ -0,0 +1,225 @@
+"""POST ``/alerts/{alert_id}/explain`` — structured AI explainer.
+
+This endpoint is the API-side counterpart to the existing NDJSON
+streaming explainer in ``services/agents``. The agent service still
+exists for the *streaming* console UX (token-by-token); this endpoint
+exists so console clients, the case-summary PDF builder, and headless
+SOAR playbooks can ask one question — *"what is this alert?"* — and
+get back a structured JSON envelope with:
+
+* ``rule_lineage`` — which detection rule fired (best-effort)
+* ``contributing_events`` — the raw event signals that drove it
+* ``mitre_techniques`` — resolved ATT&CK cards
+* ``historical_fp_rate`` — per-rule (or per-category) FPR over the
+ last 30 days
+* ``suggested_actions`` — deterministic, hand-curated next steps
+* ``summary`` — LLM-written or deterministic-fallback prose
+
+The work itself lives in :mod:`app.services.alert_explain`; this
+module is purely an HTTP shell. It is responsible for:
+
+1. Permission gating (``alerts:read``).
+2. Per-tenant rate limiting via :class:`ExplainRateLimiter`. Explain
+ calls hit an LLM and run two analytic queries; without a cap a
+ misbehaving frontend or a runaway agent loop can drain budget in
+ minutes.
+3. Loading the alert under the tenant-scoped session (RLS) so the
+ downstream query helpers can safely run untenanted queries.
+4. Emitting an audit event — explains are user-visible LLM calls and
+ compliance auditors want a paper trail.
+
+The endpoint is mounted under the existing alerts prefix, so the
+final path is ``POST /api/v1/alerts/{alert_id}/explain``.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import asdict
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from sqlalchemy import select
+
+from app.api.v1.deps import AuthUser, require_permission
+from app.db.rls import TenantDBSession
+from app.models.alert import Alert
+from app.services.alert_explain import (
+ AlertExplanation,
+ generate_alert_explanation,
+)
+from app.services.audit import emit_audit
+from app.services.explain_rate_limit import (
+ ExplainRateLimitDecision,
+ get_explain_rate_limiter,
+)
+
+logger = logging.getLogger(__name__)
+
+# Mount on the alerts prefix so the route reads
+# ``POST /api/v1/alerts/{alert_id}/explain``. We could have hung this
+# off the existing ``alerts.py`` module but that file is already 600+
+# lines and the explain workflow has three collaborating helpers
+# (resolver, service, rate limiter); a dedicated module keeps the
+# blast radius small if we need to revisit it later.
+router = APIRouter(prefix="/alerts", tags=["alerts"])
+
+
+async def _acquire_or_429(
+ *,
+ response: Response,
+ tenant_id: uuid.UUID,
+ cost: float = 1.0,
+) -> ExplainRateLimitDecision:
+ """Charge the explain bucket; raise HTTP 429 on overflow.
+
+ Mirrors the lake endpoint's ``_acquire_or_429`` so operators get
+ consistent ``X-RateLimit-*`` semantics across both expensive APIs.
+ The headers are stamped on both the allowed and the denied path
+ so a polite client always knows where it stands without having to
+ parse error envelopes.
+ """
+ limiter = get_explain_rate_limiter()
+ decision = await limiter.acquire(tenant_id, cost=cost)
+
+ headers = decision.to_headers()
+ for name, value in headers.items():
+ response.headers[name] = value
+
+ if not decision.allowed:
+ # INFO so a noisy tenant surfaces in standard ops dashboards
+ # without flooding ERROR. The same headers are reused on the
+ # error envelope so retry-after semantics survive the 429.
+ logger.info(
+ "explain.rate_limited tenant_id=%s cost=%.2f remaining=%.2f retry_after=%.2fs",
+ tenant_id,
+ cost,
+ decision.remaining,
+ decision.retry_after_seconds,
+ )
+ raise HTTPException(
+ status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+ detail="explain endpoint rate limit exceeded",
+ headers=headers,
+ )
+ return decision
+
+
+def _explanation_to_payload(explanation: AlertExplanation) -> dict[str, Any]:
+ """Serialise the dataclass tree to a plain JSON-able dict.
+
+ ``dataclasses.asdict`` does the recursive walk for us, including
+ the nested ``MitreTechnique``/``ContributingEvent``/``SuggestedAction``
+ lists and the ``RuleLineage`` / ``HistoricalFpRate`` objects. We
+ use it instead of a Pydantic model for two reasons: (1) the
+ explain payload is read-only — we never validate it inbound — so
+ Pydantic adds no value, and (2) the dataclass shape lives next to
+ the business logic in ``alert_explain.py``, which keeps the
+ contract close to its only producer.
+ """
+ return asdict(explanation)
+
+
+ "/{alert_id}/explain",
+ summary="Generate a structured AI explanation for an alert",
+ response_description="Structured explanation payload (rule lineage, MITRE, FPR, actions, summary)",
+)
+async def explain_alert(
+ alert_id: uuid.UUID,
+ request: Request,
+ response: Response,
+ current_user: Annotated[AuthUser, Depends(require_permission("alerts:read"))],
+ db: TenantDBSession,
+) -> dict[str, Any]:
+ """Return a structured explanation for one alert.
+
+ This is the *single-shot* counterpart to the agent service's
+ NDJSON stream. Use this when the client is a non-interactive
+ consumer (PDF builder, SOAR playbook, mobile app) or when the
+ UI just wants the final payload without rendering tokens.
+ """
+ # Rate-limit *before* hitting the database. The limiter is
+ # asyncio-cheap (token-bucket math + a per-key lock) and shedding
+ # at the door costs less than fetching the alert and then
+ # discarding the work.
+ await _acquire_or_429(
+ response=response,
+ tenant_id=current_user.tenant_id,
+ )
+
+ # The session is already RLS-scoped to ``current_user.tenant_id``,
+ # but we add a redundant ``tenant_id`` filter on the alert lookup
+ # so the 404 we return is not "row hidden by RLS" — it really is
+ # "no such alert in your tenant". Defence in depth.
+ result = await db.execute(
+ select(Alert).where(
+ Alert.id == alert_id,
+ Alert.tenant_id == current_user.tenant_id,
+ )
+ )
+ alert = result.scalar_one_or_none()
+ if alert is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail="Alert not found",
+ )
+
+ try:
+ explanation = await generate_alert_explanation(db, alert=alert)
+ except Exception as exc: # noqa: BLE001
+ # The explain pipeline is defensive — it falls back to a
+ # deterministic summary on LLM failure, swallows cost-tracking
+ # errors, etc. — so reaching this branch means something
+ # unexpected (e.g. database read failure mid-explain) blew up.
+ # Log loudly and return a 502 so the client can retry; we do
+ # *not* expose the exception text to the caller.
+ logger.exception(
+ "explain.failed tenant=%s alert=%s",
+ current_user.tenant_id,
+ alert_id,
+ )
+ raise HTTPException(
+ status_code=status.HTTP_502_BAD_GATEWAY,
+ detail="failed to generate explanation",
+ ) from exc
+
+ # Audit *after* the explain succeeds so failures don't pollute
+ # the audit stream with phantom events. We log enough context for
+ # a compliance reviewer to recreate "who explained what, when, and
+ # whether the LLM actually answered" without storing the prose
+ # itself (which can leak event PII into the audit log).
+ try:
+ await emit_audit(
+ db=db,
+ tenant_id=current_user.tenant_id,
+ actor_id=current_user.user_id,
+ actor_email=current_user.email,
+ action="alerts.explain",
+ resource="alert",
+ resource_id=str(alert_id),
+ changes={
+ "llm_used": explanation.llm_used,
+ "llm_source": explanation.llm_source,
+ "llm_reason": explanation.llm_reason,
+ "rule_match_method": explanation.rule_lineage.match_method,
+ "rule_id": explanation.rule_lineage.rule_id,
+ "fp_rate_scope": explanation.historical_fp_rate.scope,
+ "fp_rate_sample_size": explanation.historical_fp_rate.sample_size,
+ "mitre_technique_count": len(explanation.mitre_techniques),
+ },
+ request=request,
+ )
+ except Exception as exc: # noqa: BLE001
+ # Audit-log failures must never break the explain response.
+ # We log a warning so ops can investigate, but we do not
+ # propagate — the user already got their answer.
+ logger.warning(
+ "explain.audit_failed tenant=%s alert=%s error=%s",
+ current_user.tenant_id,
+ alert_id,
+ exc,
+ )
+
+ return _explanation_to_payload(explanation)
diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.py
index 070685ef5..715421e5d 100644
--- a/services/api/app/api/v1/router.py
+++ b/services/api/app/api/v1/router.py
@@ -5,6 +5,7 @@ from fastapi import APIRouter
from app.api.v1.endpoints import (
agents,
airgap,
+ alert_explain,
alerts,
api_keys,
approvals,
@@ -68,6 +69,9 @@ api_router = APIRouter(prefix="/api/v1")
api_router.include_router(auth.router)
api_router.include_router(api_keys.router)
api_router.include_router(alerts.router)
+# Structured AI explainer (POST /alerts/{id}/explain) — single-shot
+# JSON envelope counterpart to the agent service's NDJSON stream.
+api_router.include_router(alert_explain.router)
api_router.include_router(cases.router)
api_router.include_router(connectors.router)
# Hosted OAuth one-click for connectors (Workstream 2 of AI Stack plan).
diff --git a/services/api/app/services/alert_explain.py b/services/api/app/services/alert_explain.py
new file mode 100644
index 000000000..c5f9203e6
--- /dev/null
+++ b/services/api/app/services/alert_explain.py
@@ -0,0 +1,969 @@
+"""Structured alert explanation generator (Stage 2 #6).
+
+This service powers ``POST /api/v1/alerts/{alert_id}/explain``. It
+produces a single structured JSON payload — *not* an NDJSON stream —
+because the API service's contract is request/response and the UI
+tolerates a one-shot reply for the explain drawer.
+
+The agents service exposes a streaming variant at
+``services/agents/app/api/explain.py`` that the legacy ``ExplainDrawer``
+already consumes. This service is intentionally lighter: it returns
+the structured fields the spec calls for (``rule_lineage``,
+``contributing_events``, ``mitre_techniques``, ``historical_fp_rate``,
+``suggested_actions``) plus a brief ``summary`` so the drawer can paint
+without a second round-trip.
+
+Design choices
+--------------
+
+* **Best-effort rule lineage.** ``Alert`` does not carry a foreign key
+ to ``DetectionRule`` (alerts can come from connectors that don't fire
+ rules at all — see ``services/fusion``). We probe the alert's
+ ``raw_event`` for an explicit ``rule_id`` / ``detection_rule_id``,
+ then sweep ``tags`` for ``rule:<uuid>``, then fall back to matching
+ rules by MITRE technique overlap and category. The matched rule
+ drives the ``historical_fp_rate`` query and the rule lineage card.
+* **Historical FP rate is computed live, not cached.** The query is
+ bounded (last 90 days, capped at 5k rows) and indexed. Computing on
+ read keeps the explanation honest — a tenant tuning a noisy rule
+ will see the FP rate drop in real time.
+* **LLM call is best-effort with a deterministic fallback.** The
+ resolver in :mod:`app.services.llm_resolver` returns
+ ``allowed=False`` whenever the tenant has no key, the env baseline
+ is empty, or air-gap policy bites. In all of those cases we still
+ return a useful explanation built from the corpus, so the explain
+ button never fails closed.
+* **Cost tracking is mandatory when the LLM fires.** Every successful
+ outbound call books a row into ``aisoc_run_costs`` keyed by
+ ``run_id=alert:<alert_uuid>`` so the cost dashboard can attribute
+ spend back to the specific alert. This gives operators a clean
+ audit trail when the explain button gets abused.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+from sqlalchemy import and_, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.airgap import AirgapViolation, enforce_airgap_for_url
+from app.models.alert import Alert
+from app.models.detection_rule import DetectionRule
+from app.services.cost_dashboard import _impute_public_cost
+from app.services.llm_resolver import LlmConfig, resolve_llm_config
+
+logger = logging.getLogger(__name__)
+
+
+# Lookback window for the historical FP rate query. 90 days is long
+# enough to see a tenant's tuning trends but short enough to dodge
+# stale rules that haven't been triggered in a year. Capped at 5k
+# alerts so a chatty rule can't blow up the explain endpoint.
+_FP_RATE_LOOKBACK_DAYS = 90
+_FP_RATE_SAMPLE_CAP = 5_000
+
+# Max number of contributing events we surface from the alert. The
+# drawer only needs a few; the rest are available via the alert detail
+# view and the lake API.
+_MAX_CONTRIBUTING_EVENTS = 5
+
+# Cap MITRE technique cards so the drawer stays scannable.
+_MAX_MITRE_TECHNIQUES = 5
+
+# Match any T#### or T####.### technique id in free text. Mirrors the
+# pattern used by the agents-side explainer.
+_MITRE_ID_RE = re.compile(r"\bT\d{4}(?:\.\d{1,3})?\b")
+
+
+@dataclass(frozen=True)
+class RuleLineage:
+ """Provenance chain for the rule that (likely) fired this alert."""
+
+ rule_id: str | None
+ rule_name: str | None
+ rule_description: str | None
+ rule_status: str | None
+ rule_severity: str | None
+ rule_confidence: int | None
+ rule_language: str | None
+ is_builtin: bool
+ confidence: str # "high" | "medium" | "low" — how sure we are about the match
+ match_method: str # "raw_event" | "tags" | "mitre_overlap" | "none"
+
+
+@dataclass(frozen=True)
+class HistoricalFpRate:
+ """Live-computed false-positive rate for the matched rule + scope."""
+
+ fp_rate: float # 0.0 .. 1.0
+ sample_size: int # # of resolved alerts considered
+ false_positives: int # # within sample with disposition='false_positive'
+ lookback_days: int
+ scope: str # "rule" | "category" | "technique" — which fallback we used
+ notes: str # human-readable explanation
+
+
+@dataclass(frozen=True)
+class SuggestedAction:
+ """One concrete next step grounded in the alert."""
+
+ title: str
+ rationale: str
+ playbook_id: str | None # link into the playbook engine when available
+ priority: str # "immediate" | "soon" | "fyi"
+
+
+@dataclass(frozen=True)
+class ContributingEvent:
+ """Compact representation of one observable from the raw event."""
+
+ label: str
+ value: str
+ annotation: str = ""
+
+
+@dataclass(frozen=True)
+class MitreTechnique:
+ """One MITRE ATT&CK technique resolved from the local corpus."""
+
+ id: str
+ name: str
+ tactic_names: list[str]
+ description: str
+ url: str
+
+
+@dataclass(frozen=True)
+class AlertExplanation:
+ """Top-level explain payload returned by the endpoint."""
+
+ alert_id: str
+ summary: str
+ rule_lineage: RuleLineage
+ contributing_events: list[ContributingEvent]
+ mitre_techniques: list[MitreTechnique]
+ historical_fp_rate: HistoricalFpRate
+ suggested_actions: list[SuggestedAction]
+ llm_used: bool
+ llm_source: str
+ llm_reason: str # populated when ``llm_used`` is False
+ generated_at: str # ISO-8601
+
+
+# ---------------------------------------------------------------------------
+# Rule lineage matching
+# ---------------------------------------------------------------------------
+
+
+_RULE_TAG_RE = re.compile(r"^rule:([0-9a-fA-F-]{36})$")
+
+
+def _coerce_rule_id(value: Any) -> uuid.UUID | None:
+ """Best-effort coerce an arbitrary value to a rule UUID."""
+ if value is None:
+ return None
+ try:
+ return uuid.UUID(str(value))
+ except (TypeError, ValueError):
+ return None
+
+
+def _explicit_rule_id_from_alert(alert: Alert) -> uuid.UUID | None:
+ """Probe the alert for an explicit rule reference.
+
+ Connectors that *do* track rule provenance will normally drop the
+ id into ``raw_event`` (most common) or stamp a ``rule:<uuid>`` tag
+ on the alert. We accept both.
+ """
+ raw = alert.raw_event or {}
+ if isinstance(raw, dict):
+ for key in ("rule_id", "detection_rule_id", "ruleId", "detectionRuleId"):
+ rid = _coerce_rule_id(raw.get(key))
+ if rid is not None:
+ return rid
+ # Some connectors nest the rule under an "alert" or "detection" object.
+ for nest_key in ("alert", "detection", "rule"):
+ nested = raw.get(nest_key)
+ if isinstance(nested, dict):
+ for key in ("id", "rule_id", "detection_rule_id"):
+ rid = _coerce_rule_id(nested.get(key))
+ if rid is not None:
+ return rid
+
+ tags = alert.tags or []
+ if isinstance(tags, list):
+ for tag in tags:
+ if not isinstance(tag, str):
+ continue
+ match = _RULE_TAG_RE.match(tag.strip())
+ if match:
+ rid = _coerce_rule_id(match.group(1))
+ if rid is not None:
+ return rid
+
+ return None
+
+
+async def _resolve_rule_lineage(db: AsyncSession, alert: Alert) -> tuple[DetectionRule | None, str, str]:
+ """Find the detection rule (if any) that produced this alert.
+
+ Returns ``(rule, confidence, match_method)``:
+
+ * ``rule`` — the matched ``DetectionRule`` row, or ``None`` when
+ no plausible match exists.
+ * ``confidence`` — ``"high"`` for explicit references, ``"medium"``
+ when we matched on category + technique overlap, ``"low"`` for
+ single-axis matches, ``"none"`` when nothing matched.
+ * ``match_method`` — one of the strings above (``raw_event``,
+ ``tags``, ``mitre_overlap``, ``category``, ``none``) so the UI
+ can flag low-confidence guesses.
+ """
+ # 1. Explicit reference in raw_event or tags.
+ explicit_id = _explicit_rule_id_from_alert(alert)
+ if explicit_id is not None:
+ result = await db.execute(select(DetectionRule).where(DetectionRule.id == explicit_id))
+ rule = result.scalar_one_or_none()
+ if rule is not None:
+ # The raw_event probe wins over the tag probe; we don't
+ # bother distinguishing here because both signals come
+ # from the connector and both are equally trustworthy.
+ return rule, "high", "raw_event"
+
+ # 2. Best-effort match by MITRE technique overlap + category.
+ techniques = list(alert.mitre_techniques or [])
+ technique_ids = [str(t) for t in techniques if isinstance(t, str)]
+
+ if not technique_ids and not alert.category:
+ # Nothing to match on; bail out early.
+ return None, "none", "none"
+
+ # Build a candidate set scoped to this tenant (RLS already filters
+ # by tenant_id, but we add the predicate explicitly so the index
+ # path is obvious to anyone reading the query log).
+ filters = [
+ # Match either the tenant-scoped rule or a platform-wide
+ # built-in rule (NULL tenant_id). A connector firing in a
+ # tenant context is very likely to match a builtin rule when
+ # the tenant hasn't authored their own.
+ ((DetectionRule.tenant_id == alert.tenant_id) | DetectionRule.tenant_id.is_(None)),
+ DetectionRule.status.in_(["enabled", "active", "production"]),
+ ]
+ if alert.category:
+ filters.append(DetectionRule.category == alert.category)
+
+ result = await db.execute(
+ select(DetectionRule)
+ .where(and_(*filters))
+ # Limit to a sane number — we only need to score a handful of
+ # candidates, not every rule in the catalogue.
+ .limit(50)
+ )
+ candidates = list(result.scalars().all())
+ if not candidates:
+ return None, "none", "none"
+
+ # Score each candidate by technique-set overlap. A perfect match
+ # (same techniques, same category) is high confidence; partial
+ # overlap is medium; category-only is low.
+ best: tuple[int, DetectionRule] | None = None
+ for rule in candidates:
+ rule_techniques = {str(t) for t in (rule.mitre_techniques or []) if isinstance(t, str)}
+ overlap = len(rule_techniques.intersection(technique_ids))
+ # Score: technique overlap dominates, with a tie-breaker on
+ # rule confidence and a small bonus for built-in rules (they
+ # tend to be higher quality than ad-hoc tenant rules).
+ score = overlap * 10 + min(rule.confidence or 0, 100) // 10
+ if rule.is_builtin:
+ score += 1
+ if best is None or score > best[0]:
+ best = (score, rule)
+
+ if best is None or best[0] == 0:
+ # No technique overlap. If we narrowed by category and got
+ # candidates, fall through to a low-confidence category match
+ # using the highest-confidence candidate.
+ if alert.category and candidates:
+ top = max(candidates, key=lambda r: r.confidence or 0)
+ return top, "low", "category"
+ return None, "none", "none"
+
+ score, rule = best
+ if score >= 20: # at least two technique matches
+ return rule, "high", "mitre_overlap"
+ if score >= 10: # one technique match
+ return rule, "medium", "mitre_overlap"
+ return rule, "low", "mitre_overlap"
+
+
+# ---------------------------------------------------------------------------
+# Historical FP rate
+# ---------------------------------------------------------------------------
+
+
+async def _historical_fp_rate(
+ db: AsyncSession,
+ *,
+ tenant_id: uuid.UUID,
+ rule: DetectionRule | None,
+ alert: Alert,
+) -> HistoricalFpRate:
+ """Compute the live FP rate for the most specific available scope.
+
+ Order of preference: same rule (when we have one) → same category
+ + technique overlap → same category. We always cap the sample to
+ keep the query bounded.
+ """
+ cutoff = datetime.now(UTC) - timedelta(days=_FP_RATE_LOOKBACK_DAYS)
+
+ base_filters = [
+ Alert.tenant_id == tenant_id,
+ Alert.disposition.is_not(None),
+ Alert.created_at >= cutoff,
+ ]
+
+ scope: str
+ notes: str
+ extra_filters: list[Any] = []
+
+ if rule is not None and rule.id is not None:
+ # Match alerts that either reference this rule explicitly or
+ # share its category + technique signature. We don't have a FK
+ # so we approximate; this is documented as an approximation
+ # in the response notes so analysts know what they're seeing.
+ extra_filters = [Alert.category == rule.category] if rule.category else []
+ rule_techniques = list(rule.mitre_techniques or [])
+ if rule_techniques:
+ # Postgres JSONB ?| asks "does any of these top-level keys
+ # appear in the array?". We use the SQLAlchemy ``op`` form
+ # so we don't depend on the dialect-specific extension.
+ extra_filters.append(Alert.mitre_techniques.op("?|")(rule_techniques))
+ scope = "rule"
+ notes = (
+ f"Approximated by category={rule.category!r} and MITRE techniques matching {rule.name!r}; alerts don't carry a direct rule FK."
+ )
+ elif alert.category and (alert.mitre_techniques or []):
+ extra_filters = [
+ Alert.category == alert.category,
+ Alert.mitre_techniques.op("?|")(list(alert.mitre_techniques or [])),
+ ]
+ scope = "category"
+ notes = f"Computed across category={alert.category!r} alerts sharing at least one MITRE technique with this alert."
+ elif alert.category:
+ extra_filters = [Alert.category == alert.category]
+ scope = "category"
+ notes = f"Computed across all category={alert.category!r} alerts (no MITRE refinement)."
+ else:
+ # Tenant-wide fallback. Useful but very noisy; we mark it as
+ # such in ``notes`` so the UI can warn the analyst.
+ scope = "category"
+ notes = "Tenant-wide fallback — alert has no category or MITRE data."
+
+ query = (
+ select(
+ func.count().label("total"),
+ func.count().filter(Alert.disposition == "false_positive").label("fps"),
+ )
+ .where(and_(*base_filters, *extra_filters))
+ .limit(_FP_RATE_SAMPLE_CAP)
+ )
+
+ try:
+ row = (await db.execute(query)).one()
+ except Exception as exc: # noqa: BLE001
+ # FP rate is informational; never fail the whole explain
+ # endpoint because the analytics query timed out.
+ logger.warning("explain.fp_rate_query_failed tenant=%s error=%s", tenant_id, exc)
+ return HistoricalFpRate(
+ fp_rate=0.0,
+ sample_size=0,
+ false_positives=0,
+ lookback_days=_FP_RATE_LOOKBACK_DAYS,
+ scope=scope,
+ notes=f"Query failed: {exc}; treat with caution.",
+ )
+
+ total = int(row.total or 0)
+ fps = int(row.fps or 0)
+ rate = (fps / total) if total else 0.0
+ return HistoricalFpRate(
+ fp_rate=round(rate, 4),
+ sample_size=total,
+ false_positives=fps,
+ lookback_days=_FP_RATE_LOOKBACK_DAYS,
+ scope=scope,
+ notes=notes,
+ )
+
+
+# ---------------------------------------------------------------------------
+# MITRE technique resolution
+# ---------------------------------------------------------------------------
+
+
+def _extract_mitre_ids(alert: Alert) -> list[str]:
+ """Pull MITRE technique IDs from the alert.
+
+ Accepts the structured ``mitre_techniques`` column first (the
+ canonical source) and falls back to a regex sweep over tags +
+ title + description so older alerts without the structured field
+ still get something useful.
+ """
+ found: list[str] = []
+ seen: set[str] = set()
+
+ for item in alert.mitre_techniques or []:
+ if not isinstance(item, str):
+ continue
+ if item not in seen:
+ found.append(item)
+ seen.add(item)
+
+ text_pool = " ".join(str(v) for v in (alert.tags or []) + [alert.title or "", alert.description or ""])
+ for tid in _MITRE_ID_RE.findall(text_pool):
+ if tid not in seen:
+ found.append(tid)
+ seen.add(tid)
+
+ return found[:_MAX_MITRE_TECHNIQUES]
+
+
+def _resolve_technique_card(technique_id: str) -> MitreTechnique:
+ """Look up the technique in the local MITRE corpus when available.
+
+ The MITRE corpus lives in the agents service; we do not import it
+ from the API service to avoid a hard dependency. If a sibling
+ module has already loaded the corpus into ``app.tools.mitre_full``
+ we use it; otherwise we emit a stub card with just the ATT&CK URL.
+ The drawer renders both shapes.
+ """
+ try:
+ # Lazy import: the API service does not ship mitre_full by
+ # default. When run inside the monorepo with the agents
+ # package on the path it's available; in production API-only
+ # deployments it isn't, and that's fine.
+ from app.tools.mitre_full import get_technique # type: ignore[import-not-found]
+ except Exception:
+ return MitreTechnique(
+ id=technique_id,
+ name=technique_id,
+ tactic_names=[],
+ description="",
+ url=f"https://attack.mitre.org/techniques/{technique_id.replace('.', '/')}/",
+ )
+
+ raw = get_technique(technique_id)
+ desc = (raw.get("description") or "").strip()
+ return MitreTechnique(
+ id=raw.get("id", technique_id),
+ name=raw.get("name", technique_id),
+ tactic_names=list(raw.get("tactic_names") or []),
+ description=desc[:280] + ("…" if len(desc) > 280 else ""),
+ url=raw.get("url") or f"https://attack.mitre.org/techniques/{technique_id.replace('.', '/')}/",
+ )
+
+
+# ---------------------------------------------------------------------------
+# Contributing events + suggested actions
+# ---------------------------------------------------------------------------
+
+
+def _extract_contributing_events(alert: Alert) -> list[ContributingEvent]:
+ """Surface the most useful observables from the alert.
+
+ Order: severity / risk score / source first (always available),
+ then named observables from ``raw_event`` (user, IPs, host,
+ process, hashes, URLs), then any structured IOCs the connector
+ attached. Capped at ``_MAX_CONTRIBUTING_EVENTS``.
+ """
+ events: list[ContributingEvent] = []
+ seen_labels: set[str] = set()
+
+ def add(label: str, value: Any, annotation: str = "") -> None:
+ if value in (None, "", [], {}) or label in seen_labels:
+ return
+ events.append(
+ ContributingEvent(
+ label=label,
+ value=str(value)[:160],
+ annotation=annotation,
+ )
+ )
+ seen_labels.add(label)
+
+ add("Severity", alert.severity)
+ add("Source", alert.connector_type or "platform")
+ if alert.ai_score is not None:
+ add("AI score", round(float(alert.ai_score), 2))
+
+ raw = alert.raw_event or {}
+ if isinstance(raw, dict):
+ for label, key in (
+ ("User", "user"),
+ ("User", "user_name"),
+ ("Source IP", "src_ip"),
+ ("Source IP", "source_ip"),
+ ("Destination IP", "dest_ip"),
+ ("Destination IP", "destination_ip"),
+ ("Host", "hostname"),
+ ("Host", "host"),
+ ("Process", "process_name"),
+ ("Process", "process"),
+ ("File hash", "file_hash"),
+ ("Domain", "domain"),
+ ("URL", "url"),
+ ):
+ add(label, raw.get(key))
+
+ return events[:_MAX_CONTRIBUTING_EVENTS]
+
+
+def _build_suggested_actions(alert: Alert, mitre_ids: list[str]) -> list[SuggestedAction]:
+ """Curated, never LLM-generated list of next steps.
+
+ Generated suggestions are deliberately curated (not LLM-derived)
+ so the explain button can never recommend a non-existent playbook
+ or hallucinate a destructive action. The LLM only ever produces
+ the prose summary.
+ """
+ tags = {str(t).lower() for t in (alert.tags or [])}
+ severity = (alert.severity or "").lower()
+ actions: list[SuggestedAction] = []
+
+ if "account-takeover" in tags or "ato" in tags or "T1078" in mitre_ids:
+ actions.append(
+ SuggestedAction(
+ title="Run ATO containment playbook",
+ rationale="Block sessions, force password reset, and require step-up MFA on the affected identity.",
+ playbook_id="ato-impossible-travel-block-v1",
+ priority="immediate",
+ )
+ )
+
+ if "ransomware" in tags or "T1486" in mitre_ids:
+ actions.append(
+ SuggestedAction(
+ title="Isolate the host",
+ rationale="Suspected ransomware activity — quarantine the endpoint to stop encryption spread.",
+ playbook_id="ransomware-host-isolate-v1",
+ priority="immediate",
+ )
+ )
+
+ if "phishing" in tags or "bec" in tags:
+ actions.append(
+ SuggestedAction(
+ title="Pull the message and similar deliveries",
+ rationale="Identify other recipients and remove the message from inboxes before clicks propagate.",
+ playbook_id="phishing-message-pull-v1",
+ priority="soon",
+ )
+ )
+
+ if any(t.startswith("T1190") or t.startswith("T1133") for t in mitre_ids):
+ actions.append(
+ SuggestedAction(
+ title="Tighten perimeter exposure",
+ rationale="Initial-access vector points at an external-facing service — review WAF rules and patch level.",
+ playbook_id=None,
+ priority="soon",
+ )
+ )
+
+ if not actions:
+ actions.append(
+ SuggestedAction(
+ title="Correlate with the last 24 h of alerts",
+ rationale="Look for the same user, host, or IOC in adjacent detections to spot a multi-stage attack.",
+ playbook_id=None,
+ priority="fyi",
+ )
+ )
+
+ if severity in ("high", "critical"):
+ actions.append(
+ SuggestedAction(
+ title="Open a case and notify on-call",
+ rationale=f"Severity is {severity}; promote to a tracked incident before further investigation.",
+ playbook_id=None,
+ priority="immediate" if severity == "critical" else "soon",
+ )
+ )
+
+ return actions[:4]
+
+
+# ---------------------------------------------------------------------------
+# Summary (deterministic + optional LLM)
+# ---------------------------------------------------------------------------
+
+
+def _deterministic_summary(
+ alert: Alert,
+ mitre_techniques: list[MitreTechnique],
+ rule_lineage: RuleLineage,
+ fp: HistoricalFpRate,
+) -> str:
+ """Always-available summary built from the alert + corpus data.
+
+ Used when the LLM is disabled (no key, air-gapped, etc.) or when
+ the LLM call fails. The prose is intentionally bland — it exists
+ to keep the drawer useful, not to delight.
+ """
+ title = alert.title or "Security alert"
+ severity = (alert.severity or "unknown").lower()
+ source = alert.connector_type or "an upstream connector"
+
+ parts = [f"{title} fired at {severity} severity from {source}."]
+
+ if rule_lineage.rule_name and rule_lineage.confidence != "none":
+ confidence_note = (
+ f"matched detection rule {rule_lineage.rule_name!r}"
+ if rule_lineage.confidence == "high"
+ else f"likely produced by {rule_lineage.rule_name!r} (match confidence: {rule_lineage.confidence})"
+ )
+ parts.append(f"This alert was {confidence_note}.")
+
+ if mitre_techniques:
+ ids = ", ".join(t.id for t in mitre_techniques[:3])
+ parts.append(f"MITRE ATT&CK coverage: {ids}.")
+
+ if fp.sample_size >= 10:
+ pct = round(fp.fp_rate * 100, 1)
+ parts.append(
+ f"Historically {pct}% of similar alerts ({fp.sample_size} sampled in the last "
+ f"{fp.lookback_days} days) were resolved as false positives."
+ )
+
+ desc = (alert.description or "").strip()
+ if desc:
+ snippet = desc if len(desc) <= 240 else desc[:237] + "…"
+ parts.append(snippet)
+
+ return " ".join(parts)
+
+
+@dataclass(frozen=True)
+class _LlmCallResult:
+ """Internal: raw outcome of one LLM round-trip."""
+
+ text: str | None
+ model: str
+ prompt_tokens: int
+ completion_tokens: int
+ latency_ms: float
+ error: str | None
+
+
+async def _call_llm_for_summary(
+ *,
+ alert: Alert,
+ rule_lineage: RuleLineage,
+ mitre_techniques: list[MitreTechnique],
+ fp: HistoricalFpRate,
+ llm_config: LlmConfig,
+) -> _LlmCallResult:
+ """One round-trip to the configured LLM, with hard timeouts.
+
+ Returns a populated :class:`_LlmCallResult` regardless of outcome
+ so the caller can both surface a summary and book accurate cost
+ metadata into ``aisoc_run_costs``.
+ """
+ started = time.monotonic()
+ base = llm_config.base_url.rstrip("/")
+ url = f"{base}/v1/chat/completions"
+
+ prompt_alert = {
+ "title": alert.title,
+ "severity": alert.severity,
+ "category": alert.category,
+ "source": alert.connector_type,
+ "description": alert.description,
+ "tags": alert.tags or [],
+ }
+ prompt_rule = (
+ {
+ "name": rule_lineage.rule_name,
+ "description": rule_lineage.rule_description,
+ "match_confidence": rule_lineage.confidence,
+ "match_method": rule_lineage.match_method,
+ }
+ if rule_lineage.rule_name
+ else None
+ )
+ prompt_mitre = [{"id": t.id, "name": t.name, "tactic_names": t.tactic_names} for t in mitre_techniques]
+ prompt_fp = {
+ "fp_rate": fp.fp_rate,
+ "sample_size": fp.sample_size,
+ "lookback_days": fp.lookback_days,
+ "scope": fp.scope,
+ }
+
+ messages = [
+ {
+ "role": "system",
+ "content": (
+ "You are AiSOC's alert explainer. Given one security alert, the "
+ "detection rule that fired (when known), a list of MITRE ATT&CK "
+ "techniques pulled from the local corpus, and the historical "
+ "false-positive rate for similar alerts, write a tight 3-5 "
+ "sentence brief for an L1/L2 SOC analyst. Be concrete about "
+ "WHAT happened, WHY it matters, and what the FP context implies "
+ "for triage urgency. Never invent technique IDs, vendor names, "
+ "or IOCs that aren't in the input. No bullet lists, no headings — "
+ "just prose. Do not promise to take actions; the analyst decides."
+ ),
+ },
+ {
+ "role": "user",
+ "content": json.dumps(
+ {
+ "alert": prompt_alert,
+ "rule": prompt_rule,
+ "mitre_techniques": prompt_mitre,
+ "historical_fp": prompt_fp,
+ },
+ indent=2,
+ ),
+ },
+ ]
+
+ # Air-gap belt-and-braces: the resolver already vetoed
+ # api.openai.com when ``AISOC_AIRGAPPED`` is on, but we re-check at
+ # the actual call site so a future code path that bypasses the
+ # resolver still gets stopped.
+ try:
+ enforce_airgap_for_url(url)
+ except AirgapViolation as exc:
+ return _LlmCallResult(
+ text=None,
+ model=llm_config.model,
+ prompt_tokens=0,
+ completion_tokens=0,
+ latency_ms=(time.monotonic() - started) * 1000.0,
+ error=f"airgap_violation: {exc}",
+ )
+
+ try:
+ async with httpx.AsyncClient(timeout=20) as client:
+ resp = await client.post(
+ url,
+ headers={"Authorization": f"Bearer {llm_config.api_key}"},
+ json={"model": llm_config.model, "messages": messages, "max_tokens": 360},
+ )
+ resp.raise_for_status()
+ payload = resp.json()
+ except Exception as exc: # noqa: BLE001
+ return _LlmCallResult(
+ text=None,
+ model=llm_config.model,
+ prompt_tokens=0,
+ completion_tokens=0,
+ latency_ms=(time.monotonic() - started) * 1000.0,
+ error=str(exc),
+ )
+
+ text = ""
+ try:
+ text = (payload["choices"][0]["message"]["content"] or "").strip()
+ except (KeyError, IndexError, TypeError):
+ text = ""
+
+ usage = payload.get("usage") or {}
+ return _LlmCallResult(
+ text=text or None,
+ model=llm_config.model,
+ prompt_tokens=int(usage.get("prompt_tokens") or 0),
+ completion_tokens=int(usage.get("completion_tokens") or 0),
+ latency_ms=(time.monotonic() - started) * 1000.0,
+ error=None if text else "empty_response",
+ )
+
+
+# ---------------------------------------------------------------------------
+# Cost tracking
+# ---------------------------------------------------------------------------
+
+
+async def _record_llm_cost(
+ db: AsyncSession,
+ *,
+ tenant_id: uuid.UUID,
+ alert_id: uuid.UUID,
+ call: _LlmCallResult,
+) -> None:
+ """Book the LLM round-trip into ``aisoc_run_costs``.
+
+ Uses ``run_id=alert:<uuid>`` so the cost dashboard's per-run drill-
+ down can attribute the spend to the originating alert. The pricing
+ is imputed against the public list price via
+ :func:`_impute_public_cost` so BYOK customers see what they'd
+ have paid had they used the platform's account; the actual on-key
+ cost is whatever their LLM provider charges them and is opaque
+ to us.
+ """
+ if call.text is None and call.error:
+ # Don't book failed calls — they didn't consume billable
+ # tokens (or the provider returned an error before the
+ # response). We log them via the caller's structured log so
+ # operators still see them in the audit trail.
+ return
+
+ cost_usd = _impute_public_cost(
+ call.model,
+ call.prompt_tokens,
+ call.completion_tokens,
+ )
+
+ run_id = f"alert:{alert_id}"
+
+ # ``aisoc_run_costs`` PK is (run_id, tenant_id, model). We use an
+ # upsert so multiple explain calls for the same alert accumulate
+ # rather than blowing up on a duplicate key — analysts may click
+ # "explain" several times during triage.
+ await db.execute(
+ # Plain SQL keeps the dialect-specific INSERT … ON CONFLICT
+ # in one place. The cost dashboard already uses the same
+ # table; we don't introduce a new abstraction.
+ _UPSERT_RUN_COST,
+ {
+ "run_id": run_id,
+ "tenant_id": str(tenant_id),
+ "model": call.model,
+ "prompt_tokens": call.prompt_tokens,
+ "completion_tokens": call.completion_tokens,
+ "cost_usd": cost_usd,
+ "latency_ms": call.latency_ms,
+ },
+ )
+
+
+from sqlalchemy import text # noqa: E402 (kept near use site for clarity)
+
+_UPSERT_RUN_COST = text(
+ """
+ INSERT INTO aisoc_run_costs (
+ run_id, tenant_id, model,
+ total_prompt_tokens, total_completion_tokens,
+ total_cost_usd, total_latency_ms, call_count, recorded_at
+ )
+ VALUES (
+ :run_id, :tenant_id, :model,
+ :prompt_tokens, :completion_tokens,
+ :cost_usd, :latency_ms, 1, now()
+ )
+ ON CONFLICT (run_id, tenant_id, model) DO UPDATE SET
+ total_prompt_tokens = aisoc_run_costs.total_prompt_tokens + EXCLUDED.total_prompt_tokens,
+ total_completion_tokens = aisoc_run_costs.total_completion_tokens + EXCLUDED.total_completion_tokens,
+ total_cost_usd = aisoc_run_costs.total_cost_usd + EXCLUDED.total_cost_usd,
+ total_latency_ms = aisoc_run_costs.total_latency_ms + EXCLUDED.total_latency_ms,
+ call_count = aisoc_run_costs.call_count + 1,
+ recorded_at = now()
+ """
+)
+
+
+# ---------------------------------------------------------------------------
+# Top-level orchestration
+# ---------------------------------------------------------------------------
+
+
+async def generate_alert_explanation(
+ db: AsyncSession,
+ *,
+ alert: Alert,
+) -> AlertExplanation:
+ """Produce the full structured explanation for one alert.
+
+ The caller is responsible for permission checks (``alerts:read``)
+ and rate limiting; this function only does the explain work and
+ assumes the session's RLS context already restricts visibility to
+ the alert's tenant.
+ """
+ rule, lineage_confidence, lineage_method = await _resolve_rule_lineage(db, alert)
+ rule_lineage = RuleLineage(
+ rule_id=str(rule.id) if rule else None,
+ rule_name=rule.name if rule else None,
+ rule_description=rule.description if rule else None,
+ rule_status=rule.status if rule else None,
+ rule_severity=rule.severity if rule else None,
+ rule_confidence=rule.confidence if rule else None,
+ rule_language=rule.rule_language if rule else None,
+ is_builtin=bool(rule.is_builtin) if rule else False,
+ confidence=lineage_confidence,
+ match_method=lineage_method,
+ )
+
+ fp = await _historical_fp_rate(
+ db,
+ tenant_id=alert.tenant_id,
+ rule=rule,
+ alert=alert,
+ )
+
+ mitre_ids = _extract_mitre_ids(alert)
+ mitre_techniques = [_resolve_technique_card(tid) for tid in mitre_ids]
+ contributing = _extract_contributing_events(alert)
+ actions = _build_suggested_actions(alert, mitre_ids)
+
+ fallback_summary = _deterministic_summary(alert, mitre_techniques, rule_lineage, fp)
+
+ llm_config = await resolve_llm_config(db, alert.tenant_id)
+ llm_used = False
+ llm_reason = llm_config.reason
+ summary = fallback_summary
+
+ if llm_config.allowed and llm_config.api_key:
+ call = await _call_llm_for_summary(
+ alert=alert,
+ rule_lineage=rule_lineage,
+ mitre_techniques=mitre_techniques,
+ fp=fp,
+ llm_config=llm_config,
+ )
+ if call.text:
+ summary = call.text
+ llm_used = True
+ else:
+ llm_reason = call.error or "llm_returned_empty_response"
+ # Always attempt to book the cost — _record_llm_cost no-ops on
+ # failed calls so we don't pollute the cost table with zero
+ # rows.
+ try:
+ await _record_llm_cost(
+ db,
+ tenant_id=alert.tenant_id,
+ alert_id=alert.id,
+ call=call,
+ )
+ except Exception as exc: # noqa: BLE001
+ # Cost tracking failures must never break the explain
+ # response. Log and move on.
+ logger.warning(
+ "explain.cost_track_failed tenant=%s alert=%s error=%s",
+ alert.tenant_id,
+ alert.id,
+ exc,
+ )
+
+ return AlertExplanation(
+ alert_id=str(alert.id),
+ summary=summary,
+ rule_lineage=rule_lineage,
+ contributing_events=contributing,
+ mitre_techniques=mitre_techniques,
+ historical_fp_rate=fp,
+ suggested_actions=actions,
+ llm_used=llm_used,
+ llm_source=llm_config.source,
+ llm_reason="" if llm_used else (llm_reason or "llm_disabled"),
+ generated_at=datetime.now(UTC).isoformat(),
+ )
diff --git a/services/api/app/services/explain_rate_limit.py b/services/api/app/services/explain_rate_limit.py
new file mode 100644
index 000000000..8a1a42ab0
--- /dev/null
+++ b/services/api/app/services/explain_rate_limit.py
@@ -0,0 +1,183 @@
+"""Per-tenant token-bucket rate limiter for the alert-explain endpoint.
+
+The explain endpoint hits an LLM on every successful call and runs
+two analytics queries (rule lineage + historical FP rate). Without a
+per-tenant cap a runaway agent loop, a misconfigured frontend, or a
+bored analyst clicking "explain" in a tight loop can:
+
+ 1. Burn LLM budget faster than the cost dashboard can update.
+ 2. Drive concurrency on the analytics queries through the floor.
+
+The lake API already proved out a token-bucket limiter
+(:mod:`app.services.lake_rate_limit`); we instantiate a second bucket
+with explain-tuned defaults rather than refactoring that module
+mid-flight. The class is identical in spirit (lazy-refill,
+per-tenant, asyncio-safe) but the defaults are tighter to reflect
+the cost profile:
+
+ * **capacity = 20** — a human triaging an incident might explain a
+ handful of related alerts in a row; 20 lets that happen without
+ pause while still capping a runaway loop.
+ * **refill = 0.2 / sec** — sustained 12 explains/minute. A
+ well-behaved console will stay well under this even during a
+ busy shift.
+
+Operators can override both via env vars without code changes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from dataclasses import dataclass, field
+from uuid import UUID
+
+# Defaults tuned for explain-call cost profile.
+_DEFAULT_CAPACITY: float = 20.0
+_DEFAULT_REFILL: float = 0.2 # tokens / second → 12/minute sustained
+
+
+def _env_float(name: str, default: float) -> float:
+ raw = os.getenv(name, "").strip()
+ if not raw:
+ return default
+ try:
+ value = float(raw)
+ except ValueError:
+ return default
+ return value if value > 0 else default
+
+
+@dataclass
+class _ExplainBucket:
+ """One tenant's bucket. Identical machinery to the lake limiter."""
+
+ capacity: float
+ refill_per_second: float
+ tokens: float = field(default=_DEFAULT_CAPACITY)
+ last_refill: float = field(default_factory=time.monotonic)
+ lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+ def __post_init__(self) -> None:
+ if self.tokens > self.capacity:
+ self.tokens = self.capacity
+
+ def _refill(self, now: float) -> None:
+ elapsed = max(0.0, now - self.last_refill)
+ if elapsed > 0.0:
+ self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_per_second)
+ self.last_refill = now
+
+
+@dataclass(frozen=True)
+class ExplainRateLimitDecision:
+ """Outcome of an :meth:`acquire` attempt."""
+
+ allowed: bool
+ remaining: float
+ capacity: float
+ retry_after_seconds: float
+
+ def to_headers(self) -> dict[str, str]:
+ headers = {
+ "X-RateLimit-Limit": f"{int(self.capacity)}",
+ "X-RateLimit-Remaining": f"{max(0, int(self.remaining))}",
+ }
+ if not self.allowed:
+ # RFC 7231 §7.1.3: integer seconds, non-negative.
+ headers["Retry-After"] = f"{max(1, int(self.retry_after_seconds + 0.999))}"
+ return headers
+
+
+class ExplainRateLimiter:
+ """Per-tenant token-bucket limiter for the explain endpoint.
+
+ See module docstring for the design rationale and the rationale
+ for the explain-specific defaults. The ``cost`` parameter exists
+ so we can charge differently when (eventually) the explain payload
+ grows a "deep" mode that triggers additional LLM calls.
+ """
+
+ def __init__(
+ self,
+ *,
+ capacity: float | None = None,
+ refill_per_second: float | None = None,
+ ) -> None:
+ cap = capacity if capacity is not None else _env_float("AISOC_EXPLAIN_RATE_CAPACITY", _DEFAULT_CAPACITY)
+ ref = refill_per_second if refill_per_second is not None else _env_float("AISOC_EXPLAIN_RATE_REFILL", _DEFAULT_REFILL)
+ if cap <= 0:
+ raise ValueError("capacity must be positive")
+ if ref <= 0:
+ raise ValueError("refill_per_second must be positive")
+ self._capacity = cap
+ self._refill_per_second = ref
+ self._buckets: dict[str, _ExplainBucket] = {}
+ self._registry_lock = asyncio.Lock()
+
+ async def acquire(
+ self,
+ tenant_id: UUID | str,
+ *,
+ cost: float = 1.0,
+ ) -> ExplainRateLimitDecision:
+ """Attempt to consume ``cost`` tokens for ``tenant_id``."""
+ if cost <= 0:
+ raise ValueError("cost must be positive")
+ if cost > self._capacity:
+ raise ValueError(f"cost {cost} exceeds capacity {self._capacity}; would never succeed")
+
+ bucket = await self._get_bucket(str(tenant_id))
+ async with bucket.lock:
+ now = time.monotonic()
+ bucket._refill(now)
+ if bucket.tokens >= cost:
+ bucket.tokens -= cost
+ return ExplainRateLimitDecision(
+ allowed=True,
+ remaining=bucket.tokens,
+ capacity=self._capacity,
+ retry_after_seconds=0.0,
+ )
+ shortfall = cost - bucket.tokens
+ return ExplainRateLimitDecision(
+ allowed=False,
+ remaining=bucket.tokens,
+ capacity=self._capacity,
+ retry_after_seconds=shortfall / self._refill_per_second,
+ )
+
+ async def reset(self, tenant_id: UUID | str | None = None) -> None:
+ """Drop bucket state. Used by tests and (potentially) admins."""
+ async with self._registry_lock:
+ if tenant_id is None:
+ self._buckets.clear()
+ else:
+ self._buckets.pop(str(tenant_id), None)
+
+ async def _get_bucket(self, key: str) -> _ExplainBucket:
+ bucket = self._buckets.get(key)
+ if bucket is not None:
+ return bucket
+ async with self._registry_lock:
+ bucket = self._buckets.get(key)
+ if bucket is None:
+ bucket = _ExplainBucket(
+ capacity=self._capacity,
+ refill_per_second=self._refill_per_second,
+ tokens=self._capacity,
+ )
+ self._buckets[key] = bucket
+ return bucket
+
+
+# Process-wide singleton. Mirrors the lake-limiter convention: tests
+# call ``reset`` on the singleton rather than reconstructing the
+# limiter so they don't fight import-time wiring.
+_explain_rate_limiter = ExplainRateLimiter()
+
+
+def get_explain_rate_limiter() -> ExplainRateLimiter:
+ """Return the process-wide explain rate limiter singleton."""
+ return _explain_rate_limiter
diff --git a/services/api/app/services/llm_resolver.py b/services/api/app/services/llm_resolver.py
new file mode 100644
index 000000000..29d2e4df4
--- /dev/null
+++ b/services/api/app/services/llm_resolver.py
@@ -0,0 +1,281 @@
+"""Resolve the effective LLM configuration for a single API-side request.
+
+This module is the API-service twin of
+:mod:`services.agents.app.security.llm_resolver`. It exists so the
+``POST /api/v1/alerts/{alert_id}/explain`` endpoint can resolve a
+tenant's BYOK configuration *without* round-tripping to the agents
+service.
+
+Why a second resolver?
+----------------------
+The agents service has its own resolver because it owns its own
+asyncpg pool and isolates from the API service for latency reasons.
+This module is the SQLAlchemy equivalent that the API service uses
+directly, going through the same RLS context (``app.current_tenant_id``)
+that ``get_tenant_db`` already establishes for the request.
+
+Resolution rules (must match the agents resolver exactly)
+---------------------------------------------------------
+1. Pull the env baseline (``OPENAI_BASE_URL`` / ``OPENAI_MODEL`` /
+ ``OPENAI_API_KEY``, plus the modern ``LLM_*`` aliases).
+2. Look up ``tenant_llm_credentials`` for this tenant. If a row
+ exists and ``enabled=true``, layer non-NULL fields over the env
+ baseline and decrypt the ciphertext via :class:`CredentialVault`.
+3. Apply air-gap policy: when ``AISOC_AIRGAPPED`` is on, only allow
+ base URLs that point at a non-``api.openai.com`` host.
+4. Return an :class:`LlmConfig` describing whether a live call is
+ permitted and the effective ``(base_url, model, api_key)`` triple.
+
+The resolver never raises — every failure path returns
+``allowed=False`` with a populated ``reason`` so callers can record
+exactly why the explain endpoint fell back to the deterministic
+synthesizer.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.llm_credential import TenantLlmCredential
+from app.security.credential_vault import CredentialVaultError, get_vault
+
+logger = logging.getLogger(__name__)
+
+
+_DEFAULT_OPENAI_BASE = "https://api.openai.com"
+_DEFAULT_OPENAI_MODEL = "gpt-4o-mini"
+
+
+@dataclass(frozen=True)
+class LlmConfig:
+ """Effective LLM configuration for a single explain request.
+
+ Attributes:
+ allowed: ``True`` when an outbound LLM call is permitted right
+ now. ``False`` means the explain path must use the
+ deterministic synthesizer.
+ base_url: The base URL to POST chat completions against.
+ Always populated, even on ``allowed=False``, so callers
+ can log it.
+ model: The model identifier to send in the request body.
+ api_key: The plaintext API key. Only present when
+ ``allowed=True``. Never logged, never returned to clients.
+ source: One of ``"tenant"``, ``"environment"``, ``"mixed"``,
+ ``"none"`` — describes where the layered config came
+ from. Mirrors ``llm_status._compute_status``.
+ reason: When ``allowed=False``, a short note explaining why.
+ Empty when ``allowed=True``.
+ """
+
+ allowed: bool
+ base_url: str
+ model: str
+ api_key: str | None
+ source: str
+ reason: str
+
+
+def _env_baseline() -> tuple[str, str, str | None]:
+ """Return the ``(base_url, model, api_key)`` triple from process env.
+
+ Mirrors :func:`services.api.app.api.v1.endpoints.llm_status._env_baseline`
+ and the agents-side resolver so the three code paths can never
+ disagree about what "the env baseline" actually is. We accept
+ both modern ``LLM_*`` names and legacy ``OPENAI_*`` /
+ ``AISOC_LLM_MODEL`` because every deployment in the field today
+ uses some mix of the two.
+ """
+ base_url = os.getenv("OPENAI_BASE_URL", "").strip() or os.getenv("LLM_BASE_URL", "").strip()
+ model = os.getenv("OPENAI_MODEL", "").strip() or os.getenv("LLM_MODEL", "").strip() or os.getenv("AISOC_LLM_MODEL", "").strip()
+ api_key = os.getenv("OPENAI_API_KEY", "").strip() or os.getenv("LLM_API_KEY", "").strip()
+ return base_url, model, (api_key or None)
+
+
+def _airgap_blocks(base_url: str) -> tuple[bool, str]:
+ """Return ``(blocked, reason)`` under the current air-gap policy.
+
+ Replicates the semantics of the agents-side ``_airgap_blocks``
+ helper. We deliberately do not import :func:`enforce_airgap_for_url`
+ from ``app.core.airgap`` because that helper is intended for the
+ actual outbound call and raises; here we want a non-raising
+ classification for the resolver's "would this be allowed?"
+ decision. The two paths must agree on the same hostname rule
+ (no ``api.openai.com``), and they do.
+ """
+ airgapped = os.getenv("AISOC_AIRGAPPED", "").lower() in ("1", "true", "yes")
+ if not airgapped:
+ return False, ""
+
+ base = (base_url or "").strip()
+ if not base:
+ return (
+ True,
+ "AISOC_AIRGAPPED is on and no base_url is configured (would default to api.openai.com).",
+ )
+ try:
+ hostname = (urlparse(base).hostname or "").lower()
+ except Exception: # noqa: BLE001
+ hostname = ""
+ # Exact hostname or subdomain match — substring matching would
+ # let ``evil.com/api.openai.com`` slip through.
+ if hostname == "api.openai.com" or hostname.endswith(".api.openai.com"):
+ return True, "AISOC_AIRGAPPED is on and base_url points at api.openai.com."
+ return False, ""
+
+
+def _decrypt_vault_token(vault_token: str, tenant_id: uuid.UUID) -> str | None:
+ """Decrypt a stored ``vault:v1:<base64>`` token; ``None`` on failure.
+
+ The vault may be unconfigured on operator boxes that haven't
+ migrated to BYOK yet (``AISOC_CREDENTIAL_KEY`` not set) — log
+ once and fall back rather than treating it as an error.
+ """
+ try:
+ vault = get_vault()
+ except CredentialVaultError as exc:
+ logger.warning(
+ "explain.llm_resolve_vault_disabled tenant=%s reason=%s",
+ tenant_id,
+ exc,
+ )
+ return None
+ try:
+ return vault.decrypt(vault_token)
+ except CredentialVaultError as exc:
+ logger.warning(
+ "explain.llm_resolve_decrypt_failed tenant=%s error=%s",
+ tenant_id,
+ exc,
+ )
+ return None
+
+
+def _classify_source(
+ *,
+ env_base_url: str,
+ env_model: str,
+ env_key: str | None,
+ tenant_contributed_base_url: bool,
+ tenant_contributed_model: bool,
+ tenant_contributed_key: bool,
+) -> str:
+ """Label the merge result.
+
+ Mirrors the agents-side resolver and ``llm_status._compute_status``
+ so the API-side ``source`` value matches what the Settings UI's
+ LLM status indicator reports.
+ """
+ tenant_contributed = tenant_contributed_base_url or tenant_contributed_model or tenant_contributed_key
+ env_contributed = (
+ (not tenant_contributed_base_url and bool(env_base_url))
+ or (not tenant_contributed_model and bool(env_model))
+ or (not tenant_contributed_key and bool(env_key))
+ )
+
+ if tenant_contributed and env_contributed:
+ return "mixed"
+ if tenant_contributed:
+ return "tenant"
+ if env_contributed:
+ return "environment"
+ return "none"
+
+
+async def resolve_llm_config(db: AsyncSession, tenant_id: uuid.UUID) -> LlmConfig:
+ """Resolve the effective LLM configuration for ``tenant_id``.
+
+ The DB session must already have its RLS context set to
+ ``tenant_id`` (use :class:`TenantDBSession`). We re-pass the
+ tenant id explicitly only to scope the SELECT and to avoid
+ spelunking through session info dictionaries.
+
+ Returns:
+ An :class:`LlmConfig`. Never raises — failures collapse to
+ ``allowed=False`` with a populated ``reason``.
+ """
+ env_base_url, env_model, env_key = _env_baseline()
+
+ base_url = env_base_url
+ model = env_model
+ api_key = env_key
+ tenant_contributed_base_url = False
+ tenant_contributed_model = False
+ tenant_contributed_key = False
+
+ try:
+ result = await db.execute(
+ select(TenantLlmCredential).where(
+ TenantLlmCredential.tenant_id == tenant_id,
+ TenantLlmCredential.enabled.is_(True),
+ )
+ )
+ cred = result.scalar_one_or_none()
+ except Exception as exc: # noqa: BLE001
+ logger.warning("explain.llm_resolve_db_failed tenant=%s error=%s", tenant_id, exc)
+ cred = None
+
+ if cred is not None:
+ if cred.base_url:
+ base_url = cred.base_url
+ tenant_contributed_base_url = True
+ if cred.model:
+ model = cred.model
+ tenant_contributed_model = True
+ if cred.api_key_vault:
+ decrypted = _decrypt_vault_token(cred.api_key_vault, tenant_id)
+ if decrypted is not None:
+ api_key = decrypted
+ tenant_contributed_key = True
+ # else: fall through to env_key — corrupt tenant ciphertext
+ # should not break a tenant that has a working env baseline.
+
+ source = _classify_source(
+ env_base_url=env_base_url,
+ env_model=env_model,
+ env_key=env_key,
+ tenant_contributed_base_url=tenant_contributed_base_url,
+ tenant_contributed_model=tenant_contributed_model,
+ tenant_contributed_key=tenant_contributed_key,
+ )
+
+ final_base = base_url or _DEFAULT_OPENAI_BASE
+ final_model = model or _DEFAULT_OPENAI_MODEL
+
+ if not api_key:
+ return LlmConfig(
+ allowed=False,
+ base_url=final_base,
+ model=final_model,
+ api_key=None,
+ source=source,
+ reason="no API key configured (neither tenant BYOK nor env)",
+ )
+
+ blocked, reason = _airgap_blocks(base_url)
+ if blocked:
+ # Discard the api_key on the failure path so callers physically
+ # cannot exfiltrate it via a wayward log statement.
+ return LlmConfig(
+ allowed=False,
+ base_url=final_base,
+ model=final_model,
+ api_key=None,
+ source=source,
+ reason=reason,
+ )
+
+ return LlmConfig(
+ allowed=True,
+ base_url=final_base,
+ model=final_model,
+ api_key=api_key,
+ source=source,
+ reason="",
+ )
diff --git a/services/api/tests/test_alert_explain.py b/services/api/tests/test_alert_explain.py
new file mode 100644
index 000000000..ba6d319a3
--- /dev/null
+++ b/services/api/tests/test_alert_explain.py
@@ -0,0 +1,1233 @@
+"""Unit tests for the alert-explain pipeline (Stage 2 #6).
+
+The explain pipeline is intentionally split into pure helpers + an
+orchestrator, so we test it the same way:
+
+* **Pure helpers** (``_explicit_rule_id_from_alert``, ``_extract_mitre_ids``,
+ ``_extract_contributing_events``, ``_build_suggested_actions``,
+ ``_deterministic_summary``) get straightforward in-process tests
+ with hand-built ``Alert`` stand-ins. These cover lineage probing,
+ observable extraction, and the deterministic-fallback summary.
+
+* **DB-touching helpers** (``_resolve_rule_lineage``,
+ ``_historical_fp_rate``) are exercised against an in-memory
+ ``MagicMock(AsyncSession)`` whose ``execute`` returns canned rows.
+ We do not stand up a real database here — the goal is to lock in
+ the matching/scoring logic, not Postgres semantics. The integration
+ tests in CI cover the SQLAlchemy translation.
+
+* **Orchestrator** (``generate_alert_explanation``) is tested with
+ the LLM resolver and the per-call helpers patched out, so we can
+ assert the four observable branches: LLM-enabled-and-succeeds,
+ LLM-enabled-but-empty, LLM-blocked, and LLM-allowed-but-airgap.
+
+* **Endpoint helpers** (``_acquire_or_429``, ``_explanation_to_payload``)
+ use the same mocking style as ``test_lake_endpoint.py`` —
+ patching the rate-limiter factory at the call site so the test
+ stays hermetic.
+
+* **Rate limiter** gets a dedicated suite mirroring
+ ``test_lake_rate_limit.py``: monkeypatched ``time.monotonic`` to
+ prove first-request-allowed, capacity exhaustion, refill-after-wait,
+ and per-tenant isolation. Without these we'd be one off-by-one bug
+ away from a tenant burning the explain budget in seconds.
+
+The tests deliberately do NOT spin up FastAPI's TestClient. The
+endpoint module itself is a thin orchestration layer; the lake
+endpoint pattern (test the helpers, integration test the wiring)
+keeps these tests fast and deterministic.
+"""
+
+from __future__ import annotations
+
+import uuid
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from app.api.v1.endpoints.alert_explain import (
+ _acquire_or_429,
+ _explanation_to_payload,
+)
+from app.services.alert_explain import (
+ AlertExplanation,
+ ContributingEvent,
+ HistoricalFpRate,
+ MitreTechnique,
+ RuleLineage,
+ SuggestedAction,
+ _build_suggested_actions,
+ _deterministic_summary,
+ _explicit_rule_id_from_alert,
+ _extract_contributing_events,
+ _extract_mitre_ids,
+ _historical_fp_rate,
+ _resolve_rule_lineage,
+ generate_alert_explanation,
+)
+from app.services.explain_rate_limit import (
+ ExplainRateLimitDecision,
+ ExplainRateLimiter,
+)
+from app.services.llm_resolver import LlmConfig
+from fastapi import HTTPException, Response
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _alert(
+ *,
+ alert_id: uuid.UUID | None = None,
+ tenant_id: uuid.UUID | None = None,
+ title: str = "Suspicious login from new geo",
+ description: str | None = "User signed in from an unusual country.",
+ severity: str = "high",
+ category: str | None = "identity",
+ connector_type: str | None = "okta",
+ raw_event: dict[str, Any] | None = None,
+ tags: list[str] | None = None,
+ mitre_techniques: list[str] | None = None,
+ ai_score: float | None = 0.82,
+ disposition: str | None = None,
+) -> SimpleNamespace:
+ """Build a stand-in for the ``Alert`` ORM object.
+
+ We use ``SimpleNamespace`` so the test doesn't have to wire up the
+ SQLAlchemy mapper or instantiate a real session. The explain
+ helpers only ever attribute-access the fields they need; they
+ don't call any ORM-only methods.
+ """
+ return SimpleNamespace(
+ id=alert_id or uuid.uuid4(),
+ tenant_id=tenant_id or uuid.uuid4(),
+ title=title,
+ description=description,
+ severity=severity,
+ category=category,
+ connector_type=connector_type,
+ raw_event=raw_event or {},
+ tags=tags or [],
+ mitre_techniques=mitre_techniques or [],
+ ai_score=ai_score,
+ disposition=disposition,
+ )
+
+
+def _rule(
+ *,
+ rule_id: uuid.UUID | None = None,
+ tenant_id: uuid.UUID | None = None,
+ name: str = "Impossible travel",
+ description: str | None = "Detect impossible travel between consecutive logins.",
+ category: str | None = "identity",
+ severity: str = "high",
+ status: str = "enabled",
+ confidence: int = 80,
+ rule_language: str = "sigma",
+ is_builtin: bool = True,
+ mitre_techniques: list[str] | None = None,
+) -> SimpleNamespace:
+ """Stand-in for the ``DetectionRule`` ORM object."""
+ return SimpleNamespace(
+ id=rule_id or uuid.uuid4(),
+ tenant_id=tenant_id,
+ name=name,
+ description=description,
+ category=category,
+ severity=severity,
+ status=status,
+ confidence=confidence,
+ rule_language=rule_language,
+ is_builtin=is_builtin,
+ mitre_techniques=mitre_techniques or ["T1078"],
+ )
+
+
+def _scalar_one_or_none_result(value: Any) -> MagicMock:
+ """Mock an ``await session.execute(...)`` whose ``scalar_one_or_none()`` returns ``value``."""
+ result = MagicMock()
+ result.scalar_one_or_none = MagicMock(return_value=value)
+ return result
+
+
+def _scalars_all_result(values: list[Any]) -> MagicMock:
+ """Mock ``await session.execute(...)`` whose ``scalars().all()`` returns ``values``."""
+ result = MagicMock()
+ scalars = MagicMock()
+ scalars.all = MagicMock(return_value=values)
+ result.scalars = MagicMock(return_value=scalars)
+ return result
+
+
+def _row_one_result(*, total: int, fps: int) -> MagicMock:
+ """Mock ``await session.execute(...).one()`` for the FPR aggregate."""
+ row = SimpleNamespace(total=total, fps=fps)
+ result = MagicMock()
+ result.one = MagicMock(return_value=row)
+ return result
+
+
+# ---------------------------------------------------------------------------
+# _explicit_rule_id_from_alert — connector-supplied lineage signals
+# ---------------------------------------------------------------------------
+
+
+class TestExplicitRuleIdFromAlert:
+ """Probes the connector-supplied rule lineage signals.
+
+ These probes are the *only* high-confidence rule-attribution
+ signal in the explain pipeline (everything else is heuristic), so
+ we exercise every documented shape exhaustively. A regression here
+ would silently demote ``RuleLineage.confidence`` from ``"high"``
+ to ``"medium"`` for entire connectors.
+ """
+
+ def test_returns_none_for_alert_without_signals(self) -> None:
+ # No raw_event, no tags → nothing to probe → None.
+ alert = _alert(raw_event={}, tags=[])
+ assert _explicit_rule_id_from_alert(alert) is None
+
+ def test_picks_up_top_level_rule_id_from_raw_event(self) -> None:
+ # Most common case: connector wrote the rule UUID into the raw event.
+ rid = uuid.uuid4()
+ alert = _alert(raw_event={"rule_id": str(rid)})
+ assert _explicit_rule_id_from_alert(alert) == rid
+
+ def test_picks_up_camel_case_rule_id(self) -> None:
+ # Some connectors emit camelCase. The probe MUST tolerate both
+ # spellings or we'd miss the lineage signal half the time.
+ rid = uuid.uuid4()
+ alert = _alert(raw_event={"detectionRuleId": str(rid)})
+ assert _explicit_rule_id_from_alert(alert) == rid
+
+ def test_picks_up_nested_rule_id(self) -> None:
+ # The Sentinel/SCC family of connectors nests the rule under a
+ # parent object. The probe walks one level deep.
+ rid = uuid.uuid4()
+ alert = _alert(raw_event={"detection": {"id": str(rid)}})
+ assert _explicit_rule_id_from_alert(alert) == rid
+
+ def test_picks_up_rule_tag(self) -> None:
+ # Some pipelines stamp a ``rule:<uuid>`` tag rather than
+ # mutating raw_event. The probe falls back to tags after
+ # raw_event yields nothing.
+ rid = uuid.uuid4()
+ alert = _alert(tags=[f"rule:{rid}", "ato"])
+ assert _explicit_rule_id_from_alert(alert) == rid
+
+ def test_ignores_malformed_rule_tag(self) -> None:
+ # ``rule:not-a-uuid`` must NOT be coerced into a fake UUID.
+ # Returning a junk UUID would later 404 in _resolve_rule_lineage
+ # instead of falling through to the heuristic match.
+ alert = _alert(tags=["rule:not-a-uuid"])
+ assert _explicit_rule_id_from_alert(alert) is None
+
+ def test_ignores_invalid_uuid_in_raw_event(self) -> None:
+ # Defensive: connectors sometimes write integer IDs. We must
+ # treat them as "no signal" rather than crashing the explain.
+ alert = _alert(raw_event={"rule_id": 12345})
+ assert _explicit_rule_id_from_alert(alert) is None
+
+ def test_rejects_non_string_tag_entries(self) -> None:
+ # A list with mixed types must not crash the regex match.
+ rid = uuid.uuid4()
+ alert = _alert(tags=[None, 123, f"rule:{rid}"])
+ assert _explicit_rule_id_from_alert(alert) == rid
+
+
+# ---------------------------------------------------------------------------
+# _resolve_rule_lineage — full matching pipeline (mocked DB)
+# ---------------------------------------------------------------------------
+
+
+class TestResolveRuleLineage:
+ """End-to-end matching from alert → DetectionRule.
+
+ Each branch returns a different ``(confidence, match_method)``
+ tuple, and the UI uses ``match_method`` to flag low-confidence
+ guesses. Without these tests a refactor could silently downgrade
+ every alert's lineage to ``"none"``.
+ """
+
+ @pytest.mark.asyncio
+ async def test_explicit_match_returns_high_confidence(self) -> None:
+ # Explicit rule_id → fast-path lookup → high confidence.
+ rid = uuid.uuid4()
+ rule = _rule(rule_id=rid)
+ alert = _alert(raw_event={"rule_id": str(rid)})
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalar_one_or_none_result(rule))
+
+ result_rule, confidence, method = await _resolve_rule_lineage(db, alert)
+ assert result_rule is rule
+ assert confidence == "high"
+ assert method == "raw_event"
+ # Only ONE query needed: the explicit-id lookup.
+ assert db.execute.await_count == 1
+
+ @pytest.mark.asyncio
+ async def test_falls_through_when_explicit_id_does_not_exist(self) -> None:
+ # Explicit id present but no matching rule (deleted, wrong tenant)
+ # → fall through to the candidate search.
+ rid = uuid.uuid4()
+ alert = _alert(
+ raw_event={"rule_id": str(rid)},
+ mitre_techniques=["T1078"],
+ )
+
+ db = MagicMock()
+ # First call: explicit lookup → no row.
+ # Second call: candidate scan → one matching rule.
+ rule = _rule(mitre_techniques=["T1078"])
+ db.execute = AsyncMock(
+ side_effect=[
+ _scalar_one_or_none_result(None),
+ _scalars_all_result([rule]),
+ ]
+ )
+
+ result_rule, confidence, method = await _resolve_rule_lineage(db, alert)
+ assert result_rule is rule
+ # One technique overlap → medium confidence per the scoring rule.
+ assert confidence == "medium"
+ assert method == "mitre_overlap"
+
+ @pytest.mark.asyncio
+ async def test_returns_none_when_alert_has_no_signals(self) -> None:
+ # No explicit id, no category, no MITRE → bail out early
+ # without hitting the DB a second time.
+ alert = _alert(category=None, mitre_techniques=[])
+
+ db = MagicMock()
+ # No explicit signal in this alert, so no lookup at all.
+ # We assert we never call execute (early return).
+ db.execute = AsyncMock()
+
+ result_rule, confidence, method = await _resolve_rule_lineage(db, alert)
+ assert result_rule is None
+ assert confidence == "none"
+ assert method == "none"
+ db.execute.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_high_confidence_on_two_technique_overlap(self) -> None:
+ # Score rule: overlap*10 + confidence//10 + (1 if builtin else 0)
+ # Two-technique overlap → score >= 20 → high confidence.
+ rule = _rule(
+ confidence=80,
+ mitre_techniques=["T1078", "T1110"],
+ is_builtin=True,
+ )
+ alert = _alert(mitre_techniques=["T1078", "T1110", "T1059"])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalars_all_result([rule]))
+
+ result_rule, confidence, method = await _resolve_rule_lineage(db, alert)
+ assert result_rule is rule
+ assert confidence == "high"
+ assert method == "mitre_overlap"
+
+ @pytest.mark.asyncio
+ async def test_low_confidence_category_only_match(self) -> None:
+ # No technique overlap but category matches → low confidence
+ # category fall-back. The UI shows a "match guess" warning.
+ #
+ # Scoring: overlap*10 + min(confidence,100)//10 + (1 if builtin).
+ # We deliberately force score=0 by setting confidence=0 and
+ # is_builtin=False so the "category fallback" branch fires —
+ # otherwise the rule would still match via mitre_overlap (low)
+ # because of the confidence/builtin tie-breakers.
+ rule = _rule(
+ mitre_techniques=["T1110"],
+ category="identity",
+ confidence=0,
+ is_builtin=False,
+ )
+ alert = _alert(category="identity", mitre_techniques=["T1059"])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalars_all_result([rule]))
+
+ result_rule, confidence, method = await _resolve_rule_lineage(db, alert)
+ # No technique overlap, score=0 → category fall-back branch.
+ assert result_rule is rule
+ assert confidence == "low"
+ assert method == "category"
+
+ @pytest.mark.asyncio
+ async def test_candidate_set_empty_returns_none(self) -> None:
+ # Alert has signals but no rules came back → return None.
+ # This is the "tenant disabled all rules" corner.
+ alert = _alert(category="identity", mitre_techniques=["T1078"])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalars_all_result([]))
+
+ result_rule, confidence, method = await _resolve_rule_lineage(db, alert)
+ assert result_rule is None
+ assert confidence == "none"
+ assert method == "none"
+
+
+# ---------------------------------------------------------------------------
+# _historical_fp_rate — scope selection + bounded sample
+# ---------------------------------------------------------------------------
+
+
+class TestHistoricalFpRate:
+ """Selects the most specific FPR scope and computes the rate.
+
+ The FPR drives an analyst's gut on whether to keep digging or
+ triage as noise. A bug here biases triage decisions, so we lock
+ every scope branch + the bounded-failure path.
+ """
+
+ @pytest.mark.asyncio
+ async def test_rule_scope_with_techniques(self) -> None:
+ tenant = uuid.uuid4()
+ rule = _rule(category="identity", mitre_techniques=["T1078"])
+ alert = _alert(tenant_id=tenant, category="identity", mitre_techniques=["T1078"])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_row_one_result(total=200, fps=20))
+
+ fp = await _historical_fp_rate(db, tenant_id=tenant, rule=rule, alert=alert)
+
+ # 20 / 200 = 0.10 → exact rounding to 4 dp.
+ assert fp.fp_rate == pytest.approx(0.1)
+ assert fp.sample_size == 200
+ assert fp.false_positives == 20
+ assert fp.scope == "rule"
+ assert "Approximated by category" in fp.notes
+
+ @pytest.mark.asyncio
+ async def test_category_scope_when_no_rule(self) -> None:
+ # When we couldn't pin a rule down we fall back to a
+ # category+technique scope; the response notes must say so.
+ tenant = uuid.uuid4()
+ alert = _alert(tenant_id=tenant, category="identity", mitre_techniques=["T1078"])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_row_one_result(total=50, fps=5))
+
+ fp = await _historical_fp_rate(db, tenant_id=tenant, rule=None, alert=alert)
+ assert fp.scope == "category"
+ assert fp.sample_size == 50
+ assert "MITRE technique" in fp.notes
+
+ @pytest.mark.asyncio
+ async def test_category_only_when_no_techniques(self) -> None:
+ tenant = uuid.uuid4()
+ alert = _alert(tenant_id=tenant, category="identity", mitre_techniques=[])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_row_one_result(total=10, fps=1))
+
+ fp = await _historical_fp_rate(db, tenant_id=tenant, rule=None, alert=alert)
+ assert fp.scope == "category"
+ assert "no MITRE refinement" in fp.notes
+
+ @pytest.mark.asyncio
+ async def test_tenant_wide_fallback_when_alert_is_bare(self) -> None:
+ # Alert with no category and no techniques → tenant-wide
+ # fallback. UI must surface this as low-signal.
+ tenant = uuid.uuid4()
+ alert = _alert(tenant_id=tenant, category=None, mitre_techniques=[])
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_row_one_result(total=100, fps=10))
+
+ fp = await _historical_fp_rate(db, tenant_id=tenant, rule=None, alert=alert)
+ assert fp.scope == "category"
+ assert "Tenant-wide fallback" in fp.notes
+
+ @pytest.mark.asyncio
+ async def test_zero_sample_returns_zero_rate(self) -> None:
+ # No alerts → must NOT divide by zero.
+ tenant = uuid.uuid4()
+ alert = _alert(tenant_id=tenant)
+
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_row_one_result(total=0, fps=0))
+
+ fp = await _historical_fp_rate(db, tenant_id=tenant, rule=None, alert=alert)
+ assert fp.fp_rate == 0.0
+ assert fp.sample_size == 0
+ assert fp.false_positives == 0
+
+ @pytest.mark.asyncio
+ async def test_query_failure_collapses_to_safe_default(self) -> None:
+ # If the analytics DB is hot and the query times out, we MUST
+ # NOT fail the whole explain endpoint. Returning a notes-tagged
+ # zero-rate row keeps the rest of the explain payload usable.
+ tenant = uuid.uuid4()
+ alert = _alert(tenant_id=tenant)
+
+ db = MagicMock()
+ db.execute = AsyncMock(side_effect=RuntimeError("connection reset"))
+
+ fp = await _historical_fp_rate(db, tenant_id=tenant, rule=None, alert=alert)
+ assert fp.fp_rate == 0.0
+ assert fp.sample_size == 0
+ assert "Query failed" in fp.notes
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers: extracting MITRE ids, contributing events, suggested actions
+# ---------------------------------------------------------------------------
+
+
+class TestExtractMitreIds:
+ """The MITRE ID extractor is pure and deterministic."""
+
+ def test_prefers_structured_field(self) -> None:
+ # Structured field is canonical; regex sweep is a fallback.
+ alert = _alert(
+ mitre_techniques=["T1078"],
+ tags=["T1059"],
+ description="Technique T1110 was observed",
+ )
+ ids = _extract_mitre_ids(alert)
+ # Structured field appears first; regex hits added afterwards
+ # without duplicates.
+ assert ids[0] == "T1078"
+ assert "T1059" in ids
+ assert "T1110" in ids
+
+ def test_dedupes_across_sources(self) -> None:
+ alert = _alert(
+ mitre_techniques=["T1078"],
+ tags=["T1078"],
+ description="T1078 again",
+ )
+ assert _extract_mitre_ids(alert) == ["T1078"]
+
+ def test_caps_to_max_techniques(self) -> None:
+ # Drawer cap is 5 — more than that and the card list overflows
+ # the responsive layout.
+ alert = _alert(mitre_techniques=[f"T{1000 + i}" for i in range(20)])
+ ids = _extract_mitre_ids(alert)
+ assert len(ids) == 5
+
+ def test_recognises_subtechnique_ids(self) -> None:
+ # Sub-techniques use a dot suffix (T1078.001). The regex must
+ # accept both spellings or we'd silently drop the granularity.
+ alert = _alert(
+ mitre_techniques=[],
+ description="Saw T1078.001 in the trace",
+ )
+ assert "T1078.001" in _extract_mitre_ids(alert)
+
+
+class TestExtractContributingEvents:
+ """Observable extraction is purely structural."""
+
+ def test_includes_severity_and_source(self) -> None:
+ alert = _alert(
+ severity="high",
+ connector_type="okta",
+ ai_score=0.9,
+ raw_event={"user": "[email protected]"},
+ )
+ events = _extract_contributing_events(alert)
+ labels = {e.label for e in events}
+ assert "Severity" in labels
+ assert "Source" in labels
+ assert "AI score" in labels
+ assert "User" in labels
+
+ def test_truncates_long_values(self) -> None:
+ # Cap is 160 chars — keeps the drawer scannable. A 500-char IOC
+ # like a base64 cert blob would otherwise blow up the layout.
+ alert = _alert(raw_event={"url": "https://example.com/" + "a" * 500})
+ events = _extract_contributing_events(alert)
+ url_event = next(e for e in events if e.label == "URL")
+ assert len(url_event.value) <= 160
+
+ def test_skips_empty_observables(self) -> None:
+ # Empty strings, empty lists, None → not included.
+ alert = _alert(
+ connector_type=None,
+ raw_event={"user": "", "src_ip": None, "host": []},
+ ai_score=None,
+ )
+ events = _extract_contributing_events(alert)
+ labels = {e.label for e in events}
+ # Severity always present.
+ assert labels == {"Severity", "Source"} # connector_type=None → "platform"
+
+
+class TestBuildSuggestedActions:
+ """Suggested actions are hand-curated; LLM never picks them."""
+
+ def test_ato_tag_triggers_ato_playbook(self) -> None:
+ alert = _alert(tags=["ato"])
+ actions = _build_suggested_actions(alert, mitre_ids=[])
+ titles = [a.title for a in actions]
+ assert any("ATO containment" in t for t in titles)
+
+ def test_t1078_triggers_ato_playbook(self) -> None:
+ # Technique-driven path — also fires the ATO playbook.
+ alert = _alert(tags=[])
+ actions = _build_suggested_actions(alert, mitre_ids=["T1078"])
+ titles = [a.title for a in actions]
+ assert any("ATO containment" in t for t in titles)
+
+ def test_ransomware_tag_triggers_isolation(self) -> None:
+ alert = _alert(tags=["ransomware"], severity="critical")
+ actions = _build_suggested_actions(alert, mitre_ids=[])
+ titles = [a.title for a in actions]
+ assert any("Isolate the host" in t for t in titles)
+
+ def test_critical_severity_promotes_to_case(self) -> None:
+ alert = _alert(severity="critical")
+ actions = _build_suggested_actions(alert, mitre_ids=[])
+ # Critical severity always adds "Open a case" with priority=immediate.
+ case_action = next(a for a in actions if "Open a case" in a.title)
+ assert case_action.priority == "immediate"
+
+ def test_default_action_when_no_signals(self) -> None:
+ # Every alert gets at least one suggested action — the drawer
+ # never shows an empty list.
+ alert = _alert(tags=[], severity="low")
+ actions = _build_suggested_actions(alert, mitre_ids=[])
+ assert len(actions) >= 1
+
+ def test_caps_at_four_actions(self) -> None:
+ # Drawer hard cap; tested with the noisiest possible alert.
+ alert = _alert(tags=["ato", "ransomware", "phishing"], severity="critical")
+ actions = _build_suggested_actions(alert, mitre_ids=["T1078", "T1190"])
+ assert len(actions) <= 4
+
+
+class TestDeterministicSummary:
+ """Fallback summary used when LLM is disabled or fails."""
+
+ def _stub_lineage(self, *, name: str | None = "Test rule") -> RuleLineage:
+ return RuleLineage(
+ rule_id="abc" if name else None,
+ rule_name=name,
+ rule_description="desc",
+ rule_status="enabled",
+ rule_severity="high",
+ rule_confidence=80,
+ rule_language="sigma",
+ is_builtin=True,
+ confidence="high" if name else "none",
+ match_method="raw_event" if name else "none",
+ )
+
+ def _stub_fp(self, *, sample: int = 100, rate: float = 0.2) -> HistoricalFpRate:
+ return HistoricalFpRate(
+ fp_rate=rate,
+ sample_size=sample,
+ false_positives=int(sample * rate),
+ lookback_days=90,
+ scope="rule",
+ notes="",
+ )
+
+ def test_includes_alert_title_and_severity(self) -> None:
+ alert = _alert(title="My alert", severity="medium", connector_type="zeek")
+ summary = _deterministic_summary(
+ alert,
+ mitre_techniques=[],
+ rule_lineage=self._stub_lineage(name=None),
+ fp=self._stub_fp(sample=0),
+ )
+ assert "My alert" in summary
+ assert "medium" in summary
+ assert "zeek" in summary
+
+ def test_includes_rule_name_when_matched(self) -> None:
+ alert = _alert()
+ summary = _deterministic_summary(
+ alert,
+ mitre_techniques=[],
+ rule_lineage=self._stub_lineage(name="Impossible travel"),
+ fp=self._stub_fp(sample=0),
+ )
+ assert "Impossible travel" in summary
+
+ def test_omits_fp_blurb_below_sample_threshold(self) -> None:
+ # Sample < 10 → no FP sentence (statistically unreliable).
+ alert = _alert()
+ summary = _deterministic_summary(
+ alert,
+ mitre_techniques=[],
+ rule_lineage=self._stub_lineage(name=None),
+ fp=self._stub_fp(sample=5, rate=0.4),
+ )
+ assert "false positive" not in summary.lower()
+
+ def test_includes_fp_blurb_above_sample_threshold(self) -> None:
+ alert = _alert()
+ summary = _deterministic_summary(
+ alert,
+ mitre_techniques=[],
+ rule_lineage=self._stub_lineage(name=None),
+ fp=self._stub_fp(sample=50, rate=0.3),
+ )
+ assert "false positive" in summary.lower()
+ # 30% as a percentage with one decimal.
+ assert "30.0%" in summary
+
+ def test_truncates_long_descriptions(self) -> None:
+ # Description cap is 240 chars to keep summaries tight.
+ long_desc = "x" * 500
+ alert = _alert(description=long_desc)
+ summary = _deterministic_summary(
+ alert,
+ mitre_techniques=[],
+ rule_lineage=self._stub_lineage(name=None),
+ fp=self._stub_fp(sample=0),
+ )
+ assert "…" in summary
+
+
+# ---------------------------------------------------------------------------
+# generate_alert_explanation — top-level orchestrator
+# ---------------------------------------------------------------------------
+
+
+def _llm_config_disabled(*, reason: str = "no_key") -> LlmConfig:
+ return LlmConfig(
+ allowed=False,
+ base_url="https://api.openai.com",
+ model="gpt-4o-mini",
+ api_key=None,
+ source="none",
+ reason=reason,
+ )
+
+
+def _llm_config_allowed() -> LlmConfig:
+ return LlmConfig(
+ allowed=True,
+ base_url="https://api.openai.com",
+ model="gpt-4o-mini",
+ api_key="sk-test-key-not-real",
+ source="environment",
+ reason="",
+ )
+
+
+class TestGenerateAlertExplanation:
+ """Top-level orchestration: rule lineage + FPR + LLM + cost.
+
+ We patch the resolver, the LLM client, and the cost recorder so
+ each branch is observable. The DB mock satisfies the lineage and
+ FPR queries (no rule found, zero-sample FPR — minimum useful
+ fixture).
+ """
+
+ @pytest.mark.asyncio
+ async def test_returns_deterministic_summary_when_llm_disabled(self) -> None:
+ # When the resolver vetoes (no key, air-gap, etc.) we must
+ # return a useful explanation built entirely from the corpus.
+ # The endpoint should NEVER fail-closed because the LLM is off.
+ alert = _alert(category="identity", mitre_techniques=["T1078"])
+
+ db = MagicMock()
+ # No explicit rule → falls through to candidate scan returning
+ # no candidates → no rule. FPR query returns zero sample.
+ db.execute = AsyncMock(
+ side_effect=[
+ _scalars_all_result([]), # candidate scan (no explicit id probe needed)
+ _row_one_result(total=0, fps=0), # FPR query
+ ]
+ )
+
+ with patch(
+ "app.services.alert_explain.resolve_llm_config",
+ new=AsyncMock(return_value=_llm_config_disabled(reason="no_key")),
+ ):
+ explanation = await generate_alert_explanation(db, alert=alert)
+
+ assert isinstance(explanation, AlertExplanation)
+ assert explanation.llm_used is False
+ assert explanation.llm_reason == "no_key"
+ # Deterministic summary is always non-empty.
+ assert explanation.summary
+ assert explanation.alert_id == str(alert.id)
+ # Rule lineage falls back to "none" with no candidates.
+ assert explanation.rule_lineage.confidence == "none"
+
+ @pytest.mark.asyncio
+ async def test_uses_llm_summary_when_call_succeeds(self) -> None:
+ # Happy path: resolver allows, LLM returns text, cost is booked.
+ alert = _alert(category="identity", mitre_techniques=["T1078"])
+
+ db = MagicMock()
+ db.execute = AsyncMock(
+ side_effect=[
+ _scalars_all_result([]), # no candidate rules
+ _row_one_result(total=0, fps=0), # FPR
+ MagicMock(), # cost upsert
+ ]
+ )
+
+ from app.services.alert_explain import _LlmCallResult
+
+ canned_call = _LlmCallResult(
+ text="LLM-written prose explanation.",
+ model="gpt-4o-mini",
+ prompt_tokens=300,
+ completion_tokens=120,
+ latency_ms=842.0,
+ error=None,
+ )
+
+ with (
+ patch(
+ "app.services.alert_explain.resolve_llm_config",
+ new=AsyncMock(return_value=_llm_config_allowed()),
+ ),
+ patch(
+ "app.services.alert_explain._call_llm_for_summary",
+ new=AsyncMock(return_value=canned_call),
+ ),
+ ):
+ explanation = await generate_alert_explanation(db, alert=alert)
+
+ assert explanation.llm_used is True
+ assert explanation.llm_reason == ""
+ assert explanation.summary == "LLM-written prose explanation."
+ # Cost upsert must have been issued (the third execute call).
+ assert db.execute.await_count == 3
+
+ @pytest.mark.asyncio
+ async def test_falls_back_to_deterministic_on_empty_llm(self) -> None:
+ # LLM allowed but returned an empty/error response → we keep
+ # the deterministic summary and surface the failure reason.
+ alert = _alert(category="identity")
+
+ db = MagicMock()
+ db.execute = AsyncMock(
+ side_effect=[
+ _scalars_all_result([]),
+ _row_one_result(total=0, fps=0),
+ ]
+ )
+
+ from app.services.alert_explain import _LlmCallResult
+
+ empty_call = _LlmCallResult(
+ text=None,
+ model="gpt-4o-mini",
+ prompt_tokens=0,
+ completion_tokens=0,
+ latency_ms=12.0,
+ error="upstream_503",
+ )
+
+ with (
+ patch(
+ "app.services.alert_explain.resolve_llm_config",
+ new=AsyncMock(return_value=_llm_config_allowed()),
+ ),
+ patch(
+ "app.services.alert_explain._call_llm_for_summary",
+ new=AsyncMock(return_value=empty_call),
+ ),
+ ):
+ explanation = await generate_alert_explanation(db, alert=alert)
+
+ assert explanation.llm_used is False
+ assert explanation.llm_reason == "upstream_503"
+ # The deterministic summary still carries the alert title.
+ assert alert.title in explanation.summary
+
+ @pytest.mark.asyncio
+ async def test_swallows_cost_recording_failures(self) -> None:
+ # Cost-tracking outage must NOT corrupt the explain response.
+ # The dashboard will simply miss this row.
+ alert = _alert(category="identity")
+
+ db = MagicMock()
+ db.execute = AsyncMock(
+ side_effect=[
+ _scalars_all_result([]),
+ _row_one_result(total=0, fps=0),
+ RuntimeError("aisoc_run_costs unavailable"),
+ ]
+ )
+
+ from app.services.alert_explain import _LlmCallResult
+
+ canned_call = _LlmCallResult(
+ text="Summary text.",
+ model="gpt-4o-mini",
+ prompt_tokens=100,
+ completion_tokens=50,
+ latency_ms=300.0,
+ error=None,
+ )
+
+ with (
+ patch(
+ "app.services.alert_explain.resolve_llm_config",
+ new=AsyncMock(return_value=_llm_config_allowed()),
+ ),
+ patch(
+ "app.services.alert_explain._call_llm_for_summary",
+ new=AsyncMock(return_value=canned_call),
+ ),
+ ):
+ # Must NOT raise even though the cost upsert blew up.
+ explanation = await generate_alert_explanation(db, alert=alert)
+
+ assert explanation.llm_used is True
+ assert explanation.summary == "Summary text."
+
+
+# ---------------------------------------------------------------------------
+# _explanation_to_payload — dataclass → dict round-trip
+# ---------------------------------------------------------------------------
+
+
+def _stub_explanation() -> AlertExplanation:
+ """Build a minimal but realistic AlertExplanation for serialisation tests."""
+ return AlertExplanation(
+ alert_id=str(uuid.uuid4()),
+ summary="Test summary.",
+ rule_lineage=RuleLineage(
+ rule_id="rid",
+ rule_name="Test rule",
+ rule_description="desc",
+ rule_status="enabled",
+ rule_severity="high",
+ rule_confidence=80,
+ rule_language="sigma",
+ is_builtin=True,
+ confidence="high",
+ match_method="raw_event",
+ ),
+ contributing_events=[
+ ContributingEvent(label="Severity", value="high", annotation=""),
+ ],
+ mitre_techniques=[
+ MitreTechnique(
+ id="T1078",
+ name="Valid Accounts",
+ tactic_names=["Initial Access"],
+ description="desc",
+ url="https://attack.mitre.org/techniques/T1078/",
+ ),
+ ],
+ historical_fp_rate=HistoricalFpRate(
+ fp_rate=0.1,
+ sample_size=50,
+ false_positives=5,
+ lookback_days=90,
+ scope="rule",
+ notes="ok",
+ ),
+ suggested_actions=[
+ SuggestedAction(
+ title="Look here",
+ rationale="Because.",
+ playbook_id=None,
+ priority="fyi",
+ ),
+ ],
+ llm_used=False,
+ llm_source="none",
+ llm_reason="no_key",
+ generated_at="2026-05-12T00:00:00+00:00",
+ )
+
+
+class TestExplanationToPayload:
+ """``asdict`` round-trip — JSON-serialisable, deeply nested."""
+
+ def test_returns_dict_with_top_level_keys(self) -> None:
+ payload = _explanation_to_payload(_stub_explanation())
+ assert set(payload.keys()) >= {
+ "alert_id",
+ "summary",
+ "rule_lineage",
+ "contributing_events",
+ "mitre_techniques",
+ "historical_fp_rate",
+ "suggested_actions",
+ "llm_used",
+ "llm_source",
+ "llm_reason",
+ "generated_at",
+ }
+
+ def test_nested_dataclasses_become_dicts(self) -> None:
+ payload = _explanation_to_payload(_stub_explanation())
+ # The drawer indexes into rule_lineage by key — fail loudly
+ # if asdict ever produces a tuple or named-tuple instead.
+ assert isinstance(payload["rule_lineage"], dict)
+ assert payload["rule_lineage"]["rule_name"] == "Test rule"
+ assert isinstance(payload["mitre_techniques"], list)
+ assert payload["mitre_techniques"][0]["id"] == "T1078"
+
+ def test_payload_is_json_serialisable(self) -> None:
+ # Realistic safety check: the endpoint returns the payload
+ # straight to FastAPI which json-encodes it. Anything not
+ # JSON-clean would 500 the request.
+ import json
+
+ payload = _explanation_to_payload(_stub_explanation())
+ round_tripped = json.loads(json.dumps(payload))
+ assert round_tripped["alert_id"] == payload["alert_id"]
+
+
+# ---------------------------------------------------------------------------
+# _acquire_or_429 — endpoint rate-limit shim
+# ---------------------------------------------------------------------------
+
+
+class TestAcquireOr429:
+ """Mirrors test_lake_endpoint patterns for the explain rate-limit shim."""
+
+ @pytest.mark.asyncio
+ async def test_allowed_path_stamps_headers_no_retry_after(self) -> None:
+ decision = ExplainRateLimitDecision(
+ allowed=True,
+ remaining=15.0,
+ capacity=20.0,
+ retry_after_seconds=0.0,
+ )
+ limiter = MagicMock()
+ limiter.acquire = AsyncMock(return_value=decision)
+
+ response = Response()
+ tenant_id = uuid.uuid4()
+
+ with patch(
+ "app.api.v1.endpoints.alert_explain.get_explain_rate_limiter",
+ return_value=limiter,
+ ):
+ await _acquire_or_429(response=response, tenant_id=tenant_id, cost=1.0)
+
+ limiter.acquire.assert_awaited_once_with(tenant_id, cost=1.0)
+ assert response.headers["X-RateLimit-Limit"] == "20"
+ assert response.headers["X-RateLimit-Remaining"] == "15"
+ # The allowed path must NOT advertise Retry-After.
+ assert "retry-after" not in {k.lower() for k in response.headers.keys()}
+
+ @pytest.mark.asyncio
+ async def test_denied_raises_429_with_headers_on_exception(self) -> None:
+ decision = ExplainRateLimitDecision(
+ allowed=False,
+ remaining=0.0,
+ capacity=20.0,
+ retry_after_seconds=4.7,
+ )
+ limiter = MagicMock()
+ limiter.acquire = AsyncMock(return_value=decision)
+
+ response = Response()
+ tenant_id = uuid.uuid4()
+
+ with patch(
+ "app.api.v1.endpoints.alert_explain.get_explain_rate_limiter",
+ return_value=limiter,
+ ):
+ with pytest.raises(HTTPException) as exc_info:
+ await _acquire_or_429(
+ response=response,
+ tenant_id=tenant_id,
+ cost=1.0,
+ )
+
+ exc = exc_info.value
+ assert exc.status_code == 429
+ # Belt-and-braces: headers go on BOTH the response and the
+ # exception so middleware that strips error headers still sees
+ # the rate-limit info on the live response object.
+ assert exc.headers["Retry-After"] == "5" # 4.7 → ceil → 5
+ assert exc.headers["X-RateLimit-Limit"] == "20"
+ assert response.headers["X-RateLimit-Limit"] == "20"
+ assert response.headers["Retry-After"] == "5"
+
+
+# ---------------------------------------------------------------------------
+# ExplainRateLimiter — token-bucket math (mirrors test_lake_rate_limit)
+# ---------------------------------------------------------------------------
+
+
+async def _seed_explain_bucket(
+ limiter: ExplainRateLimiter,
+ tenant: str | uuid.UUID,
+ *,
+ at_time: float,
+) -> None:
+ """Force-create a tenant's bucket with a known last_refill time.
+
+ Mirrors the helper in ``test_lake_rate_limit.py``. We cannot patch
+ ``time.monotonic`` *before* the bucket is constructed (that would
+ require patching for the entire process) so we patch around the
+ creation step explicitly.
+ """
+ with patch("app.services.explain_rate_limit.time.monotonic", return_value=at_time):
+ bucket = await limiter._get_bucket(str(tenant))
+ bucket.last_refill = at_time
+
+
+class TestExplainRateLimiterMath:
+ """Token-bucket invariants for the explain limiter."""
+
+ @pytest.mark.asyncio
+ async def test_first_request_allowed(self) -> None:
+ # Bucket starts full → first acquire MUST succeed instantly.
+ limiter = ExplainRateLimiter(capacity=20, refill_per_second=0.2)
+ tid = uuid.uuid4()
+ await _seed_explain_bucket(limiter, tid, at_time=1000.0)
+
+ with patch("app.services.explain_rate_limit.time.monotonic", return_value=1000.0):
+ decision = await limiter.acquire(tid, cost=1.0)
+
+ assert decision.allowed is True
+ # 20 - 1 = 19 remaining.
+ assert decision.remaining == pytest.approx(19.0)
+ assert decision.capacity == 20.0
+ assert decision.retry_after_seconds == 0.0
+
+ @pytest.mark.asyncio
+ async def test_capacity_exhaustion_blocks_with_retry_after(self) -> None:
+ # Exhaust the bucket; next acquire must be rejected with a
+ # non-zero retry-after computed from the configured refill.
+ limiter = ExplainRateLimiter(capacity=3, refill_per_second=0.5)
+ tid = uuid.uuid4()
+ await _seed_explain_bucket(limiter, tid, at_time=2000.0)
+
+ with patch("app.services.explain_rate_limit.time.monotonic", return_value=2000.0):
+ for _ in range(3):
+ allowed = await limiter.acquire(tid, cost=1.0)
+ assert allowed.allowed is True
+
+ denied = await limiter.acquire(tid, cost=1.0)
+
+ assert denied.allowed is False
+ assert denied.remaining == pytest.approx(0.0)
+ # Need 1 token; refill rate is 0.5/sec → 2 seconds to recover.
+ assert denied.retry_after_seconds == pytest.approx(2.0)
+
+ @pytest.mark.asyncio
+ async def test_refill_recovers_capacity(self) -> None:
+ # After enough wall-clock time passes the bucket refills,
+ # subject to the per-second refill rate and the capacity cap.
+ limiter = ExplainRateLimiter(capacity=2, refill_per_second=1.0)
+ tid = uuid.uuid4()
+ await _seed_explain_bucket(limiter, tid, at_time=3000.0)
+
+ # Exhaust the bucket.
+ with patch("app.services.explain_rate_limit.time.monotonic", return_value=3000.0):
+ await limiter.acquire(tid, cost=1.0)
+ await limiter.acquire(tid, cost=1.0)
+ denied = await limiter.acquire(tid, cost=1.0)
+ assert denied.allowed is False
+
+ # Skip 5 seconds → refill (capped at capacity=2).
+ with patch("app.services.explain_rate_limit.time.monotonic", return_value=3005.0):
+ recovered = await limiter.acquire(tid, cost=1.0)
+
+ assert recovered.allowed is True
+ # Refill brings us back up to capacity (2.0), then we charge
+ # 1, so 1.0 token remains.
+ assert recovered.remaining == pytest.approx(1.0)
+
+ @pytest.mark.asyncio
+ async def test_per_tenant_isolation(self) -> None:
+ # One tenant draining their bucket must NOT throttle another.
+ limiter = ExplainRateLimiter(capacity=2, refill_per_second=0.1)
+ loud = uuid.uuid4()
+ quiet = uuid.uuid4()
+ await _seed_explain_bucket(limiter, loud, at_time=4000.0)
+ await _seed_explain_bucket(limiter, quiet, at_time=4000.0)
+
+ with patch("app.services.explain_rate_limit.time.monotonic", return_value=4000.0):
+ await limiter.acquire(loud, cost=1.0)
+ await limiter.acquire(loud, cost=1.0)
+ loud_denied = await limiter.acquire(loud, cost=1.0)
+ quiet_allowed = await limiter.acquire(quiet, cost=1.0)
+
+ assert loud_denied.allowed is False
+ assert quiet_allowed.allowed is True
+
+ @pytest.mark.asyncio
+ async def test_cost_above_capacity_raises(self) -> None:
+ # A cost greater than capacity could never succeed; surface
+ # the bug at the call site rather than waiting forever.
+ limiter = ExplainRateLimiter(capacity=5, refill_per_second=1.0)
+ with pytest.raises(ValueError):
+ await limiter.acquire(uuid.uuid4(), cost=10.0)
+
+ @pytest.mark.asyncio
+ async def test_negative_cost_raises(self) -> None:
+ limiter = ExplainRateLimiter(capacity=5, refill_per_second=1.0)
+ with pytest.raises(ValueError):
+ await limiter.acquire(uuid.uuid4(), cost=0.0)
+
+ @pytest.mark.asyncio
+ async def test_invalid_construction_raises(self) -> None:
+ # Defensive: a misconfigured env override (refill=0) would
+ # silently neuter the limiter; we'd rather crash on import.
+ with pytest.raises(ValueError):
+ ExplainRateLimiter(capacity=0, refill_per_second=0.1)
+ with pytest.raises(ValueError):
+ ExplainRateLimiter(capacity=10, refill_per_second=0)
+
+
+class TestExplainRateLimitDecisionHeaders:
+ """``ExplainRateLimitDecision.to_headers`` is what stamps responses."""
+
+ def test_allowed_omits_retry_after(self) -> None:
+ decision = ExplainRateLimitDecision(
+ allowed=True,
+ remaining=10.0,
+ capacity=20.0,
+ retry_after_seconds=0.0,
+ )
+ headers = decision.to_headers()
+ assert headers["X-RateLimit-Limit"] == "20"
+ assert headers["X-RateLimit-Remaining"] == "10"
+ assert "Retry-After" not in headers
+
+ def test_denied_includes_ceiled_retry_after(self) -> None:
+ # 1.2s → must round UP to 2 (RFC 7231 §7.1.3 wants integer
+ # seconds, and rounding down would tell clients to retry too
+ # early and double-trip the limiter).
+ decision = ExplainRateLimitDecision(
+ allowed=False,
+ remaining=0.0,
+ capacity=20.0,
+ retry_after_seconds=1.2,
+ )
+ headers = decision.to_headers()
+ assert headers["Retry-After"] == "2"
+
+ def test_denied_minimum_retry_after_is_one(self) -> None:
+ # Even a sub-second retry must surface as "1" so polite
+ # clients back off at least one tick.
+ decision = ExplainRateLimitDecision(
+ allowed=False,
+ remaining=0.0,
+ capacity=20.0,
+ retry_after_seconds=0.05,
+ )
+ headers = decision.to_headers()
+ assert headers["Retry-After"] == "1"
+
+ def test_remaining_clamps_to_non_negative_int(self) -> None:
+ # Float arithmetic can briefly go slightly negative around
+ # contention. Headers must be stable integers, not "-0".
+ decision = ExplainRateLimitDecision(
+ allowed=False,
+ remaining=-0.0001,
+ capacity=20.0,
+ retry_after_seconds=1.0,
+ )
+ headers = decision.to_headers()
+ assert headers["X-RateLimit-Remaining"] == "0"