Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

fix(metrics): count open work, score what the agent says, and reconcile case status (#1124)

Beenu Aroraf08b859eafa4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 480a2f0d8..bf916e60f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -63,6 +63,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
daemon configuration, and on Apple Silicon says plainly that no amount of
installing will help and points at `make up-host-llm` instead.
+- **Reopening a closed case**, as its own route rather than a backward edge
+ in the transition table. The forward-only machine is what makes "this case
+ was closed" mean something, and `closed -> investigating` in `TRANSITIONS`
+ would let an ordinary `PATCH` walk a case backwards silently. A reason is
+ required, `reopen_count` increments, and `closed_at`/`resolved_at` are
+ cleared so the case is not terminal and active at once.
+
+ Migration `090` adds the columns **first**: the handed-over version wrote
+ `reopened_at` without creating it, so every call raised
+ `UndefinedColumnError` -- reproduced here by dropping the columns and
+ watching the suite fail the same way.
+
+- **Investigations now reason over the real alerts.** The console sent the
+ literal string `"Investigate alert: <title>"`, `InvestigateRequest` carried
+ only a summary, and the case's `alert_ids` were written and read by
+ nothing -- while auto-triage, the same agent through the other entry point,
+ correctly passed the whole `raw_event`. The receiver was always ready:
+ `InvestigationRequest` has declared `raw_alert` since it was written.
+
+ The API assembles the evidence server-side, so the Slack path gets it too
+ without Slack knowing anything about alerts.
+
+- **The groundedness gate now covers the investigator**, not just background
+ auto-triage. It could not simply be copied: it scores against `raw_alert`,
+ and with that empty every cited indicator reads as unsupported, so the gate
+ would have demoted everything while looking like it was catching
+ hallucination. It now **refuses to score an empty evidence set** and
+ reports `groundedness: null` -- distinct from `0.0`, which means it ran.
+ On the investigator path the intervention is a lowered confidence plus a
+ caveat naming the unsupported indicators, since nothing auto-closes there.
+
### Fixed
- **`make doctor` told operators to stop their own Ollama.** `11434` is in the
@@ -79,6 +110,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`enforce_airgap_for_url`, the same function every other outbound call uses,
which reads the flag at call time.
+- **Every approval 502'd.** `approvals.py` built its principal from
+ `user.roles` and `user.permissions`; `CurrentUser` defines neither, so both
+ `getattr` defaults fired silently, the actions service received an empty
+ permission list, and `has_action_permission` denies unconditionally on one.
+ The approval row recorded the decision and the action never ran.
+
+ Resolution now lives on `CurrentUser.effective_permissions()`, using the
+ same `scopes -> resolved_permissions -> role` order as `require_permission`
+ so one principal cannot be allowed to approve something it would be refused
+ for elsewhere. The test double was shaped around the bug -- a
+ `SimpleNamespace` carrying exactly the two attributes the real class lacks
+ -- and is now a real `CurrentUser`.
+
+- **Alert tiles counted the historical backlog as active work.** No status
+ predicate at all, under labels reading "Active Alerts" and "Critical —
+ Require immediate action", so a tenant who had resolved everything saw
+ their whole intake as outstanding and the number only ever rose. Four other
+ sites already had the right filter; all of them now read
+ `app.services.alert_status`. The same omission appears again in GraphQL,
+ beside a case count on `["open", "in_progress"]` -- neither of which the
+ vocabulary contains, making that figure structurally zero.
+
+- **Period deltas were double-scaled.** `_pct_delta` returns a percentage and
+ the renderer multiplied by 100 again, so a drop from 160 to 10 events
+ rendered as **-9375%**. The test beside it fed fraction-shaped data the
+ backend has never emitted, so fixture and defect agreed and passed
+ together.
+
+- **The global time-window selector drove nothing.** `useTimeWindow()` had
+ zero data-fetching consumers: the dashboard's SWR key was a constant string
+ and `period="24h"` was hardcoded into two tiles. `/metrics/dashboard` and
+ `/metrics/soc` now take a period, the keys name the window, and the SOC
+ Insights page's private copy of the state is folded in -- clamping `1h` to
+ `24h` **visibly**, because that endpoint has no 1h window and a silent
+ clamp is a wrong number under a confident label.
+
+- **Four sites used a case vocabulary the database forbids**, and
+ `hunt_scheduler.py` was the one that mattered: an `INSERT` with
+ `status="open"` against a CHECK that rejects it, so a scheduled hunt that
+ fired could not create its case at all. Also the ORM default, the MSSP
+ portfolio tuples and the GraphQL count.
+
+ Fixing those surfaced a **live** wrong vocabulary in the console whose
+ round-trip was destructive: `contained` arrived as `in_progress` and went
+ back as `investigating`, so saving any edit to a contained case silently
+ undid the containment. Six states cannot round-trip through five; the
+ translation maps are gone and the console speaks the backend's vocabulary.
+ `packages/types/src/case.ts` -- a third, entirely dead vocabulary -- is
+ retired.
+
+- **`check_one_case_table` passed while missing all four leaks**, because its
+ regex knew two spellings out of five. Rebuilt on an AST for Python, which
+ is what lets it tell `Case(status="open")` from
+ `PostureFinding(status="open")` -- a regex cannot, and flagging the CSPM
+ model is how a gate gets suppressed. Against the pre-fix tree it names all
+ four sites; the old one reported OK.
+
+- **`/dashboard` returned the wrong shape**, found by `check_route_auth`
+ after the tests missed it: a decorator had attached to a private helper
+ instead of its handler. The suite could not see it because every test
+ called the helper directly, so there are now assertions that read the
+ mounted route out of `app.openapi()`.
+
+
### Security
- **A revoked session kept the graph WebSocket open** ([GHSA-25fh-rxp8-67j8]).
diff --git a/apps/web/src/app/(responder)/responder/case/[caseId]/page.tsx b/apps/web/src/app/(responder)/responder/case/[caseId]/page.tsx
index 1bd680f3c..ebcc76972 100644
--- a/apps/web/src/app/(responder)/responder/case/[caseId]/page.tsx
+++ b/apps/web/src/app/(responder)/responder/case/[caseId]/page.tsx
@@ -93,7 +93,10 @@ export default function ResponderCaseDetailPage() {
const updates: Partial<Case> = { status };
// Claim the case if we're moving it to "active" and nobody owns it.
if (
- status === 'in_progress' &&
+ // `investigating`, which is what "Active" means in the canonical
+ // vocabulary. `in_progress` is not a state `aisoc_cases` accepts,
+ // so this button's PATCH was refused on every press.
+ status === 'investigating' &&
!caseRecord?.assignee &&
profile?.email
) {
@@ -273,8 +276,8 @@ export default function ResponderCaseDetailPage() {
<ActionButton
label="Active"
busy={busyAction === 'Active'}
- disabled={caseRecord.status === 'in_progress'}
- onClick={() => void updateStatus('in_progress', 'Active')}
+ disabled={caseRecord.status === 'investigating'}
+ onClick={() => void updateStatus('investigating', 'Active')}
icon={
<svg
className="w-5 h-5"
diff --git a/apps/web/src/components/alerts/AlertDetailView.tsx b/apps/web/src/components/alerts/AlertDetailView.tsx
index e6c1d2ceb..039fb7930 100644
--- a/apps/web/src/components/alerts/AlertDetailView.tsx
+++ b/apps/web/src/components/alerts/AlertDetailView.tsx
@@ -384,13 +384,19 @@ function AIInvestigation({ alertId, alertTitle }: { alertId: string; alertTitle?
setIsRunning(true);
setError(null);
try {
- const summary = alertTitle ? `Investigate alert: ${alertTitle}` : 'Investigate alert';
+ // `alertIds` is the part that matters. The API reads it to load the
+ // alerts' real `raw_event` payloads and sends those to the agent as
+ // `raw_alert`; it used to forward only the string below, so the
+ // forensic agent reasoned over a restated headline while auto-triage --
+ // the same agent, the other entry point -- got the whole event.
const createdCase = await casesApi.create({
title: alertTitle ? `Investigation — ${alertTitle}` : `Investigation — alert ${alertId}`,
- description: summary,
+ description: alertTitle ? `Opened from alert: ${alertTitle}` : `Opened from alert ${alertId}`,
alertIds: [alertId],
});
- await casesApi.investigate(createdCase.id, summary);
+ // A note about *why*, not a substitute for the evidence. The API
+ // prepends this to what it assembled rather than using it instead.
+ await casesApi.investigate(createdCase.id, 'Opened from the alert detail view by an analyst.');
router.push(`/cases/${createdCase.id}?tab=ledger`);
} catch (err) {
setError(
diff --git a/apps/web/src/components/cases/CaseWorkspace.test.tsx b/apps/web/src/components/cases/CaseWorkspace.test.tsx
index 0ffa98497..22f992634 100644
--- a/apps/web/src/components/cases/CaseWorkspace.test.tsx
+++ b/apps/web/src/components/cases/CaseWorkspace.test.tsx
@@ -109,7 +109,7 @@ const fakeCase: Case = {
id: 'INC-001',
title: 'Suspected lateral movement from finance subnet',
description: 'Multiple high-severity alerts indicate a pivot via SMB.',
- status: 'in_progress',
+ status: 'investigating',
severity: 'critical',
assignee: '[email protected]',
tags: ['lateral-movement'],
diff --git a/apps/web/src/components/cases/CaseWorkspace.tsx b/apps/web/src/components/cases/CaseWorkspace.tsx
index 5c13f5be3..46692db62 100644
--- a/apps/web/src/components/cases/CaseWorkspace.tsx
+++ b/apps/web/src/components/cases/CaseWorkspace.tsx
@@ -64,7 +64,7 @@ function buildDemoCase(id: string): Case {
"Multiple high-severity alerts indicate an attacker pivoted from " +
"WIN-FIN-DB01 to BACKUP-SRV-12 using compromised service account credentials. " +
"Behavior consistent with T1021.002 (SMB/Windows Admin Shares).",
- status: 'in_progress',
+ status: 'investigating',
severity: 'critical',
assignee: '[email protected]',
alertIds: ['alert-9012', 'alert-9013', 'alert-9019', 'alert-9024'],
@@ -153,18 +153,26 @@ const SEVERITY_BADGE: Record<CaseSeverity, string> = {
low: 'bg-blue-500/15 text-blue-300 ring-blue-500/30',
};
+// Keyed on the six states the database actually permits. These used to name
+// `open`, `in_progress` and `pending` -- none of which `aisoc_cases` allows --
+// and omit `new`, `triaged`, `investigating` and `contained`, which is where a
+// case spends nearly all of its life. A real case rendered `undefined` as its
+// label and had no dot colour, while `Record<CaseStatus, …>` called the maps
+// exhaustive because the union was wrong in the same direction.
const STATUS_LABEL: Record<CaseStatus, string> = {
- open: 'Open',
- in_progress: 'In progress',
- pending: 'Pending',
+ new: 'New',
+ triaged: 'Triaged',
+ investigating: 'Investigating',
+ contained: 'Contained',
resolved: 'Resolved',
closed: 'Closed',
};
const STATUS_DOT: Record<CaseStatus, string> = {
- open: 'bg-slate-400',
- in_progress: 'bg-blue-400 animate-pulse',
- pending: 'bg-amber-400',
+ new: 'bg-slate-400',
+ triaged: 'bg-sky-400',
+ investigating: 'bg-blue-400 animate-pulse',
+ contained: 'bg-amber-400',
resolved: 'bg-emerald-400',
closed: 'bg-slate-600',
};
@@ -693,7 +701,21 @@ export function CaseWorkspace({ caseId }: { caseId: string }) {
disabled={statusUpdating}
className="rounded-md border border-slate-700/70 bg-slate-900/60 px-2 py-1.5 text-xs text-slate-200 focus:border-emerald-500/40 focus:outline-none"
>
- {(['open', 'in_progress', 'pending', 'resolved', 'closed'] as CaseStatus[]).map(
+ {/*
+ The three it used to offer -- open, in_progress, pending --
+ are refused by the API, so every status change from this
+ control failed validation.
+ */}
+ {(
+ [
+ 'new',
+ 'triaged',
+ 'investigating',
+ 'contained',
+ 'resolved',
+ 'closed',
+ ] as CaseStatus[]
+ ).map(
(s) => (
<option key={s} value={s}>
{STATUS_LABEL[s]}
diff --git a/apps/web/src/components/cases/CaseWorkspaceHonesty.test.tsx b/apps/web/src/components/cases/CaseWorkspaceHonesty.test.tsx
index 355057ab4..5f0d10ab7 100644
--- a/apps/web/src/components/cases/CaseWorkspaceHonesty.test.tsx
+++ b/apps/web/src/components/cases/CaseWorkspaceHonesty.test.tsx
@@ -142,7 +142,7 @@ function realCase(overrides: Partial<Case> = {}): Case {
id: CASE_ID,
title: 'Unusual sign-in from an unrecognised ASN',
description: 'One failed conditional-access challenge followed by a success.',
- status: 'open',
+ status: 'new',
severity: 'medium',
alertIds: [],
alertCount: 0,
@@ -249,7 +249,7 @@ describe('a failed investigation is not reported as a completed one', () => {
describe('a rejected status write does not stick in the UI', () => {
it('rolls the optimistic mutation back when the API refuses it', async () => {
- swrData.set(SWR_KEY, realCase({ status: 'open' }));
+ swrData.set(SWR_KEY, realCase({ status: 'new' }));
casesApi.update.mockRejectedValue(new Error('403 Forbidden'));
render(<CaseWorkspace caseId={CASE_ID} />);
@@ -264,12 +264,12 @@ describe('a rejected status write does not stick in the UI', () => {
// sat on `resolved` for a case the database still had as `open`.
await waitFor(() => {
const restored = swrMutate.mock.calls.at(-1)?.[0] as Case | undefined;
- expect(restored?.status, 'the rejected write must be rolled back').toBe('open');
+ expect(restored?.status, 'the rejected write must be rolled back').toBe('new');
});
});
it('keeps the write when the API accepts it', async () => {
- swrData.set(SWR_KEY, realCase({ status: 'open' }));
+ swrData.set(SWR_KEY, realCase({ status: 'new' }));
casesApi.update.mockResolvedValue(realCase({ status: 'resolved' }));
render(<CaseWorkspace caseId={CASE_ID} />);
diff --git a/apps/web/src/components/cases/CasesView.tsx b/apps/web/src/components/cases/CasesView.tsx
index 769e74cab..311325431 100644
--- a/apps/web/src/components/cases/CasesView.tsx
+++ b/apps/web/src/components/cases/CasesView.tsx
@@ -57,13 +57,19 @@ const SEVERITY_CONFIG = {
low: { label: 'Low', className: 'text-blue-400 bg-blue-500/10 border-blue-500/20' },
};
+// Keyed on the six states `aisoc_cases` permits. It used to name `open`,
+// `in_progress` and `pending` -- all refused by the table's CHECK -- and omit
+// the four a case actually passes through, so every real row fell through to
+// the `?? STATUS_CONFIG.open` fallback below and the list showed every case
+// as "Open" whatever it was.
const STATUS_CONFIG: Record<
Case['status'],
{ label: string; className: string; dot: string }
> = {
- open: { label: 'Open', className: 'text-gray-300 bg-gray-700/50 border-gray-600/50', dot: 'bg-gray-400' },
- in_progress: { label: 'In Progress', className: 'text-blue-300 bg-blue-500/10 border-blue-500/20', dot: 'bg-blue-400 animate-pulse' },
- pending: { label: 'Pending', className: 'text-amber-300 bg-amber-500/10 border-amber-500/20', dot: 'bg-amber-400' },
+ new: { label: 'New', className: 'text-gray-300 bg-gray-700/50 border-gray-600/50', dot: 'bg-gray-400' },
+ triaged: { label: 'Triaged', className: 'text-sky-300 bg-sky-500/10 border-sky-500/20', dot: 'bg-sky-400' },
+ investigating: { label: 'Investigating', className: 'text-blue-300 bg-blue-500/10 border-blue-500/20', dot: 'bg-blue-400 animate-pulse' },
+ contained: { label: 'Contained', className: 'text-amber-300 bg-amber-500/10 border-amber-500/20', dot: 'bg-amber-400' },
resolved: { label: 'Resolved', className: 'text-green-300 bg-green-500/10 border-green-500/20', dot: 'bg-green-400' },
closed: { label: 'Closed', className: 'text-gray-500 bg-gray-800/50 border-gray-700/50', dot: 'bg-gray-600' },
};
@@ -74,7 +80,7 @@ function CaseCard({ c }: { c: Case }) {
const sev = SEVERITY_CONFIG[c.severity] ?? SEVERITY_CONFIG.medium;
// Defensive: if normalization missed an unexpected status string, fall back
// to "open" styling so the entire list never blanks the page.
- const sts = STATUS_CONFIG[c.status] ?? STATUS_CONFIG.open;
+ const sts = STATUS_CONFIG[c.status] ?? STATUS_CONFIG.new;
const displayId = c.caseNumber ?? `${c.id ?? ''}`.slice(-6);
const detailHref = `/cases/${encodeURIComponent(c.caseNumber ?? c.id)}`;
@@ -182,11 +188,11 @@ export function CasesView() {
// zeros rendered on first paint and stayed there when the read failed.
const countsUnknown = !casesData;
const statCounts: Record<string, number | null> = countsUnknown
- ? { all: null, open: null, in_progress: null, resolved: null, closed: null }
+ ? { all: null, new: null, investigating: null, resolved: null, closed: null }
: {
all: allCases.length,
- open: allCases.filter(c => c.status === 'open').length,
- in_progress: allCases.filter(c => c.status === 'in_progress').length,
+ new: allCases.filter(c => c.status === 'new').length,
+ investigating: allCases.filter(c => c.status === 'investigating').length,
resolved: allCases.filter(c => c.status === 'resolved').length,
closed: allCases.filter(c => c.status === 'closed').length,
};
@@ -218,7 +224,14 @@ export function CasesView() {
{/* Stats */}
<div className="grid grid-cols-5 gap-3">
- {(['all', 'open', 'in_progress', 'resolved', 'closed'] as const).map((s) => {
+ {/*
+ Five tabs for a five-column grid, naming states that exist. These
+ were `open` and `in_progress`, which `aisoc_cases` forbids, so both
+ counters read zero on every deployment and neither filter returned
+ anything. `triaged` and `contained` show on each row rather than as
+ their own tab.
+ */}
+ {(['all', 'new', 'investigating', 'resolved', 'closed'] as const).map((s) => {
return (
<button
key={s}
diff --git a/apps/web/src/components/dashboard/DashboardFirstPaint.test.tsx b/apps/web/src/components/dashboard/DashboardFirstPaint.test.tsx
index 353ddda89..480ea6342 100644
--- a/apps/web/src/components/dashboard/DashboardFirstPaint.test.tsx
+++ b/apps/web/src/components/dashboard/DashboardFirstPaint.test.tsx
@@ -18,6 +18,7 @@
* still read as empty.
*/
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { TimeWindowProvider } from '@/components/layout/TimeWindowProvider';
import { cleanup, render, screen } from '@testing-library/react';
import { __setDemoModeForTests } from '@/lib/demoMode';
@@ -28,7 +29,17 @@ const swrLoading = vi.hoisted(() => new Set<string>());
vi.mock('swr', () => ({
__esModule: true,
default: (key: unknown) => {
- const k = typeof key === 'string' ? key : JSON.stringify(key);
+ // An SWR key is now `['dashboard-metrics', timeWindow]` rather than a
+ // bare string, because the window has to be part of the cache key or
+ // every window shares one entry. These fixtures name the resource and
+ // not the window, so resolve an array key by its head -- the tests here
+ // are about what the dashboard *renders*, and threading a window through
+ // each one would obscure that without testing anything.
+ //
+ // That the window reaches the request is a separate assertion, in
+ // DashboardTimeWindow.test.tsx, where it is the subject rather than
+ // incidental setup.
+ const k = typeof key === 'string' ? key : String((key as unknown[])[0]);
return {
data: swrData.get(k),
error: swrErrors.get(k),
@@ -40,6 +51,14 @@ vi.mock('swr', () => ({
vi.mock('@/lib/api', () => ({
__esModule: true,
+ // The dashboard binds to the real `TimeWindowProvider`, which reconciles
+ // the window with the signed-in user's stored preference. An absent export
+ // makes the provider throw during render, which reads as a component
+ // failure rather than a missing mock.
+ authApi: {
+ currentUser: vi.fn(() => null),
+ updateUserPreferences: vi.fn(() => Promise.resolve()),
+ },
metricsApi: {
getDashboard: vi.fn(),
getSOC: vi.fn(),
@@ -99,7 +118,11 @@ describe('the dashboard does not report a result it has not got', () => {
it('claims nothing on first paint, while the request is still in flight', () => {
swrLoading.add('dashboard-metrics');
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
for (const claim of MEASURED_CLAIMS) {
expect(screen.queryByText(claim), `"${claim}" is a measured claim and the request has not landed`).toBeNull();
@@ -112,7 +135,11 @@ describe('the dashboard does not report a result it has not got', () => {
// unmeasured, and the branch a plain `isLoading` check would miss.
swrData.set('dashboard-metrics', { cases: { open: 0, inProgress: 0, resolvedThisWeek: 0 } });
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
for (const claim of MEASURED_CLAIMS) {
expect(screen.queryByText(claim)).toBeNull();
@@ -123,7 +150,11 @@ describe('the dashboard does not report a result it has not got', () => {
it('still shows the failure when the request failed', () => {
swrErrors.set('dashboard-metrics', new Error('503 Service Unavailable'));
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expect(screen.getAllByText(/503 Service Unavailable/i).length).toBeGreaterThan(0);
expect(screen.queryByText(/No alerts in the last 24 hours/i)).toBeNull();
@@ -141,7 +172,11 @@ describe('the dashboard does not report a result it has not got', () => {
threatsBySource: [],
});
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expect(screen.getByText(/No alerts in the last 24 hours/i)).toBeInTheDocument();
expect(screen.queryByText(/Not loaded yet/i)).toBeNull();
diff --git a/apps/web/src/components/dashboard/DashboardHonesty.test.tsx b/apps/web/src/components/dashboard/DashboardHonesty.test.tsx
index 92dca658d..12e9aa63d 100644
--- a/apps/web/src/components/dashboard/DashboardHonesty.test.tsx
+++ b/apps/web/src/components/dashboard/DashboardHonesty.test.tsx
@@ -20,6 +20,7 @@
*/
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { TimeWindowProvider } from '@/components/layout/TimeWindowProvider';
import { cleanup, render, screen } from '@testing-library/react';
import { __setDemoModeForTests } from '@/lib/demoMode';
@@ -29,7 +30,17 @@ const swrErrors = vi.hoisted(() => new Map<string, unknown>());
vi.mock('swr', () => ({
__esModule: true,
default: (key: unknown) => {
- const k = typeof key === 'string' ? key : JSON.stringify(key);
+ // An SWR key is now `['dashboard-metrics', timeWindow]` rather than a
+ // bare string, because the window has to be part of the cache key or
+ // every window shares one entry. These fixtures name the resource and
+ // not the window, so resolve an array key by its head -- the tests here
+ // are about what the dashboard *renders*, and threading a window through
+ // each one would obscure that without testing anything.
+ //
+ // That the window reaches the request is a separate assertion, in
+ // DashboardTimeWindow.test.tsx, where it is the subject rather than
+ // incidental setup.
+ const k = typeof key === 'string' ? key : String((key as unknown[])[0]);
return {
data: swrData.get(k),
error: swrErrors.get(k),
@@ -41,6 +52,14 @@ vi.mock('swr', () => ({
vi.mock('@/lib/api', () => ({
__esModule: true,
+ // The dashboard binds to the real `TimeWindowProvider`, which reconciles
+ // the window with the signed-in user's stored preference. An absent export
+ // makes the provider throw during render, which reads as a component
+ // failure rather than a missing mock.
+ authApi: {
+ currentUser: vi.fn(() => null),
+ updateUserPreferences: vi.fn(() => Promise.resolve()),
+ },
metricsApi: {
getDashboard: vi.fn(),
getSOC: vi.fn(),
@@ -122,7 +141,11 @@ describe('DashboardView — no fabricated data outside demo mode', () => {
it('renders an error state, not a mock connector inventory, when the metrics API fails', () => {
swrErrors.set('dashboard-metrics', new Error('503 Service Unavailable'));
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expectNoFabrication(FABRICATED_SOURCE_NAMES);
// The failure itself is surfaced rather than swallowed.
@@ -132,7 +155,11 @@ describe('DashboardView — no fabricated data outside demo mode', () => {
it('does not invent a 1247-alert baseline when the API fails', () => {
swrErrors.set('dashboard-metrics', new Error('network down'));
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expect(screen.queryByText('1247')).toBeNull();
expect(screen.queryByText('42m')).toBeNull();
@@ -151,7 +178,11 @@ describe('DashboardView — no fabricated data outside demo mode', () => {
threatsBySource: [],
});
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
// Real numbers still render.
expect(screen.getByText('4')).toBeTruthy();
@@ -171,7 +202,11 @@ describe('DashboardView — no fabricated data outside demo mode', () => {
threatsBySource: [],
});
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
// `/metrics/dashboard` returns no period-over-period comparison, so the
// "+12% vs yesterday" / "-3% vs yesterday" / "-8% vs last week" literals
@@ -358,7 +393,11 @@ describe('a mean over no samples is unmeasured, not zero', () => {
threatsBySource: [],
});
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expect(screen.getByText('1.5h')).toBeTruthy();
expect(screen.queryByText('1.5m')).toBeNull();
@@ -374,7 +413,11 @@ describe('a mean over no samples is unmeasured, not zero', () => {
threatsBySource: [],
});
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expect(screen.getByText(/not measured · no cases closed/i)).toBeTruthy();
expect(screen.queryByText('0m')).toBeNull();
@@ -398,7 +441,11 @@ describe('demo mode still populates the dashboards', () => {
threatsBySource: [],
});
- render(<DashboardView />);
+ render(
+ <TimeWindowProvider>
+ <DashboardView />
+ </TimeWindowProvider>,
+ );
expect(screen.getByText('CrowdStrike EDR')).toBeTruthy();
});
diff --git a/apps/web/src/components/dashboard/DashboardTimeWindow.test.tsx b/apps/web/src/components/dashboard/DashboardTimeWindow.test.tsx
new file mode 100644
index 000000000..3a306dcf1
--- /dev/null
+++ b/apps/web/src/components/dashboard/DashboardTimeWindow.test.tsx
@@ -0,0 +1,129 @@
+/**
+ * Changing the time window changes what is fetched.
+ *
+ * The defect
+ * ----------
+ * The console shipped a global time-window selector in the header, with a
+ * provider that persisted the choice to localStorage *and* to the user's
+ * server-side preferences so it roamed between browsers. `useTimeWindow()`
+ * had **zero** data-fetching consumers: the only callers were the selector
+ * itself and its own tests.
+ *
+ * So the control worked perfectly and drove nothing. `DashboardView`'s SWR
+ * key was the constant string `'dashboard-metrics'`, and `period="24h"` was
+ * hardcoded into both `<FunnelKpiBar>` and `<EfficiencyReport>`. A user
+ * switching to 7d got a re-rendered header, an unchanged dashboard, and no
+ * indication that the two disagreed.
+ *
+ * Why the SWR key matters as much as the request
+ * ----------------------------------------------
+ * Passing the window to the fetcher alone would not have been enough: SWR
+ * caches on the key, so a constant key serves one entry for every window.
+ * The fetcher would be called once and its result reused forever. The key has
+ * to name its inputs, which is the assertion below.
+ */
+
+import { render, screen } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const swrCalls = vi.hoisted(() => [] as unknown[]);
+const dashboardCalls = vi.hoisted(() => [] as unknown[]);
+const funnelCalls = vi.hoisted(() => [] as unknown[]);
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: (key: unknown, fetcher?: () => unknown) => {
+ swrCalls.push(key);
+ // Call it so the arguments the component passes are observable. Without
+ // this the key could be right while the request carried a stale window.
+ try {
+ fetcher?.();
+ } catch {
+ /* a stubbed api may throw; the call itself is what is being recorded */
+ }
+ return { data: undefined, error: undefined, isLoading: true, mutate: vi.fn() };
+ },
+}));
+
+vi.mock('@/lib/api', () => ({
+ __esModule: true,
+ metricsApi: {
+ getDashboard: vi.fn((period?: unknown) => {
+ dashboardCalls.push(period);
+ return Promise.resolve({});
+ }),
+ getFunnel: vi.fn((period?: unknown) => {
+ funnelCalls.push(period);
+ return Promise.resolve({});
+ }),
+ getSOC: vi.fn(() => Promise.resolve({})),
+ getAlertTrend: vi.fn(() => Promise.resolve({ data: [] })),
+ getPipelineHealth: vi.fn(() => Promise.resolve({})),
+ },
+ authApi: {
+ currentUser: vi.fn(() => null),
+ updateUserPreferences: vi.fn(() => Promise.resolve()),
+ },
+ connectorsApi: { list: vi.fn(() => Promise.resolve([])) },
+ alertsApi: { list: vi.fn(() => Promise.resolve({ items: [], total: 0 })) },
+}));
+
+vi.mock('@/lib/demoMode', () => ({
+ __esModule: true,
+ isDemoMode: () => false,
+ demoFallback: () => undefined,
+}));
+
+import { TIME_WINDOWS, type TimeWindow } from '@/lib/timeWindow';
+
+import { FunnelKpiBar } from './FunnelKpiBar';
+
+describe('the global time window drives the fetches', () => {
+ beforeEach(() => {
+ swrCalls.length = 0;
+ dashboardCalls.length = 0;
+ funnelCalls.length = 0;
+ window.localStorage.clear();
+ });
+
+ it.each(TIME_WINDOWS)('a %s window reaches the funnel request', (period: TimeWindow) => {
+ render(<FunnelKpiBar period={period} />);
+
+ expect(funnelCalls).toContain(period);
+ });
+
+ it('the funnel SWR key names the window, not just the resource', () => {
+ // A constant key is the half of this bug that survives passing the window
+ // to the fetcher: SWR would serve one cached entry for every window and
+ // the fetcher would run once.
+ render(<FunnelKpiBar period="7d" />);
+
+ const keys = swrCalls.map((k) => JSON.stringify(k));
+ expect(keys.some((k) => k.includes('7d'))).toBe(true);
+ });
+
+ it('two different windows do not share a cache key', () => {
+ render(<FunnelKpiBar period="1h" />);
+ const first = swrCalls.map((k) => JSON.stringify(k));
+ swrCalls.length = 0;
+ render(<FunnelKpiBar period="30d" />);
+ const second = swrCalls.map((k) => JSON.stringify(k));
+
+ expect(first).not.toEqual(second);
+ });
+
+ it('every window the selector offers is one the API accepts', () => {
+ // `_PERIOD_QUERY` server-side is `^(1h|24h|7d|30d)$`. A selector offering
+ // a fifth value would 422 on every tile, and the control would look
+ // broken rather than the contract.
+ expect([...TIME_WINDOWS]).toEqual(['1h', '24h', '7d', '30d']);
+ });
+
+ it('renders without throwing for each window', () => {
+ for (const period of TIME_WINDOWS) {
+ const { unmount } = render(<FunnelKpiBar period={period} />);
+ expect(screen.getAllByText(/Operations Funnel/i).length).toBeGreaterThan(0);
+ unmount();
+ }
+ });
+});
diff --git a/apps/web/src/components/dashboard/DashboardView.tsx b/apps/web/src/components/dashboard/DashboardView.tsx
index a9007a287..33590bcda 100644
--- a/apps/web/src/components/dashboard/DashboardView.tsx
+++ b/apps/web/src/components/dashboard/DashboardView.tsx
@@ -17,6 +17,7 @@
import React, { Component, Suspense, type ErrorInfo, type ReactNode, useState, useEffect, useRef, useCallback } from 'react';
import useSWR from 'swr';
import { metricsApi, type DashboardMetrics } from '@/lib/api';
+import { useTimeWindow } from '@/components/layout/TimeWindowProvider';
import { clsx } from 'clsx';
import dynamic from 'next/dynamic';
import Link from 'next/link';
@@ -455,14 +456,24 @@ function useDashboardLayout() {
// ─── Main Dashboard ───────────────────────────────────────────────────────────
export function DashboardView() {
+ // The global selector in the header. Every fetch below binds to it, so
+ // changing the window actually changes what is shown -- it used to drive
+ // nothing at all.
+ const { window: timeWindow } = useTimeWindow();
+
const {
data: rawMetrics,
error: metricsError,
isLoading: metricsLoading,
mutate: mutateMetrics,
} = useSWR(
- 'dashboard-metrics',
- () => metricsApi.getDashboard(),
+ // The window is part of the key, which is the whole fix: it was the
+ // constant string 'dashboard-metrics', so SWR served one cache entry for
+ // every window and the selector could not have refetched even if it had
+ // asked. A key that does not name its inputs is a cache that cannot
+ // distinguish them.
+ ['dashboard-metrics', timeWindow],
+ () => metricsApi.getDashboard(timeWindow),
{
fallbackData: demoFallback(MOCK_METRICS),
refreshInterval: 60000,
@@ -547,13 +558,13 @@ export function DashboardView() {
// PR-3 / W1: Six-tile funnel KPI strip (events → correlations → alerts +
// signal/noise, MTTD, analyst queue) backed by /api/v1/metrics/funnel.
- 'funnel-kpis': <FunnelKpiBar period="24h" />,
+ 'funnel-kpis': <FunnelKpiBar period={timeWindow} />,
// PR-3 / W1+W9: Efficiency ratios (correlation efficiency, alert yield,
// MITRE coverage) alongside per-stage pipeline health.
'efficiency-and-pipeline': (
<div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
- <EfficiencyReport period="24h" />
+ <EfficiencyReport period={timeWindow} />
<PipelineHealth />
</div>
),
diff --git a/apps/web/src/components/dashboard/FunnelKpiBar.test.tsx b/apps/web/src/components/dashboard/FunnelKpiBar.test.tsx
index 076b70fa0..588ad84d0 100644
--- a/apps/web/src/components/dashboard/FunnelKpiBar.test.tsx
+++ b/apps/web/src/components/dashboard/FunnelKpiBar.test.tsx
@@ -70,13 +70,18 @@ const SAMPLE_FUNNEL = {
correlation_efficiency: 0.48,
alert_yield: 0.034,
mitre_coverage: { covered: 42, total: 201, ratio: 0.209 },
+ // Percentages, which is what `_pct_delta` returns: it multiplies by 100 and
+ // rounds before the value leaves the API. These used to be `0.12`-shaped
+ // fractions the backend has never emitted, and the component multiplied by
+ // 100 a second time -- so fixture and defect agreed, the pair passed, and
+ // the dashboard rendered `-9375%`.
deltas: {
- events_of_interest: 0.12,
- correlation_instances: 0.05,
- alerts_generated: -0.08,
- signal_to_noise: 0.02,
- mttd_seconds: -0.15,
- analyst_queue_depth: 0.2,
+ events_of_interest: 12.0,
+ correlation_instances: 5.0,
+ alerts_generated: -8.0,
+ signal_to_noise: 2.0,
+ mttd_seconds: -15.0,
+ analyst_queue_depth: 20.0,
},
generated_at: '2026-05-13T10:00:00Z',
};
@@ -129,6 +134,35 @@ describe('FunnelKpiBar', () => {
expect(screen.getByText('−8%')).toBeInTheDocument();
});
+ it('renders a large real delta at its true magnitude', () => {
+ // The reproduction, with the numbers the defect was found on: a tenant
+ // whose events-of-interest fell from 160 to 10 gets `_pct_delta` =
+ // -93.75, which rendered as `−9375%`. Four significant figures of
+ // nonsense on the first tile of the dashboard.
+ swrData.set(FUNNEL_KEY, {
+ ...SAMPLE_FUNNEL,
+ deltas: { ...SAMPLE_FUNNEL.deltas, events_of_interest: -93.75 },
+ });
+ render(<FunnelKpiBar period="24h" />);
+
+ expect(screen.getByText('−94%')).toBeInTheDocument();
+ expect(screen.queryByText('−9375%')).not.toBeInTheDocument();
+ });
+
+ it('does not rescale a small delta that happens to look like a fraction', () => {
+ // Scale comes from the contract, never the magnitude. A real +1% delta
+ // and a fraction of 1.0 are the same number, so any renderer deciding
+ // "this is small, it must be a fraction" is right until it is not.
+ swrData.set(FUNNEL_KEY, {
+ ...SAMPLE_FUNNEL,
+ deltas: { ...SAMPLE_FUNNEL.deltas, events_of_interest: 1.0 },
+ });
+ render(<FunnelKpiBar period="24h" />);
+
+ expect(screen.getByText('+1%')).toBeInTheDocument();
+ expect(screen.queryByText('+100%')).not.toBeInTheDocument();
+ });
+
it('shows skeleton tiles while loading', () => {
swrLoading.add(FUNNEL_KEY);
render(<FunnelKpiBar period="24h" />);
diff --git a/apps/web/src/components/dashboard/FunnelKpiBar.tsx b/apps/web/src/components/dashboard/FunnelKpiBar.tsx
index c81ec1057..eee4d55ed 100644
--- a/apps/web/src/components/dashboard/FunnelKpiBar.tsx
+++ b/apps/web/src/components/dashboard/FunnelKpiBar.tsx
@@ -65,11 +65,26 @@ function formatPercent(ratio: number): string {
return `${(ratio * 100).toFixed(1).replace(/\.0$/, '')}%`;
}
-function formatDelta(delta: number | null): string {
- if (delta === null || !Number.isFinite(delta)) return '—';
- const pct = delta * 100;
- const rounded = Math.abs(pct) >= 10 ? Math.round(pct) : pct.toFixed(1);
- const sign = pct > 0 ? '+' : pct < 0 ? '−' : '';
+/**
+ * Render a period-over-period delta.
+ *
+ * The value arrives as a **percentage**, not a fraction: the backend's
+ * `_pct_delta` already multiplies by 100 and rounds, so a run that fell from
+ * 160 events to 10 sends `-93.75`. This used to multiply by 100 again and
+ * render `-9375%`, which is not a plausible number on a dashboard and was
+ * nevertheless shipped, because the test beside it fed `0.12`-shaped fractions
+ * the backend has never emitted and asserted `+12%`.
+ *
+ * Scale is decided by the contract, never by the magnitude. A real delta of
+ * 1% and a fraction of 1.0 are indistinguishable by value, so "it looks small,
+ * it must be a fraction" is a guess that is right until it is catastrophically
+ * not.
+ */
+function formatDelta(deltaPercent: number | null): string {
+ if (deltaPercent === null || !Number.isFinite(deltaPercent)) return '—';
+ const rounded =
+ Math.abs(deltaPercent) >= 10 ? Math.round(deltaPercent) : deltaPercent.toFixed(1);
+ const sign = deltaPercent > 0 ? '+' : deltaPercent < 0 ? '−' : '';
return `${sign}${Math.abs(Number(rounded))}%`;
}
diff --git a/apps/web/src/components/soc-insights/SOCInsightsView.test.tsx b/apps/web/src/components/soc-insights/SOCInsightsView.test.tsx
index 309f6a36b..478493a14 100644
--- a/apps/web/src/components/soc-insights/SOCInsightsView.test.tsx
+++ b/apps/web/src/components/soc-insights/SOCInsightsView.test.tsx
@@ -19,6 +19,14 @@ vi.mock('@/lib/api', () => ({
insightsApi: {
getSOC: vi.fn(),
},
+ // Needed because the view now binds to the real `TimeWindowProvider`, which
+ // reconciles the window with the signed-in user's stored preference. Stubbed
+ // rather than omitted: an absent export makes the provider throw during
+ // render, which reads as a component failure rather than a missing mock.
+ authApi: {
+ currentUser: vi.fn(() => null),
+ updateUserPreferences: vi.fn(() => Promise.resolve()),
+ },
}));
vi.mock('@/lib/realtime', () => ({
@@ -32,6 +40,7 @@ vi.mock('@/lib/realtime', () => ({
}));
import { insightsApi, type SOCInsightsResponse } from '@/lib/api';
+import { TimeWindowProvider } from '@/components/layout/TimeWindowProvider';
import { SOCInsightsView } from './SOCInsightsView';
import { pointsToPath } from './Sparkline';
@@ -47,7 +56,14 @@ import { pointsToPath } from './Sparkline';
function renderIsolated(node: ReactElement) {
return render(
<SWRConfig value={{ provider: () => new Map(), dedupingInterval: 0 }}>
- {node}
+ {/*
+ The view binds to the global time window rather than holding a private
+ copy, so it needs the provider the app layout supplies. Wrapping here
+ rather than mocking the hook: a mocked `useTimeWindow` would make the
+ test agree with whatever the component asked for, which is exactly how
+ a selector that drove nothing passed its own suite.
+ */}
+ <TimeWindowProvider>{node}</TimeWindowProvider>
</SWRConfig>,
);
}
diff --git a/apps/web/src/components/soc-insights/SOCInsightsView.tsx b/apps/web/src/components/soc-insights/SOCInsightsView.tsx
index 269d69a0c..2b40fbd88 100644
--- a/apps/web/src/components/soc-insights/SOCInsightsView.tsx
+++ b/apps/web/src/components/soc-insights/SOCInsightsView.tsx
@@ -9,6 +9,7 @@
'use client';
import { useEffect, useMemo, useState } from 'react';
+import { useTimeWindow } from '@/components/layout/TimeWindowProvider';
import useSWR from 'swr';
import { useRealtimeChannel } from '@/lib/realtime';
@@ -31,7 +32,18 @@ interface RealtimePoke {
}
export function SOCInsightsView() {
- const [window, setWindow] = useState<InsightsWindow>('24h');
+ // Bound to the global selector rather than a private `useState`. Two
+ // controls on one page that both say "24h" and move independently is the
+ // kind of thing a user reads as the data itself being wrong.
+ //
+ // This endpoint has no 1h window, so a global `1h` is clamped to `24h` --
+ // and the clamp is *shown*, not silent. Rendering a day of data under a
+ // header reading "1h" would be a quietly wrong number, which is worse than
+ // an explicit note.
+ const { window: globalWindow, setWindow: setGlobalWindow } = useTimeWindow();
+ const clamped = globalWindow === '1h';
+ const window: InsightsWindow = clamped ? '24h' : globalWindow;
+ const setWindow = setGlobalWindow;
const { data, error, isLoading, mutate } = useSWR<SOCInsightsResponse>(
['insights:soc', window],
@@ -67,6 +79,7 @@ export function SOCInsightsView() {
<div className="space-y-6 p-6">
<Header
window={window}
+ clamped={clamped}
onWindowChange={setWindow}
generatedAt={data?.generated_at}
manualMinutes={data?.manual_investigation_minutes}
@@ -92,12 +105,13 @@ export function SOCInsightsView() {
interface HeaderProps {
window: InsightsWindow;
+ clamped: boolean;
onWindowChange: (w: InsightsWindow) => void;
generatedAt: string | undefined;
manualMinutes: number | undefined;
}
-function Header({ window, onWindowChange, generatedAt, manualMinutes }: HeaderProps) {
+function Header({ window, clamped, onWindowChange, generatedAt, manualMinutes }: HeaderProps) {
const stamp = useMemo(() => {
if (!generatedAt) return null;
try {
@@ -117,6 +131,11 @@ function Header({ window, onWindowChange, generatedAt, manualMinutes }: HeaderPr
window. Hours-saved assumes {manualMinutes ?? 45} minutes of analyst
time per auto-closed case.
</p>
+ {clamped ? (
+ <p className="mt-1 text-xs text-amber-500/90">
+ These tiles have no 1-hour window, so they are showing 24 hours.
+ </p>
+ ) : null}
</div>
<div className="flex items-center gap-4">
{stamp ? (
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index ac2ff6c6c..f1968c561 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -1549,10 +1549,33 @@ export const entityRiskApi = {
// ─── Cases ───────────────────────────────────────────────────────────────────
+/**
+ * The six states a case can hold, matching the `aisoc_cases` CHECK and
+ * `services/api/app/services/case_status.py`.
+ *
+ * This read `open | in_progress | pending | resolved | closed`, which shares
+ * exactly two members with the real vocabulary. Three of its values the
+ * database rejects outright, and the four states a case is actually *in* for
+ * most of its life -- new, triaged, investigating, contained -- were absent.
+ * Every `Record<CaseStatus, …>` keyed off this union was therefore complete
+ * by the type checker and missing an entry for most real rows, so the case
+ * workspace rendered an undefined label and the status dropdown offered three
+ * values the API refuses.
+ */
+export const CASE_STATUSES = [
+ 'new',
+ 'triaged',
+ 'investigating',
+ 'contained',
+ 'resolved',
+ 'closed',
+] as const;
+
export type CaseStatus =
- | 'open'
- | 'in_progress'
- | 'pending'
+ | 'new'
+ | 'triaged'
+ | 'investigating'
+ | 'contained'
| 'resolved'
| 'closed';
export type CaseSeverity = 'critical' | 'high' | 'medium' | 'low';
@@ -1605,34 +1628,22 @@ export interface Case {
tasks?: CaseTask[];
}
-// The backend uses a 6-state lifecycle (`new | triaged | investigating |
-// contained | resolved | closed`) while the web console renders a simpler
-// 5-state model. Without translation, `STATUS_CONFIG[c.status]` returns
-// `undefined` and `<CaseCard>` throws a TypeError, which React surfaces as a
-// blank loading state on /cases. Keep these maps colocated with the Case type.
-const BACKEND_TO_UI_STATUS: Record<string, CaseStatus> = {
- new: 'open',
- open: 'open',
- triaged: 'pending',
- pending: 'pending',
- investigating: 'in_progress',
- in_progress: 'in_progress',
- contained: 'in_progress',
- resolved: 'resolved',
- closed: 'closed',
-};
-
-const UI_TO_BACKEND_STATUS: Record<CaseStatus, string> = {
- open: 'new',
- pending: 'triaged',
- in_progress: 'investigating',
- resolved: 'resolved',
- closed: 'closed',
-};
-
+// The console speaks the backend vocabulary directly.
+//
+// There were two translation maps here, and the round trip through them was
+// **destructive**: `contained` came in as `in_progress`, and `in_progress`
+// went back out as `investigating`. So opening a contained case and saving
+// any edit -- a title, an assignee -- silently moved it backwards and
+// discarded the containment an analyst had recorded. The lossiness is
+// structural: six states cannot round-trip through five.
+//
+// The UI simplification they existed for is not worth that. Four of the six
+// states now have their own label and colour, which is more information
+// than the collapsed model carried anyway.
function toUiStatus(raw: unknown): CaseStatus {
- if (typeof raw !== 'string') return 'open';
- return BACKEND_TO_UI_STATUS[raw] ?? 'open';
+ if (typeof raw !== 'string') return 'new';
+ const known: readonly string[] = CASE_STATUSES;
+ return known.includes(raw) ? (raw as CaseStatus) : 'new';
}
export interface CasesResponse {
@@ -1864,17 +1875,12 @@ export function normalizeCasesResponse(raw: unknown, filters: CaseFilters = {}):
export const casesApi = {
list: async (filters: CaseFilters = {}) => {
- // Translate UI status filter into the backend lifecycle vocabulary so
- // querying "In Progress" in the console actually returns rows where the
- // backend stored "investigating".
+ // The status filter is passed through unchanged. It used to be rewritten
+ // through a five-state UI vocabulary, which could not express `contained`
+ // at all and mapped it onto `investigating` on the way back.
const params: Record<string, string> = {};
for (const [key, value] of Object.entries(filters)) {
if (value === undefined || value === null || value === '') continue;
- if (key === 'status' && typeof value === 'string' && value !== 'all') {
- params.status =
- UI_TO_BACKEND_STATUS[value as CaseStatus] ?? value;
- continue;
- }
params[key] = String(value);
}
const raw = await request<unknown>('/api/v1/cases', { params });
@@ -2279,7 +2285,14 @@ export interface FunnelMetrics {
/** Alerts produced per event-of-interest, clamped to [0, 1]. */
alert_yield: number;
mitre_coverage: { covered: number; total: number; ratio: number };
- /** Period-over-period deltas (fraction, e.g. 0.05 = +5%). */
+ /**
+ * Period-over-period deltas as **percentages**, e.g. `5.0` = +5%.
+ *
+ * This said "fraction, e.g. 0.05 = +5%", which is backwards: the
+ * backend's `_pct_delta` multiplies by 100 before returning, and
+ * `test_funnel_and_pipeline.py` pins `_pct_delta(150.0, 100.0) == 50.0`.
+ * The renderer believed the comment and scaled a second time.
+ */
deltas: {
events_of_interest: number;
correlation_instances: number;
@@ -2405,11 +2418,26 @@ export interface CostAggregate {
totals: CostAggregateRow | null;
}
+/**
+ * The windows every metrics route accepts, matching `_PERIOD_QUERY`'s pattern
+ * server-side and `TIME_WINDOWS` in `lib/timeWindow.ts`. Named once so the
+ * four call sites below cannot drift apart from each other.
+ */
+export type TimeWindowParam = '1h' | '24h' | '7d' | '30d';
+
export const metricsApi = {
- getDashboard: () =>
- request<DashboardMetrics>('/api/v1/metrics/dashboard'),
+ /**
+ * Dashboard tiles for a time window.
+ *
+ * `period` was not a parameter: the console shipped a global time-window
+ * selector whose only consumer was itself, so changing it re-rendered a
+ * header and fetched nothing. Defaulted rather than required so no existing
+ * caller changes behaviour by omission.
+ */
+ getDashboard: (period: TimeWindowParam = '24h') =>
+ request<DashboardMetrics>('/api/v1/metrics/dashboard', { params: { period } }),
- getAlertTrend: (period: '1h' | '24h' | '7d' | '30d') =>
+ getAlertTrend: (period: TimeWindowParam) =>
request<{ data: Array<{ timestamp: string; count: number }> }>(
`/api/v1/metrics/alerts/trend`,
{
@@ -2418,7 +2446,7 @@ export const metricsApi = {
),
/** Funnel KPIs (events → correlations → alerts) with deltas. */
- getFunnel: (period: '1h' | '24h' | '7d' | '30d' = '24h') =>
+ getFunnel: (period: TimeWindowParam = '24h') =>
request<FunnelMetrics>('/api/v1/metrics/funnel', { params: { period } }),
/** Per-stage pipeline health (ingest → normalize → fuse → correlate → alert). */
@@ -2431,7 +2459,8 @@ export const metricsApi = {
* Tenant-scoped server-side; the client just needs the bearer token
* and X-Tenant-Id header that `request()` already attaches.
*/
- getSOC: () => request<SOCMetrics>('/api/v1/metrics/soc'),
+ getSOC: (period: TimeWindowParam = '24h') =>
+ request<SOCMetrics>('/api/v1/metrics/soc', { params: { period } }),
};
// ─── Operational health: connector fleet, rejected events, alert posture ─────
diff --git a/apps/web/src/lib/responder/format.ts b/apps/web/src/lib/responder/format.ts
index 9f7808819..61c90fec3 100644
--- a/apps/web/src/lib/responder/format.ts
+++ b/apps/web/src/lib/responder/format.ts
@@ -117,10 +117,14 @@ const ALERT_STATUS: Record<string, StatusTone> = {
snoozed: { bg: 'bg-amber-500/20', fg: 'text-amber-300', label: 'Snoozed' },
};
+// The six the database permits. `open`, `in_progress` and `pending` were
+// entries nothing could ever match, so every real case fell through to the
+// grey "unknown" default and the responder console showed no status colour.
const CASE_STATUS: Record<string, StatusTone> = {
- open: { bg: 'bg-blue-500/20', fg: 'text-blue-300', label: 'Open' },
- in_progress: { bg: 'bg-purple-500/20', fg: 'text-purple-300', label: 'Active' },
- pending: { bg: 'bg-yellow-500/20', fg: 'text-yellow-300', label: 'Pending' },
+ new: { bg: 'bg-blue-500/20', fg: 'text-blue-300', label: 'New' },
+ triaged: { bg: 'bg-sky-500/20', fg: 'text-sky-300', label: 'Triaged' },
+ investigating: { bg: 'bg-purple-500/20', fg: 'text-purple-300', label: 'Investigating' },
+ contained: { bg: 'bg-yellow-500/20', fg: 'text-yellow-300', label: 'Contained' },
resolved: { bg: 'bg-green-500/20', fg: 'text-green-300', label: 'Resolved' },
closed: { bg: 'bg-slate-500/20', fg: 'text-slate-300', label: 'Closed' },
};
@@ -132,7 +136,7 @@ export function alertStatusTone(status: AlertStatus | string | undefined | null)
}
export function caseStatusTone(status: CaseStatus | string | undefined | null): StatusTone {
- if (!status) return CASE_STATUS.open;
+ if (!status) return CASE_STATUS.new;
const key = status.toLowerCase();
return CASE_STATUS[key] ?? { bg: 'bg-slate-500/20', fg: 'text-slate-300', label: status };
}
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 4c0a3766c..7e8f98be6 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -987,6 +987,52 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
+ /api/v1/cases/{case_id}/reopen:
+ post:
+ tags:
+ - cases
+ summary: Reopen a closed case
+ description: "Bring a terminal case back, deliberately and on the record.\n\n\
+ Its own route rather than a backward edge in `TRANSITIONS`. The forward-only\n\
+ machine is what makes \"this case was closed\" mean something, and adding\n\
+ `closed -> investigating` to the table would let an ordinary `PATCH` --\n\
+ a title edit that happens to carry a status -- walk a case backwards\nsilently.\
+ \ `PATCH` stays forward-only.\n\nThree things separate this from a status\
+ \ change:\n\n* a reason is required, because an unexplained reopen is exactly\
+ \ what an\n auditor asks about six months later;\n* `reopen_count` increments,\
+ \ so a case reopened four times is\n distinguishable from one reopened once;\n\
+ * `closed_at` and `resolved_at` are cleared, because leaving them set\n would\
+ \ make the case terminal and active at the same time -- and every\n closure\
+ \ metric reads those columns."
+ operationId: reopen_case_api_v1_cases__case_id__reopen_post
+ security:
+ - HTTPBearer: []
+ parameters:
+ - name: case_id
+ in: path
+ required: true
+ schema:
+ type: string
+ title: Case Id
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ReopenCaseRequest'
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CaseResponse'
+ '422':
+ description: Validation Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/HTTPValidationError'
/api/v1/cases/{case_id}/alerts:
post:
tags:
@@ -7570,8 +7616,41 @@ paths:
tags:
- metrics
summary: Get Dashboard Metrics
- description: Return aggregated KPI metrics for the dashboard overview tiles.
+ description: 'Return aggregated KPI metrics for the dashboard overview tiles.
+
+
+ `period` drives every windowed figure below. It did not exist: the console
+
+ shipped a global time-window selector whose only consumer was itself, so
+
+ changing it re-rendered a header and fetched nothing. The trend chart and
+
+ the "closed this week" tile were fixed at 7 days whatever the control
+
+ said.
+
+
+ Counts of *current state* -- open alerts by severity -- are deliberately
+
+ not windowed. "How many criticals are open" is a question about now, and
+
+ answering it for the last hour would hide the backlog rather than scope
+
+ it.'
operationId: get_dashboard_metrics_api_v1_metrics_dashboard_get
+ security:
+ - HTTPBearer: []
+ parameters:
+ - name: period
+ in: query
+ required: false
+ schema:
+ type: string
+ pattern: ^(1h|24h|7d|30d)$
+ description: Time window for this view.
+ default: 24h
+ title: Period
+ description: Time window for this view.
responses:
'200':
description: Successful Response
@@ -7579,8 +7658,12 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/DashboardMetrics'
- security:
- - HTTPBearer: []
+ '422':
+ description: Validation Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/HTTPValidationError'
/api/v1/metrics/soc:
get:
tags:
@@ -7591,6 +7674,19 @@ paths:
\ analyst overrides\n - ATT&CK technique × tactic heatmap\n - Confidence\
\ calibration over time (reliability curve)"
operationId: get_soc_metrics_api_v1_metrics_soc_get
+ security:
+ - HTTPBearer: []
+ parameters:
+ - name: period
+ in: query
+ required: false
+ schema:
+ type: string
+ pattern: ^(1h|24h|7d|30d)$
+ description: Time window for this view.
+ default: 24h
+ title: Period
+ description: Time window for this view.
responses:
'200':
description: Successful Response
@@ -7598,8 +7694,12 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/SOCMetrics'
- security:
- - HTTPBearer: []
+ '422':
+ description: Validation Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/HTTPValidationError'
/api/v1/metrics/alerts/trend:
get:
tags:
@@ -7662,8 +7762,10 @@ paths:
schema:
type: string
pattern: ^(1h|24h|7d|30d)$
+ description: Time window for this view.
default: 24h
title: Period
+ description: Time window for this view.
responses:
'200':
description: Successful Response
@@ -18396,6 +18498,10 @@ components:
resolvedToday:
type: integer
title: Resolvedtoday
+ resolved:
+ type: integer
+ title: Resolved
+ default: 0
mttr:
type: number
title: Mttr
@@ -20348,6 +20454,21 @@ components:
format: date-time
- type: 'null'
title: Closed At
+ reopened_at:
+ anyOf:
+ - type: string
+ format: date-time
+ - type: 'null'
+ title: Reopened At
+ reopen_count:
+ type: integer
+ title: Reopen Count
+ default: 0
+ reopen_reason:
+ anyOf:
+ - type: string
+ - type: 'null'
+ title: Reopen Reason
created_at:
type: string
format: date-time
@@ -29936,6 +30057,28 @@ components:
required:
- reason
title: ReleaseRequest
+ ReopenCaseRequest:
+ properties:
+ reason:
+ type: string
+ maxLength: 2000
+ minLength: 8
+ title: Reason
+ description: Why the case is being reopened. Recorded on the case and in
+ the audit log.
+ status:
+ type: string
+ enum:
+ - new
+ - triaged
+ - investigating
+ title: Status
+ default: investigating
+ type: object
+ required:
+ - reason
+ title: ReopenCaseRequest
+ description: Why this case is coming back.
ReplaceRulesRequest:
properties:
yaml:
diff --git a/packages/types/src/case.ts b/packages/types/src/case.ts
deleted file mode 100644
index ea2ec08f6..000000000
--- a/packages/types/src/case.ts
+++ /dev/null
@@ -1,135 +0,0 @@
-/**
- * AiSOC Case Management types
- */
-
-export type CaseStatus = "open" | "in_progress" | "pending_closure" | "closed" | "cancelled";
-export type CasePriority = "critical" | "high" | "medium" | "low";
-export type CaseType =
- | "incident"
- | "investigation"
- | "threat_hunt"
- | "vulnerability"
- | "compliance"
- | "false_positive_review"
- | "post_mortem";
-
-export interface CaseTimeline {
- id: string;
- case_id: string;
- timestamp: string;
- type: "alert_added" | "comment" | "status_change" | "action_taken" | "evidence_added" | "assignment" | "tag_added" | "playbook_step";
- author: string;
- content: string;
- metadata?: Record<string, unknown>;
- is_automated: boolean;
-}
-
-export interface CaseTask {
- id: string;
- case_id: string;
- title: string;
- description?: string;
- status: "todo" | "in_progress" | "done" | "skipped";
- assigned_to?: string;
- due_at?: string;
- completed_at?: string;
- created_by: string;
- created_at: string;
- playbook_step_id?: string;
-}
-
-export interface CaseArtifact {
- id: string;
- case_id: string;
- name: string;
- type: "file" | "screenshot" | "log_export" | "memory_dump" | "pcap" | "report";
- size_bytes?: number;
- sha256?: string;
- storage_path: string;
- uploaded_by: string;
- uploaded_at: string;
- description?: string;
- tags?: string[];
-}
-
-export interface CaseTicketRef {
- integration: "jira" | "servicenow" | "pagerduty" | "linear" | "github" | "custom";
- ticket_id: string;
- ticket_url?: string;
- synced_at?: string;
- status?: string;
-}
-
-export interface Case {
- id: string;
- tenant_id: string;
- case_number: string; // Human-readable: SOC-2024-0001
-
- // Core fields
- title: string;
- description: string;
- type: CaseType;
- status: CaseStatus;
- priority: CasePriority;
-
- // Timing
- created_at: string;
- updated_at: string;
- closed_at?: string;
- sla_due_at?: string;
- sla_breached?: boolean;
-
- // Ownership
- created_by: string;
- assigned_to?: string;
- team?: string;
- watchers?: string[];
-
- // Links
- alert_ids: string[];
- incident_id?: string;
- parent_case_id?: string;
- child_case_ids?: string[];
-
- // Content
- tags: string[];
- affected_assets: string[];
- tasks: CaseTask[];
- timeline: CaseTimeline[];
- artifacts: CaseArtifact[];
- external_tickets?: CaseTicketRef[];
-
- // Playbook
- active_playbook_id?: string;
- playbook_run_id?: string;
- playbook_progress?: number; // 0-100
-
- // AI
- ai_summary?: string;
- ai_recommended_actions?: string[];
- threat_score?: number; // 0-100
- containment_state?: "unknown" | "not_contained" | "partial" | "contained" | "eradicated" | "recovered";
-
- // Metrics
- mttr_minutes?: number;
- time_to_contain_minutes?: number;
- analyst_hours?: number;
- cost_estimate_usd?: number;
-}
-
-export interface CaseFilters {
- tenant_id?: string;
- status?: CaseStatus[];
- priority?: CasePriority[];
- type?: CaseType[];
- assigned_to?: string;
- created_by?: string;
- from?: string;
- to?: string;
- search?: string;
- has_sla_breach?: boolean;
- limit?: number;
- offset?: number;
- sort_by?: "created_at" | "updated_at" | "priority" | "sla_due_at";
- sort_dir?: "asc" | "desc";
-}
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index dde20917c..5477df311 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -10,7 +10,6 @@ export * from "./ocsf";
// Core domain types
export * from "./alert";
-export * from "./case";
export * from "./tenant";
export * from "./connector";
export * from "./playbook";
diff --git a/scripts/check_one_case_table.py b/scripts/check_one_case_table.py
index 7fdb42819..54eb4bd75 100644
--- a/scripts/check_one_case_table.py
+++ b/scripts/check_one_case_table.py
@@ -34,15 +34,22 @@ wrong, on one table instead of two.
from __future__ import annotations
import argparse
+import ast
import re
import sys
+import textwrap
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
-from gate_toolkit import repo_root, self_test_if_requested # noqa: E402
+from gate_toolkit import repo_root, self_test_main, verdict_args # noqa: E402
-self_test_if_requested(__file__)
+# No module-level `self_test_if_requested` here, unlike most gates in this
+# tree. It would answer `--self-test` before `_impossible_in` is defined, so
+# the one thing worth proving -- that the detector catches the shapes that got
+# past its first version -- could never run. The checks are handed to
+# `self_test_main` through its `extra` parameter instead, which is what that
+# parameter exists for.
# Ask git which tree this is, rather than counting directories above this
# file. Two levels up is whatever happens to be there — a worktree, a
@@ -93,14 +100,57 @@ def _without_comments(line: str, suffix: str) -> str:
return (_SQL_COMMENT_RE if suffix == ".sql" else _PY_COMMENT_RE).sub("", line)
-#: Status strings the console's machine can never produce. Finding one of
-#: these is proof a reader is using the pre-consolidation vocabulary.
-IMPOSSIBLE_STATUSES = ("open", "in_progress")
+#: Status strings no AiSOC state machine produces. `open` is in neither the
+#: case vocabulary (`aisoc_cases`' CHECK) nor the alert one
+#: (`models/alert.py`: new/triaging/in_progress/resolved), so finding it
+#: anywhere is proof of the pre-consolidation vocabulary.
+IMPOSSIBLE_STATUSES = ("open",)
+#: Impossible for a **case** and perfectly valid for an **alert**.
+#:
+#: This distinction is not pedantry: widening the detector without it
+#: immediately produced three false positives on
+#: `Alert.status.in_(["new", "triaging", "in_progress"])`, which is correct
+#: code. A gate that flags correct code gets suppressed, and then it catches
+#: nothing at all -- so these are only reported where the line is visibly
+#: about cases.
+CASE_ONLY_IMPOSSIBLE = ("in_progress",)
+
+#: What makes a line visibly about cases. Deliberately narrow: a missed leak
+#: is a wrong count, while a false positive on working alert code is how a
+#: gate gets turned off.
+_CASE_CONTEXT_RE = re.compile(r"\bCase\b|\baisoc_cases\b|CASE_STATUS|_CASE_STATUSES|case_status")
+
+#: The four shapes a retired status literal actually takes in this tree.
+#:
+#: The first version of this gate matched only `Case.status == "x"` and
+#: `"status": "x"`, and **passed while missing all four live leaks**: an ORM
+#: `status="open"` keyword in an INSERT, two `_OPEN_*_STATUSES = (...)` tuples,
+#: and a `.in_(["open", "in_progress"])`. None of those is an exotic spelling
+#: -- they are how the code is ordinarily written -- so a detector that only
+#: recognised two forms was a gate whose green was meaningless.
+#:
+#: Each alternative captures the literal in group 1 except `_IN_LIST_RE` and
+#: `_TUPLE_RE`, which capture a whole collection body and are rescanned.
_STATUS_LITERAL_RE = re.compile(
- r"""(?:Case\.status\s*==\s*|["']status["']\s*:\s*)["'](\w+)["']""",
+ r"""(?:Case\.status\s*==\s*|["']status["']\s*:\s*|\bstatus\s*=\s*)["'](\w+)["']""",
)
+#: `.in_(["open", "in_progress"])` and `.in_(("open",))`, on one line or
+#: wrapped. The body is captured and each literal inside it checked.
+_IN_LIST_RE = re.compile(r"""status\s*\.in_\s*\(\s*[\[\(]([^\]\)]*)""", re.S)
+
+#: A module-level tuple or list of status strings, which is how two of the
+#: live leaks were written -- under a comment saying they were kept in one
+#: place precisely so they could not drift.
+_STATUS_COLLECTION_RE = re.compile(
+ r"""^\s*_?[A-Z_]*STATUS(?:ES)?[A-Z_]*\s*[:=][^=]*?[\[\(]([^\]\)]*)""",
+ re.M,
+)
+
+#: Any quoted word, used to rescan a captured collection body.
+_QUOTED_RE = re.compile(r"""["'](\w+)["']""")
+
#: Where the vocabulary is allowed to be spelled out.
VOCABULARY_OWNER = "services/api/app/services/case_status.py"
@@ -156,30 +206,198 @@ def find_retired_table_reads(paths: list[Path]) -> list[str]:
return findings
+def _is_case_attr(node: ast.AST, attr: str) -> bool:
+ """True for `Case.<attr>`, which is the unambiguous case reference."""
+ return isinstance(node, ast.Attribute) and node.attr == attr and isinstance(node.value, ast.Name) and node.value.id == "Case"
+
+
+def _constants(node: ast.AST) -> list[str]:
+ """Every string constant directly inside a list/tuple/set node."""
+ if not isinstance(node, ast.List | ast.Tuple | ast.Set):
+ return []
+ return [e.value for e in node.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+
+
+def _scan_python(tree: ast.AST, impossible_case: set[str], impossible_any: set[str]) -> list[tuple[int, str]]:
+ """Find retired case-status literals, by structure rather than by spelling.
+
+ An AST rather than a regex, because the two cannot be told apart textually.
+ `status: Mapped[str] = mapped_column(String(20), default="open")` is a
+ defect in `models/case.py` and perfectly correct in `models/posture.py`,
+ where a CSPM finding really is open or resolved -- and a regex sees one
+ line. Flagging the posture model would be the kind of false positive that
+ gets a gate suppressed, after which it catches nothing at all.
+
+ Five shapes, each a reconstruction of something that shipped:
+
+ 1. `Case(status="open")` -- the constructor keyword
+ 2. `Case.status == "open"` -- the comparison
+ 3. `Case.status.in_([...])` -- the membership test
+ 4. `_OPEN_CASE_STATUSES = (...)` -- the module collection
+ 5. `status: Mapped[...] = mapped_column(default="open")` inside a Case
+ model -- the column default, scoped to the class it sits in
+ """
+ found: list[tuple[int, str]] = []
+
+ def report(node: ast.AST, value: str) -> None:
+ found.append((getattr(node, "lineno", 0), value))
+
+ class _Visitor(ast.NodeVisitor):
+ def __init__(self) -> None:
+ self.class_stack: list[str] = []
+
+ def visit_ClassDef(self, node: ast.ClassDef) -> None: # noqa: N802
+ self.class_stack.append(node.name)
+ self.generic_visit(node)
+ self.class_stack.pop()
+
+ @property
+ def in_case_model(self) -> bool:
+ return any("Case" in name for name in self.class_stack)
+
+ def visit_Call(self, node: ast.Call) -> None: # noqa: N802
+ # 1. Case(status="open")
+ if isinstance(node.func, ast.Name) and node.func.id == "Case":
+ for kw in node.keywords:
+ if kw.arg == "status" and isinstance(kw.value, ast.Constant):
+ if kw.value.value in impossible_case:
+ report(kw.value, str(kw.value.value))
+
+ # 3. Case.status.in_([...])
+ if isinstance(node.func, ast.Attribute) and node.func.attr == "in_" and _is_case_attr(node.func.value, "status"):
+ for arg in node.args:
+ for value in _constants(arg):
+ if value in impossible_case:
+ report(arg, value)
+
+ self.generic_visit(node)
+
+ def visit_Compare(self, node: ast.Compare) -> None: # noqa: N802
+ # 2. Case.status == "open"
+ if _is_case_attr(node.left, "status"):
+ for comparator in node.comparators:
+ if isinstance(comparator, ast.Constant) and comparator.value in impossible_case:
+ report(comparator, str(comparator.value))
+ self.generic_visit(node)
+
+ def visit_AnnAssign(self, node: ast.AnnAssign) -> None: # noqa: N802
+ # 5. the ORM column default, only inside a Case model
+ if self.in_case_model and isinstance(node.target, ast.Name) and node.target.id == "status" and isinstance(node.value, ast.Call):
+ for kw in node.value.keywords:
+ if kw.arg == "default" and isinstance(kw.value, ast.Constant):
+ if kw.value.value in impossible_case:
+ report(kw.value, str(kw.value.value))
+ self.generic_visit(node)
+
+ def visit_Assign(self, node: ast.Assign) -> None: # noqa: N802
+ # 4. a named collection of case statuses
+ for target in node.targets:
+ if isinstance(target, ast.Name) and "CASE" in target.id.upper() and "STATUS" in target.id.upper():
+ for value in _constants(node.value):
+ if value in impossible_case:
+ report(node.value, value)
+ self.generic_visit(node)
+
+ def visit_Constant(self, node: ast.Constant) -> None: # noqa: N802
+ # `open` is in neither vocabulary, so it is worth reporting
+ # wherever it appears as a status value in a dict literal. Handled
+ # by the caller's regex pass, which keeps this visitor to the
+ # structural cases it can decide confidently.
+ self.generic_visit(node)
+
+ _Visitor().visit(tree)
+ return found
+
+
+def _impossible_in(line: str) -> list[str]:
+ """Every retired status literal on one line, across all four shapes.
+
+ Returned in source order and de-duplicated, so a line naming the same
+ retired value twice reports once.
+ """
+ # `in_progress` is a real alert status, so it only counts against a line
+ # that is visibly about cases. `open` counts everywhere, being absent from
+ # both vocabularies.
+ #
+ # The structural cases are decided by `_scan_python`, which can tell a
+ # `Case` from a `PostureFinding`. This pass is the textual backstop for
+ # the shapes an AST does not resolve cleanly -- a dict literal, a SQL
+ # string -- so it stays conservative on purpose.
+ impossible = set(IMPOSSIBLE_STATUSES)
+ if _CASE_CONTEXT_RE.search(line):
+ impossible |= set(CASE_ONLY_IMPOSSIBLE)
+
+ found: list[str] = []
+
+ for match in _STATUS_LITERAL_RE.finditer(line):
+ if match.group(1) in impossible:
+ found.append(match.group(1))
+
+ for pattern in (_IN_LIST_RE, _STATUS_COLLECTION_RE):
+ for match in pattern.finditer(line):
+ for quoted in _QUOTED_RE.finditer(match.group(1)):
+ if quoted.group(1) in impossible:
+ found.append(quoted.group(1))
+
+ # Written out rather than the `f in seen or seen.add(f)` idiom, which uses
+ # a `None` return as a value and reads as a trick either way.
+ seen: set[str] = set()
+ unique: list[str] = []
+ for value in found:
+ if value not in seen:
+ seen.add(value)
+ unique.append(value)
+ return unique
+
+
def find_impossible_statuses(paths: list[Path]) -> list[str]:
+ """Report every retired case-status literal in the API service.
+
+ Two passes, because the two kinds of evidence are different. The AST pass
+ decides the structural cases confidently -- it knows `Case(status="open")`
+ from `PostureFinding(status="open")`, which no regex can. The line pass
+ then catches `open` in a status position anywhere, since `open` belongs to
+ neither the case vocabulary nor the alert one and so is wrong wherever a
+ status is being named.
+ """
findings: list[str] = []
+ impossible_case = set(IMPOSSIBLE_STATUSES) | set(CASE_ONLY_IMPOSSIBLE)
+
for path in paths:
rel = str(path.relative_to(ROOT))
if rel in (VOCABULARY_OWNER, "scripts/check_one_case_table.py"):
continue
if not rel.endswith(".py") or not rel.startswith("services/api/app/"):
- # A connector describing its own vendor finding as "open" is
- # not speaking this vocabulary, and flagging it would teach a
- # reader the gate does not know what it is looking at.
+ # A connector describing its own vendor finding as "open" is not
+ # speaking this vocabulary, and flagging it would teach a reader
+ # the gate does not know what it is looking at.
continue
try:
text = path.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
continue
+
+ seen: set[tuple[int, str]] = set()
+
+ try:
+ tree = ast.parse(text)
+ except SyntaxError:
+ tree = None
+ if tree is not None:
+ for number, value in _scan_python(tree, impossible_case, set(IMPOSSIBLE_STATUSES)):
+ seen.add((number, value))
+
for number, raw in enumerate(text.splitlines(), 1):
line = _without_comments(raw, path.suffix)
- for match in _STATUS_LITERAL_RE.finditer(line):
- if match.group(1) in IMPOSSIBLE_STATUSES:
- findings.append(
- f"[impossible-status] {rel}:{number} filters case status "
- f"{match.group(1)!r}, which the console's state machine cannot produce, so "
- "this counter is structurally zero. Use app.services.case_status"
- )
+ for value in _impossible_in(line):
+ seen.add((number, value))
+
+ for number, value in sorted(seen):
+ findings.append(
+ f"[impossible-status] {rel}:{number} names case status "
+ f"{value!r}, which the console's state machine cannot produce and the "
+ "aisoc_cases CHECK rejects. Read app.services.case_status instead"
+ )
return findings
@@ -197,9 +415,115 @@ def find_stale_exemptions(paths: list[Path]) -> list[str]:
return findings
+def _self_test() -> int:
+ """Prove the detector catches each shape that got past the first version.
+
+ This is the part that matters. The original regex matched exactly two
+ spellings and **passed while four live leaks sat in the tree**, so a
+ self-test that only confirmed those two would have been just as green and
+ just as useless. Each case below is a verbatim reconstruction of a line
+ that shipped.
+
+ The negatives are equally load-bearing: `in_progress` is a valid *alert*
+ status, and a gate that reddens correct code gets suppressed, after which
+ it catches nothing at all.
+ """
+ positives = [
+ # hunt_scheduler.py:224 -- an ORM keyword in an INSERT. The CHECK
+ # rejected this row, so a scheduled hunt that fired could not create
+ # its case at all.
+ (' status="open",', "open", "ORM keyword in a Case() constructor"),
+ # graphql/query.py:417 -- a membership test whose count was
+ # structurally zero.
+ (
+ ' Case.status.in_(["open", "in_progress"])',
+ "open",
+ ".in_([...]) membership",
+ ),
+ # mssp_portfolio.py:134 -- a module tuple, under a comment claiming it
+ # was kept in one place so it could not drift.
+ (
+ '_OPEN_CASE_STATUSES = ("open", "investigating", "in_progress")',
+ "open",
+ "module-level status tuple",
+ ),
+ # The two the original regex did catch, kept so widening cannot
+ # silently drop them.
+ (' if Case.status == "open":', "open", "Case.status == literal"),
+ (' payload = {"status": "open"}', "open", "dict literal"),
+ # Case-only: flagged because the line is visibly about cases.
+ (
+ ' Case.status.in_(["in_progress"])',
+ "in_progress",
+ "case-only value in a case context",
+ ),
+ ]
+ negatives = [
+ # Correct alert code. Flagging this is how a gate gets turned off.
+ (
+ ' Alert.status.in_(["new", "triaging", "in_progress"]),',
+ "a valid alert status outside any case context",
+ ),
+ ('_OPEN_ALERT_STATUSES = ("new", "triaging", "in_progress")', "the alert tuple"),
+ (' Case.status == "investigating"', "a valid case status"),
+ (' status="new",', "the corrected constructor"),
+ ]
+
+ def _detect(snippet: str) -> list[str]:
+ """Run both passes, as `find_impossible_statuses` does.
+
+ A self-test that exercised only the regex would prove nothing about
+ the three shapes the AST now owns, and those are the three that got
+ past the first version of this gate.
+ """
+ values = list(_impossible_in(_without_comments(snippet, ".py")))
+ try:
+ tree = ast.parse(textwrap.dedent(snippet))
+ except SyntaxError:
+ return values
+ impossible = set(IMPOSSIBLE_STATUSES) | set(CASE_ONLY_IMPOSSIBLE)
+ values += [v for _, v in _scan_python(tree, impossible, set(IMPOSSIBLE_STATUSES))]
+ return values
+
+ checks: list[tuple[str, bool]] = []
+ for line, expected, label in positives:
+ checks.append((f"catches {label}", expected in _detect(line)))
+ for line, label in negatives:
+ checks.append((f"does not flag {label}", not _detect(line)))
+
+ # The false positive that made the AST necessary. A CSPM posture finding
+ # really is open or resolved, and a regex cannot tell it from a case.
+ posture = 'class PostureFinding(Base):\n status: Mapped[str] = mapped_column(String(20), default="open")\n'
+ checks.append(("does not flag a posture finding's own 'open' status", not _detect(posture)))
+
+ # And its counterpart, which must still be caught.
+ case_model = 'class Case(Base):\n status: Mapped[str] = mapped_column(String(30), default="open", index=True)\n'
+ checks.append(("catches the same default on a Case model", "open" in _detect(case_model)))
+
+ # The constructor keyword, in the multi-line form it actually shipped in.
+ constructor = 'case = Case(\n title="x",\n status="open",\n)\n'
+ checks.append(("catches a Case() constructor spanning lines", "open" in _detect(constructor)))
+
+ # A comment describing the retired vocabulary must not trip the gate on
+ # the commit that removes it.
+ checks.append(
+ (
+ "ignores a comment naming the retired value",
+ not _impossible_in(_without_comments(' x = 1 # was status="open"', ".py")),
+ )
+ )
+
+ script = Path(__file__)
+ return self_test_main(script.name, verdict_args(script), extra=checks)
+
+
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
- parser.parse_args()
+ parser.add_argument("--self-test", action="store_true")
+ args = parser.parse_args()
+
+ if args.self_test:
+ return _self_test()
paths = _tracked_sources()
if not paths:
diff --git a/services/agents/app/confidence/verdict_gate.py b/services/agents/app/confidence/verdict_gate.py
new file mode 100644
index 000000000..8b59fb0d3
--- /dev/null
+++ b/services/agents/app/confidence/verdict_gate.py
@@ -0,0 +1,174 @@
+"""Demote a verdict whose reasoning cites indicators the evidence does not contain.
+
+Why this module exists
+----------------------
+`score_groundedness` measures what fraction of the concrete indicators an
+output asserts -- IPs, hashes, CVEs, MITRE techniques, domains -- actually
+appear in the evidence the agent was given. The gate around it was real,
+default-on and demoting, and it lived in exactly one place:
+`workers/fused_alert_consumer.py`, the auto-triage path.
+
+The *investigator* path had none. So a verdict reached through
+`POST /cases/{id}/investigate` -- the one an analyst launches deliberately,
+reads carefully and is most likely to act on -- was never checked, while the
+background path that nobody is watching was.
+
+Why it could not simply have been added
+---------------------------------------
+The gate scores against `json.dumps(state.raw_alert or {})`, and on the
+investigator path `raw_alert` was `{}`: the console sent the literal string
+`"Investigate alert: <title>"` and no evidence at all. Scoring reasoning
+against an empty evidence set does not fail safe -- `_extract` finds no
+indicators in the evidence, so every indicator the model mentions is
+unsupported, and the gate would have demoted *everything*. Tuning around that
+by lowering the floor would have made it certify anything.
+
+So the payload had to flow first. It now does: `services/api` loads the case's
+alerts and their `raw_event` payloads and sends them as `raw_alert`.
+
+What is gated, and what deliberately is not
+-------------------------------------------
+Only verdicts that would close something without a human. Demoting an
+escalation because its prose mentioned one extra indicator adds review load
+without reducing risk, and a verdict already routed to a person is not making
+an unsupervised decision.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import structlog
+
+from app.confidence.groundedness import score_groundedness
+
+logger = structlog.get_logger(__name__)
+
+#: Default floor. A verdict citing fewer than this fraction of its indicators
+#: in the evidence does not get to close anything unattended.
+DEFAULT_FLOOR = 0.6
+
+
+def _dispositions() -> Any:
+ """Load `app.agents.dispositions` lazily, to break a real import cycle.
+
+ Importing it at module scope runs `app/agents/__init__.py`, which pulls in
+ `auto_triage_agent` -> `context.knowledge_base` -> ... ->
+ `app.prompting.envelope`, which imports `app.investigator` -- whose
+ `orchestrator` imports this module. The chain is genuine and predates
+ this file; the cycle only closes because this gate is now used from both
+ ends of it, which is the point of sharing it.
+
+ Deferred to call time rather than restructured, matching how the tree
+ already handles this (see `app/llm/tool_loop.py`, moved for the same
+ reason). The import is cached by `sys.modules` after the first call.
+ """
+ from app.agents import dispositions
+
+ return dispositions
+
+
+def _truthy(name: str, default: str = "1") -> bool:
+ return (os.getenv(name, default) or "").strip().lower() not in ("", "0", "false", "no")
+
+
+def gate_enabled() -> bool:
+ """On by default; disable with `AISOC_AGENT_GROUNDEDNESS_GATE=0`."""
+ return _truthy("AISOC_AGENT_GROUNDEDNESS_GATE")
+
+
+def floor() -> float:
+ raw = os.getenv("AISOC_AGENT_GROUNDEDNESS_FLOOR", "")
+ try:
+ return float(raw) if raw.strip() else DEFAULT_FLOOR
+ except ValueError:
+ return DEFAULT_FLOOR
+
+
+@dataclass
+class GateOutcome:
+ """What the gate decided, and why."""
+
+ verdict: Any
+ confidence: float
+ #: `None` when the gate did not run -- disabled, not an auto-closing
+ #: verdict, no reasoning, or **no evidence to score against**. Distinct
+ #: from `0.0`, which means it ran and found nothing supported.
+ score: float | None = None
+ demoted: bool = False
+ reason: str = ""
+ hallucinated: tuple[str, ...] = ()
+
+ @property
+ def skipped(self) -> bool:
+ return self.score is None
+
+
+def evaluate(
+ *,
+ verdict: Any,
+ confidence: float,
+ reasoning: str,
+ raw_alert: dict[str, Any] | None,
+ alert_summary: str | None = None,
+) -> GateOutcome:
+ """Score `reasoning` against the evidence and demote it if it is unsupported.
+
+ Pure, so both callers can be tested without a Kafka consumer or an HTTP
+ stack behind them.
+ """
+ unchanged = GateOutcome(verdict=verdict, confidence=confidence)
+
+ if not gate_enabled() or not verdict:
+ return unchanged
+
+ dispositions = _dispositions()
+ normalized = dispositions.normalize_disposition(str(verdict), default=dispositions.NEEDS_REVIEW)
+ if normalized not in dispositions.AUTO_CLOSEABLE_DISPOSITIONS:
+ return unchanged
+ if not (reasoning or "").strip():
+ return unchanged
+
+ # The refusal that makes this safe to wire into a second path.
+ #
+ # With no evidence, `_extract` finds nothing, every indicator the model
+ # mentions is "unsupported", and the gate demotes unconditionally. That is
+ # not caution -- it is a measurement of nothing, reported as a finding
+ # about the model. Say the gate did not run instead.
+ evidence_blob = f"{json.dumps(raw_alert or {}, default=str)}\n{alert_summary or ''}"
+ if not (raw_alert or {}):
+ logger.debug("groundedness_gate.no_evidence", verdict=str(verdict))
+ return GateOutcome(
+ verdict=verdict,
+ confidence=confidence,
+ reason="not scored: the investigation carried no alert payload to score against",
+ )
+
+ try:
+ result = score_groundedness(reasoning, evidence_blob)
+ except Exception as exc: # noqa: BLE001 - a scoring failure must not change the verdict
+ logger.debug("groundedness_gate.failed", error=str(exc))
+ return unchanged
+
+ if result.score >= floor():
+ return GateOutcome(verdict=verdict, confidence=confidence, score=result.score)
+
+ hallucinated = tuple(result.hallucinated[:10])
+ return GateOutcome(
+ verdict=dispositions.NEEDS_REVIEW,
+ # Confidence describes the demoted verdict now, not the discarded one.
+ confidence=min(float(confidence or 0.0), result.score),
+ score=result.score,
+ demoted=True,
+ reason=(
+ f"Verdict demoted to needs_review: only {result.score:.0%} of the indicators cited in "
+ f"the reasoning appear in the evidence (unsupported: {', '.join(hallucinated[:5])})."
+ ),
+ hallucinated=hallucinated,
+ )
+
+
+__all__ = ["DEFAULT_FLOOR", "GateOutcome", "evaluate", "floor", "gate_enabled"]
diff --git a/services/agents/app/investigator/orchestrator.py b/services/agents/app/investigator/orchestrator.py
index 6e85fc137..1c6397b69 100644
--- a/services/agents/app/investigator/orchestrator.py
+++ b/services/agents/app/investigator/orchestrator.py
@@ -20,6 +20,7 @@ import structlog
from langgraph.graph import END, START, StateGraph
from opentelemetry import trace
+from app.confidence import verdict_gate
from app.core.cost_telemetry import CostTracker
from . import ledger
@@ -146,6 +147,72 @@ def _build_graph():
# ---------------------------------------------------------------------------
+def _apply_groundedness(state: InvestigatorState) -> None:
+ """Score the forensic analysis against the evidence, and say so if it is thin.
+
+ The gate was real, default-on and demoting, and lived only in
+ `workers/fused_alert_consumer.py` -- the background auto-triage path. This
+ path, the one an analyst launches deliberately and is most likely to act
+ on, had no check at all.
+
+ It could not simply have been copied here, because it scores against
+ `raw_alert` and on this path `raw_alert` was `{}`: the console sent a
+ restated title and nothing else. With no evidence every indicator reads as
+ unsupported, so the gate would have demoted everything, and tuning around
+ that would have made it certify anything. The payload flows now --
+ `services/api` loads the case's alerts and their raw events -- so the
+ measurement means something.
+
+ The intervention differs from auto-triage's on purpose. Nothing
+ auto-closes here; a human reads this. So rather than demoting a verdict
+ it lowers the reported confidence to the measured groundedness and writes
+ the caveat into the summary the analyst actually reads. A number quietly
+ reduced with no explanation would be worse than leaving it alone.
+ """
+ forensic = state.forensic
+ reasoning = " ".join(
+ str(part)
+ for part in [
+ forensic.root_cause_hypothesis,
+ forensic.summary,
+ forensic.blast_radius,
+ *(forensic.artefacts or []),
+ ]
+ if part
+ )
+
+ outcome = verdict_gate.evaluate(
+ # This path has no auto-closing disposition, so the gate is asked
+ # about the analysis itself. `benign` is the auto-closeable member
+ # that makes `evaluate` score rather than skip; the verdict it returns
+ # is discarded and only the measurement is used.
+ verdict="benign",
+ confidence=float(forensic.confidence or 0.0),
+ reasoning=reasoning,
+ raw_alert=state.raw_alert,
+ alert_summary=state.alert_summary,
+ )
+
+ forensic.groundedness = outcome.score
+ if not outcome.demoted:
+ return
+
+ logger.warning(
+ "investigation.ungrounded_analysis",
+ run_id=str(state.run_id),
+ case_id=state.case_id,
+ groundedness=outcome.score,
+ hallucinated=list(outcome.hallucinated[:10]),
+ )
+ forensic.confidence = outcome.confidence
+ caveat = (
+ f"Groundedness {outcome.score:.0%}: some indicators cited above do not appear in the "
+ f"evidence provided to the agent ({', '.join(outcome.hallucinated[:5])}). "
+ "Treat them as unverified."
+ )
+ forensic.summary = f"{forensic.summary}\n\n{caveat}" if forensic.summary else caveat
+
+
class InvestigatorOrchestrator:
"""High-level wrapper around the compiled LangGraph."""
@@ -368,6 +435,10 @@ class InvestigatorOrchestrator:
cost_summary = tracker.summary()
if last_state is not None:
last_state.cost_summary = cost_summary
+ # After the run and before anything is persisted or emitted,
+ # so the ledger, the report and the `done` event all carry the
+ # same caveated numbers.
+ _apply_groundedness(last_state)
# Emit the final "done" event with the complete state payload
if last_state is not None:
diff --git a/services/agents/app/investigator/state.py b/services/agents/app/investigator/state.py
index 40312ea5b..001fafe6f 100644
--- a/services/agents/app/investigator/state.py
+++ b/services/agents/app/investigator/state.py
@@ -81,6 +81,16 @@ class ForensicFindings(BaseModel):
blast_radius: str = ""
confidence: float = 0.0 # 0–1
summary: str = ""
+ #: What fraction of the concrete indicators this analysis asserts -- IPs,
+ #: hashes, CVEs, techniques, domains -- actually appear in the evidence
+ #: the agent was given.
+ #:
+ #: `None` means **not scored**, which is a real and common state: a case
+ #: opened by hand carries no alert payload, and scoring prose against an
+ #: empty evidence set would mark every indicator unsupported and report
+ #: that as a finding about the model. Distinct from `0.0`, which means it
+ #: was scored and nothing was supported.
+ groundedness: float | None = None
class ResponderPlan(BaseModel):
diff --git a/services/agents/tests/test_investigator_groundedness.py b/services/agents/tests/test_investigator_groundedness.py
new file mode 100644
index 000000000..37dc135af
--- /dev/null
+++ b/services/agents/tests/test_investigator_groundedness.py
@@ -0,0 +1,191 @@
+"""The investigator's analysis is scored against the evidence it was given.
+
+What was missing
+----------------
+`score_groundedness` measures what fraction of the concrete indicators an
+output asserts -- IPs, hashes, CVEs, techniques, domains -- actually appear in
+the evidence. The gate around it was real, default-on and demoting, and it
+existed in exactly one place: `workers/fused_alert_consumer.py`, the
+background auto-triage path.
+
+The investigator path had none. A verdict reached through
+`POST /cases/{id}/investigate` -- launched deliberately by an analyst, read
+carefully, most likely to be acted on -- was never checked, while the path
+nobody watches was.
+
+Why it had to wait for the payload
+----------------------------------
+The gate scores against `raw_alert`, and on this path `raw_alert` was `{}`:
+the console sent the literal string `"Investigate alert: <title>"`. With no
+evidence, `_extract` finds no indicators to support anything, so **every**
+indicator the model mentions reads as unsupported and the gate demotes
+unconditionally. That is not a cautious default -- it is a measurement of
+nothing, reported as a finding about the model, and lowering the floor to
+cope would have made it certify anything.
+
+`test_no_evidence_is_not_scored` below is the test that pins the refusal.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+def _state(*, raw_alert: dict | None = None, summary: str = "", hypothesis: str = "", confidence: float = 0.9):
+ from app.investigator.state import ForensicFindings, InvestigatorState
+
+ state = InvestigatorState(case_id="CASE-1", tenant_id="t")
+ state.raw_alert = raw_alert if raw_alert is not None else {}
+ state.alert_summary = summary
+ state.forensic = ForensicFindings(
+ root_cause_hypothesis=hypothesis,
+ summary=hypothesis,
+ confidence=confidence,
+ )
+ return state
+
+
+class TestTheGateRefusesToScoreNothing:
+ def test_no_evidence_is_not_scored(self) -> None:
+ """The reason this could not be wired before the payload flowed.
+
+ An empty evidence set makes every cited indicator unsupported, so a
+ gate that scored anyway would demote every investigation on a
+ hand-opened case -- and would look like it was catching hallucination.
+ """
+ from app.confidence import verdict_gate
+
+ outcome = verdict_gate.evaluate(
+ verdict="benign",
+ confidence=0.9,
+ reasoning="The host 10.1.2.3 contacted evil.example.com and dropped a1b2c3d4.",
+ raw_alert={},
+ )
+
+ assert outcome.skipped, "scored against no evidence"
+ assert outcome.score is None
+ assert not outcome.demoted
+ assert outcome.confidence == 0.9
+ assert "no alert payload" in outcome.reason
+
+ def test_an_unscored_run_reports_none_not_zero(self) -> None:
+ """`0.0` would mean "scored, nothing supported". A case opened by hand
+ has not been measured, and rendering that as a hard zero is the
+ fabricated-metric failure in miniature."""
+ from app.investigator.orchestrator import _apply_groundedness
+
+ state = _state(raw_alert={}, hypothesis="Something involving 10.1.2.3.")
+
+ _apply_groundedness(state)
+
+ assert state.forensic.groundedness is None
+ assert state.forensic.confidence == 0.9
+
+
+class TestItScoresWhenThereIsEvidence:
+ def test_a_grounded_analysis_keeps_its_confidence(self) -> None:
+ from app.investigator.orchestrator import _apply_groundedness
+
+ state = _state(
+ raw_alert={
+ "alerts": [
+ {
+ "raw_event": {
+ "src_ip": "10.1.2.3",
+ "dest_host": "evil.example.com",
+ "sha256": "a1b2c3d4",
+ }
+ }
+ ]
+ },
+ hypothesis="Host 10.1.2.3 contacted evil.example.com and dropped a1b2c3d4.",
+ confidence=0.88,
+ )
+
+ _apply_groundedness(state)
+
+ assert state.forensic.groundedness is not None
+ assert state.forensic.confidence == pytest.approx(0.88)
+ assert "Groundedness" not in state.forensic.summary
+
+ def test_an_invented_indicator_lowers_confidence_and_says_why(self) -> None:
+ """The whole point. A confident analysis citing an address that
+ appears nowhere in the evidence used to be persisted, reported and
+ acted on with nothing recording that it was invented."""
+ from app.investigator.orchestrator import _apply_groundedness
+
+ state = _state(
+ raw_alert={"alerts": [{"raw_event": {"src_ip": "10.1.2.3"}}]},
+ hypothesis=("Host 203.0.113.77 beaconed to c2.invalid, dropped deadbeefcafe1234 and exploited CVE-2024-99999 via T1566.002."),
+ confidence=0.95,
+ )
+
+ _apply_groundedness(state)
+
+ assert state.forensic.groundedness is not None
+ assert state.forensic.confidence < 0.95, "confidence was not reduced"
+ assert "Groundedness" in state.forensic.summary
+ assert "unverified" in state.forensic.summary
+
+ def test_the_caveat_names_the_unsupported_indicators(self) -> None:
+ """A bare score tells an analyst something is wrong without saying
+ what, which is the kind of warning people learn to scroll past."""
+ from app.investigator.orchestrator import _apply_groundedness
+
+ state = _state(
+ raw_alert={"alerts": [{"raw_event": {"src_ip": "10.1.2.3"}}]},
+ hypothesis="Traffic to 198.51.100.42 and 203.0.113.77 from an unknown binary.",
+ confidence=0.9,
+ )
+
+ _apply_groundedness(state)
+
+ assert "198.51.100.42" in state.forensic.summary or "203.0.113.77" in state.forensic.summary
+
+
+class TestTheSwitchStillWorks:
+ def test_the_gate_can_be_turned_off(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from app.confidence import verdict_gate
+
+ monkeypatch.setenv("AISOC_AGENT_GROUNDEDNESS_GATE", "0")
+
+ outcome = verdict_gate.evaluate(
+ verdict="benign",
+ confidence=0.9,
+ reasoning="Entirely invented 203.0.113.77.",
+ raw_alert={"src_ip": "10.1.2.3"},
+ )
+
+ assert outcome.skipped
+ assert outcome.confidence == 0.9
+
+ def test_an_escalating_verdict_is_left_alone(self) -> None:
+ """Demoting something already routed to a human adds review load
+ without reducing risk."""
+ from app.confidence import verdict_gate
+
+ outcome = verdict_gate.evaluate(
+ verdict="true_positive",
+ confidence=0.9,
+ reasoning="Entirely invented 203.0.113.77.",
+ raw_alert={"src_ip": "10.1.2.3"},
+ )
+
+ assert outcome.skipped
+ assert outcome.verdict == "true_positive"
+
+
+class TestItIsActuallyReachable:
+ def test_the_orchestrator_calls_it(self) -> None:
+ """The failure mode this whole plan item is about: a mechanism that
+ exists, is tested, and has no caller on the path that needs it."""
+ import inspect
+
+ from app.investigator import orchestrator
+
+ source = inspect.getsource(orchestrator.InvestigatorOrchestrator)
+ module_source = inspect.getsource(orchestrator)
+
+ assert "_apply_groundedness(" in module_source
+ assert module_source.count("_apply_groundedness(") >= 2, "the gate is defined but never called — that is the defect, not the fix"
+ assert source # the class exists and was readable
diff --git a/services/api/app/api/v1/deps.py b/services/api/app/api/v1/deps.py
index e6ee1bc9a..bc8cf7819 100644
--- a/services/api/app/api/v1/deps.py
+++ b/services/api/app/api/v1/deps.py
@@ -42,7 +42,13 @@ from app.api.v1.dev_auth import (
is_dev_mode,
)
from app.core.permission_cache import grants, resolve_permissions
-from app.core.security import decode_token, has_permission, hash_api_key, token_is_revoked
+from app.core.security import (
+ ROLE_PERMISSIONS,
+ decode_token,
+ has_permission,
+ hash_api_key,
+ token_is_revoked,
+)
from app.db.database import get_db
from app.models.tenant import ApiKey, Tenant, User
@@ -134,6 +140,44 @@ class CurrentUser:
detail=f"Permission denied: {permission}",
)
+ def effective_permissions(self) -> list[str]:
+ """Every permission string this principal holds, in one list.
+
+ `require_permission` above answers "may this principal do X". This
+ answers "what may this principal do", which is what a *downstream*
+ service needs: `services/actions` re-authorises an approval itself,
+ and it cannot ask us one verb at a time.
+
+ Same three-step order as `require_permission`, deliberately. Two
+ answers from two orders would mean a caller allowed to approve
+ something the same principal is refused for elsewhere, and the
+ divergence would show up as an intermittent 403 rather than as a bug.
+
+ This exists because `approvals.py` was reading `user.roles` and
+ `user.permissions` -- neither of which this class defines -- through
+ `getattr(..., [])`. Both defaults fired silently, the actions service
+ received an empty permission list, and since `has_action_permission`
+ denies unconditionally on an empty list, **every** approval 502'd while
+ the approval row recorded the decision.
+
+ Returns a list rather than a set because it crosses a JSON boundary;
+ sorted so two identical principals produce identical request bodies
+ and a diff of two audit entries is readable.
+ """
+ if self.scopes is not None:
+ # An API key's scopes are an explicit, deliberately narrower grant
+ # than its owner's role. Inheriting the owner's full set here would
+ # defeat the point of scoping a key.
+ return sorted(set(self.scopes))
+ if self.resolved_permissions is not None:
+ return sorted(self.resolved_permissions)
+ # Static fallback. `ROLE_PERMISSIONS` is read here, in the one module
+ # that owns principal resolution, rather than in a route -- a route
+ # deciding its own permissions is what `check_one_permission_model`
+ # refuses, and it refuses it because a published advisory came from
+ # exactly that.
+ return sorted(set(ROLE_PERMISSIONS.get(self.role, [])))
+
async def has_permission_db(self, permission: str, db: AsyncSession) -> bool:
"""Check permission via RBAC tables (granular RBAC).
diff --git a/services/api/app/api/v1/endpoints/approvals.py b/services/api/app/api/v1/endpoints/approvals.py
index cf32be74e..34c0d750c 100644
--- a/services/api/app/api/v1/endpoints/approvals.py
+++ b/services/api/app/api/v1/endpoints/approvals.py
@@ -311,11 +311,26 @@ async def _dispatch_decision(
# identifier. Without that, "which action did this approval authorise"
# requires a join nobody wrote.
action_id = str(row.id)
+ # `CurrentUser` has `role` (singular), `scopes` and `resolved_permissions`.
+ # This used to read `user.roles` and `user.permissions` through
+ # `getattr(..., [])`, and since neither attribute exists both defaults
+ # fired silently -- so the actions service received an empty permission
+ # list, `has_action_permission` denied unconditionally, and *every*
+ # approval came back 502 with the decision already recorded.
+ #
+ # Resolved by the principal rather than here on purpose: a route deciding
+ # its own permissions is what `check_one_permission_model` refuses, and
+ # `effective_permissions()` uses the same scopes -> resolved -> role order
+ # as `require_permission`, so one principal cannot be allowed to approve
+ # something it would be refused for elsewhere.
+ permissions = user.effective_permissions()
principal = {
"user_id": str(user.user_id),
"email": getattr(user, "email", None),
- "roles": list(getattr(user, "roles", []) or []),
- "permissions": list(getattr(user, "permissions", []) or []),
+ # Singular on this class; sent as a list because that is the shape
+ # `services/actions` reads.
+ "roles": [user.role] if user.role else [],
+ "permissions": permissions,
}
try:
@@ -331,6 +346,11 @@ async def _dispatch_decision(
# approver here would make them both, and separation of duties
# would pass by accident.
requested_by=row.requested_by or "agent",
+ # Identifies the caller to the gate. Omitting it was harmless only
+ # while `AISOC_ACTIONS_REQUIRE_PRINCIPAL` defaults false; turning
+ # that on would have broken the submit leg exactly as the decide
+ # leg was broken.
+ principal=principal,
)
except ActionsServiceError as exc:
logger.warning(
diff --git a/services/api/app/api/v1/endpoints/cases.py b/services/api/app/api/v1/endpoints/cases.py
index 595a295a7..acc24c6f7 100644
--- a/services/api/app/api/v1/endpoints/cases.py
+++ b/services/api/app/api/v1/endpoints/cases.py
@@ -51,6 +51,7 @@ from sqlalchemy import text
from app.api.v1.deps import AuthUser, DBSession, require_permission
from app.core.logging import safe_log_value
from app.services import case_orchestration, case_status, evidence_custody
+from app.services.audit import emit_audit
from app.services.case_fanout import (
FanoutResult,
fanout_create_case,
@@ -179,6 +180,15 @@ class CaseResponse(BaseModel):
triaged_at: datetime | None
resolved_at: datetime | None
closed_at: datetime | None
+ #: When this case was last reopened. `None` means never -- which is the
+ #: honest value for every row that predates migration 090, since we
+ #: cannot know whether a historical case was reopened and inventing a
+ #: timestamp would be worse than saying nothing.
+ reopened_at: datetime | None = None
+ #: How many times. `reopened_at` is overwritten on each reopen, so it
+ #: cannot tell one reopen from four.
+ reopen_count: int = 0
+ reopen_reason: str | None = None
created_at: datetime
updated_at: datetime
created_by: str | None
@@ -318,6 +328,11 @@ def _row_to_case(row: Any) -> CaseResponse:
description=row.description,
severity=row.severity,
status=row.status,
+ # `getattr` with a default because this mapper is also handed rows
+ # from queries that select an explicit column list.
+ reopened_at=getattr(row, "reopened_at", None),
+ reopen_count=getattr(row, "reopen_count", 0) or 0,
+ reopen_reason=getattr(row, "reopen_reason", None),
assignee=row.assignee,
mitre_techniques=_coerce_mitre(row.mitre_techniques),
alert_ids=list(row.alert_ids or []),
@@ -522,6 +537,131 @@ async def get_case(case_id: str, db: DBSession, user: AuthUser) -> CaseResponse:
return _row_to_case(row)
+class ReopenCaseRequest(BaseModel):
+ """Why this case is coming back."""
+
+ reason: str = Field(
+ min_length=8,
+ max_length=2000,
+ description="Why the case is being reopened. Recorded on the case and in the audit log.",
+ )
+ #: Where it lands. Restricted to the states a case can genuinely resume
+ #: in -- reopening straight to `contained` would assert a containment
+ #: nobody performed on this pass.
+ status: Literal["new", "triaged", "investigating"] = "investigating"
+
+
[email protected]("/{case_id}/reopen", response_model=CaseResponse, summary="Reopen a closed case")
+async def reopen_case(
+ case_id: str,
+ body: ReopenCaseRequest,
+ db: DBSession,
+ user: Annotated[AuthUser, Depends(require_permission("cases:write"))],
+) -> CaseResponse:
+ """Bring a terminal case back, deliberately and on the record.
+
+ Its own route rather than a backward edge in `TRANSITIONS`. The forward-only
+ machine is what makes "this case was closed" mean something, and adding
+ `closed -> investigating` to the table would let an ordinary `PATCH` --
+ a title edit that happens to carry a status -- walk a case backwards
+ silently. `PATCH` stays forward-only.
+
+ Three things separate this from a status change:
+
+ * a reason is required, because an unexplained reopen is exactly what an
+ auditor asks about six months later;
+ * `reopen_count` increments, so a case reopened four times is
+ distinguishable from one reopened once;
+ * `closed_at` and `resolved_at` are cleared, because leaving them set
+ would make the case terminal and active at the same time -- and every
+ closure metric reads those columns.
+ """
+ cid = await _resolve_case_id(case_id, db, user.tenant_id)
+ existing = (
+ await db.execute(
+ text("SELECT status, reopen_count FROM aisoc_cases WHERE id = :id AND tenant_id = :tenant_id").bindparams(
+ id=cid, tenant_id=user.tenant_id
+ )
+ )
+ ).fetchone()
+ if not existing:
+ raise HTTPException(status_code=404, detail="Case not found.")
+
+ if existing.status not in case_status.TERMINAL_STATUSES:
+ raise HTTPException(
+ status_code=409,
+ detail=(
+ f"Case is {existing.status!r}, which is not a terminal state, so there is nothing "
+ f"to reopen. Use PATCH to move it to {sorted(case_status.TRANSITIONS.get(existing.status, set()))}."
+ ),
+ )
+
+ now = datetime.now(UTC)
+ await db.execute(
+ text(
+ """
+ UPDATE aisoc_cases
+ SET status = :status,
+ reopened_at = :now,
+ reopen_count = COALESCE(reopen_count, 0) + 1,
+ reopen_reason = :reason,
+ -- Cleared deliberately: a case that is open again has not
+ -- been closed, and every closure metric reads these.
+ closed_at = NULL,
+ resolved_at = NULL,
+ updated_at = :now
+ WHERE id = :id AND tenant_id = :tenant_id
+ """
+ ).bindparams(
+ status=body.status,
+ now=now,
+ reason=body.reason,
+ id=cid,
+ tenant_id=user.tenant_id,
+ )
+ )
+ await db.commit()
+
+ try:
+ await emit_audit(
+ db=db,
+ tenant_id=user.tenant_id,
+ actor_id=user.user_id,
+ actor_email=user.email,
+ action="case.reopen",
+ resource="case",
+ resource_id=str(cid),
+ changes={
+ "from_status": existing.status,
+ "to_status": body.status,
+ "reason": body.reason,
+ "reopen_count": (existing.reopen_count or 0) + 1,
+ },
+ # Which credential, not just which person. A key owned by an
+ # analyst resolves to that analyst's email, so without this an
+ # auditor cannot tell "Dana reopened this at her console" from "a
+ # key Dana minted a year ago reopened it from a script" -- and
+ # those call for different responses.
+ api_key_prefix=getattr(user, "api_key_prefix", None),
+ )
+ except Exception: # noqa: BLE001 - an audit failure must not undo the reopen
+ # Roll the *failed audit attempt* back, not the reopen: that already
+ # committed above. Without this the session stays in a failed
+ # transaction and the read below raises, so an audit problem would
+ # surface to the caller as the reopen itself failing -- when in fact
+ # it succeeded and only the log entry did not. A live test caught
+ # exactly that.
+ await db.rollback()
+ logger.exception("cases.reopen.audit_failed case=%s", cid)
+
+ row = (
+ await db.execute(
+ text("SELECT * FROM aisoc_cases WHERE id = :id AND tenant_id = :tenant_id").bindparams(id=cid, tenant_id=user.tenant_id)
+ )
+ ).fetchone()
+ return _row_to_case(row)
+
+
@router.patch("/{case_id}", response_model=CaseResponse, summary="Update case")
async def update_case(
case_id: str, body: UpdateCaseRequest, db: DBSession, user: Annotated[AuthUser, Depends(require_permission("cases:write"))]
@@ -1217,6 +1357,101 @@ async def _agents_proxy(method: str, path: str, **kwargs: Any) -> httpx.Response
) from exc
+async def _investigation_evidence(db: Any, cid: Any, tenant_id: Any) -> tuple[str, dict[str, Any]]:
+ """Assemble what the forensic agent should reason over, from the case's alerts.
+
+ The console used to send the literal string `"Investigate alert: <title>"`
+ and nothing else, so the agent reasoned over a one-line title while
+ auto-triage -- the same agent, the other entry point -- correctly passed
+ the whole `raw_event`. Two paths into one investigator, one of them
+ starved.
+
+ The evidence was never missing. `aisoc_cases.alert_ids` is written at case
+ creation and read by nothing, and `InvestigationRequest` on the agents
+ side has always declared `raw_alert`. This reads the first and fills the
+ second.
+
+ Returns `(summary, raw_alert)`. `raw_alert` stays `{}` when the case has
+ no alerts, which is honest: a case opened by hand has no telemetry, and
+ inventing a shape would hand the groundedness gate something to certify.
+ """
+ case_row = (
+ await db.execute(
+ text("SELECT title, description, severity, alert_ids FROM aisoc_cases WHERE id = :id AND tenant_id = :tenant_id").bindparams(
+ id=cid, tenant_id=tenant_id
+ )
+ )
+ ).fetchone()
+ if case_row is None:
+ return "", {}
+
+ alert_ids = [str(a) for a in (case_row.alert_ids or [])]
+ if not alert_ids:
+ summary = f"{case_row.title}"
+ if case_row.description:
+ summary = f"{summary}\n\n{case_row.description}"
+ return summary, {}
+
+ # Bounded. A correlated case can carry hundreds of alerts and the prompt
+ # has a budget; the newest are the ones an analyst is looking at.
+ rows = (
+ await db.execute(
+ text(
+ """
+ SELECT id, title, description, severity, confidence, status,
+ connector_type, external_id, mitre_techniques, entities,
+ raw_event, created_at
+ FROM alerts
+ WHERE tenant_id = :tenant_id AND id = ANY(CAST(:ids AS uuid[]))
+ ORDER BY created_at DESC
+ LIMIT 25
+ """
+ ).bindparams(tenant_id=tenant_id, ids=alert_ids)
+ )
+ ).fetchall()
+
+ alerts = [
+ {
+ "id": str(r.id),
+ "title": r.title,
+ "description": r.description,
+ "severity": r.severity,
+ "confidence": r.confidence,
+ "status": r.status,
+ "source": r.connector_type,
+ "vendor_id": r.external_id,
+ "mitre_techniques": list(r.mitre_techniques or []),
+ "entities": r.entities or {},
+ # The payload the connector actually delivered. This is the whole
+ # point: everything above is our summary of it.
+ "raw_event": r.raw_event or {},
+ "observed_at": r.created_at.isoformat() if r.created_at else None,
+ }
+ for r in rows
+ ]
+
+ lines = [case_row.title]
+ if case_row.description:
+ lines.append(case_row.description)
+ lines.append(f"{len(alerts)} correlated alert(s) on this case:")
+ lines += [f" - [{a['severity']}] {a['title']} (source: {a['source'] or 'unknown'})" for a in alerts]
+
+ raw_alert: dict[str, Any] = {
+ "case": {
+ "id": str(cid),
+ "title": case_row.title,
+ "severity": case_row.severity,
+ },
+ "alerts": alerts,
+ # Stated rather than implied: the agent and the groundedness gate both
+ # need to know whether they are seeing everything.
+ "alert_count": len(alert_ids),
+ "alerts_included": len(alerts),
+ "truncated": len(alert_ids) > len(alerts),
+ }
+ return "\n".join(lines), raw_alert
+
+
@router.post("/{case_id}/investigate", summary="Launch investigation for case")
async def case_investigate(
case_id: str,
@@ -1233,6 +1468,23 @@ async def case_investigate(
if not exists:
raise HTTPException(status_code=404, detail="Case not found.")
+ # The evidence, assembled server-side from the case's own alerts rather
+ # than taken from the caller. The console was sending the literal string
+ # "Investigate alert: <title>", so the forensic agent reasoned over a
+ # headline while auto-triage passed the whole raw event to the same code.
+ #
+ # Server-side because the browser does not hold the raw events and should
+ # not be trusted with what the agent reasons over even if it did: an
+ # attacker-influenced payload reaching a prompt is the injection surface
+ # `PromptInjectionGuard` exists for, and narrowing it to data we loaded
+ # ourselves is cheaper than guarding it.
+ derived_summary, raw_alert = await _investigation_evidence(db, cid, user.tenant_id)
+ # A caller-supplied summary is kept as a note rather than used in place of
+ # the evidence, so an analyst can say why they are looking.
+ summary = derived_summary
+ if body.alert_summary:
+ summary = f"{body.alert_summary}\n\n{derived_summary}" if derived_summary else body.alert_summary
+
# Forward the authenticated tenant so the agents service attributes the run
# to the real tenant instead of falling back to the "default" placeholder,
# which the demo seed no longer maps to any tenant (issue #601). The ledger
@@ -1240,7 +1492,13 @@ async def case_investigate(
resp = await _agents_proxy(
"POST",
f"/api/v1/cases/{cid}/investigate",
- json={"alert_summary": body.alert_summary or "", "tenant_id": str(user.tenant_id)},
+ json={
+ "alert_summary": summary,
+ "tenant_id": str(user.tenant_id),
+ # Declared by `InvestigationRequest` on the agents side since it
+ # was written, and never sent by anything until now.
+ "raw_alert": raw_alert,
+ },
)
if resp.status_code >= 400:
raise HTTPException(status_code=resp.status_code, detail=resp.text)
diff --git a/services/api/app/api/v1/endpoints/metrics.py b/services/api/app/api/v1/endpoints/metrics.py
index 3df4d662b..281734efb 100644
--- a/services/api/app/api/v1/endpoints/metrics.py
+++ b/services/api/app/api/v1/endpoints/metrics.py
@@ -38,6 +38,7 @@ from app.models.connector import Connector
from app.models.detection_rule import DetectionRule
from app.models.remediation import RemediationGateLog
from app.services import case_status
+from app.services.alert_status import RESOLVED_STATUSES, UNRESOLVED_STATUSES
from app.services.resolution_time import (
MTTR_WINDOW,
tenant_case_mttr_minutes,
@@ -57,6 +58,10 @@ class AlertMetrics(BaseModel):
medium: int
low: int
resolvedToday: int
+ #: Alerts in a terminal state. `total` above is now **open work only**,
+ #: so without this the closed count would have disappeared from the
+ #: dashboard entirely when the active tile was corrected.
+ resolved: int = 0
# Mean time to resolve in **hours**, from the same closed cases and the
# same window as `/metrics/soc`'s `mttr_hours` and the MSSP portfolio's
# `mttr_minutes`. It used to average `alerts.resolved_at`, so the
@@ -236,24 +241,96 @@ class PipelineHealth(BaseModel):
generated_at: datetime
+#: The windows the console's time-window selector offers, and the only ones
+#: any metrics route accepts. One map rather than one per endpoint: the
+#: selector is global, so two endpoints disagreeing about what `7d` means
+#: would show a dashboard whose tiles describe different weeks.
+_FUNNEL_PERIOD_MAP: dict[str, timedelta] = {
+ "1h": timedelta(hours=1),
+ "24h": timedelta(hours=24),
+ "7d": timedelta(days=7),
+ "30d": timedelta(days=30),
+}
+
+#: `Query(...)` declaration shared by every route that takes a window, so the
+#: accepted set cannot drift between them or from `TIME_WINDOWS` in
+#: `apps/web/src/lib/timeWindow.ts`.
+_PERIOD_QUERY = Query("24h", pattern=r"^(1h|24h|7d|30d)$", description="Time window for this view.")
+
+
+async def _count_alerts_by_status(db, tenant_id) -> dict[str, int]:
+ """Alert counts for the dashboard tiles, split by whether work remains.
+
+ Every severity count here is scoped to **unresolved** alerts, because the
+ console labels them "Active Alerts" and "Critical — Require immediate
+ action". They were not scoped at all: the tiles counted the tenant's whole
+ historical intake, never went down, and a tenant who had resolved
+ everything still saw a red critical tile demanding immediate action on
+ work finished months ago.
+
+ The predicate is `app.services.alert_status`'s rather than a fifth
+ hand-written copy. Four other sites already had it right -- `alerts.py`'s
+ critical queue, the funnel query below, and `health.py` twice -- and the
+ tile being the odd one out is exactly how one rule written five times
+ drifts: each site looks locally correct.
+
+ `resolved` is returned alongside rather than dropped. Narrowing the active
+ tile must not lose the number, because "how much did we close" is a real
+ question.
+ """
+ unresolved = Alert.status.in_(UNRESOLVED_STATUSES)
+ scope = Alert.tenant_id == tenant_id
+
+ async def _n(*predicates) -> int:
+ return await db.scalar(select(func.count()).where(and_(scope, *predicates))) or 0
+
+ return {
+ "open": await _n(unresolved),
+ "resolved": await _n(Alert.status.in_(RESOLVED_STATUSES)),
+ "new": await _n(Alert.status == "new"),
+ "critical": await _n(unresolved, Alert.severity == "critical"),
+ "high": await _n(unresolved, Alert.severity == "high"),
+ "medium": await _n(unresolved, Alert.severity == "medium"),
+ "low": await _n(unresolved, Alert.severity == "low"),
+ }
+
+
@router.get("/dashboard", response_model=DashboardMetrics)
async def get_dashboard_metrics(
user: AuthUser,
db: DBSession,
+ period: str = _PERIOD_QUERY,
) -> DashboardMetrics:
- """Return aggregated KPI metrics for the dashboard overview tiles."""
+ """Return aggregated KPI metrics for the dashboard overview tiles.
+
+ `period` drives every windowed figure below. It did not exist: the console
+ shipped a global time-window selector whose only consumer was itself, so
+ changing it re-rendered a header and fetched nothing. The trend chart and
+ the "closed this week" tile were fixed at 7 days whatever the control
+ said.
+
+ Counts of *current state* -- open alerts by severity -- are deliberately
+ not windowed. "How many criticals are open" is a question about now, and
+ answering it for the last hour would hide the backlog rather than scope
+ it.
+ """
tenant_id = user.tenant_id
now = datetime.now(UTC)
today_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
- week_start = now - timedelta(days=7)
+ window = _FUNNEL_PERIOD_MAP[period]
+ week_start = now - window
# ── Alert counts ──────────────────────────────────────────────────────────
- total_q = await db.scalar(select(func.count()).where(Alert.tenant_id == tenant_id))
- new_q = await db.scalar(select(func.count()).where(and_(Alert.tenant_id == tenant_id, Alert.status == "new")))
- critical_q = await db.scalar(select(func.count()).where(and_(Alert.tenant_id == tenant_id, Alert.severity == "critical")))
- high_q = await db.scalar(select(func.count()).where(and_(Alert.tenant_id == tenant_id, Alert.severity == "high")))
- medium_q = await db.scalar(select(func.count()).where(and_(Alert.tenant_id == tenant_id, Alert.severity == "medium")))
- low_q = await db.scalar(select(func.count()).where(and_(Alert.tenant_id == tenant_id, Alert.severity == "low")))
+ # Unresolved only. See `_count_alerts_by_status`: these tiles are labelled
+ # "Active" and "Require immediate action", and counting the historical
+ # backlog made both permanently wrong and permanently rising.
+ counts = await _count_alerts_by_status(db, tenant_id)
+ total_q = counts["open"]
+ new_q = counts["new"]
+ critical_q = counts["critical"]
+ high_q = counts["high"]
+ medium_q = counts["medium"]
+ low_q = counts["low"]
resolved_today_q = await db.scalar(
select(func.count()).where(
and_(
@@ -278,6 +355,10 @@ async def get_dashboard_metrics(
medium=medium_q or 0,
low=low_q or 0,
resolvedToday=resolved_today_q or 0,
+ # Reported rather than dropped: narrowing the active tile must not
+ # lose the number, because "how much have we closed" is a real
+ # question and the dashboard is where it is asked.
+ resolved=counts["resolved"],
mttr=round(float(mttr_dashboard_q or 0.0), 2),
mttr_sample_count=mttr_dashboard_samples,
)
@@ -469,6 +550,7 @@ class SOCMetrics(BaseModel):
async def get_soc_metrics(
user: AuthUser,
db: DBSession,
+ period: str = _PERIOD_QUERY,
) -> SOCMetrics:
"""Return SOC-level KPIs, ATT&CK heatmap, and confidence calibration curve.
@@ -479,7 +561,9 @@ async def get_soc_metrics(
"""
tenant_id = user.tenant_id
now = datetime.now(UTC)
- week_start = now - timedelta(days=7)
+ # Windowed by the caller's selection. Was a hardcoded 7 days, so the SOC
+ # panel described a different period from whatever the selector showed.
+ week_start = now - _FUNNEL_PERIOD_MAP[period]
# ── MTTD ──────────────────────────────────────────────────────────────────
# Mean time from alert creation to first analyst view (first_seen_at). This
@@ -761,14 +845,6 @@ async def get_alert_trend(
# ──────────────────────────── v1.5 funnel endpoint ────────────────────────────
-_FUNNEL_PERIOD_MAP: dict[str, timedelta] = {
- "1h": timedelta(hours=1),
- "24h": timedelta(hours=24),
- "7d": timedelta(days=7),
- "30d": timedelta(days=30),
-}
-
-
def _pct_delta(current: float, previous: float) -> float:
"""Compute period-over-period percentage change.
@@ -1116,7 +1192,7 @@ async def _mitre_covered(db, tenant_id, start, end) -> int:
async def get_funnel_metrics(
user: AuthUser,
db: DBSession,
- period: str = Query("24h", pattern=r"^(1h|24h|7d|30d)$"),
+ period: str = _PERIOD_QUERY,
) -> FunnelMetrics:
"""Return the live tenant funnel for the SOC Console (v1.5).
diff --git a/services/api/app/graphql/query.py b/services/api/app/graphql/query.py
index dac761146..423576829 100644
--- a/services/api/app/graphql/query.py
+++ b/services/api/app/graphql/query.py
@@ -40,6 +40,8 @@ from app.models.alert import Alert
from app.models.case import Case
from app.models.connector import Connector
from app.models.detection_rule import DetectionRule
+from app.services.alert_status import UNRESOLVED_STATUSES
+from app.services.case_status import OPEN_STATUSES
_AGENTS_URL = os.getenv("AGENTS_SERVICE_URL") or os.getenv("AGENTS_API_URL", "http://agents:8084")
@@ -412,12 +414,30 @@ class Query:
mean_time_to_respond_hours=None,
)
- total_alerts = (await db.execute(select(func.count()).select_from(Alert).where(Alert.tenant_id == tid))).scalar_one()
+ # Unresolved only, matching `/metrics/dashboard`. Both counts used to
+ # have no status predicate at all, so a GraphQL consumer saw the
+ # tenant's entire historical intake labelled as current state.
+ total_alerts = (
+ await db.execute(select(func.count()).select_from(Alert).where(Alert.tenant_id == tid, Alert.status.in_(UNRESOLVED_STATUSES)))
+ ).scalar_one()
+ # `["open", "in_progress"]` -- neither of which the case vocabulary
+ # contains, and the `aisoc_cases` CHECK forbids both. This count was
+ # therefore *structurally* zero: not wrong by a little, incapable of
+ # ever returning anything else. Reading `OPEN_STATUSES` rather than
+ # naming states inline is what stops the next copy drifting.
open_cases = (
- await db.execute(select(func.count()).select_from(Case).where(Case.tenant_id == tid, Case.status.in_(["open", "in_progress"])))
+ await db.execute(select(func.count()).select_from(Case).where(Case.tenant_id == tid, Case.status.in_(OPEN_STATUSES)))
).scalar_one()
critical_alerts = (
- await db.execute(select(func.count()).select_from(Alert).where(Alert.tenant_id == tid, Alert.severity == "critical"))
+ await db.execute(
+ select(func.count())
+ .select_from(Alert)
+ .where(
+ Alert.tenant_id == tid,
+ Alert.severity == "critical",
+ Alert.status.in_(UNRESOLVED_STATUSES),
+ )
+ )
).scalar_one()
cutoff = datetime.now(UTC) - timedelta(hours=24)
alerts_24h = (
diff --git a/services/api/app/models/case.py b/services/api/app/models/case.py
index a3266be9a..477a522c2 100644
--- a/services/api/app/models/case.py
+++ b/services/api/app/models/case.py
@@ -3,7 +3,7 @@
import uuid
from datetime import UTC, datetime
-from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text
from sqlalchemy.dialects.postgresql import ARRAY, JSONB, UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
@@ -25,7 +25,10 @@ class Case(Base):
case_number: Mapped[str] = mapped_column(String(30), unique=True, nullable=False, index=True)
title: Mapped[str] = mapped_column(String(500), nullable=False)
description: Mapped[str | None] = mapped_column(Text, nullable=True)
- status: Mapped[str] = mapped_column(String(30), default="open", index=True)
+ # "new", not "open". The ORM default seeds every row that does not set a
+ # status explicitly, and "open" is not in the `aisoc_cases` CHECK -- so
+ # the default value for this column could never be written.
+ status: Mapped[str] = mapped_column(String(30), default="new", index=True)
priority: Mapped[str] = mapped_column(String(20), default="medium", index=True)
severity: Mapped[str] = mapped_column(String(20), default="medium")
case_type: Mapped[str] = mapped_column(String(50), default="security_incident")
@@ -60,6 +63,14 @@ class Case(Base):
lessons_learned: Mapped[str | None] = mapped_column(Text, nullable=True)
closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+ # Reopening is a deliberate act with its own route, not a backward edge in
+ # the transition table -- see migration 090. NULL means never reopened,
+ # which is the honest value for every row that predates the column.
+ reopened_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+ # `reopened_at` is overwritten on each reopen, so it cannot distinguish a
+ # case reopened once from one reopened four times. This can.
+ reopen_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")
+ reopen_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC), index=True)
updated_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True),
diff --git a/services/api/app/services/alert_status.py b/services/api/app/services/alert_status.py
new file mode 100644
index 000000000..3e2c2b48b
--- /dev/null
+++ b/services/api/app/services/alert_status.py
@@ -0,0 +1,64 @@
+"""One definition of "is this alert still someone's problem".
+
+Why this module exists
+----------------------
+The dashboard's **Active Alerts** tile counted every alert the tenant had ever
+received -- no status filter at all -- while the console labelled the number
+*Active* and the severity tile beneath it *Critical — Require immediate
+action*. A tenant who had worked their queue to zero saw their entire
+historical backlog presented as outstanding work, and the number only ever
+went up.
+
+The filter was not missing for want of a definition. Four other places already
+had it: `alerts.py`'s critical-queue count, `metrics.py`'s own funnel query,
+and `health.py` twice. The tile was the outlier, which is the shape this
+module prevents -- five hand-written copies of one rule drift one at a time
+and nothing notices, because each site looks locally correct.
+
+`case_status.py` does the same job for cases, and this is deliberately its
+sibling rather than an extension of it: alerts and cases have different
+vocabularies, and merging them would invite the `open`/`in_progress` confusion
+that migration 083 spent an entire release untangling.
+
+The vocabulary
+--------------
+`models/alert.py` documents `new | triaging | in_progress | resolved`, and
+`closed` appears in the wild from vendor writeback. Both terminal states are
+listed here, because treating an unrecognised value as resolved would hide
+work rather than show it -- the safer default for a *queue* count is to
+include what you cannot classify.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+#: An analyst still has to do something about these.
+UNRESOLVED_STATUSES: Final[tuple[str, ...]] = ("new", "triaging", "in_progress")
+
+#: Finished. Separate from the above rather than derived, so a new status
+#: added to the model does not silently become "resolved" by omission.
+RESOLVED_STATUSES: Final[tuple[str, ...]] = ("resolved", "closed")
+
+
+def is_unresolved(status: str | None) -> bool:
+ """True when the alert is still outstanding.
+
+ An unknown status counts as unresolved. An alert whose state nobody
+ recognises is work that has not demonstrably finished, and dropping it
+ from a queue count would make the backlog look smaller than it is --
+ which is the direction of error this module exists to stop.
+ """
+ if status is None:
+ return True
+ return status.strip().lower() not in RESOLVED_STATUSES
+
+
+def is_resolved(status: str | None) -> bool:
+ """True only for a status that explicitly means finished."""
+ if status is None:
+ return False
+ return status.strip().lower() in RESOLVED_STATUSES
+
+
+__all__ = ["RESOLVED_STATUSES", "UNRESOLVED_STATUSES", "is_resolved", "is_unresolved"]
diff --git a/services/api/app/services/mssp_portfolio.py b/services/api/app/services/mssp_portfolio.py
index b5f0b7e72..384af9be1 100644
--- a/services/api/app/services/mssp_portfolio.py
+++ b/services/api/app/services/mssp_portfolio.py
@@ -36,6 +36,8 @@ from typing import Any
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession
+from app.services.alert_status import UNRESOLVED_STATUSES
+from app.services.case_status import OPEN_STATUSES
from app.services.entitlements import Headroom, headroom_for_tenant
from app.services.org_scope import PortfolioScope, require_scope
from app.services.resolution_time import (
@@ -128,10 +130,17 @@ class TenantRollup:
}
-# Statuses that mean "still needs someone". Kept in one place so the
-# portfolio backlog and a single tenant's queue cannot drift apart.
-_OPEN_ALERT_STATUSES = ("new", "open", "investigating", "triaged", "in_progress")
-_OPEN_CASE_STATUSES = ("open", "investigating", "in_progress", "containment", "eradication", "recovery")
+# Statuses that mean "still needs someone".
+#
+# Read from the canonical modules rather than retyped. Both tuples here named
+# states the schema forbids -- the alert one listed "open" and "investigating"
+# against a vocabulary of new/triaging/in_progress/resolved, and the case one
+# listed six values of which only "investigating" exists, inflating the
+# portfolio backlog with members that can never match while omitting the
+# states that can. Keeping a third copy "in one place" is what made it drift:
+# one place per service is still three places.
+_OPEN_ALERT_STATUSES = UNRESOLVED_STATUSES
+_OPEN_CASE_STATUSES = OPEN_STATUSES
async def tenant_rollups(db: AsyncSession, scope: PortfolioScope) -> list[TenantRollup]:
diff --git a/services/api/app/workers/hunt_scheduler.py b/services/api/app/workers/hunt_scheduler.py
index aacfd1707..e710a11c0 100644
--- a/services/api/app/workers/hunt_scheduler.py
+++ b/services/api/app/workers/hunt_scheduler.py
@@ -71,6 +71,7 @@ from app.db.cross_tenant import assert_cross_tenant_session
from app.db.database import AsyncSessionLocal
from app.models.case import Case
from app.models.saved_hunt import SavedHunt
+from app.services import case_status
from app.services.event_warehouse import (
HuntExecutionError,
HuntNotConfigured,
@@ -221,7 +222,12 @@ async def _open_case_for_hits(db: AsyncSession, hunt: SavedHunt, hit_count: int)
case_type="hunt_finding",
priority="medium",
severity="medium",
- status="open",
+ # `NEW`, not the literal "open". `aisoc_cases` has a CHECK listing
+ # new/triaged/investigating/contained/resolved/closed, so this INSERT
+ # was rejected outright -- a scheduled hunt that fired could not
+ # create its case at all, and the worker logged `case_opened` on the
+ # line below either way.
+ status=case_status.NEW,
tags=["scheduled-hunt", f"hunt:{hunt.id}"],
)
db.add(case)
diff --git a/services/api/migrations/090_case_reopen.sql b/services/api/migrations/090_case_reopen.sql
new file mode 100644
index 000000000..4d2f9cf3c
--- /dev/null
+++ b/services/api/migrations/090_case_reopen.sql
@@ -0,0 +1,59 @@
+-- Reopening a closed case: the column, before the route that writes it.
+--
+-- Why this migration exists
+-- -------------------------
+-- `case_status.TRANSITIONS[CLOSED]` is an empty set, so the state machine has
+-- no backward move and `PATCH /cases/{id}` refuses every transition out of
+-- `closed`. That is the right default: a forward-only machine is what makes
+-- "this case was closed" mean something, and letting an ordinary edit walk it
+-- backwards is how a containment gets silently undone.
+--
+-- But "closed in error" and "it came back" are real, and the only way to
+-- record either was to open a second case, which loses the history that makes
+-- the first one worth having.
+--
+-- So reopening becomes its own deliberate act with its own column, rather
+-- than a hole in the transition table. `PATCH` stays forward-only.
+--
+-- The ordering matters
+-- --------------------
+-- A previous attempt at this feature wrote `reopened_at` from the route
+-- without ever creating the column, so every call raised
+-- `UndefinedColumnError` -- the route was merged, looked complete, and had
+-- never once succeeded. The column lands first and on its own.
+
+ALTER TABLE aisoc_cases
+ -- When it was last reopened. NULL means never, which is the honest
+ -- default for the rows that already exist: we cannot know whether a
+ -- historical case was ever reopened, and back-filling a timestamp would
+ -- invent one.
+ ADD COLUMN IF NOT EXISTS reopened_at TIMESTAMPTZ,
+
+ -- How many times. A case reopened four times is a different conversation
+ -- from one reopened once, and `reopened_at` alone cannot tell them apart
+ -- because each reopen overwrites it.
+ --
+ -- Defaulted to 0 rather than NULL: unlike the timestamp, "no reopen has
+ -- been recorded since this column existed" genuinely is zero reopens
+ -- recorded, and a count that renders as blank would read as missing data.
+ ADD COLUMN IF NOT EXISTS reopen_count INTEGER NOT NULL DEFAULT 0,
+
+ -- Why, as given by the person who did it. Required by the route, which
+ -- is the point: an unexplained reopen is the thing an auditor asks about
+ -- six months later.
+ ADD COLUMN IF NOT EXISTS reopen_reason TEXT;
+
+COMMENT ON COLUMN aisoc_cases.reopened_at IS
+ 'When this case was last reopened from a terminal state. NULL means never.';
+COMMENT ON COLUMN aisoc_cases.reopen_count IS
+ 'How many times this case has been reopened. reopened_at only holds the most recent.';
+COMMENT ON COLUMN aisoc_cases.reopen_reason IS
+ 'Why it was last reopened, required at the point of reopening.';
+
+-- Finding reopened cases is the question this data is for -- a reopen rate is
+-- a quality signal about closure, not an incident-response metric -- and it
+-- is a small minority of rows, so a partial index is both cheap and the right
+-- shape.
+CREATE INDEX IF NOT EXISTS ix_aisoc_cases_reopened
+ ON aisoc_cases (tenant_id, reopened_at DESC)
+ WHERE reopened_at IS NOT NULL;
diff --git a/services/api/tests/test_alert_tiles_count_only_open_work.py b/services/api/tests/test_alert_tiles_count_only_open_work.py
new file mode 100644
index 000000000..71e43c339
--- /dev/null
+++ b/services/api/tests/test_alert_tiles_count_only_open_work.py
@@ -0,0 +1,248 @@
+"""A tenant who worked their queue to zero sees zero, not their whole history.
+
+The defect
+----------
+`GET /api/v1/metrics/dashboard` counted alerts like this:
+
+ total_q = count(where tenant_id = ...)
+ critical_q = count(where tenant_id = ... and severity = 'critical')
+
+No status filter on either. The console renders the first as **Active Alerts**
+and the second under **Critical — Require immediate action**, so both numbers
+were the tenant's entire historical intake. They never went down. A tenant who
+had triaged and resolved every alert still saw a red critical tile demanding
+immediate action on work finished months ago.
+
+The filter was not missing for want of a definition -- `alerts.py:710`,
+`metrics.py:1018` and `health.py:416` all already carried
+`status.in_(("new", "triaging", "in_progress"))`. The tile was simply the one
+site that never got it, which is why the fix routes them through
+`app.services.alert_status` rather than adding a fifth hand-written copy.
+
+Run against live Postgres, because the defect is a missing `WHERE` clause and
+a fake session that answers any query cannot tell a filtered count from an
+unfiltered one. Skips when no database answers so a local run stays green, but
+**cannot** skip where it is meant to run: `integration.yml` sets
+`MSSP_ISOLATION_REQUIRED=1` and an unreachable database is then a failure --
+a gate that quietly declines to run is the shape this file exists to catch.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+DSN = os.environ.get("DATABASE_URL", "")
+REQUIRED = os.environ.get("MSSP_ISOLATION_REQUIRED", "").strip() not in ("", "0", "false")
+
+# Fixed so a failure names something greppable.
+TENANT = uuid.UUID("0c100000-0000-0000-0000-00000000000a")
+
+
+@pytest_asyncio.fixture
+async def db():
+ if "postgres" not in DSN and not REQUIRED:
+ pytest.skip("needs a live Postgres with the migration chain applied (integration.yml)")
+ engine = create_async_engine(DSN)
+ try:
+ async with engine.connect() as probe:
+ await probe.execute(text("SELECT 1"))
+ except Exception as exc:
+ await engine.dispose()
+ if REQUIRED:
+ pytest.fail(
+ "MSSP_ISOLATION_REQUIRED is set but no database answered at DATABASE_URL — "
+ f"the alert-tile proof did not run: {type(exc).__name__}: {exc}"
+ )
+ pytest.skip(f"no database at DATABASE_URL ({type(exc).__name__}) — runs in integration.yml")
+
+ factory = async_sessionmaker(engine, expire_on_commit=False)
+ async with factory() as session:
+ await _reset(session)
+ try:
+ yield session
+ finally:
+ await _reset(session)
+ await engine.dispose()
+
+
+async def _reset(session) -> None:
+ await session.rollback()
+ await session.execute(text("DELETE FROM alerts WHERE tenant_id = CAST(:t AS uuid)"), {"t": str(TENANT)})
+ await session.execute(text("DELETE FROM tenants WHERE id = CAST(:t AS uuid)"), {"t": str(TENANT)})
+ await session.commit()
+
+
+async def _seed(session, pairs: list[tuple[str, str]]) -> None:
+ await session.execute(
+ text("INSERT INTO tenants (id, name, slug) VALUES (CAST(:t AS uuid), 'Tile Test', 'tile-test') ON CONFLICT (id) DO NOTHING"),
+ {"t": str(TENANT)},
+ )
+ for status, severity in pairs:
+ await session.execute(
+ text(
+ """
+ INSERT INTO alerts (id, tenant_id, title, severity, status, created_at, updated_at)
+ VALUES (CAST(:i AS uuid), CAST(:t AS uuid), :ti, :s, :st, NOW(), NOW())
+ """
+ ),
+ {
+ "i": str(uuid.uuid4()),
+ "t": str(TENANT),
+ "ti": f"{severity} alert in {status}",
+ "s": severity,
+ "st": status,
+ },
+ )
+ await session.commit()
+
+
+class TestTheActiveTileCountsOnlyOpenWork:
+ async def test_a_fully_worked_queue_reports_zero_active(self, db) -> None:
+ """The reproduction. Every alert resolved, so the tile must read 0.
+ Before the fix it read 4."""
+ from app.api.v1.endpoints.metrics import _count_alerts_by_status
+
+ await _seed(
+ db,
+ [
+ ("resolved", "critical"),
+ ("resolved", "high"),
+ ("closed", "critical"),
+ ("resolved", "medium"),
+ ],
+ )
+
+ counts = await _count_alerts_by_status(db, TENANT)
+
+ assert counts["open"] == 0, (
+ f"a tenant with every alert resolved shows {counts['open']} active — the tile is counting the historical backlog"
+ )
+
+ async def test_critical_counts_only_unresolved_criticals(self, db) -> None:
+ """'Require immediate action' is a claim about now."""
+ from app.api.v1.endpoints.metrics import _count_alerts_by_status
+
+ await _seed(db, [("resolved", "critical"), ("new", "critical")])
+
+ counts = await _count_alerts_by_status(db, TENANT)
+
+ assert counts["critical"] == 1
+
+ async def test_open_work_is_still_counted(self, db) -> None:
+ """The negative control. A filter that counted nothing would pass the
+ two tests above and make the dashboard useless."""
+ from app.api.v1.endpoints.metrics import _count_alerts_by_status
+
+ await _seed(db, [("new", "high"), ("triaging", "critical"), ("in_progress", "low")])
+
+ counts = await _count_alerts_by_status(db, TENANT)
+
+ assert counts["open"] == 3
+ assert counts["critical"] == 1
+ assert counts["high"] == 1
+
+ async def test_resolved_work_is_still_reported(self, db) -> None:
+ """Narrowing the tile must not lose the number. "How much did we
+ close" is a real question, and the answer should not vanish because
+ the other tile was corrected."""
+ from app.api.v1.endpoints.metrics import _count_alerts_by_status
+
+ await _seed(db, [("resolved", "high"), ("closed", "low"), ("new", "medium")])
+
+ counts = await _count_alerts_by_status(db, TENANT)
+
+ assert counts["resolved"] == 2
+ assert counts["open"] == 1
+
+ async def test_another_tenants_alerts_are_not_counted(self, db) -> None:
+ """Every count here is tenant-scoped, and a regression that dropped
+ the predicate would be a cross-tenant read rather than a wrong tile."""
+ from app.api.v1.endpoints.metrics import _count_alerts_by_status
+
+ await _seed(db, [("new", "critical")])
+ other = uuid.uuid4()
+
+ counts = await _count_alerts_by_status(db, other)
+
+ assert counts["open"] == 0
+
+
+class TestTheDefinitionIsSharedRatherThanCopied:
+ """No database needed: these hold wherever the suite runs, and a
+ module-level skip would have confined them to the integration job."""
+
+ def test_the_dashboard_uses_the_canonical_set(self) -> None:
+ from pathlib import Path
+
+ source = (Path(__file__).resolve().parents[1] / "app" / "api" / "v1" / "endpoints" / "metrics.py").read_text(encoding="utf-8")
+
+ assert "alert_status" in source, "metrics.py does not import the shared status definition"
+
+ def test_an_unknown_status_counts_as_open(self) -> None:
+ """The safer default for a queue: dropping an unrecognised status
+ would make the backlog look smaller than it is."""
+ from app.services.alert_status import is_unresolved
+
+ assert is_unresolved("some-state-nobody-added-here") is True
+ assert is_unresolved(None) is True
+
+ def test_both_terminal_spellings_are_resolved(self) -> None:
+ """`closed` arrives from vendor writeback, `resolved` from the
+ console. Recognising only one leaves the other in the queue forever."""
+ from app.services.alert_status import is_resolved
+
+ assert is_resolved("resolved") is True
+ assert is_resolved("closed") is True
+ assert is_resolved("triaging") is False
+
+
+class TestTheRouteItselfIsIntact:
+ """Call the route table, not just the helper.
+
+ Every test above exercises `_count_alerts_by_status` directly, and all of
+ them passed while `@router.get("/dashboard")` was accidentally attached to
+ that helper instead of to `get_dashboard_metrics` -- so the endpoint
+ returned a bare counts dict rather than `DashboardMetrics`. A gate caught
+ it; the tests could not, because they never asked the app what was mounted.
+
+ Read off `app.openapi()` rather than `app.routes`: on FastAPI 0.141.x
+ `include_router` leaves an opaque object in `app.routes` and the
+ `APIRoute` count is zero, so an enumeration there silently compares
+ nothing.
+ """
+
+ def test_the_dashboard_route_is_mounted_and_returns_the_right_model(self) -> None:
+ from app.main import app
+
+ spec = app.openapi()
+ operation = spec["paths"]["/api/v1/metrics/dashboard"]["get"]
+
+ schema = operation["responses"]["200"]["content"]["application/json"]["schema"]
+ assert "DashboardMetrics" in str(schema), f"/metrics/dashboard does not return DashboardMetrics; it returns {schema}"
+
+ def test_the_private_helper_is_not_a_route(self) -> None:
+ from app.main import app
+
+ spec = app.openapi()
+ names = {op.get("operationId", "") for path in spec["paths"].values() for op in path.values() if isinstance(op, dict)}
+
+ assert not any("count_alerts_by_status" in n for n in names), (
+ "the counting helper is mounted as an endpoint — a decorator is attached to the wrong function"
+ )
+
+ def test_both_windowed_routes_accept_a_period(self) -> None:
+ """The time-window selector drives these. A route that does not
+ declare the parameter 422s on every tile once the console sends it."""
+ from app.main import app
+
+ spec = app.openapi()
+ for path in ("/api/v1/metrics/dashboard", "/api/v1/metrics/soc"):
+ params = {p["name"] for p in spec["paths"][path]["get"].get("parameters", [])}
+ assert "period" in params, f"{path} does not accept a period"
diff --git a/services/api/tests/test_approval_dispatch.py b/services/api/tests/test_approval_dispatch.py
index 7399052e5..b39e9f3bf 100644
--- a/services/api/tests/test_approval_dispatch.py
+++ b/services/api/tests/test_approval_dispatch.py
@@ -40,12 +40,26 @@ def _row(**overrides):
def _user():
- return SimpleNamespace(
+ """A real `CurrentUser`, not a stand-in.
+
+ This was a `SimpleNamespace` carrying `roles=[...]` and
+ `permissions=[...]` -- two attributes `CurrentUser` has never defined. The
+ route read exactly those two through `getattr(..., [])`, so the double was
+ shaped around the defect: in tests the attributes were there and the
+ principal looked populated, while in production both defaults fired and
+ every approval shipped an empty permission list.
+
+ A double more accommodating than the real object cannot fail the way
+ production fails, which is the whole reason this one did not.
+ """
+ from app.api.v1.deps import CurrentUser
+
+ return CurrentUser(
user_id=USER,
tenant_id=TENANT,
+ role="soc_lead",
- roles=["soc_lead"],
- permissions=["cases:write"],
+ resolved_permissions=frozenset({"cases:write", "actions:execute:high"}),
)
@@ -186,3 +200,42 @@ class TestFailureIsVisible:
# Never "executed". Claiming execution on an unreachable executor is
# the failure mode this whole wave exists to remove.
assert result["state"] == "failed"
+
+
+class TestThePrincipalReachesTheActionsService:
+ """Nobody asserted on the principal, which is how an empty one shipped.
+
+ The suite above checks the *shape* of the dispatch -- that submit happens
+ before decide, that an unreachable service reports failed. It never looked
+ inside the principal, so a principal carrying no permissions at all passed
+ every test while 502-ing in production on the first real approval.
+ """
+
+ @pytest.mark.asyncio
+ async def test_the_decision_carries_a_non_empty_permission_set(self, calls: dict) -> None:
+ await endpoint._dispatch_decision(_row(), _user(), approve=True)
+
+ assert calls["decide"], "no decision reached the actions service"
+ approver = calls["decide"][0]["approver"]
+ assert approver["permissions"], (
+ "the approver's permission list is empty, which `has_action_permission` denies "
+ "unconditionally -- this is the defect that 502'd every approval"
+ )
+ assert "cases:write" in approver["permissions"]
+
+ @pytest.mark.asyncio
+ async def test_the_submit_leg_identifies_the_caller_too(self, calls: dict) -> None:
+ """Harmless only while `AISOC_ACTIONS_REQUIRE_PRINCIPAL` is false.
+ Turning it on would have broken submit exactly as decide was broken."""
+ await endpoint._dispatch_decision(_row(), _user(), approve=True)
+
+ assert calls["submit"], "no submit reached the actions service"
+ assert calls["submit"][0].get("principal"), "submit identifies no caller"
+
+ @pytest.mark.asyncio
+ async def test_the_role_travels_as_a_list(self, calls: dict) -> None:
+ """`CurrentUser.role` is singular and the actions service reads a
+ list. The old code read `user.roles`, which does not exist."""
+ await endpoint._dispatch_decision(_row(), _user(), approve=True)
+
+ assert calls["decide"][0]["approver"]["roles"] == ["soc_lead"]
diff --git a/services/api/tests/test_approval_principal_carries_permissions.py b/services/api/tests/test_approval_principal_carries_permissions.py
new file mode 100644
index 000000000..f67e7d889
--- /dev/null
+++ b/services/api/tests/test_approval_principal_carries_permissions.py
@@ -0,0 +1,195 @@
+"""An approval dispatch carries the approver's real permissions.
+
+The defect
+----------
+`_dispatch_decision` in `approvals.py` built its principal like this:
+
+ "roles": list(getattr(user, "roles", []) or []),
+ "permissions": list(getattr(user, "permissions", []) or []),
+
+`CurrentUser` defines **neither** attribute. It has `role` (singular),
+`scopes` and `resolved_permissions`. So both `getattr` defaults fired and the
+principal shipped an empty permission list, silently -- no exception, no log.
+
+Downstream, `services/actions`'s `has_action_permission` returns `False` on an
+empty list unconditionally, so `authorize_approver` raised, the actions service
+answered 403, and the operator saw a 502 reading *"Decision recorded, but the
+action service refused it"*. The approval row recorded the decision and the
+action never ran. **Every** approval, for every role, including platform admin.
+
+Why the fix is a method on `CurrentUser` and not a local helper
+---------------------------------------------------------------
+Resolving permissions inside a route means a route deciding its own
+authorisation, which `scripts/check_one_permission_model.py` refuses -- and it
+refuses it because a published advisory came from exactly that. The order also
+has to match `require_permission`'s, or a caller could be allowed to approve
+something the same principal would be refused for elsewhere. One method, one
+order, both callers.
+"""
+
+from __future__ import annotations
+
+import ast
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+APPROVALS = REPO_ROOT / "services" / "api" / "app" / "api" / "v1" / "endpoints" / "approvals.py"
+
+
+def _principal_for(**kwargs):
+ from app.api.v1.deps import CurrentUser
+
+ base = {
+ "user_id": uuid.uuid4(),
+ "tenant_id": uuid.uuid4(),
+ "role": "analyst",
+ "email": "[email protected]",
+ }
+ base.update(kwargs)
+ return CurrentUser(**base)
+
+
+class TestCurrentUserCanAnswerWhatItMayDo:
+ def test_the_method_exists(self) -> None:
+ from app.api.v1.deps import CurrentUser
+
+ assert hasattr(CurrentUser, "effective_permissions")
+
+ def test_an_api_key_principal_reports_its_scopes(self) -> None:
+ """First in the order, matching `require_permission`: a key's scopes
+ are an explicit, narrower grant than its owner's role."""
+ user = _principal_for(scopes=["actions:execute:low", "alerts:read"])
+
+ assert set(user.effective_permissions()) == {"actions:execute:low", "alerts:read"}
+
+ def test_a_database_resolved_principal_reports_that(self) -> None:
+ """Second: the database-backed set, which is the one a grant
+ revocation actually changes."""
+ user = _principal_for(resolved_permissions=frozenset({"cases:write", "actions:execute:high"}))
+
+ assert set(user.effective_permissions()) == {"cases:write", "actions:execute:high"}
+
+ def test_scopes_win_over_resolved_permissions(self) -> None:
+ """The order is not arbitrary. An API key must not inherit its owner's
+ full database grant set -- that is the whole point of scoping a key."""
+ user = _principal_for(
+ scopes=["alerts:read"],
+ resolved_permissions=frozenset({"*"}),
+ )
+
+ assert set(user.effective_permissions()) == {"alerts:read"}
+
+ def test_a_plain_session_falls_back_to_the_static_role_map(self) -> None:
+ """Third. This is the behaviour that shipped for fourteen releases, so
+ falling back to it is no worse than before -- and never returning an
+ empty list is the whole fix."""
+ user = _principal_for(role="admin")
+
+ assert user.effective_permissions(), "an admin session resolved to no permissions at all"
+
+ def test_an_unknown_role_is_empty_rather_than_wildcard(self) -> None:
+ """The negative control. Failing *open* here would make a typo in a
+ role name grant everything."""
+ user = _principal_for(role="not-a-real-role")
+
+ assert user.effective_permissions() == []
+
+
+class TestTheRouteUsesIt:
+ def test_the_dispatch_builds_its_principal_from_the_method(self) -> None:
+ source = APPROVALS.read_text(encoding="utf-8")
+
+ assert "effective_permissions()" in source, (
+ "approvals.py does not use CurrentUser.effective_permissions(), so the principal is "
+ "still assembled from attributes CurrentUser does not have"
+ )
+
+ def test_it_no_longer_reads_attributes_that_do_not_exist(self) -> None:
+ """The exact shape of the bug: `getattr(user, "permissions", [])` on an
+ object with no such attribute, defaulting to empty and denying
+ everything downstream."""
+ source = APPROVALS.read_text(encoding="utf-8")
+
+ assert 'getattr(user, "permissions"' not in source
+ assert 'getattr(user, "roles"' not in source
+
+ def test_the_route_does_not_import_the_static_map(self) -> None:
+ """`check_one_permission_model` refuses this, and it refuses it because
+ a published advisory came from a route deciding permissions for
+ itself."""
+ tree = ast.parse(APPROVALS.read_text(encoding="utf-8"))
+
+ imported: set[str] = set()
+ for node in ast.walk(tree):
+ if isinstance(node, ast.ImportFrom):
+ imported.update(a.name for a in node.names)
+
+ assert "ROLE_PERMISSIONS" not in imported, "approvals.py imports the static permission map. Resolve through CurrentUser instead."
+
+ def test_submit_also_identifies_its_caller(self) -> None:
+ """`submit_action` passed no principal at all, which is harmless only
+ while `AISOC_ACTIONS_REQUIRE_PRINCIPAL` defaults false. Flipping that
+ flag would have broken the submit leg the same way.
+
+ Read off the call's keyword arguments rather than a character window
+ around it -- a window is sensitive to how much comment sits between
+ the call and the argument, which is a property of the prose and not
+ of the code.
+ """
+ tree = ast.parse(APPROVALS.read_text(encoding="utf-8"))
+
+ submits = [
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "submit_action"
+ ]
+
+ assert submits, "submit_action is no longer called; re-point this test"
+ for call in submits:
+ kwargs = {kw.arg for kw in call.keywords}
+ assert "principal" in kwargs, "a submit_action call still identifies no caller"
+
+
+class TestTheDownstreamCheckWouldHaveDenied:
+ """Pins *why* an empty list was fatal, so the fix cannot be undone by
+ someone concluding the empty list was harmless.
+
+ Runs the real function in a subprocess rather than importing it. Both
+ `services/api` and `services/actions` name their top-level package `app`,
+ so importing the actions one into this process shadows the API's and the
+ test silently measures the wrong thing -- or, as here, fails to import at
+ all. A subprocess gets its own `sys.path` and genuinely executes the
+ shipped code.
+ """
+
+ @pytest.mark.parametrize("required", ["actions:execute:high", "actions:execute:low"])
+ def test_an_empty_permission_list_is_an_unconditional_denial(self, required: str) -> None:
+ actions_root = REPO_ROOT / "services" / "actions"
+ if not (actions_root / "app" / "security" / "authz.py").is_file():
+ pytest.skip("services/actions is not present in this checkout")
+
+ done = subprocess.run(
+ [
+ sys.executable,
+ "-c",
+ f"from app.security.authz import has_action_permission as h;print(h([], {required!r}))",
+ ],
+ cwd=actions_root,
+ capture_output=True,
+ text=True,
+ timeout=60,
+ check=False,
+ )
+
+ if done.returncode != 0:
+ pytest.skip(f"actions service deps unavailable here: {done.stderr.strip()[-160:]}")
+ assert done.stdout.strip() == "False", (
+ "an empty permission list no longer denies. If this changed deliberately, the "
+ "approval principal fix is still required -- an empty list means the approver's "
+ "permissions were never resolved."
+ )
diff --git a/services/api/tests/test_case_reopen.py b/services/api/tests/test_case_reopen.py
new file mode 100644
index 000000000..8a4b06fcf
--- /dev/null
+++ b/services/api/tests/test_case_reopen.py
@@ -0,0 +1,297 @@
+"""Reopening a closed case works, and `PATCH` still cannot do it.
+
+Why there is a route at all
+---------------------------
+`case_status.TRANSITIONS[CLOSED]` is an empty set, so the state machine has no
+backward move and `PATCH /cases/{id}` refuses every transition out of
+`closed`. That is the right default -- a forward-only machine is what makes
+"this case was closed" mean something.
+
+But "closed in error" and "it came back" are real, and the only way to record
+either was to open a second case, which discards the history that made the
+first one worth keeping. So reopening is its own deliberate act with its own
+column, rather than a hole punched in the transition table.
+
+Why this runs against live Postgres
+-----------------------------------
+A previous attempt wrote `reopened_at` from the route without ever creating
+the column, so **every call raised `UndefinedColumnError`** -- the route was
+merged, read as complete, and had never once succeeded. A mocked session
+answers any UPDATE, so only a real database can tell the difference between
+"this works" and "this names a column that does not exist".
+
+Skips when no database answers so a local run stays green, but cannot skip
+where it is meant to run: `integration.yml` sets `MSSP_ISOLATION_REQUIRED=1`
+and an unreachable database is then a failure.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+DSN = os.environ.get("DATABASE_URL", "")
+REQUIRED = os.environ.get("MSSP_ISOLATION_REQUIRED", "").strip() not in ("", "0", "false")
+
+TENANT = uuid.UUID("0e100000-0000-0000-0000-00000000000a")
+
+
+@pytest_asyncio.fixture
+async def db():
+ if "postgres" not in DSN and not REQUIRED:
+ pytest.skip("needs a live Postgres with the migration chain applied (integration.yml)")
+ engine = create_async_engine(DSN)
+ try:
+ async with engine.connect() as probe:
+ await probe.execute(text("SELECT 1"))
+ except Exception as exc:
+ await engine.dispose()
+ if REQUIRED:
+ pytest.fail(
+ "MSSP_ISOLATION_REQUIRED is set but no database answered at DATABASE_URL — "
+ f"the reopen proof did not run: {type(exc).__name__}: {exc}"
+ )
+ pytest.skip(f"no database at DATABASE_URL ({type(exc).__name__}) — runs in integration.yml")
+
+ factory = async_sessionmaker(engine, expire_on_commit=False)
+ async with factory() as session:
+ await _reset(session)
+ try:
+ yield session
+ finally:
+ await _reset(session)
+ await engine.dispose()
+
+
+async def _reset(session) -> None:
+ """Clear the cases and leave the tenant, user and audit rows in place.
+
+ `audit_log` is append-only -- a trigger raises `audit_log rows are
+ immutable (attempted DELETE)` -- which is the control working, and the
+ `actor_id` foreign key then pins the user, which pins the tenant. So the
+ test tenant is a fixture of the database rather than of a single run, and
+ both seeds are `ON CONFLICT DO NOTHING`.
+ """
+ await session.rollback()
+ await session.execute(text("DELETE FROM aisoc_cases WHERE tenant_id = CAST(:t AS uuid)"), {"t": str(TENANT)})
+ await session.commit()
+
+
+#: A real `users` row, because `audit_log.actor_id` has a foreign key to it.
+#: Seeding one rather than passing a random UUID keeps the audit write on its
+#: production path -- and the first draft of this file did pass a random UUID,
+#: which surfaced a genuine defect: a failed audit left the session in a
+#: broken transaction, so the route's own read raised and a successful reopen
+#: was reported to the caller as a failure.
+USER = uuid.UUID("0e100000-0000-0000-0000-0000000000aa")
+
+
+async def _seed_case(session, status: str = "closed") -> uuid.UUID:
+ await session.execute(
+ text("INSERT INTO tenants (id, name, slug) VALUES (CAST(:t AS uuid), 'Reopen Test', 'reopen-test') ON CONFLICT (id) DO NOTHING"),
+ {"t": str(TENANT)},
+ )
+ await session.execute(
+ text(
+ "INSERT INTO users (id, tenant_id, username, email, hashed_password, role) "
+ "VALUES (CAST(:u AS uuid), CAST(:t AS uuid), 'reopen-analyst', '[email protected]', 'x', 'soc_lead') "
+ "ON CONFLICT (id) DO NOTHING"
+ ),
+ {"u": str(USER), "t": str(TENANT)},
+ )
+ cid = uuid.uuid4()
+ await session.execute(
+ text(
+ """
+ INSERT INTO aisoc_cases (id, tenant_id, case_number, title, status, priority, severity,
+ closed_at, resolved_at)
+ VALUES (CAST(:i AS uuid), CAST(:t AS uuid), :num, 'A case that came back', :st,
+ 'medium', 'medium', NOW(), NOW())
+ """
+ ),
+ {"i": str(cid), "t": str(TENANT), "num": f"CASE-{cid.hex[:8]}", "st": status},
+ )
+ await session.commit()
+ return cid
+
+
+class TestTheColumnsExist:
+ """The reproduction. The handed-over version wrote these without creating
+ them, so every call raised `UndefinedColumnError`."""
+
+ async def test_the_migration_added_all_three(self, db) -> None:
+ rows = (
+ await db.execute(
+ text("SELECT column_name FROM information_schema.columns WHERE table_name = 'aisoc_cases' AND column_name LIKE 'reopen%'")
+ )
+ ).fetchall()
+
+ assert {r[0] for r in rows} == {"reopened_at", "reopen_count", "reopen_reason"}
+
+ async def test_reopen_count_defaults_to_zero_not_null(self, db) -> None:
+ """Unlike the timestamp, "no reopen recorded" genuinely is zero. A
+ NULL here would render as blank and read as missing data."""
+ cid = await _seed_case(db)
+
+ row = (
+ await db.execute(text("SELECT reopen_count, reopened_at FROM aisoc_cases WHERE id = CAST(:i AS uuid)"), {"i": str(cid)})
+ ).fetchone()
+
+ assert row.reopen_count == 0
+ assert row.reopened_at is None
+
+
+class TestReopeningWorksEndToEnd:
+ async def test_a_closed_case_comes_back(self, db) -> None:
+ from app.api.v1.endpoints.cases import ReopenCaseRequest, reopen_case
+
+ cid = await _seed_case(db, status="closed")
+ user = _principal()
+
+ result = await reopen_case(
+ str(cid),
+ ReopenCaseRequest(reason="The indicator reappeared on two more hosts overnight."),
+ db,
+ user,
+ )
+
+ assert result.status == "investigating"
+ assert result.reopened_at is not None
+ assert result.reopen_count == 1
+ assert "reappeared" in (result.reopen_reason or "")
+
+ async def test_closure_timestamps_are_cleared(self, db) -> None:
+ """A case cannot be terminal and active at once, and every closure
+ metric reads these columns -- leaving them set would keep the case in
+ the MTTR average while it sits in the open queue."""
+ from app.api.v1.endpoints.cases import ReopenCaseRequest, reopen_case
+
+ cid = await _seed_case(db, status="closed")
+
+ await reopen_case(str(cid), ReopenCaseRequest(reason="Closed in error by the overnight shift."), db, _principal())
+
+ row = (
+ await db.execute(text("SELECT closed_at, resolved_at FROM aisoc_cases WHERE id = CAST(:i AS uuid)"), {"i": str(cid)})
+ ).fetchone()
+
+ assert row.closed_at is None
+ assert row.resolved_at is None
+
+ async def test_reopening_twice_counts_twice(self, db) -> None:
+ """`reopened_at` is overwritten each time, so without the counter a
+ case reopened four times is indistinguishable from one reopened once."""
+ from app.api.v1.endpoints.cases import ReopenCaseRequest, reopen_case
+
+ cid = await _seed_case(db, status="closed")
+
+ await reopen_case(str(cid), ReopenCaseRequest(reason="First reopen, indicator returned."), db, _principal())
+ await db.execute(text("UPDATE aisoc_cases SET status = 'closed' WHERE id = CAST(:i AS uuid)"), {"i": str(cid)})
+ await db.commit()
+ result = await reopen_case(str(cid), ReopenCaseRequest(reason="Second reopen, lateral movement found."), db, _principal())
+
+ assert result.reopen_count == 2
+
+ async def test_resolved_is_not_reopenable_because_it_is_not_terminal(self, db) -> None:
+ """`resolved` looks terminal and deliberately is not.
+
+ `case_status` puts it in `OPEN_STATUSES` with the reasoning attached:
+ a resolved case has an outcome but has not been closed out, and
+ treating it as finished is what made "cases closed this week" count
+ the wrong rows. It still has a forward edge to `closed`, so there is
+ nothing to reopen -- and a route that accepted it here would let a
+ case skip the closure step entirely.
+
+ This test was written the other way round first and the code was
+ right.
+ """
+ from app.api.v1.endpoints.cases import ReopenCaseRequest, reopen_case
+ from app.services import case_status
+ from fastapi import HTTPException
+
+ assert case_status.RESOLVED in case_status.OPEN_STATUSES
+ assert case_status.TRANSITIONS[case_status.RESOLVED] == {case_status.CLOSED}
+
+ cid = await _seed_case(db, status="resolved")
+
+ with pytest.raises(HTTPException) as exc:
+ await reopen_case(str(cid), ReopenCaseRequest(reason="The fix did not hold past the weekend."), db, _principal())
+
+ assert exc.value.status_code == 409
+
+
+class TestItRefusesWhatItShould:
+ async def test_an_open_case_cannot_be_reopened(self, db) -> None:
+ """409, not a silent no-op. Reopening something already open is a
+ caller confusion worth naming."""
+ from app.api.v1.endpoints.cases import ReopenCaseRequest, reopen_case
+ from fastapi import HTTPException
+
+ cid = await _seed_case(db, status="investigating")
+
+ with pytest.raises(HTTPException) as exc:
+ await reopen_case(str(cid), ReopenCaseRequest(reason="This should not be allowed."), db, _principal())
+
+ assert exc.value.status_code == 409
+ assert "not a terminal state" in str(exc.value.detail)
+
+ async def test_another_tenants_case_is_not_found(self, db) -> None:
+ from app.api.v1.endpoints.cases import ReopenCaseRequest, reopen_case
+ from fastapi import HTTPException
+
+ cid = await _seed_case(db, status="closed")
+ other = _principal(tenant_id=uuid.uuid4())
+
+ with pytest.raises(HTTPException) as exc:
+ await reopen_case(str(cid), ReopenCaseRequest(reason="Cross-tenant attempt, must 404."), db, other)
+
+ assert exc.value.status_code == 404
+
+ def test_a_reason_is_required(self) -> None:
+ """An unexplained reopen is what an auditor asks about six months
+ later. No database needed, so this holds wherever the suite runs."""
+ import pydantic
+ from app.api.v1.endpoints.cases import ReopenCaseRequest
+
+ with pytest.raises(pydantic.ValidationError):
+ ReopenCaseRequest() # type: ignore[call-arg]
+ with pytest.raises(pydantic.ValidationError):
+ ReopenCaseRequest(reason="oops") # too short to be a reason
+
+
+class TestPatchStaysForwardOnly:
+ """The property the route exists to preserve. If `PATCH` could do this,
+ a title edit carrying a status would walk a case backwards silently."""
+
+ def test_the_transition_table_has_no_backward_edge(self) -> None:
+ from app.services import case_status
+
+ assert case_status.TRANSITIONS[case_status.CLOSED] == set()
+
+ def test_reopen_is_not_implemented_by_widening_the_table(self) -> None:
+ from app.services import case_status
+
+ for terminal in case_status.TERMINAL_STATUSES:
+ assert not case_status.TRANSITIONS.get(terminal), (
+ f"{terminal!r} gained an outbound transition. Reopening must stay its own route, "
+ "or an ordinary PATCH can undo a closure without a reason or an audit entry."
+ )
+
+
+def _principal(tenant_id: uuid.UUID | None = None):
+ from app.api.v1.deps import CurrentUser
+
+ return CurrentUser(
+ user_id=USER,
+ tenant_id=tenant_id or TENANT,
+ role="soc_lead",
+ resolved_permissions=frozenset({"cases:write"}),
+ )
diff --git a/services/api/tests/test_cases_authorization.py b/services/api/tests/test_cases_authorization.py
index ad2ca59d3..b716da4e0 100644
--- a/services/api/tests/test_cases_authorization.py
+++ b/services/api/tests/test_cases_authorization.py
@@ -55,6 +55,9 @@ WRITE_HANDLERS = [
"create_task",
"update_task",
"case_investigate",
+ # Reopening is a write, and a privileged one: it moves a case out of a
+ # terminal state, which the forward-only PATCH deliberately cannot do.
+ "reopen_case",
]
diff --git a/services/api/tests/test_cases_tenant_isolation.py b/services/api/tests/test_cases_tenant_isolation.py
index 621d34991..bc1ff07e9 100644
--- a/services/api/tests/test_cases_tenant_isolation.py
+++ b/services/api/tests/test_cases_tenant_isolation.py
@@ -61,8 +61,18 @@ def _user(tenant_id: uuid.UUID | None = None) -> CurrentUser:
def _case_row(**overrides: Any) -> MagicMock:
- """A row object shaped like a SQLAlchemy ``aisoc_cases`` result."""
- row = MagicMock()
+ """A row object shaped like a SQLAlchemy ``aisoc_cases`` result.
+
+ `spec`'d to exactly these columns, which matters more than it looks. A
+ bare `MagicMock()` answers *any* attribute with another mock, so
+ `getattr(row, "some_new_column", None)` returns a mock rather than the
+ `None` a real row would give -- and that mock then flows into a response
+ model and fails Pydantic validation somewhere far from the cause. That is
+ how adding three columns to `aisoc_cases` broke this file.
+
+ With a spec, an unknown attribute raises `AttributeError`, `getattr`'s
+ default fires, and the double behaves the way the real row does.
+ """
now = datetime.now(UTC)
defaults = {
"id": uuid.uuid4(),
@@ -81,6 +91,9 @@ def _case_row(**overrides: Any) -> MagicMock:
"triaged_at": None,
"resolved_at": None,
"closed_at": None,
+ "reopened_at": None,
+ "reopen_count": 0,
+ "reopen_reason": None,
"created_at": now,
"updated_at": now,
"created_by": "[email protected]",
@@ -88,6 +101,7 @@ def _case_row(**overrides: Any) -> MagicMock:
"sla_due_at": None,
}
defaults.update(overrides)
+ row = MagicMock(spec=list(defaults))
for k, v in defaults.items():
setattr(row, k, v)
return row
diff --git a/services/api/tests/test_investigation_payload.py b/services/api/tests/test_investigation_payload.py
new file mode 100644
index 000000000..68c242577
--- /dev/null
+++ b/services/api/tests/test_investigation_payload.py
@@ -0,0 +1,248 @@
+"""An investigation is given the alerts, not a restatement of their title.
+
+The defect
+----------
+`AlertDetailView` sent the literal string `"Investigate alert: <title>"`.
+`InvestigateRequest` carried only `alert_summary`. The case's `alert_ids` were
+written at creation and read by nothing. So the forensic agent reasoned over
+one line of text, while **auto-triage -- the same agent, the other entry
+point -- correctly passed the whole `raw_event`**. Two callers into one
+investigator, one of them starved.
+
+The evidence was never missing and the receiver was never unprepared:
+`InvestigationRequest` on the agents side has declared `raw_alert` since it
+was written, and threads it all the way to the orchestrator. Nothing sent it.
+
+Why the API assembles it rather than the browser
+------------------------------------------------
+Two reasons, and the second is the stronger one. The browser does not hold
+raw events. And it should not be trusted with what reaches a model prompt
+even if it did -- an attacker-influenced payload arriving at an LLM is the
+surface `PromptInjectionGuard` exists for, and narrowing it to data the
+server loaded itself is cheaper than guarding it.
+
+Live Postgres, because the fix is a query. A fake session that answers any
+SELECT cannot tell a query that loads the alerts from one that does not.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+DSN = os.environ.get("DATABASE_URL", "")
+REQUIRED = os.environ.get("MSSP_ISOLATION_REQUIRED", "").strip() not in ("", "0", "false")
+
+TENANT = uuid.UUID("0f100000-0000-0000-0000-00000000000a")
+
+
+@pytest_asyncio.fixture
+async def db():
+ if "postgres" not in DSN and not REQUIRED:
+ pytest.skip("needs a live Postgres with the migration chain applied (integration.yml)")
+ engine = create_async_engine(DSN)
+ try:
+ async with engine.connect() as probe:
+ await probe.execute(text("SELECT 1"))
+ except Exception as exc:
+ await engine.dispose()
+ if REQUIRED:
+ pytest.fail(
+ "MSSP_ISOLATION_REQUIRED is set but no database answered at DATABASE_URL — "
+ f"the investigation-payload proof did not run: {type(exc).__name__}: {exc}"
+ )
+ pytest.skip(f"no database at DATABASE_URL ({type(exc).__name__}) — runs in integration.yml")
+
+ factory = async_sessionmaker(engine, expire_on_commit=False)
+ async with factory() as session:
+ await _reset(session)
+ try:
+ yield session
+ finally:
+ await _reset(session)
+ await engine.dispose()
+
+
+async def _reset(session) -> None:
+ await session.rollback()
+ await session.execute(text("DELETE FROM aisoc_cases WHERE tenant_id = CAST(:t AS uuid)"), {"t": str(TENANT)})
+ await session.execute(text("DELETE FROM alerts WHERE tenant_id = CAST(:t AS uuid)"), {"t": str(TENANT)})
+ await session.commit()
+
+
+async def _seed(session, *, alert_count: int = 1, with_case_link: bool = True) -> tuple[uuid.UUID, list[uuid.UUID]]:
+ await session.execute(
+ text("INSERT INTO tenants (id, name, slug) VALUES (CAST(:t AS uuid), 'Payload Test', 'payload-test') ON CONFLICT (id) DO NOTHING"),
+ {"t": str(TENANT)},
+ )
+ alert_ids: list[uuid.UUID] = []
+ for n in range(alert_count):
+ aid = uuid.uuid4()
+ alert_ids.append(aid)
+ await session.execute(
+ text(
+ """
+ INSERT INTO alerts (id, tenant_id, title, description, severity, status,
+ connector_type, external_id, mitre_techniques, entities,
+ raw_event, created_at, updated_at)
+ VALUES (CAST(:i AS uuid), CAST(:t AS uuid), :ti, :de, 'high', 'new',
+ 'crowdstrike', :ext, CAST(:mt AS jsonb), CAST(:en AS jsonb),
+ CAST(:raw AS jsonb), NOW(), NOW())
+ """
+ ),
+ {
+ "i": str(aid),
+ "t": str(TENANT),
+ "ti": f"Suspicious PowerShell {n}",
+ "de": "Encoded command observed",
+ "ext": f"VENDOR-{n}",
+ "mt": '["T1059.001"]',
+ "en": '{"host": "WIN-SRV-01"}',
+ # The distinctive value the test looks for downstream. If this
+ # string reaches the agent, the raw event reached the agent.
+ "raw": f'{{"CommandLine": "powershell -enc SQBFAFgA", "Image": "C:\\\\\\\\pwsh.exe", "marker": "needle-{n}"}}',
+ },
+ )
+
+ cid = uuid.uuid4()
+ await session.execute(
+ text(
+ """
+ INSERT INTO aisoc_cases (id, tenant_id, case_number, title, description, status,
+ priority, severity, alert_ids)
+ VALUES (CAST(:i AS uuid), CAST(:t AS uuid), :num, 'Suspicious PowerShell wave',
+ 'Three hosts in one hour', 'new', 'high', 'high', :aids)
+ """
+ ),
+ {
+ "i": str(cid),
+ "t": str(TENANT),
+ "num": f"CASE-{cid.hex[:8]}",
+ # A list, not a `{...}` literal: asyncpg binds a Python sequence
+ # to a uuid[] and rejects the text form outright.
+ "aids": [str(a) for a in alert_ids] if with_case_link else [],
+ },
+ )
+ await session.commit()
+ return cid, alert_ids
+
+
+class TestTheAgentGetsTheRealEvent:
+ async def test_the_raw_event_reaches_the_payload(self, db) -> None:
+ """The reproduction. `needle-0` exists only inside the alert's
+ `raw_event`; if it is in the payload, the real telemetry is."""
+ from app.api.v1.endpoints.cases import _investigation_evidence
+
+ cid, _ = await _seed(db, alert_count=1)
+
+ _, raw_alert = await _investigation_evidence(db, cid, TENANT)
+
+ assert raw_alert, "no evidence was assembled at all"
+ blob = str(raw_alert)
+ assert "needle-0" in blob, "the alert's raw_event did not reach the payload"
+ assert "powershell -enc" in blob
+
+ async def test_alert_metadata_travels_with_it(self, db) -> None:
+ """The raw event alone loses what AiSOC added -- severity, the
+ technique, the entity, which connector supplied it."""
+ from app.api.v1.endpoints.cases import _investigation_evidence
+
+ cid, _ = await _seed(db, alert_count=1)
+
+ _, raw_alert = await _investigation_evidence(db, cid, TENANT)
+ alert = raw_alert["alerts"][0]
+
+ assert alert["severity"] == "high"
+ assert alert["source"] == "crowdstrike"
+ assert alert["vendor_id"] == "VENDOR-0"
+ assert "T1059.001" in alert["mitre_techniques"]
+ assert alert["entities"] == {"host": "WIN-SRV-01"}
+
+ async def test_every_correlated_alert_is_included(self, db) -> None:
+ from app.api.v1.endpoints.cases import _investigation_evidence
+
+ cid, alert_ids = await _seed(db, alert_count=4)
+
+ _, raw_alert = await _investigation_evidence(db, cid, TENANT)
+
+ assert raw_alert["alerts_included"] == 4
+ assert raw_alert["alert_count"] == len(alert_ids)
+ assert raw_alert["truncated"] is False
+
+ async def test_the_summary_describes_the_alerts_not_just_the_title(self, db) -> None:
+ from app.api.v1.endpoints.cases import _investigation_evidence
+
+ cid, _ = await _seed(db, alert_count=2)
+
+ summary, _ = await _investigation_evidence(db, cid, TENANT)
+
+ assert "Suspicious PowerShell wave" in summary
+ assert "correlated alert" in summary
+ assert "crowdstrike" in summary
+
+
+class TestItStaysHonestWhenThereIsNothing:
+ async def test_a_case_with_no_alerts_sends_no_evidence(self, db) -> None:
+ """`{}`, not a plausible-looking empty shape. A case opened by hand
+ has no telemetry, and the groundedness gate reads this -- handing it
+ a skeleton to score against is how a gate certifies anything."""
+ from app.api.v1.endpoints.cases import _investigation_evidence
+
+ cid, _ = await _seed(db, alert_count=0, with_case_link=False)
+
+ summary, raw_alert = await _investigation_evidence(db, cid, TENANT)
+
+ assert raw_alert == {}
+ assert "Suspicious PowerShell wave" in summary
+
+ async def test_another_tenants_case_yields_nothing(self, db) -> None:
+ from app.api.v1.endpoints.cases import _investigation_evidence
+
+ cid, _ = await _seed(db, alert_count=1)
+
+ summary, raw_alert = await _investigation_evidence(db, cid, uuid.uuid4())
+
+ assert raw_alert == {}
+ assert summary == ""
+
+ async def test_alerts_are_tenant_scoped(self, db) -> None:
+ """The case is the caller's and the alert ids are attacker-suppliable
+ in principle, so the alert query carries its own tenant predicate
+ rather than trusting the case row."""
+ import inspect
+
+ from app.api.v1.endpoints import cases
+
+ source = inspect.getsource(cases._investigation_evidence)
+ alert_query = source[source.index("FROM alerts") :]
+
+ assert "tenant_id = :tenant_id" in alert_query
+
+
+class TestTheReceiverWasAlwaysReady:
+ """The shape of this defect: nothing was missing except the call."""
+
+ def test_the_agents_request_model_declares_raw_alert(self) -> None:
+ from pathlib import Path
+
+ router = Path(__file__).resolve().parents[3] / "services" / "agents" / "app" / "api" / "investigate.py"
+ if not router.is_file():
+ pytest.skip("services/agents is not present in this checkout")
+
+ assert "raw_alert" in router.read_text(encoding="utf-8")
+
+ def test_the_proxy_now_sends_it(self) -> None:
+ import inspect
+
+ from app.api.v1.endpoints import cases
+
+ source = inspect.getsource(cases.case_investigate)
+
+ assert '"raw_alert"' in source, "the proxy still forwards only a summary"
diff --git a/services/api/tests/test_schema_drift_046.py b/services/api/tests/test_schema_drift_046.py
index 53b4843d2..23226baa8 100644
--- a/services/api/tests/test_schema_drift_046.py
+++ b/services/api/tests/test_schema_drift_046.py
@@ -71,18 +71,26 @@ def _model_columns(model_file: str, class_name: str) -> set[str]:
return columns
-def _lineage_columns(table: str) -> set[str]:
+def _lineage_columns(table: str, *also: str) -> set[str]:
"""Every column the SQL migration lineage defines for ``table``.
Scans ``CREATE TABLE`` bodies and ``ALTER TABLE ... ADD COLUMN`` clauses
- scoped to ``table`` across all migration files (statements split on ``;``).
+ across all migration files (statements split on ``;``).
+
+ ``also`` carries the table's other names. A lineage can cross a rename --
+ migration 083 renamed ``cases`` to ``aisoc_cases`` -- and scanning only
+ one name reads a history that stops at the rename. That is not
+ hypothetical: this gate was looking for ``ALTER TABLE cases`` and had been
+ silently blind to every post-083 migration, which went unnoticed only
+ because none of them added a column until one did.
"""
+ names = "|".join(re.escape(n) for n in (table, *also))
columns: set[str] = set()
create_re = re.compile(
- rf"CREATE TABLE(?:\s+IF NOT EXISTS)?\s+{table}\s*\((?P<body>.*)",
+ rf"CREATE TABLE(?:\s+IF NOT EXISTS)?\s+(?:{names})\s*\((?P<body>.*)",
re.IGNORECASE | re.DOTALL,
)
- alter_re = re.compile(rf"ALTER TABLE\s+(?:ONLY\s+)?{table}\b", re.IGNORECASE)
+ alter_re = re.compile(rf"ALTER TABLE\s+(?:ONLY\s+)?(?:{names})\b", re.IGNORECASE)
add_col_re = re.compile(r"ADD COLUMN(?:\s+IF NOT EXISTS)?\s+(\w+)", re.IGNORECASE)
# A column definition line inside CREATE TABLE: leading identifier that is
# not a table-level constraint keyword.
@@ -159,7 +167,9 @@ def test_detection_rules_lineage_covers_model():
def test_cases_lineage_covers_model():
model_cols = _model_columns("case.py", "Case")
- lineage_cols = _lineage_columns("cases")
+ # Both names: migration 083 renamed the table, so the lineage that
+ # defines this model's columns spans `cases` and `aisoc_cases`.
+ lineage_cols = _lineage_columns("cases", "aisoc_cases")
missing = model_cols - lineage_cols
assert not missing, (
f"cases migration lineage is missing model columns {sorted(missing)} — a reconciling migration is required (see #492)"
diff --git a/services/slack-bot/app/services/aisoc_clients.py b/services/slack-bot/app/services/aisoc_clients.py
index c9d910b2c..fa083ab20 100644
--- a/services/slack-bot/app/services/aisoc_clients.py
+++ b/services/slack-bot/app/services/aisoc_clients.py
@@ -232,6 +232,12 @@ class AisocApiClient(_BaseClient):
services/api proxies to the agents service; the response carries the
``run_id`` we link back into Slack so the analyst can follow it in the
web console.
+
+ ``alert_summary`` is a *note* about why the run was requested, not the
+ evidence. The API loads the case's alerts and their raw events itself
+ and sends those to the agent, so this path gets the same material the
+ console does without Slack having to know anything about alerts --
+ which it could not, since it holds no telemetry.
"""
safe_id = quote(case_id, safe="")
response = await self._request(