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.

Six console numbers that were wrong, fabricated, or malformed on real data (#810)

Beenu Arorafa4abcc4eb71
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e43933a4e..4bacee901 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -367,6 +367,157 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`email-forwarded.yaml`, so it matched neither branch and strict mode
rejected it outright; it now has a profile mirroring that template, the way
`ai_runtime` mirrors `ai-runtime.yaml`.
+- **The dashboard published two numbers that contradicted the database, and a
+ third surface that contradicted both.** A live acceptance pass measured a
+ tenant with two cases closed in the last seven days at a 90-minute mean.
+ `/mssp/portfolio` reported that correctly as 1.5h. The dashboard reported
+ **CASES CLOSED (7D) 0** and **MTTR 0.0 hrs**, directly above its own
+ "CASES OPENED (7D) 2".
+
+ The portfolio was right and the dashboard was wrong, for two separate
+ reasons that each read plausibly in isolation:
+
+ - `cases_closed_7d` filtered `status = 'resolved' AND updated_at >= …`.
+ `resolved` is an *intermediate* state — the lifecycle's terminal one is
+ `closed`, and it is that transition which writes `closed_at` — so a case
+ that completed its lifecycle was invisible to the count. `updated_at` was
+ also the wrong clock: it moves whenever anyone edits the case, so an old
+ case gets a comment and re-enters the window while a closed one
+ eventually leaves it.
+ - `mttr_hours` averaged `alerts.resolved_at - alerts.created_at`, a
+ different lifecycle on a different table from the one the portfolio
+ measures. Nothing in ordinary case work writes that column, so the
+ average was over zero rows and `float(None or 0.0)` published the empty
+ result as a confident `0.0`.
+
+ Both now come from `app/services/resolution_time.py`, which owns the window
+ and the SQL expression that *both* surfaces use, so the two cannot quote
+ different MTTRs for one tenant again. The portfolio keeps computing its
+ figure inside one bound cross-tenant statement — one round trip for the
+ whole portfolio — and interpolates the shared fragments rather than calling
+ the shared function; a test asserts it still does, and the load-bearing
+ assertion is that the two surfaces produce the *same* number from the same
+ rows rather than that each matches a hardcoded 90.0.
+
+ The third surface was the `MTTR` tile in the Security Operations Center
+ strip, reading `alerts.mttr` off `/metrics/dashboard` — the same dead column,
+ and rendered with an `m` suffix although the field is hours, so a real
+ 1.5-hour MTTR would have displayed as "1.5m" had it ever been non-zero.
+
+ Rather than make the three means nullable — a breaking response change for
+ every existing client — each now travels with the number of rows it was
+ averaged over (`mttd_sample_count`, `mttr_sample_count`,
+ `mttc_sample_count`, and `alerts.mttr_sample_count`). A mean over zero rows
+ is unmeasured, not zero, and the tiles say "not measured" instead of
+ claiming an unbeatable response time for a tenant that has resolved nothing.
+ The fields are additive: a client that ignores them sees what it saw before.
+
+- **The entity-risk queue sent a tenant slug where a UUID was required, then
+ blamed a healthy service for the rejection.** `apps/web/next.config.js`
+ inlined `NEXT_PUBLIC_TENANT_ID` with a fallback of the literal string
+ `'default'`. Three tenant-scoped surfaces pass that value as a query
+ parameter to routes typed `tenant_id: UUID` — `/fusion/entity-risk/*`,
+ `/honeytokens/*` and `/business-context/*` — and all three answered 422.
+
+ Two things kept it hidden. `lib/api.ts` carries the correct canonical UUID
+ as its own fallback, so reading it suggested the console was already doing
+ the right thing; Next's inlining runs first, which made that fallback
+ unreachable code. And the slug is not a dependable handle either: migration
+ 001 seeds tenant `…0001` with slug `default` and the demo seed renames that
+ slug to `demo`, so on a seeded install the literal matched neither the id
+ nor the slug. The entity-risk client also read the build-time constant
+ rather than `getActiveTenantId()`, so the queue ignored both the logged-in
+ user and the tenant switcher; it now resolves the tenant the same way
+ `request()` resolves the `X-Tenant-Id` header.
+
+ `components/fim/FimDashboard.tsx` is deliberately pinned to `'default'`
+ instead: `services/osquery-tls` types its tenant as a plain string and
+ enrols nodes under that literal, so this one surface is keyed on that
+ service's own convention and reading the shared UUID here would match no
+ enrolled node. The two tenancy models still need reconciling in
+ osquery-tls.
+
+ With the request failing, the queue rendered five invented entities —
+ `[email protected]`, `updates.evil-cdn.xyz`, "last seen 5 months ago" on a
+ stack that had been up for an hour. Above them, and *outside* the amber
+ banner that disclosed them, four cards read "Contributing alerts 26" and
+ "Alert → Incident 13.0:1" off the same sample payload. A disclosure that
+ covers the rows and not the headline numbers is decorative, so the banner
+ moved above the cards and every card now reads "not measured" when its
+ request fails; the derived alert-to-incident ratio is withheld whenever the
+ counts it divides are unknown.
+
+ The banner also named the wrong subsystem. It said "Fusion service
+ unreachable" while fusion was healthy and the actual failure was a 422 —
+ a diagnosis that sends an operator to debug something that is not broken,
+ which is worse than none. It is now derived from the response status: a 422
+ reads as a console bug rather than an outage, a 5xx names fusion because
+ that is when fusion is genuinely at fault, status 0 reads as unreachable,
+ and an unrecognised failure stays vague rather than guessing. Every variant
+ says the queue is *unknown* rather than empty.
+
+- **`/alerts/[id]` rendered a confidence of 21 as `2100%`, and negative
+ evidence as `+-0.30`.** Confidence reaches the console on two keys at two
+ scales: the API surfaces `confidence` as an integer 0-100, while fusion's
+ `confidence_score` is the raw [0.0, 1.0] float the band was derived from.
+ `normalizeAlert` accepted whichever key appeared first and passed it
+ through unchanged, so `Alert.confidenceScore` meant one thing or the other
+ depending on the payload — and its consumers guessed differently.
+ `AlertDetailView` multiplied by 100; `AttackStory`, on the same page,
+ divided and rendered "21/100". Each was right for one payload shape, and
+ each had a passing test because its own mock used the scale it assumed.
+
+ Normalised once at the boundary to the canonical 0-100 integer, deciding the
+ scale from the *key* rather than the magnitude: a genuine confidence of 1 is
+ indistinguishable from a raw score of 1.0 by value alone, so the tempting
+ `v <= 1 ? v * 100 : v` would render the least-confident alert in the estate
+ as the most confident. The two mocks that encoded the old scale were
+ corrected with it, since sample data on a different scale than the real
+ payload is what hid the bug.
+
+ The rationale rows hardcoded a `+` prefix on a signed contribution, so a
+ factor that argued *against* the verdict read `+-0.30`; they now carry one
+ sign, matching the glyphs the narrative builder uses. Those rows also
+ clamped `contribution / weight` into [0, 1], which rendered every negative
+ factor at zero width — an invisible bar beside a nonsense label. Width now
+ follows the magnitude and colour follows the sign.
+
+- **The Investigation Rail's Details tab showed analysts the markup.**
+ `build_narrative` documents its output as markdown-light — `**bold**`,
+ backtick code spans, `- ` bullets, blank-line paragraphs — and the rail put
+ the string in a `whitespace-pre-wrap` paragraph, which preserves the
+ newlines and the asterisks alike. The panel read `**Medium** alert: … on
+ **Finance & Legal #2**`.
+
+ `components/alerts/NarrativeMarkdown.tsx` renders exactly that dialect and
+ nothing more; an unrecognised construct falls through as literal text rather
+ than being dropped. It builds React elements, never markup: the narrative
+ embeds the alert title and entity names, which originate in connector
+ payloads, so an HTML path here would make anyone who can name a host an XSS
+ author. It introduces no heading, leaving the page's heading order intact.
+
+- **The connector fleet badge claimed every source was reporting when none
+ was.** `ConnectorFleetPanel` rendered the badge whenever the endpoint
+ answered, and with zero connectors `failed + degraded` is zero — so a green
+ "All sources reporting" sat directly above the panel's own "No connectors
+ configured". Zero sources reporting is not the same statement as all of
+ them reporting, and the green is the part an operator scans for. There is
+ now no badge until there is a fleet, and when there is one it names the
+ count it is vouching for.
+
+- **`apps/web/src/components/landing/MitreStrip.tsx` is deleted.** Its twelve
+ ATT&CK tactic tiles carried unsourced coverage counts — 27 of 42 for Defense
+ Evasion, 9 of 11 for Initial Access — that correspond to nothing in the
+ tree. The component was imported nowhere and rendered on no route: the
+ landing page composes fifteen sections and this was not one of them, so the
+ caveat in its body copy was the only thing between those numbers and a
+ reader, and it would have stopped being so the moment somebody mounted the
+ section. Improving the disclaimer would have left the numbers in place for
+ the next person to inherit. Its entry in `ALLOWED_ILLUSTRATIVE` goes with
+ it; `scripts/check_mock_data_gated.py` checks that allow-list in both
+ directions, so a stale exemption fails the build rather than accumulating as
+ cover. The one MITRE figure the project does publish — 97.0% in
+ `BenchmarkBand` — is labelled "substrate" and is unchanged.
- **The agent recommended evidence acquisition the platform could not
perform.** `capture_forensics` was an `ActionType` with no executor
diff --git a/apps/web/next.config.js b/apps/web/next.config.js
index 5b6d1e971..6b35fc7e2 100644
--- a/apps/web/next.config.js
+++ b/apps/web/next.config.js
@@ -82,7 +82,19 @@ const nextConfig = {
NEXT_PUBLIC_ENRICHMENT_URL: process.env.NEXT_PUBLIC_ENRICHMENT_URL || '',
NEXT_PUBLIC_WS_URL: process.env.NEXT_PUBLIC_WS_URL || '',
NEXT_PUBLIC_REALTIME_URL: process.env.NEXT_PUBLIC_REALTIME_URL || '',
- NEXT_PUBLIC_TENANT_ID: process.env.NEXT_PUBLIC_TENANT_ID || 'default',
+ // The canonical tenant seeded by migration 001. This defaulted to the
+ // *slug* 'default', which every tenant-scoped caller then sent where a
+ // UUID was required — `/api/v1/fusion/entity-risk/queue` declares
+ // `tenant_id: UUID` and answered 422. It was also invisible: `api.ts`
+ // carries the correct UUID as its own fallback, but this inlining runs
+ // first, so that fallback could never be reached and reading it suggested
+ // the console was already doing the right thing. Worse, the slug is not a
+ // reliable handle either — the demo seed renames tenant ...0001's slug
+ // from 'default' to 'demo', so the literal matches neither the id nor the
+ // slug on a seeded install. Keep this equal to `DEFAULT_TENANT_ID` in
+ // `apps/web/src/lib/api.ts`; a test asserts the two agree.
+ NEXT_PUBLIC_TENANT_ID:
+ process.env.NEXT_PUBLIC_TENANT_ID || '00000000-0000-0000-0000-000000000001',
NEXT_PUBLIC_PURPLE_TEAM_API: process.env.NEXT_PUBLIC_PURPLE_TEAM_API || '',
NEXT_PUBLIC_HONEYTOKENS_URL: process.env.NEXT_PUBLIC_HONEYTOKENS_URL || '',
NEXT_PUBLIC_OSQUERY_TLS_URL: process.env.NEXT_PUBLIC_OSQUERY_TLS_URL || '',
diff --git a/apps/web/src/components/alerts/AlertDetailView.tsx b/apps/web/src/components/alerts/AlertDetailView.tsx
index 939f1cbd4..e6c1d2ceb 100644
--- a/apps/web/src/components/alerts/AlertDetailView.tsx
+++ b/apps/web/src/components/alerts/AlertDetailView.tsx
@@ -88,7 +88,9 @@ const MOCK_ALERT: Alert = {
createdAt: '2026-05-06T11:00:00Z',
updatedAt: '2026-05-06T11:30:00Z',
confidenceLabel: 'high',
- confidenceScore: 0.86,
+ // Canonical 0-100 scale, as `normalizeAlert` emits. This mock held `0.86`,
+ // which is why the view's `* 100` looked correct in every test that used it.
+ confidenceScore: 86,
confidenceRationale: [
{
factor: 'severity',
@@ -180,7 +182,12 @@ function IOCBadge({ type, value, malicious }: { type: string; value: string; mal
function ConfidenceChip({ label, score }: { label: ConfidenceLabel; score?: number }) {
const cfg = CONFIDENCE_CONFIG[label];
- const pct = typeof score === 'number' ? Math.round(score * 100) : null;
+ // `score` is already the canonical 0-100 integer (see `normalizeAlert`).
+ // This multiplied it by 100 and printed a real confidence of 21 as "2100%",
+ // which the Investigation Rail was rendering correctly as "21/100" on the
+ // same page. Rendered as `N/100` rather than a percentage because the value
+ // is not a probability that the verdict is correct.
+ const points = typeof score === 'number' ? Math.round(score) : null;
return (
<span
className={clsx(
@@ -191,25 +198,38 @@ function ConfidenceChip({ label, score }: { label: ConfidenceLabel; score?: numb
>
<span className={clsx('w-2 h-2 rounded-full', cfg.dot)} />
{cfg.label}
- {pct !== null && <span className="opacity-70 font-mono">· {pct}%</span>}
+ {points !== null && (
+ <span className="opacity-70 font-mono">{`· ${points}/100`}</span>
+ )}
</span>
);
}
+/** `+0.20` / `−0.30`, never `+-0.30`. Matches the narrative builder's glyphs. */
+function signedContribution(contribution: number): string {
+ const sign = contribution < 0 ? '\u2212' : '+';
+ return `${sign}${Math.abs(contribution).toFixed(2)}`;
+}
+
function ConfidenceFactorBar({ factor }: { factor: ConfidenceFactor }) {
- const pct = Math.max(0, Math.min(1, factor.contribution / Math.max(factor.weight, 0.001)));
- const widthPct = Math.round(pct * 100);
+ // A factor can push the score down as well as up. The magnitude drives the
+ // bar width and the sign drives its colour, so a negative factor reads as
+ // "this argued against the verdict" rather than as an empty bar: clamping
+ // the signed ratio to [0, 1] rendered every negative factor at zero width.
+ const magnitude = Math.min(1, Math.abs(factor.contribution) / Math.max(factor.weight, 0.001));
+ const widthPct = Math.round(magnitude * 100);
+ const negative = factor.contribution < 0;
return (
<div>
<div className="flex items-baseline justify-between gap-3 mb-1">
<span className="text-sm text-gray-200">{factor.label}</span>
<span className="text-xs font-mono text-gray-500 shrink-0">
- +{factor.contribution.toFixed(2)} / {factor.weight.toFixed(2)}
+ {`${signedContribution(factor.contribution)} / ${factor.weight.toFixed(2)}`}
</span>
</div>
<div className="h-1.5 bg-gray-800 rounded overflow-hidden">
<div
- className="h-full bg-emerald-500/70"
+ className={clsx('h-full', negative ? 'bg-red-500/70' : 'bg-emerald-500/70')}
style={{ width: `${widthPct}%` }}
aria-hidden="true"
/>
@@ -245,7 +265,7 @@ function ConfidenceExplainability({
<span className="text-sm font-semibold text-gray-100">{cfg.label}</span>
{typeof score === 'number' && (
<span className="text-xs font-mono text-gray-500">
- score {score.toFixed(2)} ({Math.round(score * 100)}%)
+ {`score ${Math.round(score)}/100`}
</span>
)}
</div>
diff --git a/apps/web/src/components/alerts/AlertsView.tsx b/apps/web/src/components/alerts/AlertsView.tsx
index a098793a8..3130f3c5e 100644
--- a/apps/web/src/components/alerts/AlertsView.tsx
+++ b/apps/web/src/components/alerts/AlertsView.tsx
@@ -84,7 +84,10 @@ const MOCK_ALERTS: Alert[] = Array.from({ length: 25 }, (_, i): Alert => {
mitreAttack: i % 3 === 0 ? [{ tactic: 'Execution', technique: 'PowerShell', techniqueId: 'T1059.001' }] : [],
riskScore: ((i * 37 + 13) % 100),
confidenceLabel: conf,
- confidenceScore: Number(confScore.toFixed(2)),
+ // Canonical 0-100 scale, matching what `normalizeAlert` emits for a real
+ // alert. Sample data on a different scale than the real payload is how the
+ // `2100%` render passed review.
+ confidenceScore: Math.round(confScore * 100),
};
});
diff --git a/apps/web/src/components/alerts/ConfidenceRender.test.tsx b/apps/web/src/components/alerts/ConfidenceRender.test.tsx
new file mode 100644
index 000000000..4e0fad1bc
--- /dev/null
+++ b/apps/web/src/components/alerts/ConfidenceRender.test.tsx
@@ -0,0 +1,132 @@
+/**
+ * `/alerts/[id]` rendered a confidence of 21 as **2100%**.
+ *
+ * `Alert.confidenceScore` is the canonical 0-100 integer (see
+ * `lib/confidenceScale.test.ts`, which pins the boundary). This view treated
+ * it as a [0,1] fraction and multiplied by 100, in two places — the header
+ * chip and the "Detection Confidence" section — while the Investigation Rail
+ * on the same page rendered the same field correctly as "21/100". Its mock
+ * held `0.86`, so every test that used the mock agreed with the view.
+ *
+ * It also prefixed every rationale row with a literal `+`, so a factor that
+ * argued *against* the verdict read `+-0.30`; and it clamped the signed
+ * contribution-over-weight ratio to [0, 1], so a negative factor's bar
+ * rendered at zero width — an invisible row with a nonsense label.
+ *
+ * Against the pre-change tree: the first block fails on `2100%`, the second
+ * on `+-0.30`.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import type { Alert } from '@/lib/api';
+
+const swrState = vi.hoisted(() => ({ data: undefined as unknown, isLoading: false }));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: swrState.data, error: undefined, isLoading: swrState.isLoading, mutate: vi.fn() }),
+}));
+
+vi.mock('next/navigation', () => ({
+ __esModule: true,
+ useRouter: () => ({ push: vi.fn(), replace: vi.fn(), back: vi.fn(), refresh: vi.fn() }),
+ usePathname: () => '/alerts/a1',
+ useSearchParams: () => new URLSearchParams(),
+}));
+
+vi.mock('next/link', () => ({
+ __esModule: true,
+ default: ({ children, href }: { children: React.ReactNode; href: string }) => <a href={href}>{children}</a>,
+}));
+
+vi.mock('react-hot-toast', () => ({ __esModule: true, default: { success: vi.fn(), error: vi.fn() } }));
+
+// Each of these owns its own suite; none of them is about confidence.
+vi.mock('@/components/copilot/ContextualActions', () => ({
+ __esModule: true,
+ ContextualActions: () => null,
+}));
+vi.mock('@/components/alerts/ExplainDrawer', () => ({ __esModule: true, ExplainDrawer: () => null }));
+vi.mock('@/components/alerts/CreateCaseModal', () => ({ __esModule: true, CreateCaseModal: () => null }));
+
+import { AlertDetailView } from './AlertDetailView';
+
+/** The real payload shape, at the values the live acceptance pass saw. */
+const ALERT: Alert = {
+ id: 'a1',
+ title: 'Unusual sign-in from an unrecognised location',
+ description: 'An interactive sign-in succeeded from an ASN this identity has not used before.',
+ severity: 'medium',
+ status: 'new',
+ source: 'okta',
+ tenantId: '00000000-0000-0000-0000-000000000001',
+ riskScore: 42,
+ createdAt: '2026-09-23T22:25:56Z',
+ updatedAt: '2026-09-23T22:25:56Z',
+ confidenceLabel: 'low',
+ confidenceScore: 21,
+ confidenceRationale: [
+ { factor: 'severity', label: 'Medium severity from source', value: 0.5, contribution: 0.2, weight: 0.2 },
+ { factor: 'source_reliability', label: 'Single uncorroborated source', value: 0.2, contribution: -0.3, weight: 0.4 },
+ ],
+};
+
+beforeEach(() => {
+ swrState.data = ALERT;
+ swrState.isLoading = false;
+});
+
+afterEach(() => cleanup());
+
+describe('confidence is rendered on the scale it arrives on', () => {
+ it('renders 21 as 21/100, not as a percentage of a fraction', () => {
+ render(<AlertDetailView alertId="a1" />);
+
+ expect(screen.queryByText(/2100\s*%/)).toBeNull();
+ expect(screen.getAllByText(/21\/100/).length).toBeGreaterThan(0);
+ });
+
+ it('agrees with the Investigation Rail, which renders the same field as N/100', () => {
+ render(<AlertDetailView alertId="a1" />);
+
+ // Both the header chip and the Detection Confidence section.
+ expect(screen.getAllByText(/21\/100/).length).toBe(2);
+ });
+
+ it('publishes no percentage sign for a value that is not a probability', () => {
+ // Confidence is independent of severity and is not the probability that
+ // the verdict is correct, which is why the rail's wording is "/100".
+ render(<AlertDetailView alertId="a1" />);
+
+ expect(screen.queryByText(/^score 21\.00/)).toBeNull();
+ });
+});
+
+describe('a factor that argued against the verdict reads as negative', () => {
+ it('renders a negative contribution with one sign, not "+-"', () => {
+ render(<AlertDetailView alertId="a1" />);
+
+ expect(screen.queryByText(/\+-0\.30/)).toBeNull();
+ expect(screen.getByText(/\u22120\.30 \/ 0\.40/)).toBeTruthy();
+ });
+
+ it('still renders a positive contribution with a plus', () => {
+ render(<AlertDetailView alertId="a1" />);
+
+ expect(screen.getByText(/\+0\.20 \/ 0\.20/)).toBeTruthy();
+ });
+
+ it('gives a negative factor a visible bar sized by its magnitude', () => {
+ // The old clamp took `contribution / weight` into [0, 1], so -0.30/0.40
+ // became 0 and the row rendered with no bar at all.
+ const { container } = render(<AlertDetailView alertId="a1" />);
+
+ const widths = [...container.querySelectorAll('div[style*="width"]')]
+ .map((el) => (el as HTMLElement).style.width)
+ .filter((w) => w.endsWith('%'));
+
+ // 0.30 / 0.40 = 75%
+ expect(widths).toContain('75%');
+ });
+});
diff --git a/apps/web/src/components/alerts/EntityRiskHonesty.test.tsx b/apps/web/src/components/alerts/EntityRiskHonesty.test.tsx
new file mode 100644
index 000000000..3911e65a9
--- /dev/null
+++ b/apps/web/src/components/alerts/EntityRiskHonesty.test.tsx
@@ -0,0 +1,247 @@
+/**
+ * The RBA queue must not invent entities, and its KPI cards must be covered
+ * by the same disclosure as its rows.
+ *
+ * What a live acceptance pass saw: the console requested
+ * `entity-risk/queue?tenant_id=default` — a tenant *slug* against a route
+ * that declares `tenant_id: UUID` — got a 422, and rendered
+ * `[email protected]`, `updates.evil-cdn.xyz` and "last seen 5 months ago" on
+ * a stack that had been up for an hour. Above those rows, and *outside* the
+ * amber banner that disclosed them, four cards read "Contributing alerts 26"
+ * and "Alert → Incident 13.0:1". The banner itself said "Fusion service
+ * unreachable" while fusion was healthy.
+ *
+ * **Every test here asserts on first paint as well as on the error branch.**
+ * That is the whole lesson of the bug this file descends from: two dashboards
+ * wrapped their sample data in `demoFallback()` and then defeated it with
+ * `const resolved = isValid ? data : MOCK`. `data` is undefined on first
+ * paint *and* after an error, so a test that only drives the error branch
+ * exercises a path that returns early — and a regression introduced there is
+ * unreachable from the test, which is exactly how the original survived
+ * review.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { axe } from 'vitest-axe';
+import { __setDemoModeForTests } from '@/lib/demoMode';
+
+const swrData = vi.hoisted(() => new Map<string, unknown>());
+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);
+ return {
+ data: swrData.get(k),
+ error: swrErrors.get(k),
+ isLoading: false,
+ mutate: vi.fn(),
+ };
+ },
+}));
+
+import { ApiError } from '@/lib/api';
+import { EntityRiskQueue, describeQueueFailure } from './EntityRiskQueue';
+
+const QUEUE_KEY = JSON.stringify(['entity-risk-queue', false]);
+const STATS_KEY = 'entity-risk-stats';
+
+/** Verbatim from `MOCK_ENTITIES` / `MOCK_ENTITY_STATS` in EntityRiskQueue.tsx. */
+const FABRICATED_ENTITIES = [
+ 'WS-PROD-042',
+ '198.51.100.42',
+ 'updates.evil-cdn.xyz',
+];
+
+/** The figures the four cards published from the sample stats payload. */
+const FABRICATED_COUNTS = ['26', '13.0:1'];
+
+function expectNothingFabricated() {
+ for (const value of FABRICATED_ENTITIES) {
+ expect(
+ screen.queryByText(value),
+ `"${value}" is sample data and must never render as a tenant's entity`,
+ ).toBeNull();
+ }
+ for (const value of FABRICATED_COUNTS) {
+ expect(
+ screen.queryByText(value),
+ `"${value}" is derived from sample data and must not render as a measured count`,
+ ).toBeNull();
+ }
+}
+
+beforeEach(() => {
+ swrData.clear();
+ swrErrors.clear();
+ __setDemoModeForTests(false);
+});
+
+afterEach(() => {
+ cleanup();
+ __setDemoModeForTests(null);
+});
+
+describe('EntityRiskQueue — first paint', () => {
+ it('publishes no entities and no counts before either request resolves', () => {
+ // The state a self-hoster is in for the first few hundred milliseconds of
+ // every page load, and permanently whenever the backend is unreachable.
+ render(<EntityRiskQueue />);
+
+ expectNothingFabricated();
+ });
+
+ it('shows no banner on first paint, because nothing has failed yet', () => {
+ render(<EntityRiskQueue />);
+
+ expect(screen.queryByText(/queue unavailable/i)).toBeNull();
+ expect(screen.queryByText(/unreachable/i)).toBeNull();
+ });
+
+ it('renders zeros rather than dashes once an empty queue really arrives', () => {
+ // Measured emptiness and unknown emptiness are different claims, and the
+ // cards have to be able to say both.
+ swrData.set(QUEUE_KEY, { tenant_id: 't', entities: [], threshold: 80 });
+ swrData.set(STATS_KEY, { tenant_id: 't', total: 0, promoted: 0, alert_count: 0, threshold: 80, bands: {} });
+
+ render(<EntityRiskQueue />);
+
+ expect(screen.getByText(/No entities are currently being tracked/i)).toBeTruthy();
+ expect(screen.queryByText('not measured')).toBeNull();
+ });
+});
+
+describe('EntityRiskQueue — the disclosure covers the KPI cards', () => {
+ it('reports every card as not measured when the stats request fails', () => {
+ swrErrors.set(STATS_KEY, new ApiError('API 422', 422, ''));
+ swrErrors.set(QUEUE_KEY, new ApiError('API 422', 422, ''));
+
+ render(<EntityRiskQueue />);
+
+ // Four cards, each explicitly unmeasured rather than confidently zero.
+ expect(screen.getAllByText('not measured').length).toBe(4);
+ expectNothingFabricated();
+ });
+
+ it('does not derive a ratio from counts it does not have', () => {
+ // `Alert → Incident` is computed from the two counts beside it, so it has
+ // to be unknown whenever they are. It read "13.0:1" off the sample stats.
+ swrErrors.set(STATS_KEY, new ApiError('API 422', 422, ''));
+ swrErrors.set(QUEUE_KEY, new ApiError('API 422', 422, ''));
+
+ render(<EntityRiskQueue />);
+
+ expect(screen.queryByText(/:1$/)).toBeNull();
+ expect(screen.queryByText(/2026 bar/)).toBeNull();
+ });
+
+ it('withholds sample rows and counts even in the hosted demo when the fetch fails', () => {
+ // The production repro. Demo mode supplies `fallbackData`, SWR then
+ // revalidates, the revalidation 422s — and the view showed the sample
+ // queue with a banner over it and the sample counts above the banner.
+ __setDemoModeForTests(true);
+ swrData.set(QUEUE_KEY, {
+ tenant_id: 'demo',
+ threshold: 80,
+ entities: [
+ {
+ tenant_id: 'demo',
+ entity_type: 'user',
+ entity_value: '[email protected]',
+ score: 92.4,
+ display_score: 92,
+ threshold: 80,
+ promoted: true,
+ promoted_incident_id: null,
+ alert_count: 8,
+ severity_histogram: {},
+ first_seen: new Date().toISOString(),
+ last_seen: new Date().toISOString(),
+ contributions: [],
+ },
+ ],
+ });
+ swrData.set(STATS_KEY, { tenant_id: 'demo', total: 5, promoted: 2, alert_count: 26, threshold: 80, bands: {} });
+ swrErrors.set(QUEUE_KEY, new ApiError('API 422', 422, ''));
+ swrErrors.set(STATS_KEY, new ApiError('API 422', 422, ''));
+
+ render(<EntityRiskQueue />);
+
+ expectNothingFabricated();
+ expect(screen.getByText(/The entity queue could not be loaded/i)).toBeTruthy();
+ });
+
+ it('says the queue is unknown rather than empty when the rows cannot load', () => {
+ swrErrors.set(QUEUE_KEY, new ApiError('API 422', 422, ''));
+
+ render(<EntityRiskQueue />);
+
+ expect(screen.getByText(/unknown rather than as an empty queue/i)).toBeTruthy();
+ expect(screen.queryByText(/No entities are currently being tracked/i)).toBeNull();
+ });
+});
+
+describe('accessibility (WCAG 2.1 AA)', () => {
+ // Colour contrast is disabled for the same reason as the operations suite:
+ // jsdom resolves no stylesheet, so every computed colour is the default.
+ const axeOptions = { rules: { 'color-contrast': { enabled: false } } };
+
+ it('has no violations in the degraded state, which is a new live region', async () => {
+ swrErrors.set(QUEUE_KEY, new ApiError('API 422', 422, ''));
+ swrErrors.set(STATS_KEY, new ApiError('API 422', 422, ''));
+
+ const { container } = render(<EntityRiskQueue />);
+
+ expect(await axe(container, axeOptions)).toHaveNoViolations();
+ });
+
+ it('has no violations on first paint', async () => {
+ const { container } = render(<EntityRiskQueue />);
+
+ expect(await axe(container, axeOptions)).toHaveNoViolations();
+ });
+});
+
+describe('describeQueueFailure — names the subsystem that actually failed', () => {
+ it('calls a 422 a console bug and does not blame fusion', () => {
+ // The failure that happened. "Fusion service unreachable" sent whoever
+ // read it to debug a healthy service.
+ const message = describeQueueFailure(new ApiError('API 422', 422, ''));
+
+ expect(message).toMatch(/console bug rather than an outage/i);
+ expect(message).not.toMatch(/fusion/i);
+ expect(message).not.toMatch(/unreachable/i);
+ });
+
+ it('blames fusion only when fusion actually returned an error', () => {
+ expect(describeQueueFailure(new ApiError('API 503', 503, ''))).toMatch(/fusion service returned 503/i);
+ });
+
+ it('reports a transport failure as unreachable, which is what status 0 means', () => {
+ expect(describeQueueFailure(new ApiError('Network error', 0, ''))).toMatch(/cannot reach the api/i);
+ });
+
+ it('distinguishes an authorisation refusal from an outage', () => {
+ expect(describeQueueFailure(new ApiError('API 403', 403, ''))).toMatch(/not authorised/i);
+ expect(describeQueueFailure(new ApiError('API 404', 404, ''))).toMatch(/does not expose/i);
+ });
+
+ it('stays vague rather than guessing a subsystem for an unrecognised failure', () => {
+ const message = describeQueueFailure(new Error('boom'));
+
+ expect(message).toContain('boom');
+ expect(message).not.toMatch(/fusion/i);
+ });
+
+ it('always says the queue is unknown, never that it is empty', () => {
+ for (const status of [0, 401, 403, 422, 500, 503, 418]) {
+ const message = describeQueueFailure(new ApiError(`API ${status}`, status, ''));
+ if (status === 404) continue;
+ expect(message.toLowerCase()).toMatch(/unknown|not authorised|does not expose/);
+ }
+ });
+});
diff --git a/apps/web/src/components/alerts/EntityRiskQueue.tsx b/apps/web/src/components/alerts/EntityRiskQueue.tsx
index a88261d6c..05c16ddf4 100644
--- a/apps/web/src/components/alerts/EntityRiskQueue.tsx
+++ b/apps/web/src/components/alerts/EntityRiskQueue.tsx
@@ -16,6 +16,7 @@ import useSWR from 'swr';
import { clsx } from 'clsx';
import { formatDistanceToNow } from 'date-fns';
import {
+ ApiError,
entityRiskApi,
type AlertSeverity,
type EntityRiskRecord,
@@ -107,6 +108,42 @@ const MOCK_ENTITY_STATS: EntityRiskStats = {
// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * What actually went wrong, in words an operator can act on.
+ *
+ * This panel used to print "Fusion service unreachable" for every failure.
+ * The failure in production was a 422: the console was sending the tenant
+ * *slug* to a route that declares `tenant_id: UUID`. Fusion was healthy
+ * throughout, so the banner sent whoever read it to go and debug a service
+ * that was working — which is worse than no diagnosis, because it is
+ * confidently wrong and it costs an hour.
+ *
+ * Anything that is not a recognised status stays vague on purpose rather
+ * than guessing a subsystem.
+ */
+export function describeQueueFailure(error: unknown): string {
+ if (error instanceof ApiError) {
+ if (error.status === 0) {
+ return 'Cannot reach the API from this browser. The entity queue is unknown, not empty.';
+ }
+ if (error.status === 422) {
+ return 'The API rejected this request as malformed, so this is a console bug rather than an outage. The entity queue is unknown, not empty.';
+ }
+ if (error.status === 401 || error.status === 403) {
+ return 'Not authorised to read the entity-risk queue. The queue is unknown, not empty.';
+ }
+ if (error.status === 404) {
+ return 'This deployment does not expose the entity-risk queue. Risk-Based Alerting needs the fusion service.';
+ }
+ if (error.status >= 500) {
+ return `The fusion service returned ${error.status}. The entity queue is unknown, not empty.`;
+ }
+ return `The entity-risk queue request failed with HTTP ${error.status}. The queue is unknown, not empty.`;
+ }
+ const detail = error instanceof Error ? error.message : String(error ?? 'unknown error');
+ return `Could not load the entity-risk queue: ${detail}. The queue is unknown, not empty.`;
+}
+
function bandFor(score: number, threshold: number): {
label: string;
text: string;
@@ -153,12 +190,23 @@ function RatioStat({
alertCount,
incidentCount,
}: {
- alertCount: number;
- incidentCount: number;
+ alertCount: number | undefined;
+ incidentCount: number | undefined;
}) {
- // Alert-to-incident ratio is the published 2026 KPI bar (≥ 50:1). We always
- // surface it here because it's the single number that measures whether RBA
- // is actually delivering — collapsing N alerts into 1 entity-incident.
+ // Alert-to-incident ratio is the published 2026 KPI bar (≥ 50:1) — the
+ // single number that measures whether RBA is delivering, i.e. collapsing N
+ // alerts into 1 entity-incident. It is derived from the two counts beside
+ // it, so when those are unknown this has to be unknown too: it read "13.0:1"
+ // off sample data while the queue below it was disclosed as unavailable.
+ if (alertCount === undefined || incidentCount === undefined) {
+ return (
+ <div className="bg-gray-900/60 border border-gray-800/60 rounded-xl px-4 py-3">
+ <p className="text-xs text-gray-500">Alert → Incident</p>
+ <p className="text-2xl font-bold mt-1 text-gray-600">—</p>
+ <p className="text-[10px] text-gray-600 mt-0.5">not measured</p>
+ </div>
+ );
+ }
const ratio =
incidentCount > 0
? alertCount / incidentCount
@@ -473,45 +521,89 @@ export function EntityRiskQueue() {
fallbackData: demoFallback({ tenant_id: 'demo', entities: MOCK_ENTITIES, threshold: 80 }),
},
);
- const { data: stats } = useSWR<EntityRiskStats>(
+ const { data: stats, error: statsError } = useSWR<EntityRiskStats>(
'entity-risk-stats',
() => entityRiskApi.stats(),
{ refreshInterval: 30000, fallbackData: demoFallback(MOCK_ENTITY_STATS) },
);
- const entities = queue?.entities ?? [];
+ // A failed request means "unknown", and every number on this panel is
+ // derived from one of the two requests. The four cards used to sit above the
+ // disclosure and read off sample data — "Contributing alerts 26",
+ // "Alert → Incident 13.0:1" — while the banner immediately below them said
+ // the rows were unavailable. Whatever the banner discloses has to cover the
+ // headline numbers too, or the disclosure is decorative.
+ const failure = queueError ?? statsError;
+ const entities: EntityRiskRecord[] = queueError ? [] : (queue?.entities ?? []);
+ const countsUnknown = !!statsError || !!queueError;
// Fall back to the queue's threshold (from the engine config) when the
// stats endpoint is still loading — keeps the score bars stable.
const threshold = stats?.threshold ?? queue?.threshold ?? 80;
- const promotedCount = stats?.promoted ?? entities.filter((e) => e.promoted).length;
- const total = stats?.total ?? entities.length;
- const alertCount = stats?.alert_count ?? entities.reduce((sum, e) => sum + e.alert_count, 0);
+ const promotedCount = countsUnknown
+ ? undefined
+ : (stats?.promoted ?? entities.filter((e) => e.promoted).length);
+ const total = countsUnknown ? undefined : (stats?.total ?? entities.length);
+ const alertCount = countsUnknown
+ ? undefined
+ : (stats?.alert_count ?? entities.reduce((sum, e) => sum + e.alert_count, 0));
return (
<div className="space-y-4">
+ {failure && (
+ <div
+ role="status"
+ className="rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-2 text-xs text-amber-200"
+ >
+ <span className="font-semibold">Entity-risk queue unavailable:</span>{' '}
+ {describeQueueFailure(failure)} No entity or alert counts are shown
+ below.
+ </div>
+ )}
+
{/* Stats strip — anchored on the 2026 KPI bar */}
<div className="grid grid-cols-4 gap-3">
<div className="bg-gray-900/60 border border-gray-800/60 rounded-xl px-4 py-3">
<p className="text-xs text-gray-500">Active entities</p>
- <p className="text-2xl font-bold mt-1 text-gray-200">{total}</p>
+ <p
+ className={clsx(
+ 'text-2xl font-bold mt-1',
+ total === undefined ? 'text-gray-600' : 'text-gray-200',
+ )}
+ >
+ {total ?? '—'}
+ </p>
<p className="text-[10px] text-gray-600 mt-0.5">
- threshold {Math.round(threshold)} pts
+ {total === undefined
+ ? 'not measured'
+ : `threshold ${Math.round(threshold)} pts`}
</p>
</div>
<div className="bg-gray-900/60 border border-gray-800/60 rounded-xl px-4 py-3">
<p className="text-xs text-gray-500">Promoted</p>
- <p className="text-2xl font-bold mt-1 text-red-400">
- {promotedCount}
+ <p
+ className={clsx(
+ 'text-2xl font-bold mt-1',
+ promotedCount === undefined ? 'text-gray-600' : 'text-red-400',
+ )}
+ >
+ {promotedCount ?? '—'}
</p>
<p className="text-[10px] text-gray-600 mt-0.5">
- entity-incidents
+ {promotedCount === undefined ? 'not measured' : 'entity-incidents'}
</p>
</div>
<div className="bg-gray-900/60 border border-gray-800/60 rounded-xl px-4 py-3">
<p className="text-xs text-gray-500">Contributing alerts</p>
- <p className="text-2xl font-bold mt-1 text-gray-200">{alertCount}</p>
+ <p
+ className={clsx(
+ 'text-2xl font-bold mt-1',
+ alertCount === undefined ? 'text-gray-600' : 'text-gray-200',
+ )}
+ >
+ {alertCount ?? '—'}
+ </p>
<p className="text-[10px] text-gray-600 mt-0.5">
- current decay window
+ {alertCount === undefined ? 'not measured' : 'current decay window'}
</p>
</div>
<RatioStat alertCount={alertCount} incidentCount={promotedCount} />
@@ -548,12 +640,6 @@ export function EntityRiskQueue() {
</span>
</div>
- {queueError && (
- <div className="rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-2 text-xs text-amber-200">
- Fusion service unreachable — showing demo entity queue so you can explore Risk-Based Alerting.
- </div>
- )}
-
{/* Queue */}
<div className="bg-gray-900/60 border border-gray-800/60 rounded-xl overflow-hidden">
<div className="flex items-center px-4 py-2 border-b border-gray-800/60 bg-gray-900/80 gap-4">
@@ -562,7 +648,17 @@ export function EntityRiskQueue() {
<span className="text-xs text-gray-500 w-20 text-center">BAND</span>
</div>
- {queueLoading && entities.length === 0 ? (
+ {queueError ? (
+ <div className="flex flex-col items-center justify-center h-32 text-gray-500 gap-1 px-4 text-center">
+ <p className="text-sm text-amber-200/80">
+ The entity queue could not be loaded.
+ </p>
+ <p className="text-[11px] text-gray-600">
+ Treat this as unknown rather than as an empty queue — see the
+ message above.
+ </p>
+ </div>
+ ) : queueLoading && entities.length === 0 ? (
<div className="flex items-center justify-center h-32">
<div className="w-6 h-6 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
</div>
diff --git a/apps/web/src/components/alerts/InvestigationRail.test.tsx b/apps/web/src/components/alerts/InvestigationRail.test.tsx
index bdba08c30..f1873e25e 100644
--- a/apps/web/src/components/alerts/InvestigationRail.test.tsx
+++ b/apps/web/src/components/alerts/InvestigationRail.test.tsx
@@ -399,6 +399,28 @@ describe('InvestigationRail — narrative section', () => {
renderDetails(vi.fn());
expect(screen.queryByText('Narrative')).toBeNull();
});
+
+ it('renders the builder\u2019s markdown rather than showing it to the analyst', () => {
+ // `build_narrative` emits `**bold**`, backtick code spans and `- `
+ // bullets. The rail put the string in a `whitespace-pre-wrap` paragraph,
+ // which preserves the newlines and the markup alike, so this tab read
+ // "**Medium** alert: ... on **Finance & Legal #2**".
+ swrState.data = buildAlert({
+ narrative:
+ '**Medium** alert: Unusual sign-in on **Finance & Legal #2** from `okta`.\n\n' +
+ 'Why we believe it:\n- Confidence: **low** (21/100)',
+ });
+ const { container } = renderDetails(vi.fn());
+
+ // Scoped to the section: the rail header also shows the connector name.
+ const narrative = screen.getByText('Narrative').closest('section')!;
+
+ expect(within(narrative).getByText('Medium').tagName).toBe('STRONG');
+ expect(within(narrative).getByText('Finance & Legal #2').tagName).toBe('STRONG');
+ expect(within(narrative).getByText('okta').tagName).toBe('CODE');
+ expect(within(narrative).getAllByRole('listitem').length).toBe(1);
+ expect(container.textContent).not.toContain('**');
+ });
});
// ─── Loaded rail — related entities ──────────────────────────────────────────
diff --git a/apps/web/src/components/alerts/InvestigationRail.tsx b/apps/web/src/components/alerts/InvestigationRail.tsx
index 23a90d47c..e1dd9b7d2 100644
--- a/apps/web/src/components/alerts/InvestigationRail.tsx
+++ b/apps/web/src/components/alerts/InvestigationRail.tsx
@@ -46,6 +46,7 @@ import {
} from '@/lib/api';
import { AttackStory } from './AttackStory';
import { ExplainDrawer } from './ExplainDrawer';
+import { NarrativeMarkdown } from './NarrativeMarkdown';
import { Skeleton } from '@/components/ui/Skeleton';
// ─── Visual config ───────────────────────────────────────────────────────────
@@ -351,15 +352,15 @@ function SectionHeader({ title, count }: { title: string; count?: number }) {
function NarrativeSection({ narrative }: { narrative: string | null }) {
if (!narrative || !narrative.trim()) return null;
- // Markdown-light: we preserve newlines so the deterministic
- // paragraph + bullet structure produced by `narrative.build_narrative`
- // renders without us pulling in a full Markdown engine.
+ // `build_narrative` emits a markdown-light dialect. Preserving newlines in a
+ // `whitespace-pre-wrap` paragraph preserved the *markup* too, so the rail
+ // showed analysts "**Medium** alert: … on **Finance & Legal #2**". The
+ // renderer covers that dialect and escapes everything, which matters because
+ // the narrative embeds attacker-influenceable entity names.
return (
<section className="px-4 py-4 border-b border-gray-800/40">
<SectionHeader title="Narrative" />
- <p className="text-sm text-gray-300 whitespace-pre-wrap leading-relaxed">
- {narrative}
- </p>
+ <NarrativeMarkdown source={narrative} />
</section>
);
}
diff --git a/apps/web/src/components/alerts/NarrativeMarkdown.test.tsx b/apps/web/src/components/alerts/NarrativeMarkdown.test.tsx
new file mode 100644
index 000000000..a5e0c6e73
--- /dev/null
+++ b/apps/web/src/components/alerts/NarrativeMarkdown.test.tsx
@@ -0,0 +1,128 @@
+/**
+ * The Investigation Rail's Details tab showed analysts the markup.
+ *
+ * `build_narrative` documents its output as "Markdown-light: `**bold**`,
+ * bullet lists, blank-line paragraphs. The rail renders these without a full
+ * Markdown engine." The rail put the string in a `whitespace-pre-wrap`
+ * paragraph, which preserves the newlines and the asterisks alike, so the
+ * panel read:
+ *
+ * **Medium** alert: Unusual sign-in ... on **Finance & Legal #2**
+ *
+ * Two things are being pinned here. The dialect renders (against the
+ * pre-change tree every assertion in the first block fails, because the
+ * literal `**` was in the DOM). And the renderer builds elements rather than
+ * markup: the narrative embeds the alert title and entity names, which come
+ * from connectors and are therefore attacker-influenced, so an HTML path here
+ * would make anyone who can name a host an XSS author.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { NarrativeMarkdown } from './NarrativeMarkdown';
+
+const REAL_NARRATIVE = [
+ '**Medium** alert: Unusual sign-in from an unrecognised location on **Finance & Legal #2** from `okta`.',
+ '',
+ 'Why we believe it:',
+ '- + **Medium severity from source** — Medium severity from source',
+ '- − **Single uncorroborated source** — only one source reported this',
+ '- Confidence: **low** (21/100)',
+ '',
+ 'Recommended next step:',
+ '- Triage the alert in the queue: confirm whether the activity is sanctioned before escalating.',
+].join('\n');
+
+describe('the narrative renders its dialect instead of showing it', () => {
+ it('renders bold spans and leaves no asterisks in the text', () => {
+ const { container } = render(<NarrativeMarkdown source={REAL_NARRATIVE} />);
+
+ expect(screen.getByText('Medium').tagName).toBe('STRONG');
+ expect(screen.getByText('Finance & Legal #2').tagName).toBe('STRONG');
+ expect(container.textContent).not.toContain('**');
+ });
+
+ it('renders backtick spans as code and drops the backticks', () => {
+ const { container } = render(<NarrativeMarkdown source={REAL_NARRATIVE} />);
+
+ expect(screen.getByText('okta').tagName).toBe('CODE');
+ expect(container.textContent).not.toContain('`');
+ });
+
+ it('renders `- ` lines as list items, not as text beginning with a hyphen', () => {
+ const { container } = render(<NarrativeMarkdown source={REAL_NARRATIVE} />);
+
+ const items = container.querySelectorAll('li');
+ expect(items.length).toBe(4);
+ expect(items[0].textContent).toContain('Medium severity from source');
+ // The bullet glyph itself is the list marker now, not part of the text.
+ expect(items[0].textContent?.startsWith('- ')).toBe(false);
+ });
+
+ it('keeps the lead line of a block as prose above its bullets', () => {
+ const { container } = render(<NarrativeMarkdown source={REAL_NARRATIVE} />);
+
+ const paragraphs = [...container.querySelectorAll('p')].map((p) => p.textContent);
+ expect(paragraphs).toContain('Why we believe it:');
+ expect(paragraphs).toContain('Recommended next step:');
+ });
+
+ it('keeps the word spacing around an interpolated span', () => {
+ // The JSX trap: an expression and adjacent text on separate source lines
+ // makes React inject a comment separator and drop the leading space, so
+ // "**Medium** alert" renders as "Mediumalert".
+ const { container } = render(<NarrativeMarkdown source={'**Medium** alert: something happened'} />);
+
+ expect(container.textContent).toBe('Medium alert: something happened');
+ });
+
+ it('preserves the signs the builder uses for negative factors', () => {
+ const { container } = render(<NarrativeMarkdown source={'- − **Single uncorroborated source** — only one source'} />);
+
+ expect(container.textContent).toContain('−');
+ });
+});
+
+describe('the narrative is never treated as markup', () => {
+ it('escapes HTML in an entity name rather than rendering it', () => {
+ // A connector can report a hostname, a filename or a URL containing
+ // anything. This is the payload that matters: the narrative is built
+ // server-side from fields the platform does not control.
+ const hostile = '**Medium** alert: beacon on **<img src=x onerror="alert(1)">**';
+
+ const { container } = render(<NarrativeMarkdown source={hostile} />);
+
+ expect(container.querySelector('img')).toBeNull();
+ expect(container.textContent).toContain('<img src=x onerror="alert(1)">');
+ });
+
+ it('does not let a script tag in the narrative reach the DOM', () => {
+ const { container } = render(<NarrativeMarkdown source={'alert: <script>fetch("/x")</script>'} />);
+
+ expect(container.querySelector('script')).toBeNull();
+ expect(container.textContent).toContain('<script>fetch("/x")</script>');
+ });
+});
+
+describe('the narrative degrades rather than dropping content', () => {
+ it('leaves an unclosed bold delimiter as literal text', () => {
+ const { container } = render(<NarrativeMarkdown source={'**Medium alert with no closing marker'} />);
+
+ expect(container.textContent).toBe('**Medium alert with no closing marker');
+ expect(container.querySelector('strong')).toBeNull();
+ });
+
+ it('renders an empty narrative as an empty container rather than throwing', () => {
+ const { container } = render(<NarrativeMarkdown source={' \n\n '} />);
+
+ expect(container.textContent).toBe('');
+ });
+
+ it('introduces no heading, so the page heading order is untouched', () => {
+ // There is an axe-core WCAG AA gate on heading order, and the rail
+ // already owns the section heading above this content.
+ const { container } = render(<NarrativeMarkdown source={REAL_NARRATIVE} />);
+
+ expect(container.querySelectorAll('h1,h2,h3,h4,h5,h6').length).toBe(0);
+ });
+});
diff --git a/apps/web/src/components/alerts/NarrativeMarkdown.tsx b/apps/web/src/components/alerts/NarrativeMarkdown.tsx
new file mode 100644
index 000000000..47f8ca76a
--- /dev/null
+++ b/apps/web/src/components/alerts/NarrativeMarkdown.tsx
@@ -0,0 +1,115 @@
+/**
+ * Renderer for the narrative's markdown-light dialect.
+ *
+ * `services/fusion/app/services/narrative.py` documents its output as
+ * "Markdown-light: `**bold**`, bullet lists, blank-line paragraphs. The rail
+ * renders these without a full markdown engine. No tables, no headings, no
+ * images." The rail was not rendering them at all — it put the string in a
+ * `whitespace-pre-wrap` paragraph, so an analyst read the asterisks:
+ *
+ * **Medium** alert: Unusual sign-in on **Finance & Legal #2**
+ *
+ * This covers exactly that dialect and nothing more: `**bold**`, backtick
+ * code spans, `- ` bullets, blank-line paragraphs. An unrecognised construct
+ * falls through as literal text rather than being silently dropped.
+ *
+ * It builds React elements, never HTML. The narrative embeds the alert title,
+ * entity names and connector-supplied values, all of which originate outside
+ * the platform, so `dangerouslySetInnerHTML` here would turn any attacker who
+ * can name a host into an XSS author. React escapes text children, and no
+ * branch below constructs markup from the input.
+ *
+ * Whitespace lives inside the parsed text segments rather than between JSX
+ * children on separate source lines, which is the arrangement that makes
+ * React inject `<!-- -->` separators and drop the leading space.
+ */
+
+import { Fragment, type ReactNode } from 'react';
+
+/** Bold and code spans. Split with a capturing group so the delimiters survive. */
+const INLINE_TOKEN = /(\*\*[^*\n]+\*\*|`[^`\n]+`)/g;
+
+const BULLET_PREFIX = '- ';
+
+function renderInline(text: string, keyPrefix: string): ReactNode[] {
+ return text
+ .split(INLINE_TOKEN)
+ .filter((segment) => segment !== '')
+ .map((segment, index) => {
+ const key = `${keyPrefix}i${index}`;
+ if (segment.length > 4 && segment.startsWith('**') && segment.endsWith('**')) {
+ return (
+ <strong key={key} className="font-semibold text-gray-100">
+ {segment.slice(2, -2)}
+ </strong>
+ );
+ }
+ if (segment.length > 2 && segment.startsWith('`') && segment.endsWith('`')) {
+ return (
+ <code
+ key={key}
+ className="rounded bg-gray-800/70 px-1 py-0.5 font-mono text-[0.9em] text-gray-200"
+ >
+ {segment.slice(1, -1)}
+ </code>
+ );
+ }
+ return <Fragment key={key}>{segment}</Fragment>;
+ });
+}
+
+type Run = { kind: 'text' | 'bullets'; lines: string[] };
+
+/** Group a block's lines into consecutive runs of prose and of bullets. */
+function runsFor(block: string): Run[] {
+ const runs: Run[] = [];
+ for (const line of block.split('\n')) {
+ if (line.trim() === '') continue;
+ const isBullet = line.trimStart().startsWith(BULLET_PREFIX);
+ const kind: Run['kind'] = isBullet ? 'bullets' : 'text';
+ const content = isBullet ? line.trimStart().slice(BULLET_PREFIX.length) : line;
+ const last = runs[runs.length - 1];
+ if (last && last.kind === kind) last.lines.push(content);
+ else runs.push({ kind, lines: [content] });
+ }
+ return runs;
+}
+
+export function NarrativeMarkdown({ source }: { source: string }) {
+ const blocks = source
+ .split(/\n{2,}/)
+ .map((block) => block.trim())
+ .filter((block) => block !== '');
+
+ return (
+ <div className="space-y-2 text-sm leading-relaxed text-gray-300">
+ {blocks.flatMap((block, blockIndex) =>
+ runsFor(block).map((run, runIndex) => {
+ const key = `b${blockIndex}r${runIndex}`;
+ if (run.kind === 'bullets') {
+ return (
+ <ul key={key} className="list-disc space-y-1 pl-5">
+ {run.lines.map((line, lineIndex) => (
+ <li key={`${key}l${lineIndex}`}>{renderInline(line, `${key}l${lineIndex}`)}</li>
+ ))}
+ </ul>
+ );
+ }
+ return (
+ <p key={key}>
+ {run.lines.flatMap((line, lineIndex) => {
+ const nodes = renderInline(line, `${key}l${lineIndex}`);
+ // Soft line breaks inside a prose run are preserved as
+ // spaces; the dialect has no hard break and re-flowing is
+ // what the rail's narrow column wants anyway.
+ return lineIndex === 0
+ ? nodes
+ : [<Fragment key={`${key}s${lineIndex}`}> </Fragment>, ...nodes];
+ })}
+ </p>
+ );
+ }),
+ )}
+ </div>
+ );
+}
diff --git a/apps/web/src/components/dashboard/DashboardHonesty.test.tsx b/apps/web/src/components/dashboard/DashboardHonesty.test.tsx
index 0526b76f7..760f3f60e 100644
--- a/apps/web/src/components/dashboard/DashboardHonesty.test.tsx
+++ b/apps/web/src/components/dashboard/DashboardHonesty.test.tsx
@@ -210,6 +210,107 @@ describe('SOCMetricsDashboard — no fabricated data outside demo mode', () => {
});
});
+describe('a mean over no samples is unmeasured, not zero', () => {
+ /**
+ * A live acceptance pass read MTTD/MTTR/MTTC as "0.0 hrs" on a tenant that
+ * had resolved nothing: the averages were over zero rows and
+ * `float(None or 0.0)` published that as a confident number. Zero hours to
+ * respond is the best possible score, so a tenant that had done nothing
+ * topped the league table. The API now reports each mean with the count of
+ * rows it averaged.
+ *
+ * The paired `renders the figure when there are samples` case is what stops
+ * the fix becoming "blank the tiles": both directions have to hold.
+ */
+ const KPIS = {
+ mttd_hours: 0.0,
+ mttr_hours: 0.0,
+ mttc_hours: 0.0,
+ false_positive_rate: 0,
+ escalation_rate: 0,
+ alert_volume_7d: 1,
+ cases_opened_7d: 2,
+ cases_closed_7d: 0,
+ analyst_overrides_7d: 0,
+ };
+
+ it('says so on every tile whose window contains no closures', () => {
+ swrData.set('soc-metrics', {
+ kpis: { ...KPIS, mttd_sample_count: 0, mttr_sample_count: 0, mttc_sample_count: 0 },
+ attack_heatmap: [],
+ calibration_curve: [],
+ });
+
+ render(<SOCMetricsDashboard />);
+
+ expect(screen.getAllByText(/not measured/i).length).toBe(3);
+ expect(screen.queryByText('0.0')).toBeNull();
+ });
+
+ it('renders the figure, and what it was averaged over, once there are samples', () => {
+ swrData.set('soc-metrics', {
+ kpis: { ...KPIS, mttr_hours: 1.5, mttr_sample_count: 2, cases_closed_7d: 2, mttd_sample_count: 0, mttc_sample_count: 0 },
+ attack_heatmap: [],
+ calibration_curve: [],
+ });
+
+ render(<SOCMetricsDashboard />);
+
+ expect(screen.getByText('1.5')).toBeTruthy();
+ expect(screen.getByText(/mean of 2 over 30d/i)).toBeTruthy();
+ });
+
+ it('keeps rendering means for an API build that sends no counts', () => {
+ // Back-compatibility: the counts are additive, and blanking every tile
+ // against an older API would be a worse regression than the bug.
+ swrData.set('soc-metrics', {
+ kpis: { ...KPIS, mttd_hours: 1.2, mttr_hours: 3.4, mttc_hours: 5.6 },
+ attack_heatmap: [],
+ calibration_curve: [],
+ });
+
+ render(<SOCMetricsDashboard />);
+
+ expect(screen.getByText('3.4')).toBeTruthy();
+ expect(screen.queryByText(/not measured/i)).toBeNull();
+ });
+
+ it('does not label an hours figure as minutes on the operations strip', () => {
+ // `alerts.mttr` is hours and the tile rendered it with an `m` suffix, so
+ // a 1.5-hour MTTR would have read "1.5m" had it ever been non-zero.
+ swrData.set('dashboard-metrics', {
+ alerts: { total: 1, new: 1, critical: 0, high: 0, medium: 1, low: 0, resolvedToday: 0, mttr: 1.5, mttr_sample_count: 2 },
+ cases: { open: 0, inProgress: 0, resolvedThisWeek: 0 },
+ sources: [],
+ topMitre: [],
+ alertsTrend: [],
+ threatsBySource: [],
+ });
+
+ render(<DashboardView />);
+
+ expect(screen.getByText('1.5h')).toBeTruthy();
+ expect(screen.queryByText('1.5m')).toBeNull();
+ });
+
+ it('reports the operations strip MTTR as unmeasured when no case has closed', () => {
+ swrData.set('dashboard-metrics', {
+ alerts: { total: 1, new: 1, critical: 0, high: 0, medium: 1, low: 0, resolvedToday: 0, mttr: 0, mttr_sample_count: 0 },
+ cases: { open: 0, inProgress: 0, resolvedThisWeek: 0 },
+ sources: [],
+ topMitre: [],
+ alertsTrend: [],
+ threatsBySource: [],
+ });
+
+ render(<DashboardView />);
+
+ expect(screen.getByText(/not measured · no cases closed/i)).toBeTruthy();
+ expect(screen.queryByText('0m')).toBeNull();
+ expect(screen.queryByText('0.0h')).toBeNull();
+ });
+});
+
describe('demo mode still populates the dashboards', () => {
it('renders the sample connector inventory when the build is the hosted demo', () => {
// The gate must not have become "never show sample data anywhere" — the
diff --git a/apps/web/src/components/dashboard/DashboardView.tsx b/apps/web/src/components/dashboard/DashboardView.tsx
index ba6f4efe1..7f2b248d8 100644
--- a/apps/web/src/components/dashboard/DashboardView.tsx
+++ b/apps/web/src/components/dashboard/DashboardView.tsx
@@ -129,7 +129,10 @@ const MOCK_METRICS: DashboardMetrics = {
medium: 156,
low: 289,
resolvedToday: 67,
- mttr: 42,
+ // Hours, matching the API field. This read `42`, which looked like a
+ // plausible number of minutes next to the tile's old `m` suffix.
+ mttr: 4.2,
+ mttr_sample_count: 34,
},
cases: {
open: 23,
@@ -550,10 +553,23 @@ export function DashboardView() {
sub={`${metrics.cases.inProgress} in progress`}
color="orange"
/>
+ {/* `mttr` is hours and this rendered it with an `m` suffix, so a
+ 1.5-hour MTTR would have read "1.5m". It only ever showed
+ "0m" because the figure was averaged over a column nothing
+ writes during case work — and 0 with no closures is not a
+ measurement, so the tile now says so. */}
<MetricCard
label="MTTR"
- value={`${metrics.alerts.mttr}m`}
- sub="Mean time to resolve"
+ value={
+ metrics.alerts.mttr_sample_count === 0
+ ? '—'
+ : `${metrics.alerts.mttr.toFixed(1)}h`
+ }
+ sub={
+ metrics.alerts.mttr_sample_count === 0
+ ? 'not measured · no cases closed'
+ : 'Mean time to resolve'
+ }
color="green"
/>
<MetricCard
diff --git a/apps/web/src/components/dashboard/SOCMetricsDashboard.tsx b/apps/web/src/components/dashboard/SOCMetricsDashboard.tsx
index 1f80f6453..a81166755 100644
--- a/apps/web/src/components/dashboard/SOCMetricsDashboard.tsx
+++ b/apps/web/src/components/dashboard/SOCMetricsDashboard.tsx
@@ -25,6 +25,9 @@ const MOCK_SOC_METRICS: SOCMetrics = {
cases_opened_7d: 23,
cases_closed_7d: 34,
analyst_overrides_7d: 8,
+ mttd_sample_count: 1247,
+ mttr_sample_count: 34,
+ mttc_sample_count: 12,
},
attack_heatmap: [
{ tactic: "Execution", technique: "T1059 Command & Scripting", count: 42 },
@@ -76,11 +79,13 @@ function KpiCard({
value,
unit,
color,
+ hint,
}: {
label: string;
value: string | number;
unit?: string;
color?: string;
+ hint?: string;
}) {
return (
<div className="bg-gray-900 border border-gray-700 rounded-lg p-4 flex flex-col gap-1">
@@ -89,10 +94,61 @@ function KpiCard({
{value}
{unit && <span className="text-sm font-normal text-gray-400 ml-1">{unit}</span>}
</span>
+ {hint && <span className="text-[10px] text-gray-500">{hint}</span>}
</div>
);
}
+/**
+ * A mean over no samples is unmeasured, not zero.
+ *
+ * The API reports each mean alongside the number of rows it averaged. Without
+ * that, these tiles could not distinguish "we respond in 0.0 hours" from
+ * "nothing has been resolved yet", and they rendered the first — an
+ * unbeatable MTTR for a tenant that had done nothing. `sampleCount` is
+ * optional so an older API, which sends no counts, keeps its previous
+ * behaviour rather than blanking every tile.
+ */
+function MeanHoursCard({
+ label,
+ hours,
+ sampleCount,
+ warnAbove,
+ cautionAbove,
+ window,
+}: {
+ label: string;
+ hours: number | undefined;
+ sampleCount: number | undefined;
+ warnAbove: number;
+ cautionAbove: number;
+ window: string;
+}) {
+ if (hours === undefined || sampleCount === 0) {
+ return (
+ <KpiCard
+ label={label}
+ value="—"
+ color="text-gray-500"
+ hint={sampleCount === 0 ? `not measured · no closures in ${window}` : undefined}
+ />
+ );
+ }
+ return (
+ <KpiCard
+ label={label}
+ value={hours.toFixed(1)}
+ unit="hrs"
+ color={hours > warnAbove ? "text-red-400" : hours > cautionAbove ? "text-yellow-400" : "text-green-400"}
+ hint={
+ sampleCount === undefined
+ ? undefined
+ : `mean of ${sampleCount} over ${window}`
+ }
+ />
+ );
+}
+
const TACTIC_COLORS: Record<string, string> = {
"Initial Access": "bg-red-900",
Execution: "bg-orange-900",
@@ -230,41 +286,29 @@ export function SOCMetricsDashboard() {
{/* KPI Grid */}
{kpis && (
<div className="grid grid-cols-2 md:grid-cols-4 gap-3">
- <KpiCard
+ <MeanHoursCard
label="MTTD"
- value={kpis?.mttd_hours.toFixed(1) ?? "—"}
- unit="hrs"
- color={
- (kpis?.mttd_hours ?? 0) > 4
- ? "text-red-400"
- : (kpis?.mttd_hours ?? 0) > 2
- ? "text-yellow-400"
- : "text-green-400"
- }
+ hours={kpis?.mttd_hours}
+ sampleCount={kpis?.mttd_sample_count}
+ warnAbove={4}
+ cautionAbove={2}
+ window="7d"
/>
- <KpiCard
+ <MeanHoursCard
label="MTTR"
- value={kpis?.mttr_hours.toFixed(1) ?? "—"}
- unit="hrs"
- color={
- (kpis?.mttr_hours ?? 0) > 24
- ? "text-red-400"
- : (kpis?.mttr_hours ?? 0) > 8
- ? "text-yellow-400"
- : "text-green-400"
- }
+ hours={kpis?.mttr_hours}
+ sampleCount={kpis?.mttr_sample_count}
+ warnAbove={24}
+ cautionAbove={8}
+ window="30d"
/>
- <KpiCard
+ <MeanHoursCard
label="MTTC"
- value={kpis?.mttc_hours.toFixed(1) ?? "—"}
- unit="hrs"
- color={
- (kpis?.mttc_hours ?? 0) > 24
- ? "text-red-400"
- : (kpis?.mttc_hours ?? 0) > 8
- ? "text-yellow-400"
- : "text-green-400"
- }
+ hours={kpis?.mttc_hours}
+ sampleCount={kpis?.mttc_sample_count}
+ warnAbove={24}
+ cautionAbove={8}
+ window="7d"
/>
<KpiCard
label="Escalation Rate"
diff --git a/apps/web/src/components/dashboard/operations/ConnectorFleetPanel.tsx b/apps/web/src/components/dashboard/operations/ConnectorFleetPanel.tsx
index a84ce0178..e8dff1f2d 100644
--- a/apps/web/src/components/dashboard/operations/ConnectorFleetPanel.tsx
+++ b/apps/web/src/components/dashboard/operations/ConnectorFleetPanel.tsx
@@ -110,7 +110,12 @@ export function ConnectorFleetPanel() {
Staleness measured against each connector&apos;s own poll cadence.
</p>
</div>
- {data && (
+ {/* With no connectors the badge read "All sources reporting" in green,
+ directly above an empty state saying nothing was configured. Zero
+ sources reporting is not the same statement as all of them
+ reporting, and the green is the part an operator scans for. There
+ is nothing to summarise until there is a fleet. */}
+ {data && connectors.length > 0 && (
<span
className={clsx(
'shrink-0 rounded-full px-2 py-0.5 text-[11px] font-medium',
@@ -121,7 +126,7 @@ export function ConnectorFleetPanel() {
>
{needsAttention > 0
? `${needsAttention} need attention`
- : 'All sources reporting'}
+ : `All ${connectors.length} sources reporting`}
</span>
)}
</div>
diff --git a/apps/web/src/components/dashboard/operations/OperationsDashboard.test.tsx b/apps/web/src/components/dashboard/operations/OperationsDashboard.test.tsx
index 3b7289987..b4e3ba2c1 100644
--- a/apps/web/src/components/dashboard/operations/OperationsDashboard.test.tsx
+++ b/apps/web/src/components/dashboard/operations/OperationsDashboard.test.tsx
@@ -388,6 +388,38 @@ describe('honest empty states', () => {
expect(screen.getByText(/No alerts recorded/i)).toBeTruthy();
});
+ it('claims no fleet is reporting when there is no fleet', async () => {
+ // The badge rendered whenever the endpoint answered, and with zero
+ // connectors `failed + degraded` is zero — so it printed a green "All
+ // sources reporting" directly above "No connectors configured". Zero
+ // sources reporting is not the same statement as all of them reporting,
+ // and green is the part an operator scans for.
+ fleetHealth.mockResolvedValue({ ...FLEET, connectors: [], counts: {} });
+ renderDashboard();
+
+ expect(await screen.findByText(/No connectors configured/i)).toBeTruthy();
+ expect(screen.queryByText(/All sources reporting/i)).toBeNull();
+ expect(screen.queryByText(/sources reporting/i)).toBeNull();
+ });
+
+ it('counts the fleet it is vouching for when every connector is healthy', async () => {
+ const healthy = FLEET.connectors.map((c) => ({
+ ...c,
+ state: 'healthy' as const,
+ last_sync: new Date().toISOString(),
+ missed_intervals: 0,
+ seconds_since_sync: 30,
+ }));
+ fleetHealth.mockResolvedValue({
+ ...FLEET,
+ connectors: healthy,
+ counts: { healthy: healthy.length },
+ });
+ renderDashboard();
+
+ expect(await screen.findByText(`All ${healthy.length} sources reporting`)).toBeTruthy();
+ });
+
it('says nothing is waiting rather than rendering an empty list', async () => {
listApprovals.mockResolvedValue({ ...APPROVALS, items: [], total: 0 });
renderDashboard();
diff --git a/apps/web/src/components/fim/FimDashboard.tsx b/apps/web/src/components/fim/FimDashboard.tsx
index ea66bf839..04c8962e3 100644
--- a/apps/web/src/components/fim/FimDashboard.tsx
+++ b/apps/web/src/components/fim/FimDashboard.tsx
@@ -8,10 +8,14 @@ import { getFimEvents, getFimSummary } from '@/lib/osquery-api';
import { FimSummaryCards } from './FimSummaryCards';
import { FimEventsTable } from './FimEventsTable';
-const TENANT_ID =
- typeof window !== 'undefined'
- ? (process.env.NEXT_PUBLIC_TENANT_ID ?? 'default')
- : 'default';
+// Deliberately *not* `NEXT_PUBLIC_TENANT_ID`. `services/osquery-tls` types its
+// tenant as a plain string and enrols nodes under the literal "default" when no
+// `X-AiSOC-Tenant` header is supplied, so this surface is keyed on that
+// service's own convention rather than on the platform tenant UUID the rest of
+// the console uses. Reading the shared env var here would send a UUID that
+// matches no enrolled node. The two tenancy models need reconciling in
+// osquery-tls; until then this is pinned so it cannot drift silently.
+const TENANT_ID = 'default';
const PAGE_SIZE = 25;
diff --git a/apps/web/src/components/landing/MitreStrip.tsx b/apps/web/src/components/landing/MitreStrip.tsx
deleted file mode 100644
index 7addbd502..000000000
--- a/apps/web/src/components/landing/MitreStrip.tsx
+++ /dev/null
@@ -1,110 +0,0 @@
-'use client';
-
-import { motion } from 'framer-motion';
-
-// Illustrative MITRE ATT&CK tactic strip for the landing page. The numbers
-// below are static placeholders, not a live coverage report. The actual
-// heatmap is rendered by the console against the deployed detection set.
-const TACTICS = [
- { id: 'TA0001', name: 'Initial Access', covered: 9, total: 11 },
- { id: 'TA0002', name: 'Execution', covered: 12, total: 14 },
- { id: 'TA0003', name: 'Persistence', covered: 14, total: 19 },
- { id: 'TA0004', name: 'Priv. Escalation', covered: 11, total: 13 },
- { id: 'TA0005', name: 'Defense Evasion', covered: 27, total: 42 },
- { id: 'TA0006', name: 'Credential Access', covered: 14, total: 17 },
- { id: 'TA0007', name: 'Discovery', covered: 19, total: 30 },
- { id: 'TA0008', name: 'Lateral Movement', covered: 8, total: 9 },
- { id: 'TA0009', name: 'Collection', covered: 10, total: 17 },
- { id: 'TA0011', name: 'C&C', covered: 12, total: 16 },
- { id: 'TA0010', name: 'Exfiltration', covered: 7, total: 9 },
- { id: 'TA0040', name: 'Impact', covered: 10, total: 13 },
-];
-
-function toneFor(ratio: number) {
- if (ratio >= 0.85) return 'bg-emerald-500/30 border-emerald-400/40';
- if (ratio >= 0.65) return 'bg-amber-500/25 border-amber-400/40';
- if (ratio >= 0.45) return 'bg-orange-500/25 border-orange-400/40';
- return 'bg-rose-500/25 border-rose-400/40';
-}
-
-export function MitreStrip() {
- return (
- <section id="mitre" className="relative py-24">
- <div className="mx-auto max-w-7xl px-6">
- <div className="grid grid-cols-1 gap-10 lg:grid-cols-[1fr_1.4fr] lg:items-center">
- <motion.div
- initial={{ opacity: 0, y: 16 }}
- whileInView={{ opacity: 1, y: 0 }}
- viewport={{ once: true, margin: '-100px' }}
- transition={{ duration: 0.5 }}
- >
- <span className="text-xs font-semibold uppercase tracking-wider text-velvet-emerald-mint">
- MITRE ATT&CK
- </span>
- <h2 className="font-velvet-display font-normal mt-3 text-3xl tracking-tight text-velvet-content-primary md:text-4xl">
- Coverage by tactic
- </h2>
- <p className="mt-4 text-lg text-gray-400">
- Detection rules and alerts reference ATT&CK techniques, and the
- console renders a live heatmap from the deployed rule set. The
- tiles below are illustrative; numbers depend on which detection
- packs you enable.
- </p>
- <div className="mt-6 flex flex-wrap gap-3 text-xs">
- <Legend tone="bg-emerald-500/30 border-emerald-400/40" label="≥ 85% covered" />
- <Legend tone="bg-amber-500/25 border-amber-400/40" label="65-84%" />
- <Legend tone="bg-orange-500/25 border-orange-400/40" label="45-64%" />
- <Legend tone="bg-rose-500/25 border-rose-400/40" label="< 45%" />
- </div>
- </motion.div>
-
- <motion.div
- initial={{ opacity: 0, y: 16 }}
- whileInView={{ opacity: 1, y: 0 }}
- viewport={{ once: true, margin: '-100px' }}
- transition={{ duration: 0.5, delay: 0.1 }}
- className="rounded-2xl border border-velvet-content-primary/5 bg-velvet-surface-raised/50 p-5"
- >
- <div className="grid grid-cols-3 gap-2 sm:grid-cols-4 lg:grid-cols-3 xl:grid-cols-4">
- {TACTICS.map((t) => {
- const ratio = t.covered / t.total;
- return (
- <div
- key={t.id}
- className={`relative overflow-hidden rounded-lg border p-3 ${toneFor(ratio)}`}
- >
- <div className="font-mono text-[10px] uppercase tracking-wider text-velvet-content-primary/70">
- {t.id}
- </div>
- <div className="mt-1 text-sm font-semibold text-velvet-content-primary">{t.name}</div>
- <div className="mt-2 flex items-baseline gap-1.5 text-xs text-velvet-content-primary/80">
- <span className="font-mono text-base font-bold text-velvet-content-primary">
- {t.covered}
- </span>
- <span className="text-velvet-content-primary/50">/ {t.total}</span>
- </div>
- <div className="mt-2 h-1 overflow-hidden rounded-full bg-white/10">
- <div
- className="h-full bg-white/70"
- style={{ width: `${Math.round(ratio * 100)}%` }}
- />
- </div>
- </div>
- );
- })}
- </div>
- </motion.div>
- </div>
- </div>
- </section>
- );
-}
-
-function Legend({ tone, label }: { tone: string; label: string }) {
- return (
- <span className="inline-flex items-center gap-2 text-gray-400">
- <span className={`h-3 w-3 rounded border ${tone}`} />
- {label}
- </span>
- );
-}
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index 3dd4483de..4ecc92dd3 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -653,6 +653,12 @@ export interface Alert {
updatedAt: string;
resolvedAt?: string;
confidenceLabel?: ConfidenceLabel;
+ /**
+ * Fusion detection confidence as an integer 0-100, normalised by
+ * `normalizeAlert` regardless of which key and scale the payload used.
+ * Render it as `N/100` — it is not a probability that the verdict is
+ * correct, and it is independent of severity.
+ */
confidenceScore?: number;
confidenceRationale?: ConfidenceFactor[];
ledgerRunId?: string;
@@ -751,6 +757,28 @@ function normalizeAlert(raw: unknown): Alert {
}))
: undefined;
+ // Confidence arrives on two keys at two different scales, and this field
+ // used to accept whichever showed up first: the API surfaces `confidence`
+ // as an integer 0-100, while fusion's `confidence_score` is the raw
+ // [0.0, 1.0] float the band was derived from. One field carrying two
+ // scales meant every consumer had to guess, and they guessed differently —
+ // `AlertDetailView` multiplied by 100 and rendered a real confidence of 21
+ // as "2100%", while `AttackStory` rendered the same value as "21/100".
+ // Both passed their tests because each mock used the scale its own view
+ // assumed.
+ //
+ // Normalised here, once, to the canonical 0-100 integer. The scale is
+ // decided by the *key*, never by the magnitude: a genuine confidence of 1
+ // is indistinguishable from a raw score of 1.0 by value alone.
+ const canonicalConfidence = pickNum('confidence', 'confidence');
+ const rawConfidenceScore = pickNum('confidence_score', 'confidenceScore');
+ const confidenceScore =
+ canonicalConfidence !== undefined
+ ? canonicalConfidence
+ : rawConfidenceScore !== undefined
+ ? Math.round(rawConfidenceScore * 100)
+ : undefined;
+
// ── Investigation Rail envelope (W6) ────────────────────────────────────
// `alert_rail.RelatedEntity` serialises as `{group, kind, value, label,
// pivot}`. This mapper read `e.type` and `e.pivot_path`, which the API has
@@ -858,9 +886,7 @@ function normalizeAlert(raw: unknown): Alert {
confidenceLabel: (r.confidence_label ?? r.confidenceLabel) as
| ConfidenceLabel
| undefined,
- confidenceScore:
- pickNum('confidence_score', 'confidenceScore') ??
- pickNum('confidence', 'confidence'),
+ confidenceScore,
confidenceRationale,
ledgerRunId: pickStr('ledger_run_id', 'ledgerRunId'),
disposition: (r.disposition ?? null) as Alert['disposition'],
@@ -1210,6 +1236,12 @@ export interface EntityRiskStats {
*/
const FUSION_PATH = '/api/v1/fusion';
+// These three routes take the tenant as a *query parameter* as well as the
+// `X-Tenant-Id` header, so the two have to agree or the queue reports on a
+// different tenant than the rest of the console. They read the module-scope
+// env constant, which is fixed at build time and therefore ignores both the
+// logged-in user and the tenant switcher; `getActiveTenantId()` is the same
+// resolution `request()` uses for the header.
export const entityRiskApi = {
/** Top-N entities by current decayed risk score. */
queue: (params: {
@@ -1219,7 +1251,7 @@ export const entityRiskApi = {
} = {}) =>
request<EntityRiskQueueResponse>(`${FUSION_PATH}/entity-risk/queue`, {
params: {
- tenant_id: params.tenantId ?? TENANT_ID,
+ tenant_id: params.tenantId ?? getActiveTenantId(),
limit: params.limit ?? 25,
promoted_only: params.promotedOnly ? 'true' : undefined,
},
@@ -1228,7 +1260,7 @@ export const entityRiskApi = {
/** Tenant-scoped queue stats for dashboards (banding, totals, threshold). */
stats: (tenantId?: string) =>
request<EntityRiskStats>(`${FUSION_PATH}/entity-risk/stats`, {
- params: { tenant_id: tenantId ?? TENANT_ID },
+ params: { tenant_id: tenantId ?? getActiveTenantId() },
}),
/** Full risk record for a single entity (drawer detail). */
@@ -1236,7 +1268,7 @@ export const entityRiskApi = {
const pathType = entityType === 'ip' ? 'src_ip' : entityType;
return request<EntityRiskRecord>(
`${FUSION_PATH}/entity-risk/${pathType}/${encodeURIComponent(entityValue)}`,
- { params: { tenant_id: tenantId ?? TENANT_ID } },
+ { params: { tenant_id: tenantId ?? getActiveTenantId() } },
);
},
};
@@ -1934,7 +1966,10 @@ export interface DashboardMetrics {
low: number;
info?: number;
resolvedToday: number;
+ /** Mean time to resolve, in **hours**, from closed cases. */
mttr: number;
+ /** Cases the mean was taken over. Zero means unmeasured, not zero hours. */
+ mttr_sample_count?: number;
};
cases: {
open: number;
@@ -2022,6 +2057,14 @@ export interface SOCKpis {
cases_opened_7d: number;
cases_closed_7d: number;
analyst_overrides_7d: number;
+ /**
+ * How many rows each mean above was averaged over. Zero means the figure is
+ * unmeasured rather than zero — render "not measured", not "0.0 hrs".
+ * Optional so the console still works against an API that predates them.
+ */
+ mttd_sample_count?: number;
+ mttr_sample_count?: number;
+ mttc_sample_count?: number;
}
export interface AttackHeatmapCell {
diff --git a/apps/web/src/lib/confidenceScale.test.ts b/apps/web/src/lib/confidenceScale.test.ts
new file mode 100644
index 000000000..44144b30d
--- /dev/null
+++ b/apps/web/src/lib/confidenceScale.test.ts
@@ -0,0 +1,88 @@
+/**
+ * `Alert.confidenceScore` has to mean one thing.
+ *
+ * Confidence reaches the console on two keys at two different scales: the API
+ * surfaces `confidence` as an integer 0-100, and fusion's `confidence_score`
+ * is the raw [0.0, 1.0] float the band was derived from. `normalizeAlert`
+ * accepted whichever appeared first and passed it through unchanged, so the
+ * field's scale depended on the payload — and its consumers disagreed about
+ * what they were reading. `AlertDetailView` multiplied by 100 and rendered a
+ * real confidence of 21 as **2100%**; `AttackStory` divided and rendered the
+ * same value as **21/100**. Each was correct for one payload shape, and each
+ * had a passing test because its own mock used the scale it assumed.
+ *
+ * These assertions are on the boundary rather than on either view, because
+ * that is the only place the ambiguity can be removed once.
+ *
+ * Against the pre-change tree, `normalises fusion's raw float` fails
+ * (0.21 arrives as 0.21) and `prefers the canonical integer` fails
+ * (`confidence_score` won).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { alertsApi } from '@/lib/api';
+
+function respondWith(alert: Record<string, unknown>) {
+ return vi.fn(async () =>
+ new Response(JSON.stringify({ id: 'a1', title: 't', severity: 'medium', status: 'new', ...alert }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+}
+
+beforeEach(() => {
+ vi.stubGlobal('fetch', respondWith({}));
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe('confidence normalises to one scale at the API boundary', () => {
+ it('passes the API\u2019s canonical 0-100 integer through unchanged', async () => {
+ vi.stubGlobal('fetch', respondWith({ confidence: 21, confidence_label: 'low' }));
+
+ const alert = await alertsApi.get('a1');
+
+ expect(alert.confidenceScore).toBe(21);
+ });
+
+ it("normalises fusion's raw [0,1] float to the same 0-100 scale", async () => {
+ vi.stubGlobal('fetch', respondWith({ confidence_score: 0.21 }));
+
+ const alert = await alertsApi.get('a1');
+
+ expect(alert.confidenceScore).toBe(21);
+ });
+
+ it('prefers the canonical integer when a payload carries both keys', async () => {
+ // A fused alert read back through the API carries both. Taking
+ // `confidence_score` first meant the row and the detail view could show
+ // 0.21 and 21 for the same alert.
+ vi.stubGlobal('fetch', respondWith({ confidence: 21, confidence_score: 0.21 }));
+
+ const alert = await alertsApi.get('a1');
+
+ expect(alert.confidenceScore).toBe(21);
+ });
+
+ it('decides the scale from the key, never from the magnitude', async () => {
+ // The tempting shortcut is `v <= 1 ? v * 100 : v`. A genuine confidence
+ // of 1/100 is then indistinguishable from a raw score of 1.0, and the
+ // least-confident alert in the estate renders as the most confident.
+ vi.stubGlobal('fetch', respondWith({ confidence: 1 }));
+ expect((await alertsApi.get('a1')).confidenceScore).toBe(1);
+
+ vi.stubGlobal('fetch', respondWith({ confidence_score: 1.0 }));
+ expect((await alertsApi.get('a1')).confidenceScore).toBe(100);
+ });
+
+ it('leaves confidence absent when the payload carries neither key', async () => {
+ // Legacy alerts predate the fusion confidence columns. Absent has to stay
+ // absent so the views can omit the section rather than print a zero.
+ vi.stubGlobal('fetch', respondWith({}));
+
+ expect((await alertsApi.get('a1')).confidenceScore).toBeUndefined();
+ });
+});
diff --git a/apps/web/src/lib/tenantDefault.test.ts b/apps/web/src/lib/tenantDefault.test.ts
new file mode 100644
index 000000000..e81bd9d02
--- /dev/null
+++ b/apps/web/src/lib/tenantDefault.test.ts
@@ -0,0 +1,54 @@
+/**
+ * The console's default tenant reference has to be resolvable.
+ *
+ * `next.config.js` inlined `NEXT_PUBLIC_TENANT_ID` with a fallback of the
+ * *slug* `'default'`. Three tenant-scoped surfaces pass that value as a query
+ * parameter to a route that declares a UUID — `/fusion/entity-risk/queue`,
+ * `/honeytokens/*` and `/business-context/*` — and all three answered 422.
+ *
+ * Two things made it hard to see. `api.ts` carries the correct canonical UUID
+ * as its own fallback, so reading it suggested the console was already doing
+ * the right thing; but Next's inlining runs first, so that fallback was
+ * unreachable code. And the slug is not a dependable handle either: migration
+ * 001 seeds tenant `…0001` with slug `default`, and the demo seed then renames
+ * that slug to `demo`, so on a seeded install the literal matches neither the
+ * id nor the slug.
+ *
+ * This asserts the two defaults agree, which is the part that will drift:
+ * `next.config.js` is CommonJS and cannot import the constant.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_TENANT_ID } from '@/lib/api';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function nextConfigSource(): string {
+ return readFileSync(path.join(process.cwd(), 'next.config.js'), 'utf8');
+}
+
+describe('the default tenant reference', () => {
+ it('is a UUID, because every tenant-scoped route parses it as one', () => {
+ expect(DEFAULT_TENANT_ID).toMatch(UUID);
+ });
+
+ it('is never the tenant slug', () => {
+ // The slug the demo seed renames out from under any caller relying on it.
+ expect(DEFAULT_TENANT_ID).not.toBe('default');
+ expect(DEFAULT_TENANT_ID).not.toBe('demo');
+ });
+
+ it("matches next.config.js, which inlines the value and wins over api.ts", () => {
+ const source = nextConfigSource();
+ const match = source.match(/NEXT_PUBLIC_TENANT_ID:[\s\S]{0,200}?['"]([^'"]+)['"]/);
+
+ expect(match, 'next.config.js no longer declares a NEXT_PUBLIC_TENANT_ID default').toBeTruthy();
+ expect(match?.[1]).toBe(DEFAULT_TENANT_ID);
+ });
+
+ it('does not reintroduce a slug default anywhere in next.config.js', () => {
+ expect(nextConfigSource()).not.toMatch(/NEXT_PUBLIC_TENANT_ID[\s\S]{0,120}?\|\|\s*['"]default['"]/);
+ });
+});
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 1d2e04621..912976825 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -15213,6 +15213,10 @@ components:
mttr:
type: number
title: Mttr
+ mttr_sample_count:
+ type: integer
+ title: Mttr Sample Count
+ default: 0
type: object
required:
- total
@@ -25963,6 +25967,18 @@ components:
analyst_overrides_7d:
type: integer
title: Analyst Overrides 7D
+ mttd_sample_count:
+ type: integer
+ title: Mttd Sample Count
+ default: 0
+ mttr_sample_count:
+ type: integer
+ title: Mttr Sample Count
+ default: 0
+ mttc_sample_count:
+ type: integer
+ title: Mttc Sample Count
+ default: 0
type: object
required:
- mttd_hours
diff --git a/scripts/check_mock_data_gated.py b/scripts/check_mock_data_gated.py
index 98fa322fc..aeedf730e 100644
--- a/scripts/check_mock_data_gated.py
+++ b/scripts/check_mock_data_gated.py
@@ -144,13 +144,14 @@ DEMO_GATE = re.compile(r"demoFallback|canUseDemoData|isDemoMode")
#: Checked in *both* directions — `--check-allowlist` fails when an entry no
#: longer matches anything, so a stale exemption is removed rather than
#: accumulating as cover for whatever is written next under that name.
-ALLOWED_ILLUSTRATIVE: dict[tuple[str, str], str] = {
- (
- "components/landing/MitreStrip.tsx",
- "TACTICS",
- ): "Public landing page, not tenant state. The visible copy already tells the reader "
- "'the tiles below are illustrative; numbers depend on which detection packs you enable'.",
-}
+#: Empty on purpose. The one entry this held excused `MitreStrip.tsx`, whose
+#: twelve ATT&CK tactic tiles carried unsourced coverage counts behind a caveat
+#: in the body copy. The component was imported nowhere and rendered on no
+#: route, so the caveat was the only thing standing between those numbers and a
+#: reader — and it would have stopped standing there the moment someone mounted
+#: the section. Deleting the component was the fix; improving its disclaimer
+#: would have left the numbers in the tree for the next person to inherit.
+ALLOWED_ILLUSTRATIVE: dict[tuple[str, str], str] = {}
def _array_body(lines: list[str], start: int) -> str:
diff --git a/services/api/app/api/v1/endpoints/metrics.py b/services/api/app/api/v1/endpoints/metrics.py
index 7bf2df0b8..027dcfeba 100644
--- a/services/api/app/api/v1/endpoints/metrics.py
+++ b/services/api/app/api/v1/endpoints/metrics.py
@@ -2,7 +2,10 @@
Tier 1.4 (SOC metrics dashboard) — exposes:
* MTTD (mean time to detect): alert.created_at → alert.first_seen_at
- * MTTR (mean time to respond): alert.created_at → alert.resolved_at
+ * MTTR (mean time to respond): case.created_at → case.closed_at, sharing its
+ window and expression with the MSSP portfolio via
+ ``app.services.resolution_time`` so the two surfaces cannot quote
+ different MTTRs for the same tenant
* MTTC (mean time to contain): alert.created_at → alert.resolved_at for
alerts with disposition='true_positive' (proxy for confirmed-contained)
* False-positive rate (FPR): disposition='false_positive' / total resolved
@@ -34,6 +37,11 @@ from app.models.case import Case
from app.models.connector import Connector
from app.models.detection_rule import DetectionRule
from app.models.remediation import RemediationGateLog
+from app.services.resolution_time import (
+ MTTR_WINDOW,
+ tenant_case_mttr_minutes,
+ tenant_cases_closed,
+)
logger = logging.getLogger(__name__)
@@ -48,7 +56,14 @@ class AlertMetrics(BaseModel):
medium: int
low: int
resolvedToday: int
+ # 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
+ # dashboard's own two MTTR tiles read from different tables; and the
+ # console rendered this hours value with an `m` suffix, so a 1.5-hour
+ # MTTR would have displayed as "1.5m" had it ever been non-zero.
mttr: float
+ mttr_sample_count: int = 0
class CaseMetrics(BaseModel):
@@ -240,16 +255,11 @@ async def get_dashboard_metrics(
)
)
- # MTTR for the dashboard tile: average resolved-alert duration over last 7d
- mttr_dashboard_q = await db.scalar(
- select(func.avg(func.extract("epoch", Alert.resolved_at - Alert.created_at) / 3600)).where(
- and_(
- Alert.tenant_id == tenant_id,
- Alert.resolved_at.isnot(None),
- Alert.created_at >= week_start,
- )
- )
- )
+ # MTTR for the dashboard tile — the shared definition, so this tile and the
+ # SOC Performance panel below it cannot report different numbers.
+ mttr_dashboard_minutes = await tenant_case_mttr_minutes(db, tenant_id)
+ mttr_dashboard_q = (mttr_dashboard_minutes / 60.0) if mttr_dashboard_minutes is not None else 0.0
+ mttr_dashboard_samples = await tenant_cases_closed(db, tenant_id, now - MTTR_WINDOW)
alert_metrics = AlertMetrics(
total=total_q or 0,
@@ -260,6 +270,7 @@ async def get_dashboard_metrics(
low=low_q or 0,
resolvedToday=resolved_today_q or 0,
mttr=round(float(mttr_dashboard_q or 0.0), 2),
+ mttr_sample_count=mttr_dashboard_samples,
)
# ── Case counts ───────────────────────────────────────────────────────────
@@ -383,6 +394,18 @@ class SOCKpis(BaseModel):
cases_opened_7d: int
cases_closed_7d: int
analyst_overrides_7d: int
+ # How many rows each mean was averaged over.
+ #
+ # An average over zero rows is not zero, it is unmeasured, and these three
+ # tiles could not tell the difference: `float(None or 0.0)` published "we
+ # respond in 0.0 hours" for a tenant that had resolved nothing. Rather
+ # than make the means nullable — a breaking response change for every
+ # existing client — the sample count travels alongside so the console can
+ # render "not measured" when it is zero. Additive and back-compatible: a
+ # client that ignores these fields sees exactly what it saw before.
+ mttd_sample_count: int = 0
+ mttr_sample_count: int = 0
+ mttc_sample_count: int = 0
class AttackHeatmapCell(BaseModel):
@@ -429,44 +452,40 @@ async def get_soc_metrics(
week_start = now - timedelta(days=7)
# ── MTTD ──────────────────────────────────────────────────────────────────
- # Mean time from alert creation to first analyst view (first_seen_at).
- mttd_q = await db.scalar(
- select(func.avg(func.extract("epoch", Alert.first_seen_at - Alert.created_at) / 3600)).where(
- and_(
- Alert.tenant_id == tenant_id,
- Alert.first_seen_at.isnot(None),
- Alert.created_at >= week_start,
- )
- )
+ # Mean time from alert creation to first analyst view (first_seen_at). This
+ # one genuinely is an alert property — detection latency has nothing to do
+ # with cases — so it stays on the alerts table.
+ mttd_filters = and_(
+ Alert.tenant_id == tenant_id,
+ Alert.first_seen_at.isnot(None),
+ Alert.created_at >= week_start,
)
+ mttd_q = await db.scalar(select(func.avg(func.extract("epoch", Alert.first_seen_at - Alert.created_at) / 3600)).where(mttd_filters))
+ mttd_samples = int(await db.scalar(select(func.count()).where(mttd_filters)) or 0)
mttd_hours = float(mttd_q or 0.0)
# ── MTTR ──────────────────────────────────────────────────────────────────
- # Mean time from alert creation to resolved_at, for any resolved alert.
- mttr_q = await db.scalar(
- select(func.avg(func.extract("epoch", Alert.resolved_at - Alert.created_at) / 3600)).where(
- and_(
- Alert.tenant_id == tenant_id,
- Alert.resolved_at.isnot(None),
- Alert.created_at >= week_start,
- )
- )
- )
- mttr_hours = float(mttr_q or 0.0)
+ # Mean time from case open to case close, over the shared window — the same
+ # rows and the same expression the MSSP portfolio reports, so the two
+ # surfaces cannot quote different MTTRs for one tenant again. This tile
+ # used to average `alerts.resolved_at - alerts.created_at`, which measures
+ # a different lifecycle on a different table; see `resolution_time` for
+ # why that read 0.0 while the portfolio read 1.5h from the same estate.
+ mttr_minutes = await tenant_case_mttr_minutes(db, tenant_id)
+ mttr_hours = (mttr_minutes / 60.0) if mttr_minutes is not None else 0.0
+ mttr_samples = await tenant_cases_closed(db, tenant_id, now - MTTR_WINDOW)
# ── MTTC (Mean Time to Contain) ───────────────────────────────────────────
# For confirmed true-positive alerts only — proxy for "incident contained".
# Uses resolved_at since we don't track a separate contained_at.
- mttc_q = await db.scalar(
- select(func.avg(func.extract("epoch", Alert.resolved_at - Alert.created_at) / 3600)).where(
- and_(
- Alert.tenant_id == tenant_id,
- Alert.resolved_at.isnot(None),
- Alert.disposition == "true_positive",
- Alert.created_at >= week_start,
- )
- )
+ mttc_filters = and_(
+ Alert.tenant_id == tenant_id,
+ Alert.resolved_at.isnot(None),
+ Alert.disposition == "true_positive",
+ Alert.created_at >= week_start,
)
+ mttc_q = await db.scalar(select(func.avg(func.extract("epoch", Alert.resolved_at - Alert.created_at) / 3600)).where(mttc_filters))
+ mttc_samples = int(await db.scalar(select(func.count()).where(mttc_filters)) or 0)
mttc_hours = float(mttc_q or 0.0)
# ── FPR ───────────────────────────────────────────────────────────────────
@@ -528,18 +547,12 @@ async def get_soc_metrics(
# ── Volume / case counts ──────────────────────────────────────────────────
alert_vol = await db.scalar(select(func.count()).where(and_(Alert.tenant_id == tenant_id, Alert.created_at >= week_start))) or 0
cases_opened = await db.scalar(select(func.count()).where(and_(Case.tenant_id == tenant_id, Case.created_at >= week_start))) or 0
- cases_closed = (
- await db.scalar(
- select(func.count()).where(
- and_(
- Case.tenant_id == tenant_id,
- Case.status == "resolved",
- Case.updated_at >= week_start,
- )
- )
- )
- or 0
- )
+ # Counted on `closed_at`, not on `status = 'resolved' AND updated_at`.
+ # `resolved` is an intermediate state and `closed` is the terminal one, so
+ # the old filter reported 0 for a tenant that had closed two cases; and
+ # `updated_at` moves whenever anyone edits the case, which is not when it
+ # was finished.
+ cases_closed = await tenant_cases_closed(db, tenant_id, week_start)
# ── Analyst overrides (7d) ────────────────────────────────────────────────
# Any alert with a disposition set in the last 7 days = analyst weighed in.
@@ -566,6 +579,9 @@ async def get_soc_metrics(
cases_opened_7d=cases_opened,
cases_closed_7d=cases_closed,
analyst_overrides_7d=overrides_q,
+ mttd_sample_count=mttd_samples,
+ mttr_sample_count=mttr_samples,
+ mttc_sample_count=mttc_samples,
)
# ── ATT&CK heatmap ────────────────────────────────────────────────────────
diff --git a/services/api/app/services/mssp_portfolio.py b/services/api/app/services/mssp_portfolio.py
index 4a7036e33..3cfcf6ba2 100644
--- a/services/api/app/services/mssp_portfolio.py
+++ b/services/api/app/services/mssp_portfolio.py
@@ -38,6 +38,11 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.services.entitlements import Headroom, headroom_for_tenant
from app.services.org_scope import PortfolioScope, require_scope
+from app.services.resolution_time import (
+ CLOSED_CASE_PREDICATE,
+ MTTR_MINUTES_EXPR,
+ MTTR_WINDOW,
+)
# A connector that has not synced in this long is stale. Chosen against the
# platform's own defaults: the connector scheduler polls every five minutes,
@@ -45,10 +50,15 @@ from app.services.org_scope import PortfolioScope, require_scope
# well short of a working day.
STALE_AFTER = timedelta(hours=1)
-# Window for the resolution-time average. Long enough that a tenant closing
-# a handful of cases a week still has a number, short enough that it tracks
-# how the account is being run now rather than a year ago.
-MTTR_WINDOW = timedelta(days=30)
+__all__ = [
+ "EMPTY_SUMMARY",
+ "MTTR_WINDOW",
+ "STALE_AFTER",
+ "TenantRollup",
+ "portfolio_alerts",
+ "summarise",
+ "tenant_rollups",
+]
@dataclass(frozen=True)
@@ -138,7 +148,10 @@ async def tenant_rollups(db: AsyncSession, scope: PortfolioScope) -> list[Tenant
rows = (
await db.execute(
text(
- """
+ # Interpolated fragments are module constants from
+ # `resolution_time`, never caller input; the tenant list and
+ # every window stay bound parameters below.
+ f"""
SELECT
t.id,
t.name,
@@ -193,15 +206,11 @@ async def tenant_rollups(db: AsyncSession, scope: PortfolioScope) -> list[Tenant
LEFT JOIN (
SELECT
tenant_id,
- round(
- (avg(EXTRACT(EPOCH FROM (closed_at - created_at))) / 60.0)::numeric,
- 1
- )::float8 AS mttr_minutes
+ {MTTR_MINUTES_EXPR} AS mttr_minutes
FROM cases
WHERE tenant_id = ANY(:tenant_ids)
- AND closed_at IS NOT NULL
+ AND {CLOSED_CASE_PREDICATE}
AND closed_at >= :mttr_since
- AND closed_at >= created_at
GROUP BY tenant_id
) r ON r.tenant_id = t.id
LEFT JOIN (
diff --git a/services/api/app/services/resolution_time.py b/services/api/app/services/resolution_time.py
new file mode 100644
index 000000000..05eff511b
--- /dev/null
+++ b/services/api/app/services/resolution_time.py
@@ -0,0 +1,100 @@
+"""One definition of "how long did it take to resolve", for every surface.
+
+The dashboard and the MSSP portfolio both answer "what is our MTTR?" and they
+answered it differently, from separate queries, against the same rows. The
+dashboard printed **0.0 hrs** and **Cases Closed (7d) 0** for a tenant that
+had closed two cases at a 90-minute mean, which the portfolio reported
+correctly as 1.5h. Two wrong things caused that, and both are the kind that
+survive review because each query reads plausibly on its own:
+
+**The dashboard counted the wrong lifecycle state.** It filtered
+``status = 'resolved'``, but ``resolved`` is an intermediate state — the
+terminal one is ``closed`` (see ``_TRANSITIONS`` in the cases endpoint), and
+it is the transition that writes ``closed_at``. A case that completed its
+lifecycle was therefore invisible to the count. It also windowed on
+``updated_at``, a mutable audit column, so editing a note on an old case
+would move it into the window and closing one without touching it again
+would eventually move it out.
+
+**The dashboard measured a different table.** It averaged
+``alerts.resolved_at - alerts.created_at`` while the portfolio averaged
+``cases.closed_at - cases.created_at``. Only three code paths ever write
+``alerts.resolved_at``, none of which runs during ordinary case work, so the
+average was over zero rows — and ``float(None or 0.0)`` published that as a
+confident ``0.0``.
+
+So this module owns the definition rather than the execution. The portfolio
+computes MTTR inside one bound cross-tenant statement on purpose (one round
+trip for the whole portfolio, see ``mssp_portfolio``), and splitting that
+apart to share a function would cost a query per tenant. Sharing the window
+and the SQL expression keeps one source of truth without that; the property
+that actually prevents the two surfaces drifting apart again is the test that
+asserts they report the same number for the same rows.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# Window for the resolution-time average. Long enough that a tenant closing a
+# handful of cases a week still has a number, short enough that it tracks how
+# the account is being run now rather than a year ago.
+MTTR_WINDOW = timedelta(days=30)
+
+# What "this case is finished" means. `closed_at` is written by the transition
+# into the terminal state, so its presence is the fact; `status` is a label
+# that has had several spellings. The `closed_at >= created_at` guard drops
+# rows whose timestamps were back-filled out of order rather than letting a
+# negative duration pull the mean below zero.
+CLOSED_CASE_PREDICATE = "closed_at IS NOT NULL AND closed_at >= created_at"
+
+# Mean resolution time in minutes. Rounded here, once, so no caller has to
+# decide — and so the dashboard and the portfolio round identically.
+MTTR_MINUTES_EXPR = "round((avg(EXTRACT(EPOCH FROM (closed_at - created_at))) / 60.0)::numeric, 1)::float8"
+
+
+async def tenant_case_mttr_minutes(db: AsyncSession, tenant_id) -> float | None:
+ """Mean minutes from case open to case close for one tenant.
+
+ ``None`` when the tenant closed nothing in the window. That is the whole
+ point of the return type: a tenant with no closed cases has no MTTR, and
+ reporting ``0.0`` puts them top of the league table for having done
+ nothing.
+ """
+ value = await db.scalar(
+ text(
+ f"""
+ SELECT {MTTR_MINUTES_EXPR} AS mttr_minutes
+ FROM cases
+ WHERE tenant_id = :tenant_id
+ AND {CLOSED_CASE_PREDICATE}
+ AND closed_at >= :since
+ """
+ ),
+ {"tenant_id": str(tenant_id), "since": datetime.now(UTC) - MTTR_WINDOW},
+ )
+ return float(value) if value is not None else None
+
+
+async def tenant_cases_closed(db: AsyncSession, tenant_id, since: datetime) -> int:
+ """Cases this tenant actually finished since ``since``.
+
+ Counted on ``closed_at`` for the same reason the mean is: it is the column
+ the close writes, and it does not move when someone edits the case later.
+ """
+ value = await db.scalar(
+ text(
+ f"""
+ SELECT count(*)
+ FROM cases
+ WHERE tenant_id = :tenant_id
+ AND {CLOSED_CASE_PREDICATE}
+ AND closed_at >= :since
+ """
+ ),
+ {"tenant_id": str(tenant_id), "since": since},
+ )
+ return int(value or 0)
diff --git a/services/api/tests/test_resolution_time_parity.py b/services/api/tests/test_resolution_time_parity.py
new file mode 100644
index 000000000..ce6d1da73
--- /dev/null
+++ b/services/api/tests/test_resolution_time_parity.py
@@ -0,0 +1,271 @@
+"""The dashboard and the portfolio must report the same MTTR for the same rows.
+
+A live acceptance pass found the dashboard publishing **CASES CLOSED (7D) 0**
+and **MTTR 0.0 hrs** for a tenant that had closed two cases at a 90-minute
+mean, which `/mssp/portfolio` reported correctly as 1.5h. Two surfaces
+disagreeing about one number is the symptom; two separately written queries
+over the same table is the cause.
+
+So the assertions here come in two shapes, and the second is the one that
+matters over time:
+
+* the figures are right against rows whose values are known by construction —
+ one case closed after 60 minutes, one after 120, mean 90.0; and
+* the two surfaces produce the **same** figure from the same rows, which is
+ what a shared definition is for. Checking each against a hardcoded 90.0
+ independently would let both drift together and still pass.
+
+Every test below fails against the pre-change tree:
+`cases_closed` counted `status = 'resolved' AND updated_at >= …` (the
+lifecycle's terminal state is `closed`, and `updated_at` moves whenever
+anyone edits the case), and MTTR averaged `alerts.resolved_at`, a column no
+part of ordinary case work writes — so it averaged nothing and `float(None
+or 0.0)` published that as a confident zero.
+
+Skips when no database answers so a local `pytest` run stays green, but
+cannot skip where it is supposed 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 whole file exists to
+catch.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import pytest
+import pytest_asyncio
+from app.services.mssp_portfolio import tenant_rollups
+from app.services.org_scope import PortfolioScope
+from app.services.resolution_time import (
+ CLOSED_CASE_PREDICATE,
+ MTTR_MINUTES_EXPR,
+ MTTR_WINDOW,
+ tenant_case_mttr_minutes,
+ tenant_cases_closed,
+)
+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")
+
+pytestmark = pytest.mark.skipif(
+ "postgres" not in DSN and not REQUIRED,
+ reason="needs a live Postgres with the migration chain applied (integration.yml)",
+)
+
+# Fixed ids so a failure names something greppable.
+ORG = uuid.UUID("0a100000-0000-0000-0000-000000000001")
+TENANT = uuid.UUID("0b100000-0000-0000-0000-00000000000a")
+# A tenant in the same portfolio that has closed nothing.
+TENANT_IDLE = uuid.UUID("0b100000-0000-0000-0000-00000000000b")
+
+_ALL_TENANTS = (TENANT, TENANT_IDLE)
+
+
+@pytest_asyncio.fixture
+async def db():
+ 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 MTTR parity 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 _seed(session)
+ try:
+ yield session
+ finally:
+ await _teardown(session)
+ await engine.dispose()
+
+
+async def _teardown(session) -> None:
+ await session.rollback()
+ await session.execute(
+ text("DELETE FROM cases WHERE tenant_id = ANY(:ids)"),
+ {"ids": [str(t) for t in _ALL_TENANTS]},
+ )
+ await session.execute(text("DELETE FROM organizations WHERE id = :id"), {"id": str(ORG)})
+ await session.execute(
+ text("DELETE FROM tenants WHERE id = ANY(:ids)"),
+ {"ids": [str(t) for t in _ALL_TENANTS]},
+ )
+ await session.commit()
+
+
+async def _case(session, *, tenant, number, opened_minutes_ago, duration_minutes, status="closed", closed=True):
+ now = datetime.now(UTC)
+ created = now - timedelta(minutes=opened_minutes_ago)
+ closed_at = created + timedelta(minutes=duration_minutes) if closed else None
+ await session.execute(
+ text(
+ """
+ INSERT INTO cases (id, tenant_id, case_number, title, status, created_at, closed_at, updated_at)
+ VALUES (:id, :tenant, :number, :title, :status, :created, :closed_at, :updated)
+ """
+ ),
+ {
+ "id": str(uuid.uuid4()),
+ "tenant": str(tenant),
+ "number": number,
+ "title": f"parity fixture {number}",
+ "status": status,
+ "created": created,
+ "closed_at": closed_at,
+ # Deliberately *old*, so anything windowing on `updated_at`
+ # instead of `closed_at` misses these rows.
+ "updated": created,
+ },
+ )
+
+
+async def _seed(session) -> None:
+ await _teardown(session)
+ for tenant, name in ((TENANT, "Parity Tenant"), (TENANT_IDLE, "Idle Tenant")):
+ await session.execute(
+ text("INSERT INTO tenants (id, name, slug, plan) VALUES (:id, :name, :slug, 'enterprise')"),
+ {"id": str(tenant), "name": name, "slug": f"parity-{tenant.hex}"},
+ )
+ await session.execute(
+ text("INSERT INTO organizations (id, slug, name, kind) VALUES (:id, :slug, :name, 'mssp')"),
+ {"id": str(ORG), "slug": f"parity-org-{ORG.hex[:8]}", "name": "Parity Org"},
+ )
+
+ # Mean of 60 and 120 is 90.0 minutes = 1.5 hours.
+ await _case(session, tenant=TENANT, number=f"PAR-{TENANT.hex[:6]}-1", opened_minutes_ago=4320, duration_minutes=60)
+ await _case(session, tenant=TENANT, number=f"PAR-{TENANT.hex[:6]}-2", opened_minutes_ago=2880, duration_minutes=120)
+ await session.commit()
+
+
+async def test_cases_closed_counts_the_terminal_state_not_the_intermediate_one(db) -> None:
+ """Both fixtures are `closed`; the old query looked for `resolved`."""
+ week_ago = datetime.now(UTC) - timedelta(days=7)
+ assert await tenant_cases_closed(db, TENANT, week_ago) == 2
+
+
+async def test_cases_closed_windows_on_closed_at_not_updated_at(db) -> None:
+ """The fixtures' `updated_at` is set to their creation time, days before
+ the close. Anything windowing on `updated_at` still finds them here, so
+ the sharper assertion is a row closed *inside* the window whose
+ `updated_at` sits *outside* it."""
+ await _case(
+ db,
+ tenant=TENANT,
+ number=f"PAR-{TENANT.hex[:6]}-3",
+ opened_minutes_ago=30,
+ duration_minutes=10,
+ )
+ await db.execute(
+ text("UPDATE cases SET updated_at = now() - interval '400 days' WHERE case_number = :n"),
+ {"n": f"PAR-{TENANT.hex[:6]}-3"},
+ )
+ await db.commit()
+
+ week_ago = datetime.now(UTC) - timedelta(days=7)
+ assert await tenant_cases_closed(db, TENANT, week_ago) == 3
+
+
+async def test_a_case_marked_closed_without_a_closed_at_is_not_counted(db) -> None:
+ """`closed_at` is the fact; `status` is a label that has had several
+ spellings. A row with the label and no timestamp has no duration, so
+ counting it would put a case with no measurable resolution time into the
+ denominator of the mean."""
+ await _case(
+ db,
+ tenant=TENANT,
+ number=f"PAR-{TENANT.hex[:6]}-4",
+ opened_minutes_ago=100,
+ duration_minutes=0,
+ closed=False,
+ )
+ await db.commit()
+
+ week_ago = datetime.now(UTC) - timedelta(days=7)
+ assert await tenant_cases_closed(db, TENANT, week_ago) == 2
+
+
+async def test_mttr_is_the_mean_of_the_known_durations(db) -> None:
+ assert await tenant_case_mttr_minutes(db, TENANT) == 90.0
+
+
+async def test_mttr_is_none_when_the_tenant_closed_nothing(db) -> None:
+ """Null and 0.0 are opposite claims — "no data" and "instant resolution".
+ The console renders the first as "not measured"; publishing the second put
+ a tenant that had done nothing at the top of the league table."""
+ assert await tenant_case_mttr_minutes(db, TENANT_IDLE) is None
+
+
+async def test_a_case_closed_before_it_was_created_is_excluded(db) -> None:
+ """Back-filled timestamps out of order would otherwise pull the mean
+ below zero and make the tile read as a negative duration."""
+ await _case(
+ db,
+ tenant=TENANT,
+ number=f"PAR-{TENANT.hex[:6]}-5",
+ opened_minutes_ago=200,
+ duration_minutes=-500,
+ )
+ await db.commit()
+
+ assert await tenant_case_mttr_minutes(db, TENANT) == 90.0
+
+
+async def test_the_dashboard_and_the_portfolio_agree_on_the_same_rows(db) -> None:
+ """The assertion the defect was actually about.
+
+ Not "each equals 90.0" — that would let both drift together — but that the
+ figure the SOC dashboard computes and the figure the portfolio computes
+ are the same number for one tenant's rows.
+ """
+ dashboard_minutes = await tenant_case_mttr_minutes(db, TENANT)
+
+ scope = PortfolioScope(org_id=ORG, tenant_ids=frozenset(_ALL_TENANTS), portfolio_wide=True)
+ rollups = await tenant_rollups(db, scope)
+ by_tenant = {r.tenant_id: r for r in rollups}
+
+ assert by_tenant[TENANT].mttr_minutes == dashboard_minutes
+ # And the idle tenant is absent from both, rather than zero in either.
+ assert by_tenant[TENANT_IDLE].mttr_minutes is None
+ assert await tenant_case_mttr_minutes(db, TENANT_IDLE) is None
+
+
+def test_the_portfolio_query_is_built_from_the_shared_definition() -> None:
+ """A no-database gate against the two queries drifting apart again.
+
+ The portfolio computes MTTR inside one bound cross-tenant statement on
+ purpose — one round trip for the whole portfolio — so it interpolates the
+ shared fragments rather than calling the shared function. That is only
+ safe while it really does interpolate them.
+ """
+ import inspect
+
+ from app.services import mssp_portfolio
+
+ source = inspect.getsource(mssp_portfolio.tenant_rollups)
+ assert "{MTTR_MINUTES_EXPR}" in source, "portfolio MTTR no longer uses the shared expression"
+ assert "{CLOSED_CASE_PREDICATE}" in source, "portfolio MTTR no longer uses the shared predicate"
+ # And the fragments themselves are still about the column that carries the
+ # fact, not the status label that has had several spellings.
+ assert "closed_at" in CLOSED_CASE_PREDICATE
+ assert "status" not in CLOSED_CASE_PREDICATE
+ assert "closed_at" in MTTR_MINUTES_EXPR
+ assert MTTR_WINDOW == timedelta(days=30)