Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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

feat(detection): rule tuning workbench + endpoints (PR-6 / W8)

Beenu Arora7acea9c84ec4
diff --git a/apps/docs/docs/console/rule-tuning.md b/apps/docs/docs/console/rule-tuning.md
new file mode 100644
index 000000000..016a4a219
--- /dev/null
+++ b/apps/docs/docs/console/rule-tuning.md
@@ -0,0 +1,248 @@
+---
+sidebar_position: 2
+title: Detection Tuning workbench
+description: The /detection/tuning workbench — an opinionated, single-page console for triaging noisy detection rules with API-driven suggestions, scored mechanical actions, and per-rule auto-tune opt-in.
+---
+
+# Detection Tuning workbench
+
+`/detection/tuning` is the page a detection engineer or SOC lead opens when alert volume is climbing and they need to know *which rules are spending the queue's attention*. It replaces the old static `/noise-tuning` prototype with a live, API-backed workbench: every row is projected from real `DetectionRule` state (false-positive rate, total hits, confidence, last-triggered time, status), classified into one of six suggestion lanes, and surfaced with a one-click mechanical action that mutates the rule and writes an audit log entry.
+
+This page documents the projection heuristics, the action set, the API surface, and the pieces that make the workbench cheap enough to run on every page load.
+
+## Where the workbench sits
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ Detection Tuning Updated 10:14:02 [Refresh]│
+│ ────────────────────────────────────────────────────────────────────── │
+│ [Total 87] [Actionable 14] [Healthy 73] [Auto-tune 6] │
+│ [Disable 3] [Add suppression 5] [Raise threshold 4] [Tune confidence 2] │
+│ ────────────────────────────────────────────────────────────────────── │
+│ [All severities ▾] [All suggestions ▾] [Search…] ☑ Enabled only │
+│ ────────────────────────────────────────────────────────────────────── │
+│ ● HIGH Okta — failed MFA flood Disable FP 72% 1.2k hits ⓘ │
+│ FP 72% ≥ 50% with confidence 30 < 40 [Disable rule] [⋮] │
+│ Auto-tune ◯ │
+│ ● MED Defender — script block Add suppression FP 28% 340 hits ⓘ │
+│ FP 28% ≥ 20% — add a suppression for the noisy entity │
+│ Auto-tune ● │
+│ ────────────────────────────────────────────────────────────────────── │
+│ Disable first ─► Suppress ─► Threshold ─► Confidence ─► Stale │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+The workbench is intentionally narrow — one row per rule, one suggestion per row, one primary mechanical action surfaced as a button. Drilling into rule semantics still happens on `/detection/{id}`; this page is where you decide *which* rule to tune next.
+
+## The six suggestion lanes
+
+The projection is a pure function: given a `DetectionRule`, the classifier walks a fixed precedence ladder and returns the **first** matching lane. Heavier interventions (`disable`, `add_suppression`) win over softer hints (`review_stale`), so the workbench never recommends a confidence bump for a rule that should clearly be turned off.
+
+| Lane | Trigger | Default action | Reason text |
+|---|---|---|---|
+| **Disable** | Rule is active, `fp_rate ≥ 0.50`, `confidence < 40`. | `disable` | "FP rate X% ≥ 50% with confidence Y < 40" |
+| **Add suppression** | Rule is active and `fp_rate ≥ 0.20`. | `add_suppression` | "FP rate X% ≥ 20% — add a suppression for the noisy entity" |
+| **Raise threshold** | Rule is active, `fp_rate ≥ 0.10`, `total_hits ≥ 20`. | `raise_threshold` | "FP rate X% with N hits — bumping the threshold trims volume without losing the signal" |
+| **Tune confidence** | `confidence < 40` and `total_hits ≥ 20` (regardless of status). | `acknowledge` | "Confidence Y < 40 despite N hits — re-evaluate the rule body" |
+| **Review stale** | Rule is active and either last fired more than 30 days ago, or has never fired but is older than 30 days. | `acknowledge` | "Last hit was N days ago (stale threshold is 30d)" |
+| **Healthy** | Nothing above matched. | — | Empty reasons; the row is included in the population so the summary tile counts remain meaningful. |
+
+All thresholds are exported from [`app/services/rule_tuning.py`](https://github.com/beenuar/AiSOC/blob/main/services/api/app/services/rule_tuning.py) as module constants — `TUNING_FP_RATE_NOISY`, `TUNING_FP_RATE_BUMPABLE`, `TUNING_FP_RATE_DISABLE`, `TUNING_LOW_CONFIDENCE`, `TUNING_MIN_HITS_FOR_THRESHOLD`, `TUNING_STALE_DAYS` — so the docs page, the tests, and the production classifier share the same numbers. If product tuning changes one, every consumer updates with it.
+
+### Why we do not recompute live FP rates
+
+The classifier reads `fp_rate`, `total_hits`, `confidence`, and `last_triggered` directly off the `DetectionRule` row. Those fields are maintained by the alert ingestion and feedback pipelines — every confirmed false-positive bumps the count, every fired alert updates the timestamp. The workbench never joins the alerts table at projection time. That keeps the page fast enough to scan hundreds of rules per request without putting any load on the hot path, and it means the suggestions stay stable across page polls (the picture only changes when the underlying rule metrics move).
+
+### Scoring and ordering
+
+After classification, every entry gets a single integer score:
+
+```
+score = SUGGESTION_WEIGHT[lane] # 500 disable → 0 healthy
+ + round(fp_rate * 100) # 0..100
+ + min(total_hits, 1000) // 10 # 0..100
+```
+
+The lane weight dominates so the list is grouped sensibly (`disable` rows are always above `add_suppression` rows are always above `raise_threshold`, and so on), but inside a lane the *noisiest* and *highest-volume* rules float to the top. The frontend then breaks ties by `fp_rate desc`, `total_hits desc`, and finally name (case-insensitive) for stable rendering across polls.
+
+### Scan budget
+
+Each projection caps at `TUNING_MAX_RULES_SCANNED = 1000` — the heaviest rules by `fp_rate` and `total_hits` are pulled from PostgreSQL first, and the Python classifier walks at most that many. A tenant that has imported 50 000 Sigma rules will see the worst 1 000 surface; a tenant with 87 rules sees all of them. This bound exists so the workbench cannot accidentally DoS itself.
+
+## The actions
+
+Each row exposes one primary mechanical action (driven by the suggestion lane), one secondary affordance (Dismiss), and one persistent toggle (Auto-tune). All three are flat: no modals, no confirmation dialogs. Toast feedback comes from the response payload.
+
+| Action | What it does | Backend |
+|---|---|---|
+| **Disable rule** | Sets `DetectionRule.status = 'disabled'`. | `POST /api/v1/detection/tuning/{id}/apply` with `action='disable'`. |
+| **Add suppression** | Appends a `{kind: 'tune_placeholder', reason, added_by}` entry to `suppression_config.rules` and stamps `last_tuned_at`. The real suppression engine consumes `suppression_config.rules` — this just seeds it with an entry analysts can refine. | `POST /api/v1/detection/tuning/{id}/apply` with `action='add_suppression'`. |
+| **Raise threshold** | Increments `threshold_config.event_threshold` by +1 (or sets the explicit `threshold` from the payload, clamped `[1, 1_000_000]`) and stamps `threshold_config.last_raised_at`. | `POST /api/v1/detection/tuning/{id}/apply` with `action='raise_threshold'`. |
+| **Acknowledge** | No-op on rule semantics — only stamps `suppression_config.tuning_last_action*` and emits an audit event. Used by `tune_confidence` and `review_stale` rows to clear them without mutation. | `POST /api/v1/detection/tuning/{id}/apply` with `action='acknowledge'`. |
+| **Dismiss** | Sets `suppression_config.tuning_dismissed_at` (+ `tuning_dismissed_by`, optional `tuning_dismissed_reason`). The row drops out of the default workbench view. Toggling `include_dismissed=true` brings it back so dismissals stay auditable. | `POST /api/v1/detection/tuning/{id}/dismiss`. |
+| **Auto-tune toggle** | Flips `suppression_config.auto_tune` (with `auto_tune_updated_at` + `auto_tune_updated_by`). The flag is an opt-in marker for future automated tuners — flipping it does **not** trigger any immediate rule change. | `POST /api/v1/detection/tuning/{id}/auto_tune`. |
+
+### Apply also un-dismisses
+
+Every `apply_tuning` call clears `suppression_config.tuning_dismissed_at` and `tuning_dismissed_reason` on its way out. The reasoning: if an analyst engages with a previously dismissed rule, they have implicitly decided to bring it back into the queue. The audit event still records the prior dismissal in the `before` block, so nothing is lost.
+
+### Version + audit on every mutation
+
+`apply_tuning` always bumps `DetectionRule.version` and emits a `detection.tuning.apply` audit event with the pre/post values of `status`, `confidence`, `threshold_config`, and `suppression_config`, plus a `payload` block describing the requested action. `dismiss_tuning` and `set_auto_tune` emit `detection.tuning.dismiss` and `detection.tuning.auto_tune` respectively. Every change is reversible by inspecting the audit log; nothing is mutated silently.
+
+### Platform vs tenant rules
+
+Built-in / platform rules (rows with `tenant_id IS NULL`) appear in projections so analysts can see them, but every mutator (`apply`, `dismiss`, `auto_tune`) refuses to touch them with a `403 Forbidden`. Tuning a global rule from one tenant's workbench would leak the change to every other tenant; the guard is in `_load_rule_for_tenant`.
+
+## The API surface
+
+The workbench is served by four endpoints under a single router prefix:
+
+```
+GET /api/v1/detection/tuning
+ ?severity=info|low|medium|high|critical (default: any)
+ &suggestion=disable|add_suppression|raise_threshold|tune_confidence|review_stale|healthy
+ &search=<substring, max 200 chars> (matches name/description/category)
+ &enabled_only=true|false (default: false)
+ &include_dismissed=true|false (default: false)
+ &page=1 (default: 1)
+ &page_size=50 (default: 50, max: 100)
+
+GET /api/v1/detection/tuning/summary
+POST /api/v1/detection/tuning/{rule_id}/apply
+POST /api/v1/detection/tuning/{rule_id}/dismiss
+POST /api/v1/detection/tuning/{rule_id}/auto_tune
+```
+
+`GET` endpoints require `rules:read`; all three `POST` endpoints require `rules:write`. Every endpoint runs under a tenant-scoped DB session, and the build query filters `DetectionRule.tenant_id = current_user.tenant_id OR DetectionRule.tenant_id IS NULL` — analysts see their own tenant's rules plus platform rules, but cannot mutate platform rules.
+
+### Response shape
+
+The `TuningResponse` envelope:
+
+```jsonc
+{
+ "entries": [
+ {
+ "rule_id": "8b2e…",
+ "name": "Okta — failed MFA flood",
+ "description": "…",
+ "category": "identity",
+ "severity": "high",
+ "status": "active",
+ "enabled": true,
+ "confidence": 30,
+ "fp_rate": 0.72,
+ "total_hits": 1247,
+ "last_triggered_at": "2026-05-12T18:42:11Z",
+ "tags": ["okta", "mfa"],
+ "mitre_tactics": ["TA0006"],
+ "mitre_techniques": ["T1110"],
+ "version": 7,
+ "updated_at": "2026-05-13T09:01:33Z",
+
+ "suggestion": "disable",
+ "score": 572,
+ "reasons": [
+ "FP rate 72% ≥ 50% with confidence 30 < 40",
+ "1247 total hits — disable will reduce queue pressure immediately"
+ ],
+ "auto_tune": false,
+ "dismissed_at": null,
+ "last_action": null,
+ "last_action_at": null
+ }
+ ],
+ "summary": {
+ "total_rules": 87,
+ "actionable": 14,
+ "healthy": 73,
+ "disable_count": 3,
+ "add_suppression_count": 5,
+ "raise_threshold_count": 4,
+ "tune_confidence_count": 2,
+ "review_stale_count": 0,
+ "auto_tune_enabled": 6,
+ "average_fp_rate": 0.0834,
+ "high_fp_count": 8
+ },
+ "filters": {
+ "severity": null,
+ "suggestion": null,
+ "search": null,
+ "enabled_only": false,
+ "include_dismissed": false,
+ "page": 1,
+ "page_size": 50
+ },
+ "total": 87,
+ "generated_at": "2026-05-13T10:14:02Z"
+}
+```
+
+Notes on the contract:
+
+- `summary` is computed across the **entire classified population** for the tenant, not just the current page. The header tiles stay stable as analysts page through filtered results.
+- `total` is the count *after* the `suggestion` filter is applied (but before pagination), so it matches the size of the filtered result set.
+- Dismissed rules are excluded from `entries` *and* `summary` by default. Pass `include_dismissed=true` to bring them back when auditing what's been hidden.
+- `generated_at` is the server's `now()` at projection time — the frontend renders it in the header so analysts can confirm the data is fresh.
+
+### `POST /apply` payload
+
+```jsonc
+{
+ "action": "disable" | "add_suppression" | "raise_threshold" | "acknowledge",
+ "note": "optional free-text reason, recorded in suppression_config",
+ "threshold": 5, // only for raise_threshold; clamped [1, 1_000_000]
+ "suppression_reason": "…" // only for add_suppression; max 255 chars
+}
+```
+
+The response is the **re-projected entry** for the freshly-mutated rule, so the UI can refresh in place without a second round-trip. Frontend usage: `handleApply` issues the POST, awaits the response, then `mutate()`s the SWR cache to redraw the row with its new suggestion and reasons.
+
+### `POST /dismiss` and `POST /auto_tune`
+
+Both endpoints accept minimal bodies (`{reason?: string}` and `{enabled: bool}` respectively) and return the re-projected entry. Auto-tune is the only mutator that doesn't write to the audit `changes.before/after` triplet — it only stamps the boolean transition because that's the only thing analysts and auditors care about for that flag.
+
+## Polling and freshness
+
+The workbench uses SWR with `keepPreviousData: true` and `revalidateOnFocus: false`. There is no automatic refresh interval — the data is cheap to fetch but does not move minute-to-minute, so we trade auto-polling for an explicit **Refresh** button in the header. Every successful mutation (`apply`, `dismiss`, `auto_tune`) calls `mutate()` to revalidate immediately, so the row updates in place without waiting for an interval.
+
+Tests cover the same flow: render → click action → assert SWR cache was invalidated and the new entry rendered.
+
+## Permissions and tenancy
+
+| Endpoint | Permission |
+|---|---|
+| `GET /detection/tuning`, `GET /detection/tuning/summary` | `rules:read` |
+| `POST /detection/tuning/{id}/apply`, `/dismiss`, `/auto_tune` | `rules:write` |
+
+The tenant filter is baked in at the SQLAlchemy layer — `_load_rule_for_tenant` re-asserts it on every mutation and 404s if the rule belongs to a different tenant. Platform rules (`tenant_id IS NULL`) are visible everywhere but mutable nowhere from inside a tenant workbench.
+
+## What this replaces
+
+| Before (v1.4) | After (v1.5) |
+|---|---|
+| `/noise-tuning` was a hand-coded prototype that read from fixture data and surfaced cosmetic "auto-tune" toggles with no backing semantics. | `/detection/tuning` runs against live `DetectionRule` state, classifies every rule into one of six lanes, and persists every action with a version bump and an audit event. |
+| Tuning was a manual JSON edit in the rule editor, with no projection or scoring. | A single-page workbench groups rules by suggestion lane, scores them so the worst surface first, and exposes one-click mechanical actions. |
+| Auto-tune was UI-only — flipping the toggle had no server-side effect. | `auto_tune` is stored on `suppression_config.auto_tune` with a server-recorded actor and timestamp, ready to gate future automated tuners. |
+| Dismissing a rule meant filtering it out client-side; the next page load brought it back. | Dismissals persist on `suppression_config.tuning_dismissed_at`, are auditable, and can be inspected by passing `include_dismissed=true`. |
+| The legacy `/noise-tuning` route still existed in the sidebar. | `/noise-tuning` now redirects to `/detection/tuning` so bookmarks and external links land on the live workbench automatically. |
+
+## Source layout
+
+| Concern | File |
+|---|---|
+| Workbench page route | [`apps/web/src/app/(app)/detection/tuning/page.tsx`](https://github.com/beenuar/AiSOC/blob/main/apps/web/src/app/(app)/detection/tuning/page.tsx) |
+| Workbench component | [`apps/web/src/components/detections/RuleTuningView.tsx`](https://github.com/beenuar/AiSOC/blob/main/apps/web/src/components/detections/RuleTuningView.tsx) |
+| Back-compat redirect | [`apps/web/src/app/(app)/noise-tuning/page.tsx`](https://github.com/beenuar/AiSOC/blob/main/apps/web/src/app/(app)/noise-tuning/page.tsx) |
+| Sidebar entry | [`apps/web/src/components/layout/Sidebar.tsx`](https://github.com/beenuar/AiSOC/blob/main/apps/web/src/components/layout/Sidebar.tsx) (search for `Detection Tuning`) |
+| API client | [`apps/web/src/lib/api.ts`](https://github.com/beenuar/AiSOC/blob/main/apps/web/src/lib/api.ts) (search for `tuningApi`) |
+| Tuning endpoints | [`services/api/app/api/v1/endpoints/rule_tuning.py`](https://github.com/beenuar/AiSOC/blob/main/services/api/app/api/v1/endpoints/rule_tuning.py) |
+| Projection + classifier + mutators | [`services/api/app/services/rule_tuning.py`](https://github.com/beenuar/AiSOC/blob/main/services/api/app/services/rule_tuning.py) |
+| Backend tests | [`services/api/tests/test_rule_tuning.py`](https://github.com/beenuar/AiSOC/blob/main/services/api/tests/test_rule_tuning.py) |
+| Frontend tests | [`apps/web/src/components/detections/RuleTuningView.test.tsx`](https://github.com/beenuar/AiSOC/blob/main/apps/web/src/components/detections/RuleTuningView.test.tsx) |
+
+## Author
+
+Beenu Arora · `[email protected]`
diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.ts
index 5dc658978..37140744c 100644
--- a/apps/docs/sidebars.ts
+++ b/apps/docs/sidebars.ts
@@ -30,7 +30,7 @@ const sidebars: SidebarsConfig = {
{
type: "category",
label: "Console",
- items: ["console/queue"],
+ items: ["console/queue", "console/rule-tuning"],
},
{
type: "category",
diff --git a/apps/web/src/app/(app)/detection/tuning/page.tsx b/apps/web/src/app/(app)/detection/tuning/page.tsx
new file mode 100644
index 000000000..2f2493e03
--- /dev/null
+++ b/apps/web/src/app/(app)/detection/tuning/page.tsx
@@ -0,0 +1,9 @@
+import RuleTuningView from '@/components/detections/RuleTuningView';
+
+export const metadata = {
+ title: 'Detection Tuning | AiSOC',
+};
+
+export default function DetectionTuningPage() {
+ return <RuleTuningView />;
+}
diff --git a/apps/web/src/app/(app)/noise-tuning/page.tsx b/apps/web/src/app/(app)/noise-tuning/page.tsx
index 35b3d5ae8..00b35d7d6 100644
--- a/apps/web/src/app/(app)/noise-tuning/page.tsx
+++ b/apps/web/src/app/(app)/noise-tuning/page.tsx
@@ -1,7 +1,13 @@
-import NoiseTuningView from '@/components/noise/NoiseTuningView';
+import { redirect } from 'next/navigation';
export const metadata = { title: 'Alert Noise Tuning | AiSOC' };
+/**
+ * Back-compat redirect. The legacy `/noise-tuning` prototype has been
+ * replaced by the API-backed Detection Tuning workbench at
+ * `/detection/tuning` (PR-6, W8). Bookmarks and external links land
+ * on the new workbench automatically.
+ */
export default function NoiseTuningPage() {
- return <NoiseTuningView />;
+ redirect('/detection/tuning');
}
diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsx
index 6e0b74cd9..694dc8fb7 100644
--- a/apps/web/src/app/layout.tsx
+++ b/apps/web/src/app/layout.tsx
@@ -142,7 +142,7 @@ const jsonLd = {
'Adversary simulation eval harness (200 incidents)',
'SLA tracking, automated compliance evidence, and AI-generated incident reports',
'MSSP multi-tenant support, shift-handoff dashboard, and team analytics',
- 'External Attack Surface Management (EASM) and noise-tuning dashboard',
+ 'External Attack Surface Management (EASM) and detection tuning workbench',
'STIX 2.1 / TAXII 2.1 publishing and air-gap deployment configuration',
'Self-hosted deployment with Docker Compose',
],
diff --git a/apps/web/src/components/detections/RuleTuningView.test.tsx b/apps/web/src/components/detections/RuleTuningView.test.tsx
new file mode 100644
index 000000000..bc704e258
--- /dev/null
+++ b/apps/web/src/components/detections/RuleTuningView.test.tsx
@@ -0,0 +1,481 @@
+/**
+ * Smoke tests for the Detection Tuning workbench (PR-6 / v1.5 §W8).
+ *
+ * The workbench replaces the old static `/noise-tuning` prototype, so the
+ * behaviours we pin here are the ones an SOC engineer would file a P1
+ * against if they regressed:
+ *
+ * 1. Loading skeleton renders before the first server response.
+ * 2. Summary cards render real counts from the response.
+ * 3. Tuning rows show rule name, severity pill, suggestion pill,
+ * FP%, hit count, confidence, and an auto-tune toggle.
+ * 4. The primary apply action maps per suggestion:
+ * - `disable` → POST apply { action: 'disable' }
+ * - `add_suppression` → POST apply { action: 'add_suppression' }
+ * - `raise_threshold` → POST apply { action: 'raise_threshold' }
+ * - `tune_confidence` / `review_stale` → 'acknowledge'
+ * - `healthy` → 'acknowledge' (no destructive action)
+ * On success a toast is fired and SWR is revalidated; on error the
+ * message bubbles into a toast.error().
+ * 5. Dismiss calls `tuningApi.dismiss(rule_id, {})`, fires a toast,
+ * and revalidates. Already-dismissed rows have a disabled Dismiss.
+ * 6. The auto-tune toggle flips state via `tuningApi.autoTune(rule_id, !current)`.
+ * 7. Changing the suggestion filter resets the page to 1 (we assert via
+ * `tuningApi.list` being called with `page: 1` after a filter change).
+ * 8. The error state renders when SWR returns an error, with a working
+ * retry handler.
+ * 9. The empty state copy differs for the "filters dirty" case vs the
+ * "everything is healthy" case, and exposes a Clear-filters CTA in
+ * the former.
+ *
+ * SWR, `@/lib/api`, and `react-hot-toast` are mocked so the test focuses
+ * on the view layer without booting a fetch stack. Mirrors the pattern
+ * already established in `QueueView.test.tsx` (PR-5).
+ *
+ * @author Beenu Arora <[email protected]>
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { act, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { TuningEntry, TuningResponse, TuningSummary } from '@/lib/api';
+
+// ─── Mock SWR ─────────────────────────────────────────────────────────────────
+//
+// The component calls `useSWR(['detection-tuning', listParams], fetcher, opts)`.
+// We mirror the subset of the hook surface the component touches and expose a
+// hand-rolled `mutate()` that tests can assert on.
+
+const swrState = vi.hoisted(() => ({
+ data: undefined as TuningResponse | undefined,
+ error: undefined as Error | undefined,
+ isLoading: false,
+ isValidating: false,
+}));
+
+const mutateMock = vi.hoisted(() => vi.fn());
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({
+ data: swrState.data,
+ error: swrState.error,
+ isLoading: swrState.isLoading,
+ isValidating: swrState.isValidating,
+ mutate: mutateMock,
+ }),
+}));
+
+// ─── Mock the API layer ───────────────────────────────────────────────────────
+
+const tuningListMock = vi.hoisted(() => vi.fn());
+const tuningApplyMock = vi.hoisted(() => vi.fn());
+const tuningDismissMock = vi.hoisted(() => vi.fn());
+const tuningAutoTuneMock = vi.hoisted(() => vi.fn());
+const tuningSummaryMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@/lib/api', () => ({
+ __esModule: true,
+ tuningApi: {
+ list: tuningListMock,
+ summary: tuningSummaryMock,
+ apply: tuningApplyMock,
+ dismiss: tuningDismissMock,
+ autoTune: tuningAutoTuneMock,
+ },
+}));
+
+// ─── Mock toast ───────────────────────────────────────────────────────────────
+
+const toastSuccess = vi.hoisted(() => vi.fn());
+const toastError = vi.hoisted(() => vi.fn());
+vi.mock('react-hot-toast', () => ({
+ __esModule: true,
+ default: { success: toastSuccess, error: toastError },
+}));
+
+// Import AFTER mocks so the module picks them up.
+import RuleTuningView from './RuleTuningView';
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const NOW_ISO = '2026-05-13T12:00:00Z';
+
+function makeEntry(overrides: Partial<TuningEntry> = {}): TuningEntry {
+ return {
+ rule_id: 'rule-1',
+ name: 'Suspicious PowerShell encoded command',
+ description: 'PowerShell -EncodedCommand seen on endpoint',
+ category: 'endpoint',
+ severity: 'high',
+ status: 'enabled',
+ enabled: true,
+ confidence: 78,
+ fp_rate: 0.42,
+ total_hits: 1280,
+ last_triggered_at: '2026-05-12T18:00:00Z',
+ tags: ['edr', 'living-off-the-land'],
+ mitre_tactics: ['execution'],
+ mitre_techniques: ['T1059.001'],
+ version: 3,
+ updated_at: '2026-05-13T11:30:00Z',
+ suggestion: 'add_suppression',
+ score: 0.82,
+ reasons: ['High FP rate (42%) over the last 7 days'],
+ auto_tune: false,
+ dismissed_at: null,
+ last_action: null,
+ last_action_at: null,
+ ...overrides,
+ };
+}
+
+function makeSummary(overrides: Partial<TuningSummary> = {}): TuningSummary {
+ return {
+ total_rules: 42,
+ actionable: 7,
+ healthy: 30,
+ disable_count: 1,
+ add_suppression_count: 3,
+ raise_threshold_count: 2,
+ tune_confidence_count: 1,
+ review_stale_count: 0,
+ auto_tune_enabled: 12,
+ average_fp_rate: 0.12,
+ high_fp_count: 4,
+ ...overrides,
+ };
+}
+
+function makeResponse(
+ entries: TuningEntry[],
+ overrides: Partial<TuningResponse> = {},
+): TuningResponse {
+ return {
+ entries,
+ summary: makeSummary(),
+ filters: {
+ severity: null,
+ suggestion: null,
+ search: null,
+ enabled_only: true,
+ include_dismissed: false,
+ page: 1,
+ page_size: 25,
+ },
+ total: entries.length,
+ generated_at: NOW_ISO,
+ ...overrides,
+ };
+}
+
+beforeEach(() => {
+ swrState.data = undefined;
+ swrState.error = undefined;
+ swrState.isLoading = false;
+ swrState.isValidating = false;
+ mutateMock.mockReset();
+ mutateMock.mockResolvedValue(undefined);
+ tuningListMock.mockReset();
+ tuningApplyMock.mockReset();
+ tuningDismissMock.mockReset();
+ tuningAutoTuneMock.mockReset();
+ tuningSummaryMock.mockReset();
+ toastSuccess.mockReset();
+ toastError.mockReset();
+});
+
+/**
+ * Click an action button and drain the resulting async handler inside a
+ * single `act()` boundary.
+ *
+ * Same pattern as `QueueView.test.tsx`: handlers like onApply / onDismiss
+ * end in a `finally { setBusy(null) }` state commit that lands outside
+ * user-event's implicit `act()` wrapper, so we manually drain microtasks.
+ */
+async function clickAndSettle(user: ReturnType<typeof userEvent.setup>, el: HTMLElement) {
+ await act(async () => {
+ await user.click(el);
+ await Promise.resolve();
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+}
+
+describe('RuleTuningView', () => {
+ it('renders the loading skeleton before the first server response', () => {
+ swrState.isLoading = true;
+ swrState.data = undefined;
+
+ render(<RuleTuningView />);
+
+ // Header still renders so analysts have context during cold load.
+ expect(screen.getByText(/Detection Tuning/i)).toBeInTheDocument();
+ // No rules yet.
+ expect(
+ screen.queryByText('Suspicious PowerShell encoded command'),
+ ).not.toBeInTheDocument();
+ });
+
+ it('renders the empty state when no rules need tuning', () => {
+ swrState.data = makeResponse([]);
+
+ render(<RuleTuningView />);
+
+ expect(screen.getByText(/No tuning suggestions right now/i)).toBeInTheDocument();
+ expect(
+ screen.getByText(/All enabled rules are within healthy/i),
+ ).toBeInTheDocument();
+ // No Clear-filters CTA on the happy-path empty.
+ expect(screen.queryByRole('button', { name: /Clear filters/i })).not.toBeInTheDocument();
+ });
+
+ it('renders summary cards from the response payload', () => {
+ swrState.data = makeResponse([], {
+ summary: makeSummary({
+ total_rules: 120,
+ actionable: 9,
+ healthy: 100,
+ auto_tune_enabled: 14,
+ average_fp_rate: 0.087,
+ high_fp_count: 5,
+ }),
+ });
+
+ render(<RuleTuningView />);
+
+ // Card labels render inside <p> tags; the suggestion filter option also
+ // says "Healthy" so we scope with the `selector` shim to avoid false
+ // positives.
+ expect(screen.getByText('Total Rules', { selector: 'p' })).toBeInTheDocument();
+ expect(screen.getByText('120')).toBeInTheDocument();
+ expect(screen.getByText(/9 actionable/i)).toBeInTheDocument();
+
+ // Avg FP Rate card — 8.7% with one decimal.
+ expect(screen.getByText('Avg FP Rate', { selector: 'p' })).toBeInTheDocument();
+ expect(screen.getByText('8.7%')).toBeInTheDocument();
+ expect(screen.getByText(/5 noisy rules/i)).toBeInTheDocument();
+
+ // Healthy card — 100 / 120 ≈ 83%. We disambiguate from the dropdown
+ // option by constraining the selector to the card's `<p>` label.
+ expect(screen.getByText('Healthy', { selector: 'p' })).toBeInTheDocument();
+ expect(screen.getByText('100')).toBeInTheDocument();
+ expect(screen.getByText('83% of population')).toBeInTheDocument();
+
+ // Auto-Tuned card
+ expect(screen.getByText('Auto-Tuned', { selector: 'p' })).toBeInTheDocument();
+ expect(screen.getByText('14')).toBeInTheDocument();
+ });
+
+ it('renders a tuning row with severity pill, suggestion, FP%, hits, and confidence', () => {
+ const entry = makeEntry();
+ swrState.data = makeResponse([entry]);
+
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ const withinRow = within(row);
+
+ // Name
+ expect(withinRow.getByText(entry.name)).toBeInTheDocument();
+ // Severity pill — "high" rendered verbatim (the css class uppercases).
+ expect(withinRow.getByText('high')).toBeInTheDocument();
+ // Suggestion pill — scoped to the <span> so we don't collide with the
+ // identically-labelled "Add suppression" apply button.
+ expect(
+ withinRow.getByText('Add suppression', { selector: 'span' }),
+ ).toBeInTheDocument();
+ // FP% — 0.42 → 42.0%
+ expect(withinRow.getByText('42.0%')).toBeInTheDocument();
+ // Hit count formatted with locale separators
+ expect(withinRow.getByText('1,280')).toBeInTheDocument();
+ // Confidence
+ expect(withinRow.getByText('78')).toBeInTheDocument();
+ // Reason copy from the projection
+ expect(
+ withinRow.getByText(/High FP rate \(42%\) over the last 7 days/i),
+ ).toBeInTheDocument();
+ });
+
+ it("applies the suggestion's primary action and revalidates", async () => {
+ // suggestion=disable should map to action=disable.
+ const entry = makeEntry({
+ rule_id: 'rule-disable',
+ suggestion: 'disable',
+ fp_rate: 0.81,
+ reasons: ['Fires almost exclusively on false positives'],
+ });
+ swrState.data = makeResponse([entry]);
+ tuningApplyMock.mockResolvedValue(entry);
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ const applyBtn = within(row).getByRole('button', { name: /Disable rule/i });
+ await clickAndSettle(user, applyBtn);
+
+ expect(tuningApplyMock).toHaveBeenCalledTimes(1);
+ expect(tuningApplyMock).toHaveBeenCalledWith(entry.rule_id, { action: 'disable' });
+ expect(toastSuccess).toHaveBeenCalledWith(
+ expect.stringMatching(/Applied "Disable rule"/),
+ );
+ expect(mutateMock).toHaveBeenCalled();
+ });
+
+ it("acknowledges a healthy rule via the secondary 'acknowledge' action", async () => {
+ const entry = makeEntry({
+ rule_id: 'rule-ok',
+ suggestion: 'healthy',
+ fp_rate: 0.01,
+ reasons: ['Healthy — no tuning required'],
+ });
+ swrState.data = makeResponse([entry]);
+ tuningApplyMock.mockResolvedValue(entry);
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ // Healthy rows render an "Acknowledge" button (no primary action).
+ const ackBtn = within(row).getByRole('button', { name: /^Acknowledge$/i });
+ await clickAndSettle(user, ackBtn);
+
+ expect(tuningApplyMock).toHaveBeenCalledWith(entry.rule_id, { action: 'acknowledge' });
+ expect(toastSuccess).toHaveBeenCalledWith(
+ expect.stringMatching(/^Acknowledged "/),
+ );
+ });
+
+ it('surfaces apply failures as a toast.error', async () => {
+ const entry = makeEntry({ rule_id: 'rule-fail', suggestion: 'raise_threshold' });
+ swrState.data = makeResponse([entry]);
+ tuningApplyMock.mockRejectedValue(new Error('Rule already at max threshold'));
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ await clickAndSettle(user, within(row).getByRole('button', { name: /Raise threshold/i }));
+
+ expect(toastError).toHaveBeenCalledWith('Rule already at max threshold');
+ expect(toastSuccess).not.toHaveBeenCalled();
+ });
+
+ it('dismisses a rule from the workbench', async () => {
+ const entry = makeEntry({ rule_id: 'rule-d' });
+ swrState.data = makeResponse([entry]);
+ tuningDismissMock.mockResolvedValue({ ...entry, dismissed_at: NOW_ISO });
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ await clickAndSettle(user, within(row).getByRole('button', { name: /^Dismiss$/i }));
+
+ expect(tuningDismissMock).toHaveBeenCalledWith(entry.rule_id, {});
+ expect(toastSuccess).toHaveBeenCalledWith(
+ expect.stringMatching(/Dismissed ".*" from the workbench/),
+ );
+ expect(mutateMock).toHaveBeenCalled();
+ });
+
+ it('disables the Dismiss button on rows that are already dismissed', () => {
+ const entry = makeEntry({
+ rule_id: 'rule-already',
+ dismissed_at: '2026-05-10T08:00:00Z',
+ });
+ swrState.data = makeResponse([entry], {
+ filters: {
+ severity: null,
+ suggestion: null,
+ search: null,
+ enabled_only: true,
+ include_dismissed: true,
+ page: 1,
+ page_size: 25,
+ },
+ });
+
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ const dismissBtn = within(row).getByRole('button', { name: /^Dismiss$/i });
+ expect(dismissBtn).toBeDisabled();
+ // And the "Dismissed" badge is shown.
+ expect(within(row).getByText('Dismissed')).toBeInTheDocument();
+ });
+
+ it('toggles the auto-tune flag via the per-row switch', async () => {
+ const entry = makeEntry({ rule_id: 'rule-auto', auto_tune: false });
+ swrState.data = makeResponse([entry]);
+ tuningAutoTuneMock.mockResolvedValue({ ...entry, auto_tune: true });
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ const row = screen.getByTestId(`tuning-row-${entry.rule_id}`);
+ const toggle = within(row).getByRole('button', {
+ name: /Toggle auto-tune for /i,
+ });
+ expect(toggle).toHaveAttribute('aria-pressed', 'false');
+
+ await clickAndSettle(user, toggle);
+
+ expect(tuningAutoTuneMock).toHaveBeenCalledWith(entry.rule_id, true);
+ expect(toastSuccess).toHaveBeenCalledWith(
+ expect.stringMatching(/Auto-tune enabled on "/),
+ );
+ });
+
+ it('changing the suggestion filter resets pagination to page 1', async () => {
+ const entry = makeEntry();
+ swrState.data = makeResponse([entry]);
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ // The fetcher we mock is `tuningApi.list(listParams)`; the component
+ // calls it inside the SWR fetcher. Our SWR mock skips the fetcher
+ // invocation, but the test for "filter change resets page" is best
+ // expressed via the visible select element: changing it should not
+ // throw and the corresponding `page: 1` is the default in the memo.
+ const select = screen.getByLabelText(/Filter by suggestion/i);
+ await act(async () => {
+ await user.selectOptions(select, 'disable');
+ });
+ expect((select as HTMLSelectElement).value).toBe('disable');
+ });
+
+ it('renders the error state when SWR returns an error', () => {
+ swrState.error = new Error('Network failure');
+ swrState.data = undefined;
+
+ render(<RuleTuningView />);
+
+ expect(screen.getByText(/Couldn't load tuning suggestions/i)).toBeInTheDocument();
+ });
+
+ it('shows the "filters dirty" empty state with a Clear filters CTA', async () => {
+ swrState.data = makeResponse([]);
+
+ const user = userEvent.setup();
+ render(<RuleTuningView />);
+
+ // Trip a filter so the view considers itself "dirty".
+ const select = screen.getByLabelText(/Filter by suggestion/i);
+ await act(async () => {
+ await user.selectOptions(select, 'disable');
+ });
+
+ expect(screen.getByText(/No rules match your filters/i)).toBeInTheDocument();
+ const clearBtn = screen.getByRole('button', { name: /Clear filters/i });
+ expect(clearBtn).toBeInTheDocument();
+
+ await act(async () => {
+ await user.click(clearBtn);
+ });
+ // After clearing, the select returns to its default value.
+ expect((select as HTMLSelectElement).value).toBe('all');
+ });
+});
diff --git a/apps/web/src/components/detections/RuleTuningView.tsx b/apps/web/src/components/detections/RuleTuningView.tsx
new file mode 100644
index 000000000..066eb2367
--- /dev/null
+++ b/apps/web/src/components/detections/RuleTuningView.tsx
@@ -0,0 +1,781 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+import { clsx } from 'clsx';
+import toast from 'react-hot-toast';
+import useSWR from 'swr';
+
+import { EmptyState, EmptyStateIcons } from '@/components/ui/EmptyState';
+import { ErrorState } from '@/components/ui/ErrorState';
+import { Skeleton } from '@/components/ui/Skeleton';
+import {
+ tuningApi,
+ type ApplyTuningRequest,
+ type TuningAction,
+ type TuningEntry,
+ type TuningListParams,
+ type TuningResponse,
+ type TuningSuggestion,
+} from '@/lib/api';
+
+const PAGE_SIZE = 25;
+
+const SUGGESTION_FILTERS: Array<{ value: 'all' | TuningSuggestion; label: string }> = [
+ { value: 'all', label: 'All suggestions' },
+ { value: 'disable', label: 'Disable' },
+ { value: 'add_suppression', label: 'Add suppression' },
+ { value: 'raise_threshold', label: 'Raise threshold' },
+ { value: 'tune_confidence', label: 'Tune confidence' },
+ { value: 'review_stale', label: 'Review stale' },
+ { value: 'healthy', label: 'Healthy' },
+];
+
+const SEVERITY_FILTERS = ['all', 'critical', 'high', 'medium', 'low', 'info'] as const;
+
+type SeverityFilter = (typeof SEVERITY_FILTERS)[number];
+type SuggestionFilter = 'all' | TuningSuggestion;
+
+const SUGGESTION_LABEL: Record<TuningSuggestion, string> = {
+ disable: 'Disable',
+ add_suppression: 'Add suppression',
+ raise_threshold: 'Raise threshold',
+ tune_confidence: 'Tune confidence',
+ review_stale: 'Review stale',
+ healthy: 'Healthy',
+};
+
+const SUGGESTION_TONE: Record<TuningSuggestion, string> = {
+ disable: 'bg-red-500/10 text-red-300 border-red-500/30',
+ add_suppression: 'bg-amber-500/10 text-amber-300 border-amber-500/30',
+ raise_threshold: 'bg-orange-500/10 text-orange-300 border-orange-500/30',
+ tune_confidence: 'bg-blue-500/10 text-blue-300 border-blue-500/30',
+ review_stale: 'bg-purple-500/10 text-purple-300 border-purple-500/30',
+ healthy: 'bg-emerald-500/10 text-emerald-300 border-emerald-500/30',
+};
+
+const SEVERITY_TONE: Record<string, string> = {
+ critical: 'bg-red-500/15 text-red-300 border-red-500/40',
+ high: 'bg-orange-500/15 text-orange-300 border-orange-500/40',
+ medium: 'bg-amber-500/15 text-amber-300 border-amber-500/40',
+ low: 'bg-sky-500/15 text-sky-300 border-sky-500/40',
+ info: 'bg-gray-500/15 text-gray-300 border-gray-500/40',
+};
+
+/**
+ * Suggestion → primary apply action. ``healthy`` has no primary action; we
+ * offer Acknowledge instead so the row can be cleared from the queue without
+ * mutating the rule.
+ */
+const SUGGESTION_TO_ACTION: Record<TuningSuggestion, TuningAction | null> = {
+ disable: 'disable',
+ add_suppression: 'add_suppression',
+ raise_threshold: 'raise_threshold',
+ tune_confidence: 'acknowledge',
+ review_stale: 'acknowledge',
+ healthy: null,
+};
+
+const APPLY_LABEL: Record<TuningAction, string> = {
+ disable: 'Disable rule',
+ add_suppression: 'Add suppression',
+ raise_threshold: 'Raise threshold',
+ acknowledge: 'Acknowledge',
+};
+
+type BusyAction = 'apply' | 'dismiss' | 'auto_tune';
+
+interface RuleTuningViewProps {
+ /** Initial state hook so tests / deep-links can preselect a suggestion. */
+ initialSuggestion?: SuggestionFilter;
+}
+
+export default function RuleTuningView({ initialSuggestion = 'all' }: RuleTuningViewProps = {}) {
+ const [severity, setSeverity] = useState<SeverityFilter>('all');
+ const [suggestion, setSuggestion] = useState<SuggestionFilter>(initialSuggestion);
+ const [search, setSearch] = useState('');
+ const [enabledOnly, setEnabledOnly] = useState(true);
+ const [includeDismissed, setIncludeDismissed] = useState(false);
+ const [page, setPage] = useState(1);
+ const [busyMap, setBusyMap] = useState<Record<string, BusyAction>>({});
+
+ const listParams: TuningListParams = useMemo(() => {
+ const params: TuningListParams = {
+ page,
+ page_size: PAGE_SIZE,
+ enabled_only: enabledOnly,
+ include_dismissed: includeDismissed,
+ };
+ if (severity !== 'all') params.severity = severity;
+ if (suggestion !== 'all') params.suggestion = suggestion;
+ const trimmed = search.trim();
+ if (trimmed) params.search = trimmed;
+ return params;
+ }, [page, enabledOnly, includeDismissed, severity, suggestion, search]);
+
+ const swrKey = useMemo(
+ () => ['detection-tuning', listParams] as const,
+ [listParams],
+ );
+
+ const { data, error, isLoading, isValidating, mutate } = useSWR<TuningResponse>(
+ swrKey,
+ () => tuningApi.list(listParams),
+ {
+ keepPreviousData: true,
+ revalidateOnFocus: false,
+ },
+ );
+
+ const setBusy = useCallback((ruleId: string, action: BusyAction | null) => {
+ setBusyMap((prev) => {
+ const next = { ...prev };
+ if (action === null) {
+ delete next[ruleId];
+ } else {
+ next[ruleId] = action;
+ }
+ return next;
+ });
+ }, []);
+
+ const handleApply = useCallback(
+ async (entry: TuningEntry, action: TuningAction) => {
+ setBusy(entry.rule_id, 'apply');
+ try {
+ const body: ApplyTuningRequest = { action };
+ await tuningApi.apply(entry.rule_id, body);
+ toast.success(
+ action === 'acknowledge'
+ ? `Acknowledged "${entry.name}"`
+ : `Applied "${APPLY_LABEL[action]}" to "${entry.name}"`,
+ );
+ await mutate();
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Action failed';
+ toast.error(message);
+ } finally {
+ setBusy(entry.rule_id, null);
+ }
+ },
+ [mutate, setBusy],
+ );
+
+ const handleDismiss = useCallback(
+ async (entry: TuningEntry) => {
+ setBusy(entry.rule_id, 'dismiss');
+ try {
+ await tuningApi.dismiss(entry.rule_id, {});
+ toast.success(`Dismissed "${entry.name}" from the workbench`);
+ await mutate();
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Dismiss failed';
+ toast.error(message);
+ } finally {
+ setBusy(entry.rule_id, null);
+ }
+ },
+ [mutate, setBusy],
+ );
+
+ const handleToggleAutoTune = useCallback(
+ async (entry: TuningEntry) => {
+ const nextEnabled = !entry.auto_tune;
+ setBusy(entry.rule_id, 'auto_tune');
+ try {
+ await tuningApi.autoTune(entry.rule_id, nextEnabled);
+ toast.success(
+ nextEnabled
+ ? `Auto-tune enabled on "${entry.name}"`
+ : `Auto-tune disabled on "${entry.name}"`,
+ );
+ await mutate();
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Toggle failed';
+ toast.error(message);
+ } finally {
+ setBusy(entry.rule_id, null);
+ }
+ },
+ [mutate, setBusy],
+ );
+
+ const summary = data?.summary;
+ const entries = data?.entries ?? [];
+ const total = data?.total ?? 0;
+ const totalPages = Math.max(1, Math.ceil(total / PAGE_SIZE));
+ const filtersDirty =
+ severity !== 'all' ||
+ suggestion !== 'all' ||
+ search.trim() !== '' ||
+ !enabledOnly ||
+ includeDismissed;
+
+ const resetFilters = useCallback(() => {
+ setSeverity('all');
+ setSuggestion('all');
+ setSearch('');
+ setEnabledOnly(true);
+ setIncludeDismissed(false);
+ setPage(1);
+ }, []);
+
+ return (
+ <div className="space-y-8 p-6 max-w-7xl mx-auto">
+ <header className="flex flex-wrap items-start justify-between gap-4">
+ <div>
+ <h1 className="text-2xl font-bold text-white">Detection Tuning</h1>
+ <p className="text-gray-400 mt-1 max-w-2xl">
+ Live tuning workbench for noisy or under-performing detection rules. Suggestions
+ are scored from real false-positive rates, hit volume, and confidence — no more
+ static dashboards.
+ </p>
+ </div>
+ <div className="flex items-center gap-2 text-xs text-gray-500">
+ {isValidating ? (
+ <span className="inline-flex items-center gap-1.5">
+ <span className="h-1.5 w-1.5 rounded-full bg-blue-400 animate-pulse" />
+ Refreshing…
+ </span>
+ ) : data ? (
+ <span>Updated {new Date(data.generated_at).toLocaleTimeString()}</span>
+ ) : null}
+ <button
+ type="button"
+ onClick={() => mutate()}
+ className="rounded-lg border border-gray-700 bg-gray-800/60 px-3 py-1.5 text-sm text-gray-200 hover:bg-gray-700 transition-colors"
+ >
+ Refresh
+ </button>
+ </div>
+ </header>
+
+ <SummaryCards summary={summary} isLoading={isLoading && !summary} />
+
+ <div className="rounded-xl border border-gray-800/60 bg-gray-900/40">
+ <FilterBar
+ severity={severity}
+ suggestion={suggestion}
+ search={search}
+ enabledOnly={enabledOnly}
+ includeDismissed={includeDismissed}
+ onSeverityChange={(v) => {
+ setSeverity(v);
+ setPage(1);
+ }}
+ onSuggestionChange={(v) => {
+ setSuggestion(v);
+ setPage(1);
+ }}
+ onSearchChange={(v) => {
+ setSearch(v);
+ setPage(1);
+ }}
+ onEnabledOnlyChange={(v) => {
+ setEnabledOnly(v);
+ setPage(1);
+ }}
+ onIncludeDismissedChange={(v) => {
+ setIncludeDismissed(v);
+ setPage(1);
+ }}
+ onReset={resetFilters}
+ filtersDirty={filtersDirty}
+ />
+
+ <div className="overflow-x-auto">
+ {isLoading && !data ? (
+ <TuningTableSkeleton />
+ ) : error ? (
+ <div className="p-6">
+ <ErrorState
+ title="Couldn't load tuning suggestions"
+ description="The detection tuning service didn't respond. Try again or check the service status."
+ error={error}
+ onRetry={() => mutate()}
+ />
+ </div>
+ ) : entries.length === 0 ? (
+ <div className="p-6">
+ <EmptyState
+ icon={EmptyStateIcons.search}
+ title={
+ filtersDirty
+ ? 'No rules match your filters'
+ : 'No tuning suggestions right now'
+ }
+ description={
+ filtersDirty
+ ? 'Try clearing filters or widening the search.'
+ : 'All enabled rules are within healthy false-positive bounds. We will surface tuning suggestions automatically as the picture changes.'
+ }
+ action={
+ filtersDirty ? (
+ <button
+ type="button"
+ onClick={resetFilters}
+ className="rounded-lg bg-gray-800 px-4 py-2 text-sm text-gray-200 hover:bg-gray-700 transition-colors"
+ >
+ Clear filters
+ </button>
+ ) : undefined
+ }
+ />
+ </div>
+ ) : (
+ <TuningTable
+ entries={entries}
+ busyMap={busyMap}
+ onApply={handleApply}
+ onDismiss={handleDismiss}
+ onToggleAutoTune={handleToggleAutoTune}
+ />
+ )}
+ </div>
+
+ {!error && entries.length > 0 ? (
+ <Pagination
+ page={page}
+ totalPages={totalPages}
+ total={total}
+ onPageChange={setPage}
+ />
+ ) : null}
+ </div>
+ </div>
+ );
+}
+
+// ── Summary Cards ────────────────────────────────────────────────────────────
+
+interface SummaryCardsProps {
+ summary: TuningResponse['summary'] | undefined;
+ isLoading: boolean;
+}
+
+function SummaryCards({ summary, isLoading }: SummaryCardsProps) {
+ if (isLoading || !summary) {
+ return (
+ <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+ {Array.from({ length: 4 }).map((_, i) => (
+ <div
+ key={i}
+ className="rounded-xl border border-gray-800/60 bg-gray-900/40 p-4"
+ >
+ <Skeleton className="w-24 h-3" />
+ <Skeleton className="w-20 h-7 mt-2" />
+ </div>
+ ))}
+ </div>
+ );
+ }
+
+ const cards = [
+ {
+ label: 'Total Rules',
+ value: summary.total_rules.toLocaleString(),
+ hint: `${summary.actionable.toLocaleString()} actionable`,
+ },
+ {
+ label: 'Avg FP Rate',
+ value: `${(summary.average_fp_rate * 100).toFixed(1)}%`,
+ hint: `${summary.high_fp_count} noisy rules`,
+ tone:
+ summary.average_fp_rate >= 0.2
+ ? 'text-red-300'
+ : summary.average_fp_rate >= 0.1
+ ? 'text-amber-300'
+ : 'text-emerald-300',
+ },
+ {
+ label: 'Healthy',
+ value: summary.healthy.toLocaleString(),
+ hint:
+ summary.total_rules > 0
+ ? `${Math.round((summary.healthy / summary.total_rules) * 100)}% of population`
+ : '—',
+ tone: 'text-emerald-300',
+ },
+ {
+ label: 'Auto-Tuned',
+ value: summary.auto_tune_enabled.toLocaleString(),
+ hint: 'rules opted in',
+ },
+ ];
+
+ return (
+ <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+ {cards.map((c) => (
+ <div
+ key={c.label}
+ className="rounded-xl border border-gray-800/60 bg-gray-900/40 p-4"
+ >
+ <p className="text-xs text-gray-400 uppercase tracking-wider">{c.label}</p>
+ <p className={clsx('mt-1 text-2xl font-semibold text-white', c.tone)}>
+ {c.value}
+ </p>
+ <p className="mt-1 text-xs text-gray-500">{c.hint}</p>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+// ── Filter Bar ───────────────────────────────────────────────────────────────
+
+interface FilterBarProps {
+ severity: SeverityFilter;
+ suggestion: SuggestionFilter;
+ search: string;
+ enabledOnly: boolean;
+ includeDismissed: boolean;
+ onSeverityChange: (value: SeverityFilter) => void;
+ onSuggestionChange: (value: SuggestionFilter) => void;
+ onSearchChange: (value: string) => void;
+ onEnabledOnlyChange: (value: boolean) => void;
+ onIncludeDismissedChange: (value: boolean) => void;
+ onReset: () => void;
+ filtersDirty: boolean;
+}
+
+function FilterBar({
+ severity,
+ suggestion,
+ search,
+ enabledOnly,
+ includeDismissed,
+ onSeverityChange,
+ onSuggestionChange,
+ onSearchChange,
+ onEnabledOnlyChange,
+ onIncludeDismissedChange,
+ onReset,
+ filtersDirty,
+}: FilterBarProps) {
+ return (
+ <div className="border-b border-gray-800/60 px-5 py-4 flex flex-wrap items-center gap-3">
+ <input
+ type="search"
+ value={search}
+ onChange={(e) => onSearchChange(e.target.value)}
+ placeholder="Search rules…"
+ aria-label="Search rules"
+ className="w-56 rounded-lg border border-gray-700 bg-gray-800/60 px-3 py-1.5 text-sm text-gray-200 placeholder-gray-500 focus:border-blue-500 focus:outline-none"
+ />
+
+ <label className="sr-only" htmlFor="suggestion-filter">
+ Filter by suggestion
+ </label>
+ <select
+ id="suggestion-filter"
+ value={suggestion}
+ onChange={(e) => onSuggestionChange(e.target.value as SuggestionFilter)}
+ className="rounded-lg border border-gray-700 bg-gray-800/60 px-3 py-1.5 text-sm text-gray-200 focus:border-blue-500 focus:outline-none"
+ >
+ {SUGGESTION_FILTERS.map((opt) => (
+ <option key={opt.value} value={opt.value}>
+ {opt.label}
+ </option>
+ ))}
+ </select>
+
+ <label className="sr-only" htmlFor="severity-filter">
+ Filter by severity
+ </label>
+ <select
+ id="severity-filter"
+ value={severity}
+ onChange={(e) => onSeverityChange(e.target.value as SeverityFilter)}
+ className="rounded-lg border border-gray-700 bg-gray-800/60 px-3 py-1.5 text-sm text-gray-200 focus:border-blue-500 focus:outline-none"
+ >
+ {SEVERITY_FILTERS.map((s) => (
+ <option key={s} value={s}>
+ {s === 'all' ? 'All severities' : s[0].toUpperCase() + s.slice(1)}
+ </option>
+ ))}
+ </select>
+
+ <label className="inline-flex items-center gap-2 text-sm text-gray-300 ml-2">
+ <input
+ type="checkbox"
+ checked={enabledOnly}
+ onChange={(e) => onEnabledOnlyChange(e.target.checked)}
+ className="rounded border-gray-600 bg-gray-800 text-blue-500 focus:ring-blue-500"
+ />
+ Enabled only
+ </label>
+
+ <label className="inline-flex items-center gap-2 text-sm text-gray-300">
+ <input
+ type="checkbox"
+ checked={includeDismissed}
+ onChange={(e) => onIncludeDismissedChange(e.target.checked)}
+ className="rounded border-gray-600 bg-gray-800 text-blue-500 focus:ring-blue-500"
+ />
+ Include dismissed
+ </label>
+
+ <div className="ml-auto">
+ {filtersDirty ? (
+ <button
+ type="button"
+ onClick={onReset}
+ className="text-sm px-3 py-1.5 rounded-lg border border-gray-700 bg-gray-800/60 hover:bg-gray-700 text-gray-200 transition-colors"
+ >
+ Reset filters
+ </button>
+ ) : null}
+ </div>
+ </div>
+ );
+}
+
+// ── Table ────────────────────────────────────────────────────────────────────
+
+interface TuningTableProps {
+ entries: TuningEntry[];
+ busyMap: Record<string, BusyAction>;
+ onApply: (entry: TuningEntry, action: TuningAction) => void;
+ onDismiss: (entry: TuningEntry) => void;
+ onToggleAutoTune: (entry: TuningEntry) => void;
+}
+
+function TuningTable({
+ entries,
+ busyMap,
+ onApply,
+ onDismiss,
+ onToggleAutoTune,
+}: TuningTableProps) {
+ return (
+ <table className="w-full text-sm">
+ <thead>
+ <tr className="border-b border-gray-800/60 text-left text-gray-400">
+ <th className="px-5 py-3 font-medium">Rule</th>
+ <th className="px-5 py-3 font-medium">Suggestion</th>
+ <th className="px-5 py-3 font-medium text-right">FP Rate</th>
+ <th className="px-5 py-3 font-medium text-right">Hits</th>
+ <th className="px-5 py-3 font-medium text-right">Confidence</th>
+ <th className="px-5 py-3 font-medium text-center">Auto-Tune</th>
+ <th className="px-5 py-3 font-medium text-right">Actions</th>
+ </tr>
+ </thead>
+ <tbody>
+ {entries.map((entry) => (
+ <TuningRow
+ key={entry.rule_id}
+ entry={entry}
+ busyAction={busyMap[entry.rule_id] ?? null}
+ onApply={onApply}
+ onDismiss={onDismiss}
+ onToggleAutoTune={onToggleAutoTune}
+ />
+ ))}
+ </tbody>
+ </table>
+ );
+}
+
+interface TuningRowProps {
+ entry: TuningEntry;
+ busyAction: BusyAction | null;
+ onApply: (entry: TuningEntry, action: TuningAction) => void;
+ onDismiss: (entry: TuningEntry) => void;
+ onToggleAutoTune: (entry: TuningEntry) => void;
+}
+
+function TuningRow({
+ entry,
+ busyAction,
+ onApply,
+ onDismiss,
+ onToggleAutoTune,
+}: TuningRowProps) {
+ const fpPct = entry.fp_rate * 100;
+ const primaryAction = SUGGESTION_TO_ACTION[entry.suggestion];
+ const busy = busyAction !== null;
+ const severityTone = SEVERITY_TONE[entry.severity] ?? SEVERITY_TONE.info;
+
+ return (
+ <tr
+ className={clsx(
+ 'border-b border-gray-800/40 transition-colors',
+ entry.dismissed_at ? 'opacity-60' : 'hover:bg-gray-800/30',
+ )}
+ data-testid={`tuning-row-${entry.rule_id}`}
+ >
+ <td className="px-5 py-3 align-top">
+ <div className="flex flex-col gap-1">
+ <div className="flex items-center gap-2">
+ <span className="font-medium text-white">{entry.name}</span>
+ <span
+ className={clsx(
+ 'px-1.5 py-0.5 rounded text-[10px] uppercase tracking-wider border',
+ severityTone,
+ )}
+ >
+ {entry.severity}
+ </span>
+ {!entry.enabled ? (
+ <span className="px-1.5 py-0.5 rounded text-[10px] uppercase tracking-wider border border-gray-600 text-gray-400">
+ Disabled
+ </span>
+ ) : null}
+ {entry.dismissed_at ? (
+ <span className="px-1.5 py-0.5 rounded text-[10px] uppercase tracking-wider border border-gray-600 text-gray-400">
+ Dismissed
+ </span>
+ ) : null}
+ </div>
+ {entry.reasons.length > 0 ? (
+ <p className="text-xs text-gray-400 max-w-md">
+ {entry.reasons[0]}
+ </p>
+ ) : null}
+ <p className="text-[11px] text-gray-500">
+ {entry.category}
+ {entry.last_triggered_at
+ ? ` • last hit ${new Date(entry.last_triggered_at).toLocaleDateString()}`
+ : ' • never fired'}
+ </p>
+ </div>
+ </td>
+ <td className="px-5 py-3 align-top">
+ <span
+ className={clsx(
+ 'inline-flex items-center px-2 py-1 rounded-md text-xs font-medium border',
+ SUGGESTION_TONE[entry.suggestion],
+ )}
+ >
+ {SUGGESTION_LABEL[entry.suggestion]}
+ </span>
+ </td>
+ <td
+ className={clsx(
+ 'px-5 py-3 align-top text-right font-medium',
+ fpPct >= 50 ? 'text-red-400' : fpPct >= 20 ? 'text-amber-400' : 'text-emerald-400',
+ )}
+ >
+ {fpPct.toFixed(1)}%
+ </td>
+ <td className="px-5 py-3 align-top text-right text-gray-300">
+ {entry.total_hits.toLocaleString()}
+ </td>
+ <td className="px-5 py-3 align-top text-right text-gray-300">
+ {entry.confidence}
+ </td>
+ <td className="px-5 py-3 align-top text-center">
+ <button
+ type="button"
+ onClick={() => onToggleAutoTune(entry)}
+ disabled={busy}
+ aria-label={`Toggle auto-tune for ${entry.name}`}
+ aria-pressed={entry.auto_tune}
+ className={clsx(
+ 'relative inline-flex h-5 w-9 items-center rounded-full transition-colors disabled:opacity-50',
+ entry.auto_tune ? 'bg-blue-600' : 'bg-gray-600',
+ )}
+ >
+ <span
+ className={clsx(
+ 'inline-block h-4 w-4 transform rounded-full bg-white shadow-sm transition-transform',
+ entry.auto_tune ? 'translate-x-4' : 'translate-x-0.5',
+ )}
+ />
+ </button>
+ </td>
+ <td className="px-5 py-3 align-top">
+ <div className="flex items-center justify-end gap-2">
+ {primaryAction ? (
+ <button
+ type="button"
+ onClick={() => onApply(entry, primaryAction)}
+ disabled={busy || !entry.enabled}
+ className="text-xs px-2.5 py-1.5 rounded-md bg-blue-600 hover:bg-blue-500 text-white transition-colors disabled:bg-gray-700 disabled:text-gray-400 disabled:cursor-not-allowed"
+ title={
+ !entry.enabled
+ ? 'Rule is already disabled'
+ : APPLY_LABEL[primaryAction]
+ }
+ >
+ {busyAction === 'apply' ? 'Applying…' : APPLY_LABEL[primaryAction]}
+ </button>
+ ) : (
+ <button
+ type="button"
+ onClick={() => onApply(entry, 'acknowledge')}
+ disabled={busy}
+ className="text-xs px-2.5 py-1.5 rounded-md bg-gray-800 hover:bg-gray-700 text-gray-200 transition-colors disabled:opacity-50"
+ >
+ {busyAction === 'apply' ? 'Acknowledging…' : 'Acknowledge'}
+ </button>
+ )}
+ <button
+ type="button"
+ onClick={() => onDismiss(entry)}
+ disabled={busy || Boolean(entry.dismissed_at)}
+ className="text-xs px-2.5 py-1.5 rounded-md border border-gray-700 bg-gray-800/60 hover:bg-gray-700 text-gray-200 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+ >
+ {busyAction === 'dismiss' ? 'Dismissing…' : 'Dismiss'}
+ </button>
+ </div>
+ </td>
+ </tr>
+ );
+}
+
+// ── Skeleton + Pagination ────────────────────────────────────────────────────
+
+function TuningTableSkeleton() {
+ return (
+ <div className="divide-y divide-gray-800/40">
+ {Array.from({ length: 6 }).map((_, i) => (
+ <div key={i} className="flex items-center gap-4 px-5 py-4">
+ <div className="flex-1 space-y-2">
+ <Skeleton className="w-2/3 h-4" />
+ <Skeleton className="w-1/2 h-3" />
+ </div>
+ <Skeleton className="w-24 h-6" />
+ <Skeleton className="w-14 h-4" />
+ <Skeleton className="w-12 h-4" />
+ <Skeleton className="w-9 h-5" />
+ <Skeleton className="w-32 h-7" />
+ </div>
+ ))}
+ </div>
+ );
+}
+
+interface PaginationProps {
+ page: number;
+ totalPages: number;
+ total: number;
+ onPageChange: (page: number) => void;
+}
+
+function Pagination({ page, totalPages, total, onPageChange }: PaginationProps) {
+ return (
+ <div className="px-5 py-3 border-t border-gray-800/60 flex flex-wrap items-center justify-between gap-3 text-sm text-gray-400">
+ <span>
+ Page {page} of {totalPages} • {total.toLocaleString()} rules
+ </span>
+ <div className="flex items-center gap-2">
+ <button
+ type="button"
+ onClick={() => onPageChange(Math.max(1, page - 1))}
+ disabled={page <= 1}
+ className="px-2.5 py-1 rounded-md border border-gray-700 bg-gray-800/60 hover:bg-gray-700 disabled:opacity-40 disabled:cursor-not-allowed text-gray-200 transition-colors"
+ >
+ ← Prev
+ </button>
+ <button
+ type="button"
+ onClick={() => onPageChange(Math.min(totalPages, page + 1))}
+ disabled={page >= totalPages}
+ className="px-2.5 py-1 rounded-md border border-gray-700 bg-gray-800/60 hover:bg-gray-700 disabled:opacity-40 disabled:cursor-not-allowed text-gray-200 transition-colors"
+ >
+ Next →
+ </button>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/web/src/components/layout/Sidebar.tsx b/apps/web/src/components/layout/Sidebar.tsx
index c2d6ea5a6..ecfde785a 100644
--- a/apps/web/src/components/layout/Sidebar.tsx
+++ b/apps/web/src/components/layout/Sidebar.tsx
@@ -193,6 +193,11 @@ const navSections: NavSection[] = [
href: '/detection/coverage',
icon: <ChartBarIcon />,
},
+ {
+ label: 'Detection Tuning',
+ href: '/detection/tuning',
+ icon: <ChartBarIcon />,
+ },
{
label: 'Shifts',
href: '/shifts',
@@ -288,11 +293,6 @@ const navSections: NavSection[] = [
href: '/compliance',
icon: <ShieldIcon />,
},
- {
- label: 'Noise Tuning',
- href: '/noise-tuning',
- icon: <ChartBarIcon />,
- },
{
label: 'MSSP Dashboard',
href: '/mssp',
diff --git a/apps/web/src/components/noise/NoiseTuningView.tsx b/apps/web/src/components/noise/NoiseTuningView.tsx
deleted file mode 100644
index 8fc1b8d03..000000000
--- a/apps/web/src/components/noise/NoiseTuningView.tsx
+++ /dev/null
@@ -1,193 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-import { clsx } from 'clsx';
-import toast from 'react-hot-toast';
-import { EmptyState, EmptyStateIcons } from '@/components/ui/EmptyState';
-
-interface AlertRule {
- name: string;
- alertsFired: number;
- tpCount: number;
- fpCount: number;
- autoTune: boolean;
- suggestedAction: string;
-}
-
-const INITIAL_RULES: AlertRule[] = [
- { name: 'Suspicious PowerShell Execution', alertsFired: 342, tpCount: 298, fpCount: 44, autoTune: true, suggestedAction: 'Exclude signed scripts from known admin hosts' },
- { name: 'Failed Login Brute Force', alertsFired: 1205, tpCount: 180, fpCount: 1025, autoTune: false, suggestedAction: 'Raise threshold from 5 to 15 failed attempts' },
- { name: 'Unusual Outbound DNS Volume', alertsFired: 87, tpCount: 72, fpCount: 15, autoTune: true, suggestedAction: 'Whitelist internal DNS forwarders' },
- { name: 'Lateral Movement via SMB', alertsFired: 156, tpCount: 134, fpCount: 22, autoTune: true, suggestedAction: 'Exclude domain controller-to-DC traffic' },
- { name: 'New Service Installation', alertsFired: 523, tpCount: 45, fpCount: 478, autoTune: false, suggestedAction: 'Filter SCCM and Intune deployment agents' },
- { name: 'Anomalous Cloud API Call', alertsFired: 211, tpCount: 189, fpCount: 22, autoTune: true, suggestedAction: 'Baseline CI/CD service accounts' },
- { name: 'Registry Run Key Modification', alertsFired: 94, tpCount: 81, fpCount: 13, autoTune: false, suggestedAction: 'Add GPO-deployed software to allowlist' },
- { name: 'Potential Data Exfiltration', alertsFired: 38, tpCount: 35, fpCount: 3, autoTune: true, suggestedAction: 'No changes recommended — low FP rate' },
- { name: 'Cleartext Credential in Logs', alertsFired: 678, tpCount: 102, fpCount: 576, autoTune: false, suggestedAction: 'Suppress alerts from log-rotation jobs' },
- { name: 'TLS Certificate Anomaly', alertsFired: 145, tpCount: 120, fpCount: 25, autoTune: true, suggestedAction: 'Exclude internal CA-issued certs' },
-];
-
-export default function NoiseTuningView() {
- const [rules, setRules] = useState(INITIAL_RULES);
- const [search, setSearch] = useState('');
-
- const filteredRules = search.trim()
- ? rules.filter((r) => r.name.toLowerCase().includes(search.toLowerCase()))
- : rules;
-
- const totalVerdicts = rules.reduce((s, r) => s + r.alertsFired, 0);
- const totalFP = rules.reduce((s, r) => s + r.fpCount, 0);
- const fpRate = ((totalFP / totalVerdicts) * 100).toFixed(1);
- const autoTunedCount = rules.filter((r) => r.autoTune).length;
- const noiseReduction = 34;
-
- const summaryCards = [
- { label: 'Total Verdicts This Month', value: totalVerdicts.toLocaleString() },
- { label: 'FP Rate', value: `${fpRate}%` },
- { label: 'Auto-Tuned Rules', value: autoTunedCount },
- { label: 'Noise Reduction', value: `${noiseReduction}%` },
- ];
-
- function toggleAutoTune(index: number) {
- setRules((prev) =>
- prev.map((r, i) => (i === index ? { ...r, autoTune: !r.autoTune } : r)),
- );
- }
-
- function ruleFpRate(r: AlertRule) {
- return r.alertsFired > 0 ? (r.fpCount / r.alertsFired) * 100 : 0;
- }
-
- return (
- <div className="space-y-8 p-6 max-w-7xl mx-auto">
- <div>
- <h1 className="text-2xl font-bold text-white">Alert Noise Tuning</h1>
- <p className="text-gray-400 mt-1">Reduce false positives and optimize detection signal-to-noise ratio</p>
- </div>
-
- {/* Summary Cards */}
- <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
- {summaryCards.map((c) => (
- <div key={c.label} className="rounded-xl border border-gray-800/60 bg-gray-900/40 p-4">
- <p className="text-xs text-gray-400 uppercase tracking-wider">{c.label}</p>
- <p className="mt-1 text-2xl font-semibold text-white">{c.value}</p>
- </div>
- ))}
- </div>
-
- {/* Noise Trend Placeholder */}
- <div className="rounded-xl border border-gray-800/60 bg-gray-900/40 p-6">
- <h2 className="text-lg font-semibold text-white mb-4">Noise Trend</h2>
- <div className="h-48 rounded-lg bg-gray-800/50 border border-gray-700/50 flex items-center justify-center">
- <div className="text-center">
- <div className="flex items-center justify-center gap-1 mb-2">
- {[40, 55, 35, 60, 45, 30, 25, 38, 20, 28, 18, 22].map((h, i) => (
- <div
- key={i}
- className="w-6 rounded-t bg-gradient-to-t from-blue-600/80 to-blue-400/60"
- style={{ height: `${h * 1.5}px` }}
- />
- ))}
- </div>
- <p className="text-sm text-gray-500">Monthly noise trend — FP volume declining</p>
- </div>
- </div>
- </div>
-
- {/* Rules Table */}
- <div className="rounded-xl border border-gray-800/60 bg-gray-900/40 overflow-hidden">
- <div className="px-5 py-4 border-b border-gray-800/60 flex flex-wrap items-center gap-3">
- <h2 className="text-lg font-semibold text-white flex-1 min-w-0">Alert Rules</h2>
- <input
- type="search"
- value={search}
- onChange={(e) => setSearch(e.target.value)}
- placeholder="Search rules…"
- className="w-56 rounded-lg border border-gray-700 bg-gray-800/60 px-3 py-1.5 text-sm text-gray-200 placeholder-gray-500 focus:border-blue-500 focus:outline-none"
- />
- <button
- onClick={() => toast.success('Tuning recommendations applied to 3 rules')}
- className="text-sm px-3 py-1.5 rounded-lg bg-blue-600 hover:bg-blue-500 text-white transition-colors"
- >
- Apply Tuning
- </button>
- </div>
- <div className="overflow-x-auto">
- <table className="w-full text-sm">
- <thead>
- <tr className="border-b border-gray-800/60 text-left text-gray-400">
- <th className="px-5 py-3 font-medium">Rule Name</th>
- <th className="px-5 py-3 font-medium text-right">Alerts Fired</th>
- <th className="px-5 py-3 font-medium text-right">TP</th>
- <th className="px-5 py-3 font-medium text-right">FP</th>
- <th className="px-5 py-3 font-medium text-right">FP Rate</th>
- <th className="px-5 py-3 font-medium text-center">Auto-Tune</th>
- <th className="px-5 py-3 font-medium">Suggested Action</th>
- </tr>
- </thead>
- <tbody>
- {filteredRules.length === 0 ? (
- <tr>
- <td colSpan={7} className="py-0">
- <EmptyState
- icon={EmptyStateIcons.search}
- title="No rules match your search"
- description="Try a different rule name or clear the search field."
- action={
- <button
- type="button"
- onClick={() => setSearch('')}
- className="rounded-lg bg-gray-800 px-4 py-2 text-sm text-gray-200 hover:bg-gray-700 transition-colors"
- >
- Clear search
- </button>
- }
- />
- </td>
- </tr>
- ) : (
- filteredRules.map((r, i) => {
- const fp = ruleFpRate(r);
- const originalIndex = rules.indexOf(r);
- return (
- <tr key={r.name} className="border-b border-gray-800/40 hover:bg-gray-800/30 transition-colors">
- <td className="px-5 py-3 font-medium text-white">{r.name}</td>
- <td className="px-5 py-3 text-right text-gray-300">{r.alertsFired.toLocaleString()}</td>
- <td className="px-5 py-3 text-right text-gray-300">{r.tpCount}</td>
- <td className="px-5 py-3 text-right text-gray-300">{r.fpCount}</td>
- <td
- className={clsx(
- 'px-5 py-3 text-right font-medium',
- fp >= 70 ? 'text-red-400' : fp >= 30 ? 'text-amber-400' : 'text-green-400',
- )}
- >
- {fp.toFixed(1)}%
- </td>
- <td className="px-5 py-3 text-center">
- <button
- onClick={() => toggleAutoTune(originalIndex)}
- className={clsx(
- 'relative inline-flex h-5 w-9 items-center rounded-full transition-colors',
- r.autoTune ? 'bg-blue-600' : 'bg-gray-600',
- )}
- >
- <span
- className={clsx(
- 'inline-block h-3.5 w-3.5 rounded-full bg-white transition-transform',
- r.autoTune ? 'translate-x-4.5' : 'translate-x-0.5',
- )}
- />
- </button>
- </td>
- <td className="px-5 py-3 text-gray-400 max-w-xs truncate">{r.suggestedAction}</td>
- </tr>
- );
- })
- )}
- </tbody>
- </table>
- </div>
- </div>
- </div>
- );
-}
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index 9d273dcd6..407878fc7 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -2854,6 +2854,187 @@ export const detectionProposalsApi = {
),
};
+// ─── Detection Rule Tuning Workbench (PR-6 / v1.5 §W8) ───────────────────────
+//
+// The tuning workbench replaces the static /noise-tuning prototype with a live
+// projection of ``DetectionRule`` rows into analyst-actionable suggestions.
+// The backend is intentionally cheap — every projection is derived from
+// already-materialised fields (``fp_rate``, ``total_hits``, ``confidence``,
+// ``last_triggered``, ``status``) so a tenant with thousands of imported Sigma
+// rules can still triage without hammering the alerts table.
+//
+// Three verbs ship here:
+// • ``list`` / ``summary`` — read-only projection (``rules:read``).
+// • ``apply`` — mechanically tighten a rule (``rules:write``), bumps version.
+// • ``dismiss`` / ``autoTune`` — record analyst intent (``rules:write``).
+//
+// See ``services/api/app/services/rule_tuning.py`` for the authoritative
+// wire shape; the types below mirror its Pydantic models 1:1.
+
+export type TuningSuggestion =
+ | 'disable'
+ | 'add_suppression'
+ | 'raise_threshold'
+ | 'tune_confidence'
+ | 'review_stale'
+ | 'healthy';
+
+export type TuningAction =
+ | 'raise_threshold'
+ | 'add_suppression'
+ | 'disable'
+ | 'acknowledge';
+
+export interface TuningEntry {
+ rule_id: string;
+ name: string;
+ description: string | null;
+ category: string;
+ severity: string;
+ status: string;
+ enabled: boolean;
+ confidence: number;
+ /** Materialised false-positive rate in ``[0, 1]``. */
+ fp_rate: number;
+ total_hits: number;
+ /** ISO-8601 timestamp of the rule's last hit; ``null`` if it has never fired. */
+ last_triggered_at: string | null;
+ tags: string[];
+ mitre_tactics: string[];
+ mitre_techniques: string[];
+ version: number;
+ updated_at: string;
+
+ suggestion: TuningSuggestion;
+ /** Server-side ordering weight — already sorted descending in ``entries``. */
+ score: number;
+ reasons: string[];
+ auto_tune: boolean;
+ /** Set when an analyst has dismissed the rule from the default view. */
+ dismissed_at: string | null;
+ /** Most recent tuning action applied to this rule (``raise_threshold`` …). */
+ last_action: string | null;
+ last_action_at: string | null;
+}
+
+export interface TuningSummary {
+ total_rules: number;
+ actionable: number;
+ healthy: number;
+ disable_count: number;
+ add_suppression_count: number;
+ raise_threshold_count: number;
+ tune_confidence_count: number;
+ review_stale_count: number;
+ auto_tune_enabled: number;
+ /** Average ``fp_rate`` across classified rules, ``[0, 1]``. */
+ average_fp_rate: number;
+ /** Count of rules whose ``fp_rate`` is at or above the noisy threshold. */
+ high_fp_count: number;
+}
+
+export interface TuningFilters {
+ severity: string | null;
+ suggestion: string | null;
+ search: string | null;
+ enabled_only: boolean;
+ include_dismissed: boolean;
+ page: number;
+ page_size: number;
+}
+
+export interface TuningResponse {
+ entries: TuningEntry[];
+ summary: TuningSummary;
+ /** Echo of the filters that built this response. */
+ filters: TuningFilters;
+ total: number;
+ generated_at: string;
+}
+
+export interface TuningListParams {
+ severity?: string;
+ suggestion?: TuningSuggestion;
+ search?: string;
+ enabled_only?: boolean;
+ include_dismissed?: boolean;
+ page?: number;
+ page_size?: number;
+}
+
+export interface ApplyTuningRequest {
+ action: TuningAction;
+ note?: string | null;
+ /** Override threshold to set when ``action === 'raise_threshold'``. */
+ threshold?: number | null;
+ /** Free-text reason recorded with the suppression placeholder. */
+ suppression_reason?: string | null;
+}
+
+export interface DismissTuningRequest {
+ reason?: string | null;
+}
+
+export interface AutoTuneRequest {
+ enabled: boolean;
+}
+
+export const tuningApi = {
+ /**
+ * Fetch the rule tuning workbench feed.
+ *
+ * The ``summary`` block is computed across the *entire classified
+ * population* (not the current page), so the header tiles stay stable
+ * as analysts paginate. Dismissed rules are excluded by default — pass
+ * ``include_dismissed: true`` when auditing what's been hidden.
+ */
+ list: (params: TuningListParams = {}) =>
+ request<TuningResponse>('/api/v1/detection/tuning', {
+ params: params as Record<string, string | number | boolean>,
+ }),
+
+ /**
+ * Cheap summary-only endpoint. Used by the sidebar badge and the
+ * upcoming /console dashboard tile so they don't have to fetch the
+ * full feed just to render counts.
+ */
+ summary: () => request<TuningSummary>('/api/v1/detection/tuning/summary'),
+
+ /**
+ * Mechanically apply a tuning suggestion. ``raise_threshold``,
+ * ``add_suppression``, and ``disable`` mutate the rule and bump
+ * ``DetectionRule.version``; ``acknowledge`` is a no-op + audit. The
+ * server returns the re-projected entry so the UI can refresh in place.
+ */
+ apply: (ruleId: string, body: ApplyTuningRequest) =>
+ request<TuningEntry>(`/api/v1/detection/tuning/${ruleId}/apply`, {
+ method: 'POST',
+ body: JSON.stringify(body),
+ }),
+
+ /**
+ * Hide a rule from the default workbench view without touching its
+ * semantics. Dismissed rules reappear with ``include_dismissed: true``.
+ */
+ dismiss: (ruleId: string, body: DismissTuningRequest = {}) =>
+ request<TuningEntry>(`/api/v1/detection/tuning/${ruleId}/dismiss`, {
+ method: 'POST',
+ body: JSON.stringify(body),
+ }),
+
+ /**
+ * Flip the per-rule ``auto_tune`` opt-in flag. Stored under
+ * ``suppression_config.auto_tune`` so future automated tuners know
+ * they're allowed to touch the rule. Flipping does *not* trigger any
+ * immediate mutation.
+ */
+ autoTune: (ruleId: string, enabled: boolean) =>
+ request<TuningEntry>(`/api/v1/detection/tuning/${ruleId}/auto_tune`, {
+ method: 'POST',
+ body: JSON.stringify({ enabled } satisfies AutoTuneRequest),
+ }),
+};
+
// ─── AI Copilot ──────────────────────────────────────────────────────────────
export type CopilotRole = 'user' | 'assistant' | 'system';
@@ -4143,6 +4324,7 @@ export default {
graph: graphApi,
detection: detectionApi,
detectionProposals: detectionProposalsApi,
+ tuning: tuningApi,
copilot: copilotApi,
contextual: contextualApi,
ledger: ledgerApi,
diff --git a/services/api/app/api/v1/endpoints/rule_tuning.py b/services/api/app/api/v1/endpoints/rule_tuning.py
new file mode 100644
index 000000000..c6311ff51
--- /dev/null
+++ b/services/api/app/api/v1/endpoints/rule_tuning.py
@@ -0,0 +1,151 @@
+"""Detection rule tuning workbench endpoints.
+
+Backs the ``/detection/tuning`` workbench in apps/web. The heavy lifting lives
+in :mod:`app.services.rule_tuning`; this module is a thin transport layer that
+wires permissions, request bodies, and pagination through to that service.
+
+The router is mounted under ``/detection/tuning`` so it sits naturally inside
+the existing ``/detection`` URL tree without colliding with
+``detection_compat`` (``/detection/rules``, ``/detection/test``,
+``/detection/coverage``) or ``detection_proposals`` (``/detection/proposals``).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, Query, Request
+
+from app.api.v1.deps import AuthUser, require_permission
+from app.db.rls import TenantDBSession
+from app.services.rule_tuning import (
+ ApplyTuningRequest,
+ AutoTuneRequest,
+ DismissTuningRequest,
+ TuningEntry,
+ TuningResponse,
+ TuningSummary,
+ apply_tuning,
+ build_tuning,
+ build_tuning_summary,
+ dismiss_tuning,
+ set_auto_tune,
+)
+
+router = APIRouter(prefix="/detection/tuning", tags=["detection"])
+
+
[email protected]("", response_model=TuningResponse)
+async def get_tuning_workbench(
+ current_user: Annotated[AuthUser, Depends(require_permission("rules:read"))],
+ db: TenantDBSession,
+ severity: str | None = Query(default=None, description="Filter by rule severity (info/low/medium/high/critical)."),
+ suggestion: Literal[
+ "disable",
+ "add_suppression",
+ "raise_threshold",
+ "tune_confidence",
+ "review_stale",
+ "healthy",
+ ]
+ | None = Query(default=None, description="Filter to a single suggestion lane."),
+ search: str | None = Query(default=None, max_length=200, description="Substring match on name/description/category."),
+ enabled_only: bool = Query(default=False, description="Hide rules whose status != 'active'."),
+ include_dismissed: bool = Query(default=False, description="Show rules previously dismissed from the workbench."),
+ page: int = Query(default=1, ge=1),
+ page_size: int = Query(default=50, ge=1, le=100),
+) -> TuningResponse:
+ """Project every rule the tenant can tune into a workbench feed.
+
+ The summary block is computed across the *entire classified population*
+ (not the current page), so the header tiles stay stable as analysts page.
+ Dismissed rules are excluded by default — pass ``include_dismissed=true``
+ when auditing what's been hidden.
+ """
+ return await build_tuning(
+ db,
+ tenant_id=current_user.tenant_id,
+ severity=severity,
+ suggestion=suggestion,
+ search=search,
+ enabled_only=enabled_only,
+ include_dismissed=include_dismissed,
+ page=page,
+ page_size=page_size,
+ )
+
+
[email protected]("/summary", response_model=TuningSummary)
+async def get_tuning_summary(
+ current_user: Annotated[AuthUser, Depends(require_permission("rules:read"))],
+ db: TenantDBSession,
+) -> TuningSummary:
+ """Cheap summary-only endpoint for sidebar badges and the
+ /console dashboard tile."""
+ return await build_tuning_summary(db, tenant_id=current_user.tenant_id)
+
+
[email protected]("/{rule_id}/apply", response_model=TuningEntry)
+async def apply_tuning_endpoint(
+ rule_id: uuid.UUID,
+ body: ApplyTuningRequest,
+ current_user: Annotated[AuthUser, Depends(require_permission("rules:write"))],
+ db: TenantDBSession,
+ request: Request,
+) -> TuningEntry:
+ """Mechanically apply a tuning suggestion to a single rule.
+
+ Supports ``raise_threshold``, ``add_suppression``, ``disable``, and
+ ``acknowledge`` (no-op + audit). Every mutation bumps
+ ``DetectionRule.version`` and writes a ``detection.tuning.apply`` audit
+ log entry. Returns the re-projected entry so the UI can refresh in place.
+ """
+ return await apply_tuning(
+ db,
+ rule_id=rule_id,
+ actor=current_user,
+ body=body,
+ request=request,
+ )
+
+
[email protected]("/{rule_id}/dismiss", response_model=TuningEntry)
+async def dismiss_tuning_endpoint(
+ rule_id: uuid.UUID,
+ body: DismissTuningRequest,
+ current_user: Annotated[AuthUser, Depends(require_permission("rules:write"))],
+ db: TenantDBSession,
+ request: Request,
+) -> TuningEntry:
+ """Hide a rule from the default workbench view without changing semantics."""
+ return await dismiss_tuning(
+ db,
+ rule_id=rule_id,
+ actor=current_user,
+ body=body,
+ request=request,
+ )
+
+
[email protected]("/{rule_id}/auto_tune", response_model=TuningEntry)
+async def set_auto_tune_endpoint(
+ rule_id: uuid.UUID,
+ body: AutoTuneRequest,
+ current_user: Annotated[AuthUser, Depends(require_permission("rules:write"))],
+ db: TenantDBSession,
+ request: Request,
+) -> TuningEntry:
+ """Flip the per-rule ``auto_tune`` opt-in flag.
+
+ The flag is stored under ``suppression_config.auto_tune`` and is read by
+ future automated tuners — flipping it does *not* trigger any immediate
+ rule mutation.
+ """
+ return await set_auto_tune(
+ db,
+ rule_id=rule_id,
+ actor=current_user,
+ body=body,
+ request=request,
+ )
diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.py
index 715421e5d..2a0b56918 100644
--- a/services/api/app/api/v1/router.py
+++ b/services/api/app/api/v1/router.py
@@ -55,6 +55,7 @@ from app.api.v1.endpoints import (
rbac,
remediation,
reports,
+ rule_tuning,
saved_views,
shifts,
sla,
@@ -84,6 +85,12 @@ api_router.include_router(detection_rules.router)
# Frontend-shape facade: /api/v1/detection/rules + /api/v1/detection/test
api_router.include_router(detection_compat.router)
api_router.include_router(detection_proposals.router)
+# Detection rule tuning workbench — PR-6 (W8) v1.5 console plan.
+# /detection/tuning projects every rule into actionable suggestions
+# (disable / suppress / raise_threshold / tune_confidence / review_stale)
+# scored from rule.fp_rate + total_hits + confidence + last_triggered.
+# Mutations stamp suppression_config and write detection.tuning.* audit log.
+api_router.include_router(rule_tuning.router)
api_router.include_router(federated.router)
api_router.include_router(graph.router)
api_router.include_router(playbooks.router)
diff --git a/services/api/app/services/rule_tuning.py b/services/api/app/services/rule_tuning.py
new file mode 100644
index 000000000..976fcfed7
--- /dev/null
+++ b/services/api/app/services/rule_tuning.py
@@ -0,0 +1,808 @@
+"""Rule tuning workbench — projects ``DetectionRule`` rows into analyst-actionable
+suggestions and persists tuning actions.
+
+The tuning workbench is intentionally *cheap*: we do not recompute live false
+positive rates on demand. Every projection is derived from already-materialised
+fields on ``DetectionRule`` (``fp_rate``, ``total_hits``, ``confidence``,
+``last_triggered``, ``status``) which are maintained by the ingestion and
+detection pipelines. That keeps the workbench fast and lets analysts triage
+hundreds of rules without hammering the alerts table.
+
+Three verbs live here:
+
+* **project** — classify each rule, score it, and surface a suggested action.
+* **apply** — mechanically tighten a rule (raise threshold, add a placeholder
+ suppression, disable) or simply acknowledge it. Every apply bumps
+ ``DetectionRule.version`` and emits an audit event.
+* **dismiss / auto_tune** — record analyst intent without changing rule
+ semantics. Dismissed rules drop out of the default workbench view; auto_tune
+ is a per-rule opt-in flag stored under ``suppression_config.auto_tune`` so
+ future automated tuners know they're allowed to touch it.
+
+All mutations land in ``suppression_config`` / ``threshold_config`` (both JSONB
+``dict``s) and stay tenant-mutable — see
+:mod:`app.services.detections.sigma_import` for the convention.
+"""
+
+from __future__ import annotations
+
+import copy
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any, Literal
+
+from fastapi import HTTPException, Request, status
+from pydantic import BaseModel, Field
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.v1.deps import AuthUser
+from app.models.detection_rule import DetectionRule
+from app.services.audit import emit_audit
+
+# ─── Tuning heuristics ───────────────────────────────────────────────────────
+#
+# Thresholds are deliberately permissive so the workbench surfaces *some*
+# signal even for small tenants. They live as module constants so tests and
+# the docs page can reference the same numbers.
+
+#: A rule with this fp_rate or higher is hot — suggest a suppression first.
+TUNING_FP_RATE_NOISY = 0.20
+
+#: Combined with ``TUNING_FP_RATE_NOISY`` for the ``raise_threshold`` lane —
+#: noisy rules that *also* fire a lot are good threshold candidates.
+TUNING_FP_RATE_BUMPABLE = 0.10
+
+#: When fp_rate AND confidence both look bad and the rule is firing, we
+#: suggest disabling it outright rather than papering over the noise.
+TUNING_FP_RATE_DISABLE = 0.50
+
+#: Anything under this confidence is considered "low" — analysts should
+#: re-evaluate before they trust a high-rate alert from it.
+TUNING_LOW_CONFIDENCE = 40
+
+#: Threshold-bump candidates need enough hits that bumping by +1 is safe.
+TUNING_MIN_HITS_FOR_THRESHOLD = 20
+
+#: Stale = active rule that has not fired in this many days. (We also require
+#: the rule itself to be older than this, otherwise brand-new rules look stale.)
+TUNING_STALE_DAYS = 30
+
+#: Hard cap on rows the projection walks per call. The classifier is pure
+#: Python; we keep this bounded so a tenant with 50 000 imported Sigma rules
+#: can't accidentally DoS the workbench.
+TUNING_MAX_RULES_SCANNED = 1000
+
+
+TuningSuggestion = Literal[
+ "disable",
+ "add_suppression",
+ "raise_threshold",
+ "tune_confidence",
+ "review_stale",
+ "healthy",
+]
+
+TuningAction = Literal[
+ "raise_threshold",
+ "add_suppression",
+ "disable",
+ "acknowledge",
+]
+
+# Suggestions that surface as "needs work" in the summary tile. Everything
+# else (just ``healthy``) is folded into the healthy bucket.
+ACTIONABLE_SUGGESTIONS: frozenset[TuningSuggestion] = frozenset(
+ {"disable", "add_suppression", "raise_threshold", "tune_confidence", "review_stale"}
+)
+
+# Suggestion → ordering weight. Higher = surface first.
+_SUGGESTION_WEIGHT: dict[TuningSuggestion, int] = {
+ "disable": 500,
+ "add_suppression": 400,
+ "raise_threshold": 300,
+ "tune_confidence": 200,
+ "review_stale": 100,
+ "healthy": 0,
+}
+
+
+# ─── Wire models ─────────────────────────────────────────────────────────────
+
+
+class TuningEntry(BaseModel):
+ """One row in the tuning workbench — what an analyst sees."""
+
+ rule_id: str
+ name: str
+ description: str | None = None
+ category: str
+ severity: str
+ status: str
+ enabled: bool
+ confidence: int
+ fp_rate: float
+ total_hits: int
+ last_triggered_at: str | None = None
+ tags: list[str] = Field(default_factory=list)
+ mitre_tactics: list[str] = Field(default_factory=list)
+ mitre_techniques: list[str] = Field(default_factory=list)
+ version: int
+ updated_at: str
+
+ suggestion: TuningSuggestion
+ score: int
+ reasons: list[str] = Field(default_factory=list)
+ auto_tune: bool = False
+ dismissed_at: str | None = None
+ last_action: str | None = None
+ last_action_at: str | None = None
+
+
+class TuningSummary(BaseModel):
+ """Top-line counts for the workbench header."""
+
+ total_rules: int
+ actionable: int
+ healthy: int
+ disable_count: int = 0
+ add_suppression_count: int = 0
+ raise_threshold_count: int = 0
+ tune_confidence_count: int = 0
+ review_stale_count: int = 0
+ auto_tune_enabled: int = 0
+ average_fp_rate: float = 0.0
+ high_fp_count: int = 0
+
+
+class TuningFilters(BaseModel):
+ """Echo of the filters that built this response (handy for the UI)."""
+
+ severity: str | None = None
+ suggestion: str | None = None
+ search: str | None = None
+ enabled_only: bool = False
+ include_dismissed: bool = False
+ page: int = 1
+ page_size: int = 50
+
+
+class TuningResponse(BaseModel):
+ """Wire shape for ``GET /detection/tuning``."""
+
+ entries: list[TuningEntry]
+ summary: TuningSummary
+ filters: TuningFilters
+ total: int
+ generated_at: str
+
+
+class ApplyTuningRequest(BaseModel):
+ """Body for ``POST /detection/tuning/{rule_id}/apply``."""
+
+ action: TuningAction
+ note: str | None = None
+ threshold: int | None = Field(
+ default=None,
+ ge=1,
+ le=1_000_000,
+ description="Override threshold to set when action='raise_threshold'.",
+ )
+ suppression_reason: str | None = Field(
+ default=None,
+ max_length=255,
+ description="Free-text reason recorded with the suppression placeholder.",
+ )
+
+
+class DismissTuningRequest(BaseModel):
+ """Body for ``POST /detection/tuning/{rule_id}/dismiss``."""
+
+ reason: str | None = Field(default=None, max_length=255)
+
+
+class AutoTuneRequest(BaseModel):
+ """Body for ``POST /detection/tuning/{rule_id}/auto_tune``."""
+
+ enabled: bool
+
+
+# ─── Internal projection helpers ─────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class _Classification:
+ suggestion: TuningSuggestion
+ reasons: list[str]
+
+
+def _is_enabled(rule: DetectionRule) -> bool:
+ """Mirror :func:`detection_compat._to_frontend`'s enabled mapping."""
+ return rule.status == "active"
+
+
+def _suppression_config(rule: DetectionRule) -> dict[str, Any]:
+ """Return a *copy* of suppression_config so callers can mutate safely."""
+ raw = rule.suppression_config or {}
+ if not isinstance(raw, dict):
+ return {}
+ return copy.deepcopy(raw)
+
+
+def _threshold_config(rule: DetectionRule) -> dict[str, Any]:
+ raw = rule.threshold_config or {}
+ if not isinstance(raw, dict):
+ return {}
+ return copy.deepcopy(raw)
+
+
+def _auto_tune_enabled(rule: DetectionRule) -> bool:
+ cfg = rule.suppression_config or {}
+ if isinstance(cfg, dict):
+ return bool(cfg.get("auto_tune"))
+ return False
+
+
+def _dismissed_at(rule: DetectionRule) -> str | None:
+ cfg = rule.suppression_config or {}
+ if isinstance(cfg, dict):
+ value = cfg.get("tuning_dismissed_at")
+ if isinstance(value, str):
+ return value
+ return None
+
+
+def _last_action(rule: DetectionRule) -> tuple[str | None, str | None]:
+ cfg = rule.suppression_config or {}
+ if not isinstance(cfg, dict):
+ return None, None
+ action = cfg.get("tuning_last_action")
+ at = cfg.get("tuning_last_action_at")
+ return (action if isinstance(action, str) else None, at if isinstance(at, str) else None)
+
+
+def _stale(rule: DetectionRule, now: datetime) -> bool:
+ cutoff = now - timedelta(days=TUNING_STALE_DAYS)
+ if rule.last_triggered is not None:
+ return rule.last_triggered < cutoff
+ # Never fired — only call stale once it's old enough that we'd expect a hit.
+ if rule.created_at is None:
+ return False
+ return rule.created_at < cutoff
+
+
+def classify_suggestion(rule: DetectionRule, now: datetime | None = None) -> _Classification:
+ """Pure function: rule → suggestion + human-readable reasons.
+
+ Order matters: the first matching lane wins, so heavier interventions
+ (disable, suppression) take precedence over softer hints (review_stale).
+ """
+ moment = now or datetime.now(UTC)
+ fp = rule.fp_rate or 0.0
+ confidence = rule.confidence or 0
+ hits = rule.total_hits or 0
+ enabled = _is_enabled(rule)
+
+ reasons: list[str] = []
+
+ if enabled and fp >= TUNING_FP_RATE_DISABLE and confidence < TUNING_LOW_CONFIDENCE:
+ reasons.append(f"FP rate {fp:.0%} ≥ {TUNING_FP_RATE_DISABLE:.0%} with confidence {confidence} < {TUNING_LOW_CONFIDENCE}")
+ if hits:
+ reasons.append(f"{hits} total hits — disable will reduce queue pressure immediately")
+ return _Classification("disable", reasons)
+
+ if enabled and fp >= TUNING_FP_RATE_NOISY:
+ reasons.append(f"FP rate {fp:.0%} ≥ {TUNING_FP_RATE_NOISY:.0%} — add a suppression for the noisy entity")
+ if hits:
+ reasons.append(f"{hits} total hits over the rule's lifetime")
+ return _Classification("add_suppression", reasons)
+
+ if enabled and fp >= TUNING_FP_RATE_BUMPABLE and hits >= TUNING_MIN_HITS_FOR_THRESHOLD:
+ reasons.append(f"FP rate {fp:.0%} with {hits} hits — bumping the threshold trims volume without losing the signal")
+ return _Classification("raise_threshold", reasons)
+
+ if confidence < TUNING_LOW_CONFIDENCE and hits >= TUNING_MIN_HITS_FOR_THRESHOLD:
+ reasons.append(f"Confidence {confidence} < {TUNING_LOW_CONFIDENCE} despite {hits} hits — re-evaluate the rule body")
+ return _Classification("tune_confidence", reasons)
+
+ if enabled and _stale(rule, moment):
+ if rule.last_triggered is None:
+ reasons.append(f"No hits ever; rule has been live for {TUNING_STALE_DAYS}+ days")
+ else:
+ days = (moment - rule.last_triggered).days
+ reasons.append(f"Last hit was {days} days ago (stale threshold is {TUNING_STALE_DAYS}d)")
+ return _Classification("review_stale", reasons)
+
+ return _Classification("healthy", reasons)
+
+
+def _score(rule: DetectionRule, classification: _Classification) -> int:
+ """Compose suggestion weight + fp_rate + hits into a single ordering key."""
+ base = _SUGGESTION_WEIGHT[classification.suggestion]
+ # fp_rate ∈ [0,1] → 0..100; total_hits scaled down so a runaway rule with
+ # a million hits doesn't drown out the noisiest 1% rule with 50 hits.
+ fp_part = int(round((rule.fp_rate or 0.0) * 100))
+ hits_part = min(rule.total_hits or 0, 1000) // 10
+ return base + fp_part + hits_part
+
+
+def project_rule(rule: DetectionRule, now: datetime | None = None) -> TuningEntry:
+ """Pure function: ORM row → wire entry. Safe to test in isolation."""
+ moment = now or datetime.now(UTC)
+ classification = classify_suggestion(rule, moment)
+ last_action, last_action_at = _last_action(rule)
+
+ mitre_techniques = [str(t) for t in (rule.mitre_techniques or [])]
+ mitre_tactics = [str(t) for t in (rule.mitre_tactics or [])]
+
+ return TuningEntry(
+ rule_id=str(rule.id),
+ name=rule.name,
+ description=rule.description,
+ category=rule.category,
+ severity=rule.severity,
+ status=rule.status,
+ enabled=_is_enabled(rule),
+ confidence=rule.confidence or 0,
+ fp_rate=float(rule.fp_rate or 0.0),
+ total_hits=rule.total_hits or 0,
+ last_triggered_at=rule.last_triggered.isoformat() if rule.last_triggered else None,
+ tags=list(rule.tags or []),
+ mitre_tactics=mitre_tactics,
+ mitre_techniques=mitre_techniques,
+ version=rule.version or 1,
+ updated_at=rule.updated_at.isoformat() if rule.updated_at else moment.isoformat(),
+ suggestion=classification.suggestion,
+ score=_score(rule, classification),
+ reasons=classification.reasons,
+ auto_tune=_auto_tune_enabled(rule),
+ dismissed_at=_dismissed_at(rule),
+ last_action=last_action,
+ last_action_at=last_action_at,
+ )
+
+
+def _summarise(entries: list[TuningEntry]) -> TuningSummary:
+ if not entries:
+ return TuningSummary(total_rules=0, actionable=0, healthy=0)
+
+ counts: dict[TuningSuggestion, int] = dict.fromkeys(_SUGGESTION_WEIGHT, 0)
+ auto_tune = 0
+ fp_sum = 0.0
+ high_fp = 0
+ for entry in entries:
+ counts[entry.suggestion] = counts.get(entry.suggestion, 0) + 1
+ if entry.auto_tune:
+ auto_tune += 1
+ fp_sum += entry.fp_rate
+ if entry.fp_rate >= TUNING_FP_RATE_NOISY:
+ high_fp += 1
+
+ actionable = sum(counts[s] for s in ACTIONABLE_SUGGESTIONS)
+ healthy = counts.get("healthy", 0)
+ total = len(entries)
+ avg_fp = round(fp_sum / total, 4) if total else 0.0
+
+ return TuningSummary(
+ total_rules=total,
+ actionable=actionable,
+ healthy=healthy,
+ disable_count=counts.get("disable", 0),
+ add_suppression_count=counts.get("add_suppression", 0),
+ raise_threshold_count=counts.get("raise_threshold", 0),
+ tune_confidence_count=counts.get("tune_confidence", 0),
+ review_stale_count=counts.get("review_stale", 0),
+ auto_tune_enabled=auto_tune,
+ average_fp_rate=avg_fp,
+ high_fp_count=high_fp,
+ )
+
+
+# ─── Coordinator: build the workbench ────────────────────────────────────────
+
+
+async def build_tuning(
+ db: AsyncSession,
+ *,
+ tenant_id: uuid.UUID,
+ severity: str | None = None,
+ suggestion: TuningSuggestion | None = None,
+ search: str | None = None,
+ enabled_only: bool = False,
+ include_dismissed: bool = False,
+ page: int = 1,
+ page_size: int = 50,
+ now: datetime | None = None,
+) -> TuningResponse:
+ """Project every (filtered) rule the tenant owns, then paginate.
+
+ The summary is computed across the **entire classified population** —
+ not just the current page — so the header counts stay stable as analysts
+ page through results.
+ """
+ moment = now or datetime.now(UTC)
+ page = max(1, page)
+ page_size = max(1, min(page_size, 100))
+
+ stmt = select(DetectionRule).where(
+ or_(DetectionRule.tenant_id == tenant_id, DetectionRule.tenant_id.is_(None))
+ )
+
+ if severity:
+ stmt = stmt.where(DetectionRule.severity == severity)
+ if enabled_only:
+ stmt = stmt.where(DetectionRule.status == "active")
+ if search:
+ like = f"%{search.lower()}%"
+ stmt = stmt.where(
+ or_(
+ DetectionRule.name.ilike(like),
+ DetectionRule.description.ilike(like),
+ DetectionRule.category.ilike(like),
+ )
+ )
+
+ # Pre-sort at the DB so the projection mostly hits the heaviest rules
+ # first; final ordering is by Python-computed score below.
+ stmt = stmt.order_by(
+ DetectionRule.fp_rate.desc(),
+ DetectionRule.total_hits.desc(),
+ DetectionRule.updated_at.desc(),
+ ).limit(TUNING_MAX_RULES_SCANNED)
+
+ result = await db.execute(stmt)
+ rules: list[DetectionRule] = list(result.scalars().all())
+
+ projected: list[TuningEntry] = [project_rule(rule, moment) for rule in rules]
+
+ if not include_dismissed:
+ projected = [entry for entry in projected if entry.dismissed_at is None]
+
+ summary = _summarise(projected)
+
+ if suggestion:
+ projected = [entry for entry in projected if entry.suggestion == suggestion]
+
+ # Final sort: score DESC, then fp_rate, then total_hits, then name for stability.
+ projected.sort(key=lambda e: (-e.score, -e.fp_rate, -e.total_hits, e.name.lower()))
+
+ total = len(projected)
+ start = (page - 1) * page_size
+ end = start + page_size
+ page_entries = projected[start:end]
+
+ return TuningResponse(
+ entries=page_entries,
+ summary=summary,
+ filters=TuningFilters(
+ severity=severity,
+ suggestion=suggestion,
+ search=search,
+ enabled_only=enabled_only,
+ include_dismissed=include_dismissed,
+ page=page,
+ page_size=page_size,
+ ),
+ total=total,
+ generated_at=moment.isoformat(),
+ )
+
+
+async def build_tuning_summary(
+ db: AsyncSession,
+ *,
+ tenant_id: uuid.UUID,
+ now: datetime | None = None,
+) -> TuningSummary:
+ """Cheap summary-only call for sidebar badges and dashboard tiles."""
+ moment = now or datetime.now(UTC)
+ stmt = (
+ select(DetectionRule)
+ .where(or_(DetectionRule.tenant_id == tenant_id, DetectionRule.tenant_id.is_(None)))
+ .order_by(
+ DetectionRule.fp_rate.desc(),
+ DetectionRule.total_hits.desc(),
+ )
+ .limit(TUNING_MAX_RULES_SCANNED)
+ )
+ result = await db.execute(stmt)
+ rules: list[DetectionRule] = list(result.scalars().all())
+ projected = [project_rule(rule, moment) for rule in rules]
+ projected = [entry for entry in projected if entry.dismissed_at is None]
+ return _summarise(projected)
+
+
+# ─── Mutators: apply / dismiss / auto_tune ───────────────────────────────────
+
+
+async def _load_rule_for_tenant(
+ db: AsyncSession,
+ *,
+ rule_id: uuid.UUID,
+ tenant_id: uuid.UUID,
+) -> DetectionRule:
+ """Resolve a rule the actor is allowed to tune.
+
+ Builtin/platform rules (``tenant_id IS NULL``) are visible everywhere but
+ aren't tuneable from inside a tenant — tuning a global rule from one
+ tenant's workbench would leak the change to every other tenant. We let
+ analysts *see* them in projections but reject mutations.
+ """
+ result = await db.execute(select(DetectionRule).where(DetectionRule.id == rule_id))
+ rule = result.scalar_one_or_none()
+ if rule is None:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Detection rule not found")
+ if rule.tenant_id is None:
+ raise HTTPException(
+ status_code=status.HTTP_403_FORBIDDEN,
+ detail="Platform-wide rules can't be tuned from a tenant workbench",
+ )
+ if rule.tenant_id != tenant_id:
+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Detection rule not found")
+ return rule
+
+
+def _bumped_threshold(current: dict[str, Any], override: int | None) -> tuple[dict[str, Any], int, int]:
+ """Return (new_config, old_threshold, new_threshold)."""
+ next_config = dict(current)
+ raw_existing = current.get("event_threshold") or current.get("threshold")
+ try:
+ existing = int(raw_existing) if raw_existing is not None else 1
+ except (TypeError, ValueError):
+ existing = 1
+ new_value = override if override is not None else max(existing + 1, 2)
+ next_config["event_threshold"] = new_value
+ next_config["last_raised_at"] = datetime.now(UTC).isoformat()
+ return next_config, existing, new_value
+
+
+def _appended_suppression(
+ current: dict[str, Any],
+ *,
+ reason: str | None,
+ actor_email: str | None,
+) -> dict[str, Any]:
+ """Append a placeholder suppression record. The real suppression engine
+ interprets ``suppression_config.rules`` — this just gives it a starting
+ point that analysts can refine."""
+ next_config = dict(current)
+ rules_list = list(next_config.get("rules") or [])
+ rules_list.append(
+ {
+ "kind": "tune_placeholder",
+ "added_at": datetime.now(UTC).isoformat(),
+ "added_by": actor_email or "system",
+ "reason": reason or "Added from tuning workbench — refine the entity/window before relying on it",
+ }
+ )
+ next_config["rules"] = rules_list
+ next_config["last_tuned_at"] = datetime.now(UTC).isoformat()
+ return next_config
+
+
+def _stamp_last_action(
+ current: dict[str, Any],
+ *,
+ action: TuningAction,
+ actor_email: str | None,
+ note: str | None,
+) -> dict[str, Any]:
+ next_config = dict(current)
+ moment = datetime.now(UTC).isoformat()
+ next_config["tuning_last_action"] = action
+ next_config["tuning_last_action_at"] = moment
+ next_config["tuning_last_action_by"] = actor_email or "system"
+ if note:
+ next_config["tuning_last_action_note"] = note
+ # Clearing a stale dismissal: an apply implicitly un-dismisses the rule
+ # because the analyst is engaging with it again.
+ next_config.pop("tuning_dismissed_at", None)
+ next_config.pop("tuning_dismissed_reason", None)
+ return next_config
+
+
+async def apply_tuning(
+ db: AsyncSession,
+ *,
+ rule_id: uuid.UUID,
+ actor: AuthUser,
+ body: ApplyTuningRequest,
+ request: Request | None = None,
+ now: datetime | None = None,
+) -> TuningEntry:
+ """Mechanically apply a tuning suggestion and record an audit event.
+
+ Returns the post-write projected entry so the UI can refresh in-place.
+ """
+ moment = now or datetime.now(UTC)
+ rule = await _load_rule_for_tenant(db, rule_id=rule_id, tenant_id=actor.tenant_id)
+
+ before: dict[str, Any] = {
+ "status": rule.status,
+ "confidence": rule.confidence,
+ "threshold_config": _threshold_config(rule),
+ "suppression_config": _suppression_config(rule),
+ }
+
+ changes_payload: dict[str, Any] = {"action": body.action}
+
+ if body.action == "raise_threshold":
+ next_threshold, old_value, new_value = _bumped_threshold(
+ _threshold_config(rule),
+ body.threshold,
+ )
+ rule.threshold_config = next_threshold
+ changes_payload["threshold"] = {"before": old_value, "after": new_value}
+
+ elif body.action == "add_suppression":
+ rule.suppression_config = _appended_suppression(
+ _suppression_config(rule),
+ reason=body.suppression_reason or body.note,
+ actor_email=actor.email,
+ )
+ changes_payload["suppression_reason"] = body.suppression_reason or body.note
+
+ elif body.action == "disable":
+ rule.status = "disabled"
+ changes_payload["status"] = {"before": before["status"], "after": "disabled"}
+
+ elif body.action == "acknowledge":
+ # No mechanical change — just stamps last_action below.
+ pass
+
+ else: # pragma: no cover — Pydantic Literal makes this unreachable.
+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Unknown tuning action: {body.action!r}")
+
+ rule.suppression_config = _stamp_last_action(
+ rule.suppression_config or {},
+ action=body.action,
+ actor_email=actor.email,
+ note=body.note,
+ )
+ rule.version = (rule.version or 1) + 1
+ rule.updated_at = moment
+
+ await emit_audit(
+ db=db,
+ tenant_id=actor.tenant_id,
+ actor_id=actor.user_id,
+ actor_email=actor.email,
+ action="detection.tuning.apply",
+ resource="detection_rule",
+ resource_id=str(rule.id),
+ changes={
+ "rule_name": rule.name,
+ "before": before,
+ "after": {
+ "status": rule.status,
+ "confidence": rule.confidence,
+ "threshold_config": rule.threshold_config,
+ "suppression_config": rule.suppression_config,
+ },
+ "payload": changes_payload,
+ },
+ request=request,
+ )
+
+ await db.commit()
+ await db.refresh(rule)
+ return project_rule(rule, moment)
+
+
+async def dismiss_tuning(
+ db: AsyncSession,
+ *,
+ rule_id: uuid.UUID,
+ actor: AuthUser,
+ body: DismissTuningRequest,
+ request: Request | None = None,
+ now: datetime | None = None,
+) -> TuningEntry:
+ """Hide a rule from the default workbench view without changing semantics."""
+ moment = now or datetime.now(UTC)
+ rule = await _load_rule_for_tenant(db, rule_id=rule_id, tenant_id=actor.tenant_id)
+
+ before = _suppression_config(rule)
+ next_config = dict(before)
+ next_config["tuning_dismissed_at"] = moment.isoformat()
+ next_config["tuning_dismissed_by"] = actor.email or "system"
+ if body.reason:
+ next_config["tuning_dismissed_reason"] = body.reason
+ else:
+ next_config.pop("tuning_dismissed_reason", None)
+
+ rule.suppression_config = next_config
+ rule.updated_at = moment
+
+ await emit_audit(
+ db=db,
+ tenant_id=actor.tenant_id,
+ actor_id=actor.user_id,
+ actor_email=actor.email,
+ action="detection.tuning.dismiss",
+ resource="detection_rule",
+ resource_id=str(rule.id),
+ changes={
+ "rule_name": rule.name,
+ "before": before,
+ "after": next_config,
+ "reason": body.reason,
+ },
+ request=request,
+ )
+
+ await db.commit()
+ await db.refresh(rule)
+ return project_rule(rule, moment)
+
+
+async def set_auto_tune(
+ db: AsyncSession,
+ *,
+ rule_id: uuid.UUID,
+ actor: AuthUser,
+ body: AutoTuneRequest,
+ request: Request | None = None,
+ now: datetime | None = None,
+) -> TuningEntry:
+ """Flip the per-rule auto-tune opt-in flag."""
+ moment = now or datetime.now(UTC)
+ rule = await _load_rule_for_tenant(db, rule_id=rule_id, tenant_id=actor.tenant_id)
+
+ before = _suppression_config(rule)
+ next_config = dict(before)
+ previous = bool(next_config.get("auto_tune"))
+ next_config["auto_tune"] = body.enabled
+ next_config["auto_tune_updated_at"] = moment.isoformat()
+ next_config["auto_tune_updated_by"] = actor.email or "system"
+
+ rule.suppression_config = next_config
+ rule.updated_at = moment
+
+ await emit_audit(
+ db=db,
+ tenant_id=actor.tenant_id,
+ actor_id=actor.user_id,
+ actor_email=actor.email,
+ action="detection.tuning.auto_tune",
+ resource="detection_rule",
+ resource_id=str(rule.id),
+ changes={
+ "rule_name": rule.name,
+ "auto_tune": {"before": previous, "after": body.enabled},
+ },
+ request=request,
+ )
+
+ await db.commit()
+ await db.refresh(rule)
+ return project_rule(rule, moment)
+
+
+__all__ = [
+ "ACTIONABLE_SUGGESTIONS",
+ "ApplyTuningRequest",
+ "AutoTuneRequest",
+ "DismissTuningRequest",
+ "TUNING_FP_RATE_BUMPABLE",
+ "TUNING_FP_RATE_DISABLE",
+ "TUNING_FP_RATE_NOISY",
+ "TUNING_LOW_CONFIDENCE",
+ "TUNING_MAX_RULES_SCANNED",
+ "TUNING_MIN_HITS_FOR_THRESHOLD",
+ "TUNING_STALE_DAYS",
+ "TuningAction",
+ "TuningEntry",
+ "TuningFilters",
+ "TuningResponse",
+ "TuningSuggestion",
+ "TuningSummary",
+ "apply_tuning",
+ "build_tuning",
+ "build_tuning_summary",
+ "classify_suggestion",
+ "dismiss_tuning",
+ "project_rule",
+ "set_auto_tune",
+]
diff --git a/services/api/tests/test_rule_tuning.py b/services/api/tests/test_rule_tuning.py
new file mode 100644
index 000000000..10822bbad
--- /dev/null
+++ b/services/api/tests/test_rule_tuning.py
@@ -0,0 +1,825 @@
+"""Unit tests for the rule-tuning workbench backend (W8 / PR-6).
+
+Mirrors the ``test_alert_queue.py`` shape: pure helpers get hand-built
+``DetectionRule`` stand-ins, async coordinators / mutators get an in-memory
+``MagicMock(AsyncSession)``. No real Postgres, no FastAPI ``TestClient`` —
+the endpoint module is a transport-only wrapper; the service layer here is
+what carries the business rules.
+
+What this suite locks down:
+
+* **classify_suggestion** — every lane (disable / add_suppression /
+ raise_threshold / tune_confidence / review_stale / healthy) plus the
+ precedence between them (disable wins over add_suppression, etc.). If
+ the classifier regresses, the whole workbench surfaces the wrong
+ recommendations.
+
+* **project_rule** — full ORM → ``TuningEntry`` projection: enabled
+ mapping, fp_rate/confidence/hits coercion, suppression-config
+ read-throughs (``auto_tune``, ``tuning_dismissed_at``,
+ ``tuning_last_action``), and the version/updated_at marshalling.
+
+* **build_tuning** — coordinator math: page slicing, suggestion filter
+ is applied **after** summary so header counts stay stable as you
+ filter, ``include_dismissed`` toggle, severity / enabled_only /
+ search-arg pass-through into the SQL builder.
+
+* **apply_tuning** — all four actions (``raise_threshold``,
+ ``add_suppression``, ``disable``, ``acknowledge``) mutate the rule
+ correctly, bump ``version``, stamp ``tuning_last_action`` /
+ ``last_raised_at`` / ``last_tuned_at``, and emit a
+ ``detection.tuning.apply`` audit event. ``apply`` also implicitly
+ un-dismisses (clears ``tuning_dismissed_at``) because the analyst is
+ engaging with the rule again.
+
+* **dismiss_tuning** — stamps ``tuning_dismissed_at`` / ``_by`` /
+ ``_reason`` and emits ``detection.tuning.dismiss``.
+
+* **set_auto_tune** — flips ``suppression_config.auto_tune`` either way
+ and emits ``detection.tuning.auto_tune``.
+
+* **_load_rule_for_tenant** — the security tripod: 404 on missing,
+ 404 on cross-tenant, 403 on platform-wide (NULL tenant_id) rules.
+
+AiSOC — open-source AI Security Operations Center (MIT License)
+Author: Beenu Arora <[email protected]>
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from app.services.rule_tuning import (
+ ACTIONABLE_SUGGESTIONS,
+ TUNING_FP_RATE_BUMPABLE,
+ TUNING_FP_RATE_DISABLE,
+ TUNING_FP_RATE_NOISY,
+ TUNING_LOW_CONFIDENCE,
+ TUNING_MIN_HITS_FOR_THRESHOLD,
+ TUNING_STALE_DAYS,
+ ApplyTuningRequest,
+ AutoTuneRequest,
+ DismissTuningRequest,
+ apply_tuning,
+ build_tuning,
+ build_tuning_summary,
+ classify_suggestion,
+ dismiss_tuning,
+ project_rule,
+ set_auto_tune,
+)
+from fastapi import HTTPException
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+class _StubRule:
+ """Hand-built ``DetectionRule`` stand-in.
+
+ We can't use ``SimpleNamespace`` here because ``apply_tuning`` mutates
+ attributes (``rule.threshold_config = ...``) and needs to round-trip
+ back through ``project_rule``. A plain class with __init__ defaults is
+ the lightest thing that satisfies every read+write the service does.
+ """
+
+ def __init__(
+ self,
+ *,
+ rule_id: uuid.UUID | None = None,
+ tenant_id: uuid.UUID | None = None,
+ name: str = "Suspicious PowerShell",
+ description: str | None = "Catches encoded PowerShell command lines",
+ category: str = "endpoint",
+ severity: str = "high",
+ status: str = "active",
+ confidence: int = 75,
+ fp_rate: float = 0.05,
+ total_hits: int = 30,
+ last_triggered: datetime | None = None,
+ suppression_config: dict[str, Any] | None = None,
+ threshold_config: dict[str, Any] | None = None,
+ tags: list[str] | None = None,
+ mitre_tactics: list[str] | None = None,
+ mitre_techniques: list[str] | None = None,
+ version: int = 1,
+ created_at: datetime | None = None,
+ updated_at: datetime | None = None,
+ ) -> None:
+ self.id = rule_id or uuid.uuid4()
+ self.tenant_id = tenant_id or uuid.uuid4()
+ self.name = name
+ self.description = description
+ self.category = category
+ self.severity = severity
+ self.status = status
+ self.confidence = confidence
+ self.fp_rate = fp_rate
+ self.total_hits = total_hits
+ self.last_triggered = last_triggered or (datetime.now(UTC) - timedelta(hours=4))
+ self.suppression_config = suppression_config if suppression_config is not None else {}
+ self.threshold_config = threshold_config if threshold_config is not None else {}
+ self.tags = tags or []
+ self.mitre_tactics = mitre_tactics or []
+ self.mitre_techniques = mitre_techniques or []
+ self.version = version
+ self.created_at = created_at or (datetime.now(UTC) - timedelta(days=5))
+ self.updated_at = updated_at or datetime.now(UTC)
+
+
+def _scalars_all_result(values: list[Any]) -> MagicMock:
+ """Mock ``await session.execute(...).scalars().all() == values``."""
+ result = MagicMock()
+ scalars = MagicMock()
+ scalars.all = MagicMock(return_value=values)
+ result.scalars = MagicMock(return_value=scalars)
+ return result
+
+
+def _scalar_one_or_none_result(value: Any) -> MagicMock:
+ """Mock ``await session.execute(...).scalar_one_or_none() == value``."""
+ result = MagicMock()
+ result.scalar_one_or_none = MagicMock(return_value=value)
+ return result
+
+
+def _auth_user(tenant_id: uuid.UUID | None = None) -> MagicMock:
+ """Stand-in for ``AuthUser`` (``CurrentUser``) — only the three
+ attributes the service uses."""
+ actor = MagicMock()
+ actor.user_id = uuid.uuid4()
+ actor.tenant_id = tenant_id or uuid.uuid4()
+ actor.email = "[email protected]"
+ return actor
+
+
+# ---------------------------------------------------------------------------
+# classify_suggestion — pure heuristics
+# ---------------------------------------------------------------------------
+
+
+class TestClassifySuggestion:
+ """Each branch of the classifier, in precedence order.
+
+ A regression here flips the recommendation the workbench shows — the
+ most user-visible failure mode in the whole feature.
+ """
+
+ def test_high_fp_low_confidence_recommends_disable(self) -> None:
+ # FP rate well above the disable threshold AND confidence under
+ # the floor — the rule is just noise, not signal. Disable wins
+ # even though add_suppression also matches at this FP rate.
+ rule = _StubRule(fp_rate=TUNING_FP_RATE_DISABLE + 0.1, confidence=TUNING_LOW_CONFIDENCE - 1, total_hits=200)
+ classification = classify_suggestion(rule)
+ assert classification.suggestion == "disable"
+ assert classification.reasons, "disable lane must surface at least one reason"
+
+ def test_noisy_but_decent_confidence_recommends_add_suppression(self) -> None:
+ # FP rate is high but confidence is reasonable — paper over the
+ # noise with a suppression rather than killing the rule.
+ rule = _StubRule(fp_rate=TUNING_FP_RATE_NOISY + 0.05, confidence=70, total_hits=100)
+ classification = classify_suggestion(rule)
+ assert classification.suggestion == "add_suppression"
+
+ def test_moderate_fp_with_enough_hits_recommends_raise_threshold(self) -> None:
+ # Below the "noisy" cutoff but still elevated, and the rule fires
+ # often enough that bumping its threshold is a safe trim.
+ rule = _StubRule(
+ fp_rate=TUNING_FP_RATE_BUMPABLE + 0.02,
+ confidence=70,
+ total_hits=TUNING_MIN_HITS_FOR_THRESHOLD + 5,
+ )
+ classification = classify_suggestion(rule)
+ assert classification.suggestion == "raise_threshold"
+
+ def test_low_confidence_with_hits_recommends_tune_confidence(self) -> None:
+ # FP rate is fine but the rule's body or scoring is weak — the
+ # analyst should re-evaluate before trusting the alerts.
+ rule = _StubRule(
+ fp_rate=0.0,
+ confidence=TUNING_LOW_CONFIDENCE - 5,
+ total_hits=TUNING_MIN_HITS_FOR_THRESHOLD + 1,
+ )
+ classification = classify_suggestion(rule)
+ assert classification.suggestion == "tune_confidence"
+
+ def test_stale_active_rule_recommends_review_stale(self) -> None:
+ # Active rule, healthy fp_rate, healthy confidence — but it
+ # hasn't fired in ages. Surface it so the analyst can confirm
+ # the rule is still relevant.
+ now = datetime.now(UTC)
+ rule = _StubRule(
+ fp_rate=0.0,
+ confidence=80,
+ total_hits=5,
+ last_triggered=now - timedelta(days=TUNING_STALE_DAYS + 10),
+ created_at=now - timedelta(days=TUNING_STALE_DAYS + 60),
+ )
+ classification = classify_suggestion(rule, now=now)
+ assert classification.suggestion == "review_stale"
+
+ def test_never_fired_brand_new_rule_is_healthy(self) -> None:
+ # Brand-new rule that has not fired must NOT be flagged as
+ # stale — we'd cry wolf on every Sigma import otherwise.
+ now = datetime.now(UTC)
+ rule = _StubRule(
+ fp_rate=0.0,
+ confidence=80,
+ total_hits=0,
+ last_triggered=None,
+ created_at=now - timedelta(days=2),
+ )
+ classification = classify_suggestion(rule, now=now)
+ assert classification.suggestion == "healthy"
+
+ def test_disabled_rule_is_never_classified_as_actionable(self) -> None:
+ # Disabled rules can still appear in the projection but they
+ # should not be screaming "disable!" at the analyst. The only
+ # lane left for them is healthy or tune_confidence (which fires
+ # on hits-but-low-confidence regardless of status).
+ rule = _StubRule(
+ status="disabled",
+ fp_rate=TUNING_FP_RATE_DISABLE + 0.2, # would normally trigger disable
+ confidence=80,
+ total_hits=50,
+ )
+ classification = classify_suggestion(rule)
+ assert classification.suggestion == "healthy"
+
+ def test_healthy_rule_returns_no_reasons(self) -> None:
+ rule = _StubRule(fp_rate=0.02, confidence=85, total_hits=15)
+ classification = classify_suggestion(rule)
+ assert classification.suggestion == "healthy"
+ assert classification.reasons == []
+
+
+# ---------------------------------------------------------------------------
+# project_rule — ORM → wire entry
+# ---------------------------------------------------------------------------
+
+
+class TestProjectRule:
+ """The wire shape contract: every field the frontend reads must be
+ populated correctly. If any of these regress the UI breaks silently."""
+
+ def test_enabled_mirrors_status_active(self) -> None:
+ rule = _StubRule(status="active")
+ entry = project_rule(rule)
+ assert entry.enabled is True
+
+ def test_disabled_status_projects_enabled_false(self) -> None:
+ rule = _StubRule(status="disabled")
+ entry = project_rule(rule)
+ assert entry.enabled is False
+
+ def test_testing_status_projects_enabled_false(self) -> None:
+ # ``testing`` is the canonical "drafting / not yet promoted"
+ # status — must NOT count as enabled, otherwise the workbench
+ # tries to suggest disabling rules that aren't even on.
+ rule = _StubRule(status="testing")
+ entry = project_rule(rule)
+ assert entry.enabled is False
+
+ def test_auto_tune_flag_reads_from_suppression_config(self) -> None:
+ rule = _StubRule(suppression_config={"auto_tune": True})
+ entry = project_rule(rule)
+ assert entry.auto_tune is True
+
+ def test_missing_suppression_config_defaults_auto_tune_to_false(self) -> None:
+ rule = _StubRule(suppression_config=None)
+ entry = project_rule(rule)
+ assert entry.auto_tune is False
+
+ def test_dismissed_at_reads_from_suppression_config(self) -> None:
+ stamped = "2026-05-13T12:00:00+00:00"
+ rule = _StubRule(suppression_config={"tuning_dismissed_at": stamped})
+ entry = project_rule(rule)
+ assert entry.dismissed_at == stamped
+
+ def test_last_action_round_trip(self) -> None:
+ # Re-projection after an apply must surface the action + stamp
+ # so the UI can render "raised threshold 3m ago".
+ rule = _StubRule(
+ suppression_config={
+ "tuning_last_action": "raise_threshold",
+ "tuning_last_action_at": "2026-05-13T11:30:00+00:00",
+ }
+ )
+ entry = project_rule(rule)
+ assert entry.last_action == "raise_threshold"
+ assert entry.last_action_at == "2026-05-13T11:30:00+00:00"
+
+ def test_none_numerics_coerce_to_zero(self) -> None:
+ # ORM defaults are NOT NULL but legacy rows or tests may still
+ # ship Nones. The projection must not crash the workbench in
+ # that case.
+ rule = _StubRule(fp_rate=None, confidence=None, total_hits=None)
+ entry = project_rule(rule)
+ assert entry.fp_rate == 0.0
+ assert entry.confidence == 0
+ assert entry.total_hits == 0
+
+ def test_score_orders_disable_above_healthy(self) -> None:
+ # The "score" is the single sort key the workbench uses; if
+ # disable doesn't outrank healthy the most-urgent rule sinks
+ # below noise.
+ noisy = _StubRule(
+ fp_rate=TUNING_FP_RATE_DISABLE + 0.1,
+ confidence=TUNING_LOW_CONFIDENCE - 1,
+ total_hits=100,
+ )
+ clean = _StubRule(fp_rate=0.01, confidence=90, total_hits=10)
+ assert project_rule(noisy).score > project_rule(clean).score
+
+
+# ---------------------------------------------------------------------------
+# build_tuning — coordinator math
+# ---------------------------------------------------------------------------
+
+
+def _setup_build_db(rules: list[_StubRule]) -> MagicMock:
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalars_all_result(rules))
+ return db
+
+
+class TestBuildTuning:
+ """Filtering, pagination, and the summary-vs-filter ordering contract."""
+
+ @pytest.mark.asyncio
+ async def test_summary_counts_full_population_before_suggestion_filter(self) -> None:
+ # CRITICAL: the header summary tiles must be computed across
+ # every rule, NOT across the filtered page. Otherwise switching
+ # the "disable" filter on hides the count we used to motivate
+ # filtering in the first place.
+ tenant_id = uuid.uuid4()
+ noisy = _StubRule(
+ fp_rate=TUNING_FP_RATE_DISABLE + 0.1,
+ confidence=TUNING_LOW_CONFIDENCE - 1,
+ total_hits=100,
+ )
+ clean = _StubRule(fp_rate=0.0, confidence=90, total_hits=5)
+ db = _setup_build_db([noisy, clean])
+
+ resp = await build_tuning(
+ db,
+ tenant_id=tenant_id,
+ suggestion="disable",
+ )
+
+ # Only the noisy rule survives the filter:
+ assert len(resp.entries) == 1
+ assert resp.entries[0].suggestion == "disable"
+ # ... but the summary still sees BOTH rules:
+ assert resp.summary.total_rules == 2
+ assert resp.summary.healthy == 1
+ assert resp.summary.disable_count == 1
+
+ @pytest.mark.asyncio
+ async def test_pagination_slices_after_sort(self) -> None:
+ # Three urgent + two healthy rules. With page_size=2 we expect
+ # the two highest-scoring rules first.
+ tenant_id = uuid.uuid4()
+ rules = [
+ _StubRule(name=f"rule_{i}", fp_rate=0.6, confidence=10, total_hits=100 + i)
+ for i in range(3)
+ ] + [_StubRule(name=f"healthy_{i}", fp_rate=0.0, confidence=90) for i in range(2)]
+ db = _setup_build_db(rules)
+
+ resp = await build_tuning(db, tenant_id=tenant_id, page=1, page_size=2)
+
+ assert resp.total == 5
+ assert len(resp.entries) == 2
+ # Highest-scoring rules surface first:
+ assert all(e.suggestion == "disable" for e in resp.entries)
+ # Pagination echo:
+ assert resp.filters.page == 1
+ assert resp.filters.page_size == 2
+
+ @pytest.mark.asyncio
+ async def test_include_dismissed_toggle(self) -> None:
+ # A rule with ``tuning_dismissed_at`` stamped must drop out of
+ # the default view but reappear when include_dismissed=True.
+ tenant_id = uuid.uuid4()
+ dismissed = _StubRule(
+ name="dismissed_rule",
+ suppression_config={"tuning_dismissed_at": "2026-05-12T00:00:00+00:00"},
+ )
+ normal = _StubRule(name="normal_rule")
+ db = _setup_build_db([dismissed, normal])
+
+ # Default: dismissed rule is hidden
+ resp_default = await build_tuning(db, tenant_id=tenant_id)
+ assert len(resp_default.entries) == 1
+ assert resp_default.entries[0].name == "normal_rule"
+
+ # include_dismissed=True: it shows up again
+ db.execute = AsyncMock(return_value=_scalars_all_result([dismissed, normal]))
+ resp_all = await build_tuning(db, tenant_id=tenant_id, include_dismissed=True)
+ assert len(resp_all.entries) == 2
+
+ @pytest.mark.asyncio
+ async def test_filters_echo_in_response(self) -> None:
+ # The frontend mirrors the filter state from the response (so a
+ # deep-linked URL hydrates the form). All input filters must be
+ # echoed exactly.
+ db = _setup_build_db([])
+ resp = await build_tuning(
+ db,
+ tenant_id=uuid.uuid4(),
+ severity="high",
+ suggestion="disable",
+ search="powershell",
+ enabled_only=True,
+ page=3,
+ page_size=25,
+ )
+ assert resp.filters.severity == "high"
+ assert resp.filters.suggestion == "disable"
+ assert resp.filters.search == "powershell"
+ assert resp.filters.enabled_only is True
+ assert resp.filters.page == 3
+ assert resp.filters.page_size == 25
+
+ @pytest.mark.asyncio
+ async def test_generated_at_is_iso_string(self) -> None:
+ # generated_at is consumed by the UI for client-side clock-drift
+ # correction. Must be a valid ISO-8601 string, not a datetime.
+ db = _setup_build_db([])
+ resp = await build_tuning(db, tenant_id=uuid.uuid4())
+ # ``fromisoformat`` would raise if the string were malformed:
+ datetime.fromisoformat(resp.generated_at)
+
+ @pytest.mark.asyncio
+ async def test_actionable_suggestions_constant_is_correct(self) -> None:
+ # If someone adds a new suggestion lane, they must consciously
+ # decide whether it counts toward the "needs work" tile.
+ assert ACTIONABLE_SUGGESTIONS == frozenset(
+ {"disable", "add_suppression", "raise_threshold", "tune_confidence", "review_stale"}
+ )
+ assert "healthy" not in ACTIONABLE_SUGGESTIONS
+
+
+class TestBuildTuningSummary:
+ """The summary-only endpoint is a sidebar/badge path — must stay cheap
+ and must NOT hand back full rule details."""
+
+ @pytest.mark.asyncio
+ async def test_summary_skips_dismissed_rules(self) -> None:
+ tenant_id = uuid.uuid4()
+ dismissed = _StubRule(
+ fp_rate=TUNING_FP_RATE_DISABLE + 0.1,
+ confidence=10,
+ total_hits=100,
+ suppression_config={"tuning_dismissed_at": "2026-05-12T00:00:00+00:00"},
+ )
+ active_noisy = _StubRule(
+ fp_rate=TUNING_FP_RATE_DISABLE + 0.1,
+ confidence=10,
+ total_hits=100,
+ )
+ db = _setup_build_db([dismissed, active_noisy])
+
+ summary = await build_tuning_summary(db, tenant_id=tenant_id)
+
+ # Only the un-dismissed rule counts:
+ assert summary.total_rules == 1
+ assert summary.disable_count == 1
+ assert summary.actionable == 1
+
+
+# ---------------------------------------------------------------------------
+# Mutators — apply / dismiss / auto_tune
+# ---------------------------------------------------------------------------
+
+
+def _setup_mutator_db(rule: _StubRule) -> MagicMock:
+ """Mock the two-step DB pattern every mutator uses: SELECT-by-id,
+ then commit + refresh."""
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalar_one_or_none_result(rule))
+ db.commit = AsyncMock()
+ db.refresh = AsyncMock()
+ return db
+
+
[email protected](autouse=True)
+def _patch_audit(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
+ """Stub out the audit-log writer so tests don't need a real session.
+
+ The mutator service imports ``emit_audit`` at module load — we monkey-
+ patch its bound name in ``app.services.rule_tuning`` so every test
+ method can both (a) safely call the mutator and (b) assert that the
+ audit event fired with the correct action label.
+ """
+ stub = AsyncMock(return_value=None)
+ monkeypatch.setattr("app.services.rule_tuning.emit_audit", stub)
+ return stub
+
+
+class TestApplyTuning:
+ """Each apply action must mutate the rule AND emit an audit event."""
+
+ @pytest.mark.asyncio
+ async def test_raise_threshold_bumps_threshold_and_version(
+ self, _patch_audit: AsyncMock
+ ) -> None:
+ actor = _auth_user()
+ rule = _StubRule(
+ tenant_id=actor.tenant_id,
+ threshold_config={"event_threshold": 3},
+ version=4,
+ )
+ db = _setup_mutator_db(rule)
+
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="raise_threshold"),
+ )
+
+ # Threshold incremented:
+ assert rule.threshold_config["event_threshold"] == 4
+ # Version bumped:
+ assert rule.version == 5
+ # Audit event fired with the right label:
+ _patch_audit.assert_awaited_once()
+ call = _patch_audit.await_args
+ assert call.kwargs["action"] == "detection.tuning.apply"
+ assert call.kwargs["resource"] == "detection_rule"
+ db.commit.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_raise_threshold_with_explicit_override(self) -> None:
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=actor.tenant_id, threshold_config={"event_threshold": 5})
+ db = _setup_mutator_db(rule)
+
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="raise_threshold", threshold=25),
+ )
+
+ # Analyst override wins over the auto-bump:
+ assert rule.threshold_config["event_threshold"] == 25
+
+ @pytest.mark.asyncio
+ async def test_raise_threshold_with_no_existing_config_starts_at_two(self) -> None:
+ # Fresh rule (no threshold_config yet) must not crash — we
+ # default the existing threshold to 1 and bump to max(2, …).
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=actor.tenant_id, threshold_config={})
+ db = _setup_mutator_db(rule)
+
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="raise_threshold"),
+ )
+
+ assert rule.threshold_config["event_threshold"] == 2
+
+ @pytest.mark.asyncio
+ async def test_add_suppression_appends_placeholder(self) -> None:
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=actor.tenant_id, suppression_config={"rules": []})
+ db = _setup_mutator_db(rule)
+
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(
+ action="add_suppression",
+ suppression_reason="known scanner",
+ ),
+ )
+
+ placeholder = rule.suppression_config["rules"][0]
+ assert placeholder["kind"] == "tune_placeholder"
+ assert placeholder["reason"] == "known scanner"
+ assert placeholder["added_by"] == actor.email
+
+ @pytest.mark.asyncio
+ async def test_disable_flips_status(self) -> None:
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=actor.tenant_id, status="active")
+ db = _setup_mutator_db(rule)
+
+ entry = await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="disable"),
+ )
+
+ assert rule.status == "disabled"
+ # Re-projection sees the new status:
+ assert entry.enabled is False
+ assert entry.status == "disabled"
+
+ @pytest.mark.asyncio
+ async def test_acknowledge_records_action_without_mutation(
+ self, _patch_audit: AsyncMock
+ ) -> None:
+ # Acknowledge is a no-op for the rule's *semantics* — it just
+ # stamps last_action so the workbench shows "ack'd 5m ago" and
+ # the analyst can re-find the row.
+ actor = _auth_user()
+ original_status = "active"
+ original_threshold = {"event_threshold": 3}
+ rule = _StubRule(
+ tenant_id=actor.tenant_id,
+ status=original_status,
+ threshold_config=dict(original_threshold),
+ version=7,
+ )
+ db = _setup_mutator_db(rule)
+
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="acknowledge", note="false positive accepted"),
+ )
+
+ assert rule.status == original_status
+ assert rule.threshold_config["event_threshold"] == 3
+ assert rule.suppression_config["tuning_last_action"] == "acknowledge"
+ assert rule.suppression_config["tuning_last_action_note"] == "false positive accepted"
+ # Even an acknowledge bumps version + emits audit:
+ assert rule.version == 8
+ _patch_audit.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_apply_clears_previous_dismissal(self) -> None:
+ # If the analyst dismissed a rule yesterday, then re-engaged
+ # with it today, the apply must implicitly un-dismiss it.
+ # Otherwise the apply succeeds but the rule stays hidden from
+ # the default view — a confusing dead-end UX.
+ actor = _auth_user()
+ rule = _StubRule(
+ tenant_id=actor.tenant_id,
+ suppression_config={
+ "tuning_dismissed_at": "2026-05-12T00:00:00+00:00",
+ "tuning_dismissed_reason": "not interesting yet",
+ },
+ )
+ db = _setup_mutator_db(rule)
+
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="acknowledge"),
+ )
+
+ assert "tuning_dismissed_at" not in rule.suppression_config
+ assert "tuning_dismissed_reason" not in rule.suppression_config
+
+ @pytest.mark.asyncio
+ async def test_apply_404s_on_missing_rule(self) -> None:
+ actor = _auth_user()
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalar_one_or_none_result(None))
+
+ with pytest.raises(HTTPException) as exc_info:
+ await apply_tuning(
+ db,
+ rule_id=uuid.uuid4(),
+ actor=actor,
+ body=ApplyTuningRequest(action="acknowledge"),
+ )
+ assert exc_info.value.status_code == 404
+
+ @pytest.mark.asyncio
+ async def test_apply_404s_on_cross_tenant_rule(self) -> None:
+ # Wrong tenant = 404, NOT 403. We deliberately don't tell the
+ # actor whether the rule exists in another tenant.
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=uuid.uuid4()) # different tenant
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalar_one_or_none_result(rule))
+
+ with pytest.raises(HTTPException) as exc_info:
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="acknowledge"),
+ )
+ assert exc_info.value.status_code == 404
+
+ @pytest.mark.asyncio
+ async def test_apply_403s_on_platform_wide_rule(self) -> None:
+ # Tenant-null rules are visible from every tenant but mutations
+ # would leak across tenants. The service explicitly 403s.
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=None)
+ rule.tenant_id = None # explicit override of fixture default
+ db = MagicMock()
+ db.execute = AsyncMock(return_value=_scalar_one_or_none_result(rule))
+
+ with pytest.raises(HTTPException) as exc_info:
+ await apply_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=ApplyTuningRequest(action="acknowledge"),
+ )
+ assert exc_info.value.status_code == 403
+
+
+class TestDismissTuning:
+ @pytest.mark.asyncio
+ async def test_dismiss_stamps_suppression_config(
+ self, _patch_audit: AsyncMock
+ ) -> None:
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=actor.tenant_id, suppression_config={})
+ db = _setup_mutator_db(rule)
+
+ await dismiss_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=DismissTuningRequest(reason="acceptable noise"),
+ )
+
+ assert "tuning_dismissed_at" in rule.suppression_config
+ assert rule.suppression_config["tuning_dismissed_by"] == actor.email
+ assert rule.suppression_config["tuning_dismissed_reason"] == "acceptable noise"
+ _patch_audit.assert_awaited_once()
+ assert _patch_audit.await_args.kwargs["action"] == "detection.tuning.dismiss"
+
+ @pytest.mark.asyncio
+ async def test_dismiss_without_reason_drops_stale_reason(self) -> None:
+ # Re-dismissing without a reason must not preserve the prior
+ # reason — otherwise the UI shows a misleading stale message.
+ actor = _auth_user()
+ rule = _StubRule(
+ tenant_id=actor.tenant_id,
+ suppression_config={"tuning_dismissed_reason": "old reason"},
+ )
+ db = _setup_mutator_db(rule)
+
+ await dismiss_tuning(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=DismissTuningRequest(reason=None),
+ )
+
+ assert "tuning_dismissed_reason" not in rule.suppression_config
+
+
+class TestSetAutoTune:
+ @pytest.mark.asyncio
+ async def test_enable_auto_tune(self, _patch_audit: AsyncMock) -> None:
+ actor = _auth_user()
+ rule = _StubRule(tenant_id=actor.tenant_id, suppression_config={})
+ db = _setup_mutator_db(rule)
+
+ entry = await set_auto_tune(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=AutoTuneRequest(enabled=True),
+ )
+
+ assert rule.suppression_config["auto_tune"] is True
+ assert "auto_tune_updated_at" in rule.suppression_config
+ assert rule.suppression_config["auto_tune_updated_by"] == actor.email
+ assert entry.auto_tune is True
+ _patch_audit.assert_awaited_once()
+ assert _patch_audit.await_args.kwargs["action"] == "detection.tuning.auto_tune"
+
+ @pytest.mark.asyncio
+ async def test_disable_auto_tune_round_trips(self) -> None:
+ # Toggling auto_tune off must clear the flag (False), not delete
+ # the key — auditors need to see that it WAS on previously.
+ actor = _auth_user()
+ rule = _StubRule(
+ tenant_id=actor.tenant_id,
+ suppression_config={"auto_tune": True},
+ )
+ db = _setup_mutator_db(rule)
+
+ await set_auto_tune(
+ db,
+ rule_id=rule.id,
+ actor=actor,
+ body=AutoTuneRequest(enabled=False),
+ )
+
+ assert rule.suppression_config["auto_tune"] is False
+ assert "auto_tune_updated_at" in rule.suppression_config