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: three detection-authoring modes — Python framework + AI builder + no-code (Wave 3) (#576)

Beenu Aroraef520652bd35
diff --git a/.github/workflows/python-detections.yml b/.github/workflows/python-detections.yml
new file mode 100644
index 000000000..ff9dea427
--- /dev/null
+++ b/.github/workflows/python-detections.yml
@@ -0,0 +1,43 @@
+name: Python Detections
+
+# Gate the Python detection framework (Wave 3, W3.1): every bundled detection
+# must pass its own positive/negative fixtures, and the framework's own tests
+# must pass. A blind rule (misses a positive) or a noisy one (fires on a
+# negative) fails the build.
+on:
+ pull_request:
+ paths:
+ - "packages/aisoc-detections/**"
+ - ".github/workflows/python-detections.yml"
+ push:
+ branches: [main]
+ paths:
+ - "packages/aisoc-detections/**"
+ - ".github/workflows/python-detections.yml"
+
+permissions:
+ contents: read
+
+jobs:
+ fixtures:
+ name: Python detections — fixture gate
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: "3.12"
+ cache: pip
+ - name: Install test deps
+ run: pip install --quiet pytest "ruff>=0.4.4,<0.5"
+ - name: Run the detection fixture suite
+ working-directory: packages/aisoc-detections
+ run: python -m aisoc_detections.runner detections
+ - name: Run the framework tests
+ working-directory: packages/aisoc-detections
+ run: PYTHONPATH=. python -m pytest tests/ -v --tb=short
+ - name: Lint
+ working-directory: packages/aisoc-detections
+ run: |
+ ruff check aisoc_detections detections tests
+ ruff format --check aisoc_detections detections tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 37a75af5c..edec5ffe7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **Three detection-authoring modes (Wave 3).** (1) A **Python detection
+ framework** (`packages/aisoc-detections`): write detections as
+ `def rule(event) -> bool` + metadata + inline positive/negative `TESTS`,
+ complementing the YAML/Sigma corpus; a fixture harness fails a blind rule
+ (misses a positive) or a noisy one (fires on a negative), `evaluate()` is
+ fail-closed, and a CI gate (`python-detections.yml`) runs it. Ships a CLI
+ (`aisoc-detections`) + example detections. (2) An **AI Detection Builder**
+ (`POST /nl-detection/propose`): a plain-English threat description becomes a
+ Sigma rule with **auto-generated** positive/negative fixtures **derived from
+ the rule's own selection** (not invented by the LLM), run through the
+ non-circular eval-gate, and opened as a governed DRAFT proposal. (3) A
+ **no-code / simple detection builder** (`SimpleRuleBuilder`): a form
+ (field/operator/value rows) compiles to a valid Sigma rule dropped into the
+ governed editor. Also fixes a real bug: `detection_loop` / the Wave-1 tuner +
+ hunt bridge inserted into a non-existent `aisoc_detection_rule_proposals`
+ table (the real table is `detection_rule_proposals`).
- **Detection backtesting over the event lake (Wave 2).** New
`POST /api/v1/rules/{rule_id}/backtest` runs a candidate detection rule against
REAL historical events in the tenant-scoped ClickHouse lake
diff --git a/apps/web/src/components/detections/RuleEditor.tsx b/apps/web/src/components/detections/RuleEditor.tsx
index 12c926103..11239eb34 100644
--- a/apps/web/src/components/detections/RuleEditor.tsx
+++ b/apps/web/src/components/detections/RuleEditor.tsx
@@ -19,6 +19,7 @@ import type { AlertSeverity } from '@/lib/api';
import { Skeleton } from '@/components/ui/Skeleton';
import { ErrorState } from '@/components/ui/ErrorState';
import { ContextualActions } from '@/components/copilot/ContextualActions';
+import { SimpleRuleBuilder } from '@/components/detections/SimpleRuleBuilder';
const MonacoEditor = dynamic(() => import('@monaco-editor/react'), {
ssr: false,
@@ -134,6 +135,9 @@ export function RuleEditor({ mode, ruleId }: RuleEditorProps) {
} | null>(null);
const [saving, setSaving] = useState(false);
+ // Wave 3 (W3.3) — no-code builder panel toggle.
+ const [showBuilder, setShowBuilder] = useState(false);
+
// Wave 2 (W2.3) — backtest a SAVED rule over real historical lake events.
const [backtestDays, setBacktestDays] = useState(30);
const [backtesting, setBacktesting] = useState(false);
@@ -690,6 +694,29 @@ export function RuleEditor({ mode, ruleId }: RuleEditorProps) {
))}
</div>
+ {/* Wave 3 (W3.3) — no-code builder toggle + panel */}
+ <div>
+ <button
+ type="button"
+ onClick={() => setShowBuilder((v) => !v)}
+ className="rounded-md border border-gray-800 bg-gray-900/40 px-3 py-1.5 text-xs font-medium text-gray-300 hover:border-blue-500/60"
+ >
+ {showBuilder ? 'Hide no-code builder' : 'No-code builder'}
+ </button>
+ </div>
+ {showBuilder && (
+ <SimpleRuleBuilder
+ onGenerate={(sigma) => {
+ setBody(sigma);
+ handleLanguageChange('sigma');
+ setShowBuilder(false);
+ toast.success(
+ 'Sigma generated — review, test, and propose it below',
+ );
+ }}
+ />
+ )}
+
{/* Editor */}
<div className="overflow-hidden rounded-lg border border-gray-800 bg-[#0d1117]">
<div className="flex items-center justify-between border-b border-gray-800 px-3 py-2 text-xs text-gray-500">
diff --git a/apps/web/src/components/detections/SimpleRuleBuilder.tsx b/apps/web/src/components/detections/SimpleRuleBuilder.tsx
new file mode 100644
index 000000000..908a29d7c
--- /dev/null
+++ b/apps/web/src/components/detections/SimpleRuleBuilder.tsx
@@ -0,0 +1,194 @@
+'use client';
+
+// Wave 3 (W3.3) — no-code / simple detection builder. A form (log source +
+// field/operator/value rows + optional threshold) that compiles to a valid
+// Sigma rule, for teams without detection engineers. The generated Sigma drops
+// straight into the code-first editor, where it can be tested, backtested, and
+// proposed through the same governed lifecycle.
+
+import { useState } from 'react';
+
+type Operator = 'equals' | 'contains' | 'startswith' | 'endswith';
+
+interface Condition {
+ field: string;
+ operator: Operator;
+ value: string;
+}
+
+const OPERATORS: { id: Operator; label: string }[] = [
+ { id: 'equals', label: 'equals' },
+ { id: 'contains', label: 'contains' },
+ { id: 'startswith', label: 'starts with' },
+ { id: 'endswith', label: 'ends with' },
+];
+
+function yamlEscape(value: string): string {
+ // Single-quote the scalar and escape embedded single quotes per YAML rules.
+ return `'${value.replace(/'/g, "''")}'`;
+}
+
+export function buildSigma(opts: {
+ title: string;
+ product: string;
+ category: string;
+ level: string;
+ conditions: Condition[];
+}): string {
+ const selectors = opts.conditions
+ .filter((c) => c.field.trim() && c.value.trim())
+ .map((c) => {
+ const key = c.operator === 'equals' ? c.field : `${c.field}|${c.operator}`;
+ return ` ${key}: ${yamlEscape(c.value)}`;
+ });
+ const logsource = [
+ 'logsource:',
+ opts.product ? ` product: ${opts.product}` : '',
+ opts.category ? ` category: ${opts.category}` : '',
+ ]
+ .filter(Boolean)
+ .join('\n');
+ return [
+ `title: ${opts.title || 'Untitled detection'}`,
+ 'status: experimental',
+ logsource,
+ 'detection:',
+ ' selection:',
+ selectors.length ? selectors.join('\n') : " EventID: ''",
+ ' condition: selection',
+ `level: ${opts.level}`,
+ '',
+ ].join('\n');
+}
+
+export function SimpleRuleBuilder({
+ onGenerate,
+}: {
+ onGenerate: (sigma: string) => void;
+}) {
+ const [title, setTitle] = useState('');
+ const [product, setProduct] = useState('windows');
+ const [category, setCategory] = useState('process_creation');
+ const [level, setLevel] = useState('medium');
+ const [conditions, setConditions] = useState<Condition[]>([
+ { field: 'CommandLine', operator: 'contains', value: '' },
+ ]);
+
+ const update = (i: number, patch: Partial<Condition>) =>
+ setConditions((prev) =>
+ prev.map((c, idx) => (idx === i ? { ...c, ...patch } : c)),
+ );
+
+ return (
+ <div className="space-y-3 rounded-lg border border-gray-800 bg-gray-900/40 p-4">
+ <div className="flex items-center justify-between">
+ <h3 className="text-sm font-medium text-gray-200">No-code builder</h3>
+ <button
+ type="button"
+ onClick={() =>
+ onGenerate(
+ buildSigma({ title, product, category, level, conditions }),
+ )
+ }
+ className="rounded-md bg-blue-600/80 px-3 py-1.5 text-xs font-medium text-white"
+ >
+ Generate Sigma
+ </button>
+ </div>
+
+ <div className="grid grid-cols-2 gap-2">
+ <input
+ value={title}
+ onChange={(e) => setTitle(e.target.value)}
+ placeholder="Rule title"
+ className="col-span-2 rounded-md border border-gray-800 bg-gray-950 px-2 py-1.5 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ />
+ <input
+ value={product}
+ onChange={(e) => setProduct(e.target.value)}
+ placeholder="log source product (e.g. windows)"
+ className="rounded-md border border-gray-800 bg-gray-950 px-2 py-1.5 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ />
+ <input
+ value={category}
+ onChange={(e) => setCategory(e.target.value)}
+ placeholder="category (e.g. process_creation)"
+ className="rounded-md border border-gray-800 bg-gray-950 px-2 py-1.5 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ />
+ </div>
+
+ <div className="space-y-2">
+ {conditions.map((c, i) => (
+ <div key={i} className="flex items-center gap-2">
+ <input
+ value={c.field}
+ onChange={(e) => update(i, { field: e.target.value })}
+ placeholder="field"
+ className="w-1/3 rounded-md border border-gray-800 bg-gray-950 px-2 py-1.5 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ />
+ <select
+ value={c.operator}
+ onChange={(e) =>
+ update(i, { operator: e.target.value as Operator })
+ }
+ className="rounded-md border border-gray-800 bg-gray-950 px-2 py-1.5 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ >
+ {OPERATORS.map((op) => (
+ <option key={op.id} value={op.id}>
+ {op.label}
+ </option>
+ ))}
+ </select>
+ <input
+ value={c.value}
+ onChange={(e) => update(i, { value: e.target.value })}
+ placeholder="value"
+ className="flex-1 rounded-md border border-gray-800 bg-gray-950 px-2 py-1.5 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ />
+ {conditions.length > 1 && (
+ <button
+ type="button"
+ onClick={() =>
+ setConditions((prev) => prev.filter((_, idx) => idx !== i))
+ }
+ className="rounded-md border border-gray-800 px-2 py-1.5 text-xs text-gray-400 hover:text-red-400"
+ aria-label="Remove condition"
+ >
+ ×
+ </button>
+ )}
+ </div>
+ ))}
+ <div className="flex items-center gap-2">
+ <button
+ type="button"
+ onClick={() =>
+ setConditions((prev) => [
+ ...prev,
+ { field: '', operator: 'contains', value: '' },
+ ])
+ }
+ className="rounded-md border border-gray-800 px-2 py-1 text-xs text-gray-300 hover:border-blue-500/60"
+ >
+ + Add condition
+ </button>
+ <select
+ value={level}
+ onChange={(e) => setLevel(e.target.value)}
+ className="ml-auto rounded-md border border-gray-800 bg-gray-950 px-2 py-1 text-xs text-gray-200 outline-none focus:border-blue-500/60"
+ >
+ {['info', 'low', 'medium', 'high', 'critical'].map((l) => (
+ <option key={l} value={l}>
+ {l}
+ </option>
+ ))}
+ </select>
+ </div>
+ </div>
+ <p className="text-[11px] text-gray-600">
+ Generates a Sigma rule (all conditions ANDed) into the editor — then
+ test, backtest, and propose it through the governed lifecycle.
+ </p>
+ </div>
+ );
+}
diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.md
index e6d2691a9..6a67bb4ad 100644
--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md
+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md
@@ -53,10 +53,13 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`
| Scheduled hunt findings flow into governed detection proposals | README (proactive hunting → detections) | `ci.yml` api job (`test_wave1_loop_edges.py` — a scheduled hunt that returns hits opens a DRAFT `DetectionRuleProposal` (source `hunt-finding`) into the propose→review→eval-gate→promote lifecycle; zero-hit / flag-off paths open nothing) | GATED | - |
| Analyst disposition history drives human-approval-gated tuning proposals | README (self-improving detections) | `ci.yml` api job (`test_wave1_loop_edges.py` — the previously-orphaned `suggest_tuning` engine is wired to real per-rule disposition history via `/detection/tuning/auto-suggest`, opening DRAFT proposals; `test_detection_tuner.py` fixture-gates the engine) | PARTIAL (mapping + wiring gated; end-to-end proposal insert exercised in api integration, not a unit DB) | Phase 2 |
| Detections can be backtested over historical lake data before promotion | README (detection engineering) | `ci.yml` api job (`test_backtest.py` — bounded/allow-listed SQL construction with injection-sanitised source filter, lake-row→event mapping with JSON payload expansion, exact would-fire count + hit-rate + samples; `test_backtest_gate.py` — opt-in `AISOC_BACKTEST_MAX_HIT_RATE` /decide gate) + web type-check (rule-editor backtest panel) | PARTIAL (pure backtest logic + gate gated; the live tenant-scoped ClickHouse fetch is exercised by the integration gate, not a unit) | Phase 2 |
+| Detections can be authored in Python (`def rule(event)`) with a fixture gate | README (detection engineering) | `python-detections.yml` (`aisoc_detections.runner` fails a blind rule that misses a positive or a noisy one that fires on a negative; every bundled detection must ship ≥1 positive + ≥1 negative case) + `test_framework.py` (fail-closed evaluate, metadata validation) | GATED | - |
+| AI Detection Builder: NL → rule + AUTO-generated fixtures → non-circular eval-gate → governed proposal | README (detection engineering) | `ci.yml` api job (`test_ai_detection_builder.py` — fixtures are DERIVED from the generated rule's own selection, not invented, and genuinely pass the non-circular gate: fires on the positive, quiet on the negative) | GATED | - |
+| No-code / simple detection builder compiles to a valid rule | README (detection engineering) | `ci.yml` web type-check + lint (`SimpleRuleBuilder.tsx` `buildSigma` compiles field/operator/value rows to Sigma, dropped into the governed editor) | GATED | - |
## Summary
-- GATED: 36
+- GATED: 39
- PARTIAL: 9
- NO GATE: 0 (**every claim is now backed by a failing test.** The last NO GATE — the weekly benchmark scoreboard running live against `main` — closed in Phase E1: `scripts/check_scoreboard.py` ties the published scoreboard to a deterministic per-PR live-agent MITRE-accuracy run, while the funded weekly `wet-eval.yml` appends the LLM-tier rows. The full Fully-Operational roadmap (Phases A1–E1) is complete. The 7 remaining PARTIAL rows are honest, named deferrals to future phases outside the A–E scope — each states the specific gap and the phase that closes it — not unproven claims.)
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index b6e35ad7c..72b9c90b7 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -9665,6 +9665,48 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
+ /api/v1/nl-detection/propose:
+ post:
+ tags:
+ - nl_detection
+ summary: Propose From Nl
+ description: 'AI Detection Builder (W3.2): NL threat description -> Sigma rule
+ +
+
+ AUTO-GENERATED positive/negative fixtures -> non-circular eval-gate ->
+
+ governed DRAFT proposal.
+
+
+ Fixtures are DERIVED from the generated rule''s own selection (not invented
+
+ by the LLM), so the gate genuinely proves the rule fires on a positive and
+
+ stays quiet on a negative. If the rule can''t be auto-verified, no proposal
+
+ is opened and the human is asked to supply fixtures — the honest outcome.'
+ operationId: propose_from_nl_api_v1_nl_detection_propose_post
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/NLProposeRequest'
+ required: true
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/NLProposeResponse'
+ '422':
+ description: Validation Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/HTTPValidationError'
+ security:
+ - HTTPBearer: []
/api/v1/detection-loop/suggest:
post:
tags:
@@ -21075,6 +21117,69 @@ components:
- description
- model_used
title: NLDetectionResponse
+ NLProposeRequest:
+ properties:
+ description:
+ type: string
+ maxLength: 2000
+ minLength: 10
+ title: Description
+ severity:
+ type: string
+ enum:
+ - informational
+ - low
+ - medium
+ - high
+ - critical
+ title: Severity
+ default: medium
+ mitre_techniques:
+ items:
+ type: string
+ type: array
+ title: Mitre Techniques
+ type: object
+ required:
+ - description
+ title: NLProposeRequest
+ NLProposeResponse:
+ properties:
+ proposal_id:
+ anyOf:
+ - type: string
+ format: uuid
+ - type: 'null'
+ title: Proposal Id
+ status:
+ type: string
+ title: Status
+ passed:
+ type: boolean
+ title: Passed
+ reason:
+ type: string
+ title: Reason
+ sigma:
+ type: string
+ title: Sigma
+ fixtures:
+ additionalProperties: true
+ type: object
+ title: Fixtures
+ model_used:
+ type: string
+ title: Model Used
+ type: object
+ required:
+ - proposal_id
+ - status
+ - passed
+ - reason
+ - sigma
+ - fixtures
+ - model_used
+ title: NLProposeResponse
NLQueryExecuteRequest:
properties:
question:
diff --git a/packages/aisoc-detections/README.md b/packages/aisoc-detections/README.md
new file mode 100644
index 000000000..41526f220
--- /dev/null
+++ b/packages/aisoc-detections/README.md
@@ -0,0 +1,47 @@
+# aisoc-detections — Python detection framework
+
+Write detections as Python, unit-tested against their own fixtures. Complements
+the YAML/Sigma corpus in [`detections/`](../../detections/) — use Python when a
+detection needs real logic (thresholds, correlation, stateful decisions) that is
+awkward in a declarative DSL.
+
+## A detection
+
+A detection is a `.py` module with a `rule(event) -> bool` and metadata:
+
+```python
+ID = "py-okta-mfa-fatigue"
+TITLE = "Okta MFA fatigue (push bombing)"
+SEVERITY = "high" # info | low | medium | high | critical
+MITRE = ["T1621"]
+DESCRIPTION = "Many MFA push challenges to one user in a short window."
+
+def rule(event: dict) -> bool:
+ return event.get("eventType") == "user.mfa.attempt" and event.get("attempts", 0) >= 5
+
+# Optional: def title(event) -> str, def dedup(event) -> str
+
+TESTS = [
+ {"name": "fires on 6 attempts", "event": {"eventType": "user.mfa.attempt", "attempts": 6}, "expect": True},
+ {"name": "quiet on 1 attempt", "event": {"eventType": "user.mfa.attempt", "attempts": 1}, "expect": False},
+]
+```
+
+Every detection **must** ship at least one positive and one negative `TESTS`
+case — the harness fails a blind rule (misses a positive) or a noisy one (fires
+on a negative), the same non-circular guarantee the YAML corpus gets.
+
+## Running the fixture gate
+
+```bash
+# from packages/aisoc-detections/
+python -m aisoc_detections.runner detections # aka `aisoc-detections`
+PYTHONPATH=. python -m pytest tests/
+```
+
+CI runs this on every PR ([`.github/workflows/python-detections.yml`](../../.github/workflows/python-detections.yml)).
+
+## Safety
+
+Rules are first-party and reviewed via PR. `evaluate()` is fail-closed: a rule
+that raises returns `False` (never fires, never crashes the batch).
diff --git a/packages/aisoc-detections/aisoc_detections/__init__.py b/packages/aisoc-detections/aisoc_detections/__init__.py
new file mode 100644
index 000000000..709328f53
--- /dev/null
+++ b/packages/aisoc-detections/aisoc_detections/__init__.py
@@ -0,0 +1,50 @@
+"""AiSOC Python detection framework (Wave 3, W3.1).
+
+Detection engineers write detections as Python — a module with a ``rule(event)``
+function plus metadata and inline test cases — complementing the YAML/Sigma
+corpus. Detections are unit-tested against their own positive/negative fixtures
+and gated in CI.
+
+A detection module looks like::
+
+ ID = "py-okta-mfa-bombing"
+ TITLE = "Okta MFA fatigue (push bombing)"
+ SEVERITY = "high" # info | low | medium | high | critical
+ MITRE = ["T1621"]
+ DESCRIPTION = "Many MFA push challenges to one user in a short window."
+
+ def rule(event: dict) -> bool:
+ return event.get("eventType") == "user.mfa.attempt" and event.get("attempts", 0) >= 5
+
+ # Optional overrides:
+ def title(event: dict) -> str: ... # dynamic title
+ def dedup(event: dict) -> str: ... # dedup key
+
+ TESTS = [
+ {"name": "fires on 5 attempts", "event": {"eventType": "user.mfa.attempt", "attempts": 6}, "expect": True},
+ {"name": "quiet on 1 attempt", "event": {"eventType": "user.mfa.attempt", "attempts": 1}, "expect": False},
+ ]
+"""
+
+from __future__ import annotations
+
+from .base import (
+ Detection,
+ DetectionError,
+ evaluate,
+ load_detection,
+ load_detections,
+)
+from .runner import FixtureFailure, TestReport, run_fixtures, run_suite
+
+__all__ = [
+ "Detection",
+ "DetectionError",
+ "FixtureFailure",
+ "TestReport",
+ "evaluate",
+ "load_detection",
+ "load_detections",
+ "run_fixtures",
+ "run_suite",
+]
diff --git a/packages/aisoc-detections/aisoc_detections/base.py b/packages/aisoc-detections/aisoc_detections/base.py
new file mode 100644
index 000000000..21486d54a
--- /dev/null
+++ b/packages/aisoc-detections/aisoc_detections/base.py
@@ -0,0 +1,105 @@
+"""Load + evaluate Python detection modules."""
+
+from __future__ import annotations
+
+import importlib.util
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+_VALID_SEVERITIES = frozenset({"info", "low", "medium", "high", "critical"})
+
+
+class DetectionError(Exception):
+ """A detection module is malformed (missing rule(), bad metadata, ...)."""
+
+
+@dataclass(frozen=True)
+class Detection:
+ """A loaded, validated Python detection."""
+
+ id: str
+ title: str
+ severity: str
+ description: str
+ mitre: list[str]
+ rule: Callable[[dict[str, Any]], bool]
+ tests: list[dict[str, Any]] = field(default_factory=list)
+ _title_fn: Callable[[dict[str, Any]], str] | None = None
+ _dedup_fn: Callable[[dict[str, Any]], str] | None = None
+ source_path: str | None = None
+
+ def title_for(self, event: dict[str, Any]) -> str:
+ if self._title_fn is not None:
+ return str(self._title_fn(event))
+ return self.title
+
+ def dedup_for(self, event: dict[str, Any]) -> str | None:
+ if self._dedup_fn is not None:
+ return str(self._dedup_fn(event))
+ return None
+
+
+def evaluate(detection: Detection, event: dict[str, Any]) -> bool:
+ """Run a detection's rule against one event. Fail-closed (a raising rule
+ returns False rather than firing) so a buggy rule can't storm the queue."""
+ try:
+ return bool(detection.rule(event))
+ except Exception: # noqa: BLE001 — a broken rule must not fire or crash the batch
+ return False
+
+
+def _require(module: Any, name: str, path: Path) -> Any:
+ value = getattr(module, name, None)
+ if value is None:
+ raise DetectionError(f"{path.name}: detection is missing required '{name}'")
+ return value
+
+
+def load_detection(path: str | Path) -> Detection:
+ """Import + validate one detection module from a .py file."""
+ path = Path(path)
+ spec = importlib.util.spec_from_file_location(f"aisoc_detection_{path.stem}", path)
+ if spec is None or spec.loader is None:
+ raise DetectionError(f"{path}: cannot import module")
+ module = importlib.util.module_from_spec(spec)
+ try:
+ spec.loader.exec_module(module)
+ except Exception as exc: # noqa: BLE001
+ raise DetectionError(f"{path.name}: import failed: {exc}") from exc
+
+ rule = _require(module, "rule", path)
+ if not callable(rule):
+ raise DetectionError(f"{path.name}: 'rule' must be callable")
+ severity = str(getattr(module, "SEVERITY", "medium")).lower()
+ if severity not in _VALID_SEVERITIES:
+ raise DetectionError(f"{path.name}: SEVERITY '{severity}' not in {sorted(_VALID_SEVERITIES)}")
+
+ tests = getattr(module, "TESTS", [])
+ if not isinstance(tests, list):
+ raise DetectionError(f"{path.name}: TESTS must be a list")
+
+ return Detection(
+ id=str(_require(module, "ID", path)),
+ title=str(getattr(module, "TITLE", path.stem)),
+ severity=severity,
+ description=str(getattr(module, "DESCRIPTION", "")),
+ mitre=list(getattr(module, "MITRE", []) or []),
+ rule=rule,
+ tests=tests,
+ _title_fn=getattr(module, "title", None) if callable(getattr(module, "title", None)) else None,
+ _dedup_fn=getattr(module, "dedup", None) if callable(getattr(module, "dedup", None)) else None,
+ source_path=str(path),
+ )
+
+
+def load_detections(directory: str | Path) -> list[Detection]:
+ """Load every ``*.py`` detection in ``directory`` (non-recursive, skips
+ ``_``-prefixed files). Raises on the first malformed module."""
+ directory = Path(directory)
+ detections: list[Detection] = []
+ for path in sorted(directory.glob("*.py")):
+ if path.name.startswith("_"):
+ continue
+ detections.append(load_detection(path))
+ return detections
diff --git a/packages/aisoc-detections/aisoc_detections/runner.py b/packages/aisoc-detections/aisoc_detections/runner.py
new file mode 100644
index 000000000..1131613d3
--- /dev/null
+++ b/packages/aisoc-detections/aisoc_detections/runner.py
@@ -0,0 +1,79 @@
+"""Fixture test harness + CLI for Python detections.
+
+Every detection must ship inline ``TESTS`` (positive + negative cases). The
+harness runs each case through the real ``rule`` and fails the detection if it
+misses a positive (blind) or fires on a negative (noisy) — the same
+non-circular guarantee the YAML corpus gets from its fixture replay.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .base import Detection, evaluate, load_detections
+
+
+@dataclass(frozen=True)
+class FixtureFailure:
+ detection_id: str
+ case_name: str
+ expected: bool
+ actual: bool
+
+
+@dataclass
+class TestReport:
+ detections: int = 0
+ cases: int = 0
+ failures: list[FixtureFailure] = field(default_factory=list)
+
+ @property
+ def passed(self) -> bool:
+ return not self.failures
+
+
+def run_fixtures(detection: Detection) -> list[FixtureFailure]:
+ """Run one detection's inline TESTS; return the failures (empty == pass)."""
+ failures: list[FixtureFailure] = []
+ if not detection.tests:
+ # A detection with no tests can't be trusted — treat as a failure.
+ failures.append(FixtureFailure(detection.id, "<no TESTS declared>", True, False))
+ return failures
+ has_pos = any(bool(c.get("expect")) for c in detection.tests)
+ has_neg = any(not bool(c.get("expect")) for c in detection.tests)
+ if not (has_pos and has_neg):
+ failures.append(FixtureFailure(detection.id, "<needs >=1 positive AND >=1 negative case>", True, False))
+ for case in detection.tests:
+ expected = bool(case.get("expect"))
+ actual = evaluate(detection, dict(case.get("event") or {}))
+ if actual != expected:
+ failures.append(FixtureFailure(detection.id, str(case.get("name", "unnamed")), expected, actual))
+ return failures
+
+
+def run_suite(directory: str | Path) -> TestReport:
+ """Load every detection in ``directory`` and run its fixtures."""
+ report = TestReport()
+ for detection in load_detections(directory):
+ report.detections += 1
+ report.cases += len(detection.tests)
+ report.failures.extend(run_fixtures(detection))
+ return report
+
+
+def main(argv: list[str] | None = None) -> int:
+ """CLI: ``python -m aisoc_detections.runner <dir>`` (aka ``aisoc-detections test``)."""
+ argv = argv if argv is not None else sys.argv[1:]
+ directory = argv[0] if argv else str(Path(__file__).resolve().parent.parent / "detections")
+ report = run_suite(directory)
+ for fail in report.failures:
+ print(f"FAIL {fail.detection_id}: {fail.case_name} (expected {fail.expected}, got {fail.actual})", file=sys.stderr)
+ status = "OK" if report.passed else "FAILED"
+ print(f"{status}: {report.detections} detections, {report.cases} cases, {len(report.failures)} failures")
+ return 0 if report.passed else 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/packages/aisoc-detections/detections/aws_root_console_login.py b/packages/aisoc-detections/detections/aws_root_console_login.py
new file mode 100644
index 000000000..a3d0e7194
--- /dev/null
+++ b/packages/aisoc-detections/detections/aws_root_console_login.py
@@ -0,0 +1,47 @@
+"""AWS root account console login detection (Python)."""
+
+ID = "py-aws-root-console-login"
+TITLE = "AWS root account console login"
+SEVERITY = "critical"
+MITRE = ["T1078.004"]
+DESCRIPTION = "The AWS account root user signed in to the console. Root should be locked away behind hardware MFA and never used for day-to-day work; an interactive root login warrants immediate review."
+
+
+def rule(event: dict) -> bool:
+ if event.get("eventName") != "ConsoleLogin" or event.get("eventSource") != "signin.amazonaws.com":
+ return False
+ identity = event.get("userIdentity", {})
+ return identity.get("type") == "Root"
+
+
+def title(event: dict) -> str:
+ ip = event.get("sourceIPAddress", "unknown IP")
+ return f"AWS root console login from {ip}"
+
+
+TESTS = [
+ {
+ "name": "fires on root console login",
+ "event": {
+ "eventName": "ConsoleLogin",
+ "eventSource": "signin.amazonaws.com",
+ "userIdentity": {"type": "Root"},
+ "sourceIPAddress": "203.0.113.9",
+ },
+ "expect": True,
+ },
+ {
+ "name": "quiet on an IAM user console login",
+ "event": {
+ "eventName": "ConsoleLogin",
+ "eventSource": "signin.amazonaws.com",
+ "userIdentity": {"type": "IAMUser"},
+ },
+ "expect": False,
+ },
+ {
+ "name": "quiet on a non-login API call",
+ "event": {"eventName": "DescribeInstances", "eventSource": "ec2.amazonaws.com", "userIdentity": {"type": "Root"}},
+ "expect": False,
+ },
+]
diff --git a/packages/aisoc-detections/detections/okta_mfa_fatigue.py b/packages/aisoc-detections/detections/okta_mfa_fatigue.py
new file mode 100644
index 000000000..f079a335f
--- /dev/null
+++ b/packages/aisoc-detections/detections/okta_mfa_fatigue.py
@@ -0,0 +1,45 @@
+"""Okta MFA fatigue / push-bombing detection (Python)."""
+
+ID = "py-okta-mfa-fatigue"
+TITLE = "Okta MFA fatigue (push bombing)"
+SEVERITY = "high"
+MITRE = ["T1621"]
+DESCRIPTION = "An unusually high number of MFA push challenges to a single user in a short window — a hallmark of push-bombing to wear the user down into approving."
+
+_THRESHOLD = 5
+
+
+def rule(event: dict) -> bool:
+ return (
+ event.get("eventType") == "user.mfa.attempt"
+ and str(event.get("outcome", "")).lower() in {"challenge", "sent"}
+ and int(event.get("attempts", 0)) >= _THRESHOLD
+ )
+
+
+def title(event: dict) -> str:
+ user = event.get("actor", {}).get("alternateId") or event.get("user") or "unknown user"
+ return f"MFA fatigue: {event.get('attempts', '?')} push challenges to {user}"
+
+
+def dedup(event: dict) -> str:
+ return f"mfa-fatigue:{event.get('actor', {}).get('alternateId') or event.get('user')}"
+
+
+TESTS = [
+ {
+ "name": "fires on 6 push challenges",
+ "event": {"eventType": "user.mfa.attempt", "outcome": "challenge", "attempts": 6, "user": "[email protected]"},
+ "expect": True,
+ },
+ {
+ "name": "quiet on a single legitimate challenge",
+ "event": {"eventType": "user.mfa.attempt", "outcome": "challenge", "attempts": 1, "user": "[email protected]"},
+ "expect": False,
+ },
+ {
+ "name": "quiet on an unrelated event type",
+ "event": {"eventType": "user.session.start", "attempts": 9},
+ "expect": False,
+ },
+]
diff --git a/packages/aisoc-detections/pyproject.toml b/packages/aisoc-detections/pyproject.toml
new file mode 100644
index 000000000..309b4b439
--- /dev/null
+++ b/packages/aisoc-detections/pyproject.toml
@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aisoc-detections"
+version = "0.1.0"
+description = "AiSOC Python detection framework — write detections as def rule(event), unit-tested against inline fixtures"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+ { name = "Beenu Arora", email = "[email protected]" },
+]
+keywords = ["aisoc", "soc", "security", "detection", "detection-as-code"]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: MIT License",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Topic :: Security",
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+aisoc-detections = "aisoc_detections.runner:main"
+
+[project.optional-dependencies]
+dev = [
+ "pytest>=8.0",
+ "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/beenuar/AiSOC"
+Repository = "https://github.com/beenuar/AiSOC"
+
+[tool.hatch.build.targets.wheel]
+packages = ["aisoc_detections"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+ "aisoc_detections",
+ "detections",
+ "tests",
+ "README.md",
+ "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 140
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
diff --git a/packages/aisoc-detections/tests/test_framework.py b/packages/aisoc-detections/tests/test_framework.py
new file mode 100644
index 000000000..4cd3f9002
--- /dev/null
+++ b/packages/aisoc-detections/tests/test_framework.py
@@ -0,0 +1,86 @@
+"""Tests for the Python detection framework + the bundled example detections."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from aisoc_detections import (
+ Detection,
+ DetectionError,
+ evaluate,
+ load_detection,
+ load_detections,
+ run_fixtures,
+ run_suite,
+)
+
+_ROOT = Path(__file__).resolve().parent.parent
+_DETECTIONS = _ROOT / "detections"
+
+
+def test_bundled_detections_all_pass_their_fixtures():
+ report = run_suite(_DETECTIONS)
+ assert report.detections >= 2
+ assert report.cases >= 4
+ assert report.passed, [f"{f.detection_id}:{f.case_name}" for f in report.failures]
+
+
+def test_load_detections_validates_metadata():
+ detections = load_detections(_DETECTIONS)
+ ids = {d.id for d in detections}
+ assert "py-okta-mfa-fatigue" in ids
+ okta = next(d for d in detections if d.id == "py-okta-mfa-fatigue")
+ assert okta.severity == "high"
+ assert "T1621" in okta.mitre
+ # dynamic title + dedup overrides are wired
+ event = {"eventType": "user.mfa.attempt", "outcome": "challenge", "attempts": 6, "user": "[email protected]"}
+ assert "[email protected]" in okta.title_for(event)
+ assert okta.dedup_for(event)
+
+
+def test_evaluate_is_fail_closed(tmp_path):
+ boom = tmp_path / "boom.py"
+ boom.write_text(
+ "ID='py-boom'\nSEVERITY='low'\n"
+ "def rule(event):\n raise RuntimeError('kaboom')\n"
+ "TESTS=[{'name':'p','event':{},'expect':True},{'name':'n','event':{},'expect':False}]\n"
+ )
+ det = load_detection(boom)
+ # A raising rule never fires (and never crashes the batch).
+ assert evaluate(det, {}) is False
+
+
+def test_missing_rule_raises(tmp_path):
+ bad = tmp_path / "norule.py"
+ bad.write_text("ID='x'\nSEVERITY='low'\n")
+ with pytest.raises(DetectionError):
+ load_detection(bad)
+
+
+def test_bad_severity_raises(tmp_path):
+ bad = tmp_path / "badsev.py"
+ bad.write_text("ID='x'\nSEVERITY='spicy'\ndef rule(e):\n return True\n")
+ with pytest.raises(DetectionError):
+ load_detection(bad)
+
+
+def test_detection_without_positive_and_negative_case_fails():
+ det = Detection(
+ id="py-onlypos",
+ title="t",
+ severity="low",
+ description="",
+ mitre=[],
+ rule=lambda e: True,
+ tests=[{"name": "p", "event": {}, "expect": True}], # no negative case
+ )
+ failures = run_fixtures(det)
+ assert failures # flagged: needs a negative case too
+
+
+def test_detection_with_no_tests_fails():
+ det = Detection(id="py-notests", title="t", severity="low", description="", mitre=[], rule=lambda e: True, tests=[])
+ failures = run_fixtures(det)
+ assert failures
diff --git a/services/api/app/api/v1/endpoints/detection_loop.py b/services/api/app/api/v1/endpoints/detection_loop.py
index ddd2efba7..07c581ec8 100644
--- a/services/api/app/api/v1/endpoints/detection_loop.py
+++ b/services/api/app/api/v1/endpoints/detection_loop.py
@@ -231,7 +231,7 @@ async def suggest_fp_fix(
await db.execute(
text(
"""
- INSERT INTO aisoc_detection_rule_proposals
+ INSERT INTO detection_rule_proposals
(id, tenant_id, base_rule_id, name, description,
rule_language, rule_body, category, severity, confidence,
status, source, created_at, updated_at)
diff --git a/services/api/app/api/v1/endpoints/nl_detection.py b/services/api/app/api/v1/endpoints/nl_detection.py
index 995b50cf3..0e240c897 100644
--- a/services/api/app/api/v1/endpoints/nl_detection.py
+++ b/services/api/app/api/v1/endpoints/nl_detection.py
@@ -14,18 +14,26 @@ functional in all deployment environments.
from __future__ import annotations
import os
-from typing import Literal
+import uuid
+from datetime import UTC, datetime
+from typing import Annotated, Any, Literal
import structlog
-from fastapi import APIRouter, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel, Field
+from app.api.v1.deps import AuthUser, DBSession, require_permission
from app.core.airgap import AirgapViolation, enforce_airgap_for_url
+from app.models.detection_proposal import DetectionRuleProposal
+from app.services.detection_eval import evaluate_candidate_rule
+from app.services.fixture_synth import derive_fixtures_from_sigma
logger = structlog.get_logger()
router = APIRouter(prefix="/nl-detection", tags=["nl_detection"])
+_SEVERITY_MAP = {"informational": "info", "info": "info", "low": "low", "medium": "medium", "high": "high", "critical": "critical"}
+
# ---------------------------------------------------------------------------
# Request / response models
@@ -212,3 +220,99 @@ async def translate_detection(payload: NLDetectionRequest) -> NLDetectionRespons
esql=rules.get("esql"),
model_used=model_used,
)
+
+
+class NLProposeRequest(BaseModel):
+ description: str = Field(..., min_length=10, max_length=2000)
+ severity: Literal["informational", "low", "medium", "high", "critical"] = "medium"
+ mitre_techniques: list[str] = Field(default_factory=list)
+
+
+class NLProposeResponse(BaseModel):
+ proposal_id: uuid.UUID | None
+ status: str
+ passed: bool
+ reason: str
+ sigma: str
+ fixtures: dict[str, Any]
+ model_used: str
+
+
[email protected]("/propose", response_model=NLProposeResponse)
+async def propose_from_nl(
+ payload: NLProposeRequest,
+ current_user: Annotated[AuthUser, Depends(require_permission("rules:write"))],
+ db: DBSession,
+) -> NLProposeResponse:
+ """AI Detection Builder (W3.2): NL threat description -> Sigma rule +
+ AUTO-GENERATED positive/negative fixtures -> non-circular eval-gate ->
+ governed DRAFT proposal.
+
+ Fixtures are DERIVED from the generated rule's own selection (not invented
+ by the LLM), so the gate genuinely proves the rule fires on a positive and
+ stays quiet on a negative. If the rule can't be auto-verified, no proposal
+ is opened and the human is asked to supply fixtures — the honest outcome."""
+ translate_req = NLDetectionRequest(
+ description=payload.description,
+ target_platforms=["sigma"],
+ severity=payload.severity,
+ mitre_techniques=payload.mitre_techniques,
+ )
+ rules = await _llm_translate(translate_req)
+ model_used = rules.pop("_model", "unknown")
+ sigma = rules.get("sigma") or ""
+ if not sigma.strip():
+ raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="could not generate a Sigma rule")
+
+ derived = derive_fixtures_from_sigma(sigma)
+ if derived is None:
+ return NLProposeResponse(
+ proposal_id=None,
+ status="needs_fixtures",
+ passed=False,
+ reason=(
+ "Could not auto-derive fixtures from the generated rule; supply "
+ "positive/negative fixtures via /detection-proposals/{id}/evaluate-rule."
+ ),
+ sigma=sigma,
+ fixtures={"positive": [], "negative": []},
+ model_used=model_used,
+ )
+ positive, negative = derived
+ result = evaluate_candidate_rule(rule_language="sigma", rule_body=sigma, positive_fixtures=positive, negative_fixtures=negative)
+
+ proposal = DetectionRuleProposal(
+ tenant_id=current_user.tenant_id,
+ name=f"AI: {payload.description[:60].strip()}",
+ description=payload.description,
+ rule_language="sigma",
+ rule_body=sigma,
+ category="ai-generated",
+ severity=_SEVERITY_MAP.get(payload.severity, "medium"),
+ confidence=60,
+ mitre_techniques=payload.mitre_techniques,
+ status="eval_passed" if result.passed else "draft",
+ eval_result={
+ "candidate_rule": {
+ **result.to_dict(),
+ "auto_generated_fixtures": True,
+ "fixtures": {"positive": positive, "negative": negative},
+ "ran_at": datetime.now(UTC).isoformat(),
+ }
+ },
+ proposed_by_id=current_user.user_id,
+ )
+ db.add(proposal)
+ await db.commit()
+ await db.refresh(proposal)
+
+ logger.info("nl_detection.proposed", proposal_id=str(proposal.id), passed=result.passed, model=model_used)
+ return NLProposeResponse(
+ proposal_id=proposal.id,
+ status=proposal.status,
+ passed=result.passed,
+ reason=result.to_dict().get("reason", ""),
+ sigma=sigma,
+ fixtures={"positive": positive, "negative": negative},
+ model_used=model_used,
+ )
diff --git a/services/api/app/api/v1/endpoints/rule_tuning.py b/services/api/app/api/v1/endpoints/rule_tuning.py
index 51c1c1411..a0375aac3 100644
--- a/services/api/app/api/v1/endpoints/rule_tuning.py
+++ b/services/api/app/api/v1/endpoints/rule_tuning.py
@@ -123,7 +123,7 @@ async def auto_suggest_tuning(
await db.execute(
text(
"""
- INSERT INTO aisoc_detection_rule_proposals
+ INSERT INTO detection_rule_proposals
(id, tenant_id, base_rule_id, name, description,
rule_language, rule_body, category, severity, confidence,
status, source, created_at, updated_at)
diff --git a/services/api/app/services/fixture_synth.py b/services/api/app/services/fixture_synth.py
new file mode 100644
index 000000000..9852df559
--- /dev/null
+++ b/services/api/app/services/fixture_synth.py
@@ -0,0 +1,79 @@
+"""Deterministically synthesise positive/negative fixtures from a Sigma rule.
+
+The AI Detection Builder (Wave 3, W3.2) needs test fixtures so the non-circular
+eval-gate can prove a generated rule fires on a positive and stays quiet on a
+negative. Rather than trust an LLM to invent fixtures (which could be gamed to
+pass), we DERIVE them from the rule's own ``detection.selection`` — a positive
+event that satisfies every selector, and a negative that breaks one. The gate
+then confirms the rule actually behaves as written.
+
+Supports the common Sigma selection shapes (``field: value``,
+``field|contains|startswith|endswith: value``, list values). Complex rules
+(multiple selections, ``not`` conditions) may not yield a passing fixture — in
+that case the eval-gate fails and the builder asks the human for fixtures,
+which is the honest outcome.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+_SENTINEL = "aisoc-nonmatching-sentinel-0xdeadbeef"
+
+
+def _matching_value(modifier: str, value: str) -> str:
+ value = str(value)
+ if modifier == "contains":
+ return f"pre-{value}-post"
+ if modifier == "startswith":
+ return f"{value}-post"
+ if modifier == "endswith":
+ return f"pre-{value}"
+ # equals / re / unknown → use the literal (best effort)
+ return value
+
+
+def _first_selection(detection: dict[str, Any]) -> dict[str, Any] | None:
+ for key, val in detection.items():
+ if key == "condition":
+ continue
+ if isinstance(val, dict):
+ return val
+ return None
+
+
+def derive_fixtures_from_sigma(sigma_yaml: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]]] | None:
+ """Return ``([positive_event], [negative_event])`` or ``None`` if the rule's
+ selection can't be turned into fixtures."""
+ try:
+ doc = yaml.safe_load(sigma_yaml)
+ except yaml.YAMLError:
+ return None
+ if not isinstance(doc, dict):
+ return None
+ detection = doc.get("detection")
+ if not isinstance(detection, dict):
+ return None
+ selection = _first_selection(detection)
+ if not selection:
+ return None
+
+ positive: dict[str, Any] = {}
+ for raw_key, raw_value in selection.items():
+ parts = str(raw_key).split("|")
+ field = parts[0]
+ modifier = parts[1] if len(parts) > 1 else "equals"
+ value = raw_value[0] if isinstance(raw_value, list) and raw_value else raw_value
+ if isinstance(value, dict | list):
+ continue # nested/keyless selectors — skip (can't synthesise cleanly)
+ positive[field] = _matching_value(modifier, str(value))
+
+ if not positive:
+ return None
+
+ negative = dict(positive)
+ first_field = next(iter(positive))
+ negative[first_field] = _SENTINEL
+ return [positive], [negative]
diff --git a/services/api/app/workers/hunt_scheduler.py b/services/api/app/workers/hunt_scheduler.py
index 020249280..91f8650ce 100644
--- a/services/api/app/workers/hunt_scheduler.py
+++ b/services/api/app/workers/hunt_scheduler.py
@@ -259,7 +259,7 @@ async def _propose_detection_from_hunt(db: AsyncSession, hunt: SavedHunt, hit_co
await db.execute(
text(
"""
- INSERT INTO aisoc_detection_rule_proposals
+ INSERT INTO detection_rule_proposals
(id, tenant_id, base_rule_id, name, description,
rule_language, rule_body, category, severity, confidence,
status, source, created_at, updated_at)
diff --git a/services/api/tests/test_ai_detection_builder.py b/services/api/tests/test_ai_detection_builder.py
new file mode 100644
index 000000000..b8afd2eda
--- /dev/null
+++ b/services/api/tests/test_ai_detection_builder.py
@@ -0,0 +1,68 @@
+"""Wave 3 (W3.2) - AI Detection Builder: auto-derived fixtures + eval gate.
+
+The endpoint needs a DB (proposal insert) and is covered in api integration.
+These pin the pure, deterministic core: fixtures are DERIVED from the rule's own
+selection (not invented), and those fixtures genuinely pass the non-circular
+eval gate — proving the generated rule fires on a positive and stays quiet on a
+negative.
+"""
+
+from __future__ import annotations
+
+from app.services.detection_eval import evaluate_candidate_rule
+from app.services.fixture_synth import derive_fixtures_from_sigma
+
+_SIGMA_CONTAINS = """
+title: Credential dumping via mimikatz
+logsource:
+ product: windows
+ category: process_creation
+detection:
+ selection:
+ CommandLine|contains: 'mimikatz'
+ condition: selection
+level: high
+"""
+
+_SIGMA_MULTI = """
+title: Encoded PowerShell
+logsource:
+ product: windows
+detection:
+ selection:
+ Image|endswith: '\\\\powershell.exe'
+ CommandLine|contains: '-EncodedCommand'
+ condition: selection
+level: medium
+"""
+
+
+def test_derive_positive_matches_negative_breaks():
+ derived = derive_fixtures_from_sigma(_SIGMA_CONTAINS)
+ assert derived is not None
+ pos, neg = derived
+ assert "mimikatz" in pos[0]["CommandLine"]
+ assert "mimikatz" not in neg[0]["CommandLine"]
+
+
+def test_derived_fixtures_pass_the_non_circular_gate():
+ derived = derive_fixtures_from_sigma(_SIGMA_CONTAINS)
+ assert derived is not None
+ pos, neg = derived
+ result = evaluate_candidate_rule(rule_language="sigma", rule_body=_SIGMA_CONTAINS, positive_fixtures=pos, negative_fixtures=neg)
+ assert result.passed, result.to_dict()
+
+
+def test_multi_selector_derivation_and_gate():
+ derived = derive_fixtures_from_sigma(_SIGMA_MULTI)
+ assert derived is not None
+ pos, neg = derived
+ assert pos[0]["Image"].endswith("powershell.exe")
+ assert "-EncodedCommand" in pos[0]["CommandLine"]
+ result = evaluate_candidate_rule(rule_language="sigma", rule_body=_SIGMA_MULTI, positive_fixtures=pos, negative_fixtures=neg)
+ assert result.passed, result.to_dict()
+
+
+def test_unusable_sigma_returns_none():
+ assert derive_fixtures_from_sigma("just a plain string") is None
+ assert derive_fixtures_from_sigma("title: x\nlevel: high\n") is None # no detection block
diff --git a/services/api/tests/test_detection_loop_tenant_isolation.py b/services/api/tests/test_detection_loop_tenant_isolation.py
index d8b21ef16..265fb14eb 100644
--- a/services/api/tests/test_detection_loop_tenant_isolation.py
+++ b/services/api/tests/test_detection_loop_tenant_isolation.py
@@ -11,7 +11,7 @@ The contract being protected
the **rule body lookup** on the caller's ``tenant_id``. A cross-tenant
``alert_id`` must 404 *before* any evidence or rule body is read, and
no detection-rule-proposal row may be inserted.
-* The auto-created ``aisoc_detection_rule_proposals`` row must bind the
+* The auto-created ``detection_rule_proposals`` row must bind the
**caller's** ``tenant_id`` — never one derived from a database read,
so a poisoned ``aisoc_alerts.tenant_id`` cannot redirect the write.
* ``GET /detection-loop/suggestions`` and
@@ -202,7 +202,7 @@ async def test_suggest_cross_tenant_alert_id_returns_404(_stub_llm: dict[str, An
# Critical: no rule lookup and no proposal INSERT must have run.
assert _find_select(db.executed, "aisoc_detection_rules") is None, "rule body lookup must not run when the alert lookup 404s"
- assert _find_insert(db.executed, "aisoc_detection_rule_proposals") is None, "no proposal must be inserted when the alert lookup 404s"
+ assert _find_insert(db.executed, "detection_rule_proposals") is None, "no proposal must be inserted when the alert lookup 404s"
# And nothing must land in the in-memory store.
assert detection_loop_module._SUGGESTIONS == {}
@@ -240,8 +240,8 @@ async def test_suggest_same_tenant_scopes_alert_rule_and_proposal(_stub_llm: dic
assert params.get("tenant_id") == user.tenant_id
# Proposal INSERT — the ``tid`` bind must equal the *caller's* tenant.
- proposal_insert = _find_insert(db.executed, "aisoc_detection_rule_proposals")
- assert proposal_insert is not None, "expected an INSERT into aisoc_detection_rule_proposals"
+ proposal_insert = _find_insert(db.executed, "detection_rule_proposals")
+ assert proposal_insert is not None, "expected an INSERT into detection_rule_proposals"
_sql, params = proposal_insert
assert (
params.get("tid") == user.tenant_id
@@ -277,7 +277,7 @@ async def test_suggest_proposal_insert_binds_caller_tenant_not_db_row_tenant(_st
user=user,
)
- proposal_insert = _find_insert(db.executed, "aisoc_detection_rule_proposals")
+ proposal_insert = _find_insert(db.executed, "detection_rule_proposals")
assert proposal_insert is not None
_sql, params = proposal_insert
# The critical assertion: never trust a value we read back from the DB
@@ -311,7 +311,7 @@ async def test_suggest_alert_without_rule_id_skips_rule_select(_stub_llm: dict[s
assert response.base_rule_id is None
assert _find_select(db.executed, "aisoc_detection_rules") is None
- proposal_insert = _find_insert(db.executed, "aisoc_detection_rule_proposals")
+ proposal_insert = _find_insert(db.executed, "detection_rule_proposals")
assert proposal_insert is not None
assert proposal_insert[1].get("tid") == user.tenant_id
diff --git a/services/api/tests/test_wave1_loop_edges.py b/services/api/tests/test_wave1_loop_edges.py
index 0bfe1c9a3..61d078738 100644
--- a/services/api/tests/test_wave1_loop_edges.py
+++ b/services/api/tests/test_wave1_loop_edges.py
@@ -38,7 +38,7 @@ async def test_hunt_hits_open_a_detection_proposal(monkeypatch):
await hunt_scheduler._propose_detection_from_hunt(db, _hunt(), 5)
assert db.execute.await_count == 1
sql = str(db.execute.await_args.args[0])
- assert "aisoc_detection_rule_proposals" in sql
+ assert "detection_rule_proposals" in sql
@pytest.mark.asyncio