Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(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.tsxindex 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.tsxindex 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({<DrawerHeaderalert={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 && (<NextStepsSectionsteps={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.tsindex 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.yamlindex 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.pynew file mode 100644index 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.pyindex 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 APIRouterfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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_limiterdiff --git a/services/api/app/services/llm_resolver.py b/services/api/app/services/llm_resolver.pynew file mode 100644index 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.pynew file mode 100644index 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"