Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(agents): swap /investigate to RouterOrchestrator behind ROUTER_INVESTIGATE flag (re-open of #142) (#196)
Beenu Aroraa3deeeaeb0ca
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1a833bda1..7b187d9ad 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### `/investigate` endpoint swap behind feature flag (T2.2, v8.0)++`services/agents/app/api/investigate.py` now picks an orchestrator per call+based on the `AISOC_INVESTIGATE_USE_ROUTER` environment flag (default off).+When unset, the endpoint behaves exactly as before and routes through+`InvestigatorOrchestrator.stream()`. When set to a truthy value+(`1` / `true` / `yes` / `on` / `enabled`, case-insensitive, whitespace+tolerated), the same case streams through the four-agent+`RouterOrchestrator` via the new `stream_kwargs()` adapter. The flag is+read at call time, not import time, so operators can cut traffic over+gradually — or roll back — without bouncing the agents service. Both the+HTTP POST path (`_run_and_store`) and the WebSocket path+(`stream_investigation`) share the same dispatcher, so case storage and+live streaming stay in lockstep.++`RouterOrchestrator` grew an investigator-compatible adapter:+`stream_kwargs(case_id, alert_summary, raw_alert, tenant_id, run_id=None)`.+It coerces string case / tenant / run IDs into UUIDs deterministically+(`uuid5` against a fixed namespace, so the same `case_id` always maps to+the same UUID across processes), constructs an `InvestigationState`, and+proxies to `stream()`. The adapter normalises three event-shape gaps so+the existing consumer code in `app.api.investigate` doesn't have to+branch on orchestrator type: `step` events are enriched with the+case / run IDs, `kind`, `node`, and `ts` fields the investigator path+emits; a `done` event whose `state.status == FAILED` is rewritten as an+explicit `{"type": "error"}` event (and the original `done` is+suppressed) so endpoint error handling fires identically to the+investigator path; and a stray `alert_text=` typo in the original draft+was caught and fixed — the internal state is now populated via+`alert_summary=`, matching the field actually defined on+`InvestigationState`.++Coverage: `services/agents/tests/test_investigate_router_flag.py` (27+tests) pins the dispatcher — flag parsing including case/whitespace+edge cases, orchestrator selection per call, parameter pass-through,+flag-read-at-call-time semantics (so flipping the env var mid-process+takes effect on the next call), module-singleton stability, and+defensive guards around `run_id` being `None` vs. `UUID`.+`services/agents/tests/test_orchestrator_router_stream_kwargs.py`+covers the adapter end-to-end: event-shape parity with the+investigator (`step` enrichment with `case_id` / `run_id` / `kind` /+`node` / `ts`), error synthesis from failed `done` events, ID+coercion determinism, and that `alert_summary` actually lands on+the inner state. Combined with the existing router and report+suites, all 55 router-adjacent tests stay green.+### Router orchestrator gains streaming + ledger + report (T2.2, v8.0)`RouterOrchestrator` (`services/agents/app/orchestrator/router.py`) now matchesdiff --git a/services/agents/app/api/investigate.py b/services/agents/app/api/investigate.pyindex 4e3383fe5..87cd793ac 100644--- a/services/agents/app/api/investigate.py+++ b/services/agents/app/api/investigate.py@@ -26,6 +26,7 @@ from fastapi.responses import HTMLResponse, PlainTextResponsefrom pydantic import BaseModelfrom app.investigator import InvestigatorOrchestrator+from app.orchestrator.router import RouterOrchestratorlogger = structlog.get_logger()router = APIRouter(prefix="/api/v1", tags=["investigations"])@@ -36,11 +37,66 @@ router = APIRouter(prefix="/api/v1", tags=["investigations"])_REALTIME_URL = os.environ.get("REALTIME_URL", "http://realtime:8086")_INTERNAL_TOKEN = os.environ.get("INTERNAL_TOKEN", "")+# ---------------------------------------------------------------------------+# Orchestrator selection+# ---------------------------------------------------------------------------+# T2.2: route /investigate through the four-agent ``RouterOrchestrator`` when+# the flag is on; otherwise keep the legacy ``InvestigatorOrchestrator`` path.+# Read at call time so operators can flip without restarting the service.+USE_ROUTER_FLAG = "AISOC_INVESTIGATE_USE_ROUTER"+++def is_router_investigate_enabled() -> bool:+ """Return True if /investigate should use ``RouterOrchestrator`` (default off).++ Explicit truthy values (``1`` / ``true`` / ``yes`` / ``on`` / ``enabled``,+ case-insensitive) opt into the router path; everything else, including the+ unset case, keeps the investigator path. Mirrors the convention used by+ :func:`app.orchestrator.router.is_parallel_topology_enabled`.+ """+ raw = os.environ.get(USE_ROUTER_FLAG)+ if raw is None:+ return False+ return raw.strip().lower() in {"1", "true", "yes", "on", "enabled"}++# ---------------------------------------------------------------------------# Simple in-memory run store (swap for Redis in production)# ---------------------------------------------------------------------------_runs: dict[str, dict[str, Any]] = {}_orch = InvestigatorOrchestrator()+_router_orch = RouterOrchestrator()+++def _investigate_stream(+ *,+ case_id: str,+ alert_summary: str,+ raw_alert: dict[str, Any],+ tenant_id: str,+ run_id: UUID | None = None,+):+ """Pick the orchestrator at call time based on ``AISOC_INVESTIGATE_USE_ROUTER``.++ Both orchestrators expose an investigator-compatible ``stream`` /+ ``stream_kwargs`` surface that yields the same ``step`` / ``done`` /+ ``error`` event taxonomy, so the consumer below can stay shape-agnostic.+ """+ if is_router_investigate_enabled():+ return _router_orch.stream_kwargs(+ case_id=case_id,+ alert_summary=alert_summary,+ raw_alert=raw_alert,+ tenant_id=tenant_id,+ run_id=run_id,+ )+ return _orch.stream(+ case_id=case_id,+ alert_summary=alert_summary,+ raw_alert=raw_alert,+ tenant_id=tenant_id,+ run_id=run_id,+ )# ---------------------------------------------------------------------------@@ -101,8 +157,10 @@ async def _run_and_store(run_id: str, case_id: str, req: InvestigateRequest) ->except (ValueError, TypeError):run_uuid = uuid4()try:- # Use the streaming orchestrator so we can emit events progressively- async for event in _orch.stream(+ # Use the streaming orchestrator so we can emit events progressively.+ # ``_investigate_stream`` picks investigator vs. router at call time+ # based on ``AISOC_INVESTIGATE_USE_ROUTER``.+ async for event in _investigate_stream(case_id=case_id,alert_summary=req.alert_summary,raw_alert=req.raw_alert,@@ -300,8 +358,8 @@ async def stream_investigation(ws: WebSocket, run_id: str):breakawait asyncio.sleep(0.5)else:- # Direct streaming for ad-hoc calls- async for event in _orch.stream(+ # Direct streaming for ad-hoc calls; orchestrator selected by flag.+ async for event in _investigate_stream(case_id=case_id,alert_summary=alert_summary,raw_alert={},diff --git a/services/agents/app/orchestrator/router.py b/services/agents/app/orchestrator/router.pyindex af6d43aa7..844689cd2 100644--- a/services/agents/app/orchestrator/router.py+++ b/services/agents/app/orchestrator/router.py@@ -85,6 +85,36 @@ def is_parallel_topology_enabled() -> bool:return raw.strip().lower() not in {"0", "false", "no", "off", "disabled"}+# ---------------------------------------------------------------------------+# String → UUID coercion for the investigator-compatible adapter+# ---------------------------------------------------------------------------++# Stable namespace for hashing opaque caller-supplied strings (case ids /+# tenant slugs) into UUIDs. Living under ``tryaisoc.com/router`` keeps the+# derived ids reproducible across processes — the realtime stream and the+# ledger row land on the same UUID for the same input string.+_AISOC_ROUTER_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_URL, "tryaisoc.com/router")+++def _coerce_uuid(value: str | uuid.UUID) -> uuid.UUID:+ """Return ``value`` as a :class:`uuid.UUID`.++ Accepts a real UUID, a canonical UUID string, or any opaque caller+ identifier (e.g. ``"case-42"`` or ``"default"``). Opaque strings are+ deterministically hashed under :data:`_AISOC_ROUTER_NAMESPACE` so the+ same input always resolves to the same UUID — required so the ledger+ row id, the realtime stream id, and any cross-process consumers all+ agree.+ """+ if isinstance(value, uuid.UUID):+ return value+ text = str(value)+ try:+ return uuid.UUID(text)+ except (ValueError, TypeError):+ return uuid.uuid5(_AISOC_ROUTER_NAMESPACE, text)++# ---------------------------------------------------------------------------# Signal classification — picks which sub-agents to fan out to# ---------------------------------------------------------------------------@@ -719,7 +749,11 @@ class RouterOrchestrator:if mode not in {"parallel", "sequential"}:raise ValueError(f"unknown topology: {mode!r}")- run_id = uuid.uuid4()+ # Honor the run id already on the state so the API can correlate the+ # realtime stream with the persisted ledger row. The state model+ # defaults this to ``uuid.uuid4`` so direct callers still get a fresh+ # id without ceremony.+ run_id = state.run_idstate.status = AgentStatus.RUNNINGstate.iteration_count = max(state.iteration_count, 0)state.started_at = state.started_at or datetime.utcnow()@@ -1091,6 +1125,102 @@ class RouterOrchestrator:substrate=True,)+ async def stream_kwargs(+ self,+ *,+ case_id: str,+ alert_summary: str,+ raw_alert: dict[str, Any] | None = None,+ tenant_id: str = "default",+ run_id: uuid.UUID | None = None,+ topology: str | None = None,+ ) -> AsyncIterator[dict[str, Any]]:+ """Investigator-compatible streaming adapter for the ``/investigate`` swap.++ Matches :meth:`app.investigator.orchestrator.InvestigatorOrchestrator.stream`+ signature so the API endpoint can flip between the two orchestrators+ behind a feature flag without changing its call site. The adapter:++ 1. Coerces caller-supplied strings (``case_id``, ``tenant_id``) to+ :class:`uuid.UUID` via :func:`_coerce_uuid` so the internal+ :class:`InvestigationState` validates, then surfaces the+ **original** string identifiers back on every yielded event for the+ realtime stream consumers.+ 2. Enriches router ``step`` events with the+ ``kind`` / ``node`` / ``ts`` / ``case_id`` / ``run_id`` fields the+ investigator envelope carries and the WebSocket bridge expects.+ 3. Synthesises an explicit ``{"type": "error"}`` event when the+ underlying router reports failure inside its terminal ``done``+ event (router models failure in-band; the endpoint expects an+ out-of-band error). The partial ``report_md`` / ``report_html``+ / ``state`` snapshot the router did assemble before the failure+ is included on the synthesised error event so the UI can still+ render the in-progress narrative. The original ``done`` is+ suppressed on the failure path so consumers don't see both.+ """+ # Coerce caller strings to UUIDs for the internal state model.+ # Original strings are preserved on every yielded event so /investigate+ # consumers can correlate against ledger rows and WebSocket sessions.+ incident_uuid = _coerce_uuid(case_id)+ tenant_uuid = _coerce_uuid(tenant_id)+ run_uuid = run_id if isinstance(run_id, uuid.UUID) else uuid.uuid4()++ state = InvestigationState(+ run_id=run_uuid,+ incident_id=incident_uuid,+ tenant_id=tenant_uuid,+ alert_summary=alert_summary,+ raw_alert=raw_alert or {},+ )+ run_id_str = str(run_uuid)+ failed_status = AgentStatus.FAILED.value++ async for event in self.stream(state, topology=topology):+ etype = event.get("type")++ if etype == "step":+ yield {+ **event,+ "case_id": case_id,+ "run_id": run_id_str,+ "kind": event.get("kind", "agent_action"),+ "node": event.get("node") or event.get("agent"),+ "ts": event.get("ts") or datetime.utcnow().isoformat(),+ }+ continue++ if etype == "done":+ event_state = event.get("state") or {}+ status = event_state.get("status")+ # Router embeds failure inside `done`; the /investigate+ # endpoint expects an out-of-band `error` event. Synthesise+ # it and suppress the original done.+ if status == failed_status:+ yield {+ "type": "error",+ "error": event_state.get("error") or "router investigation failed",+ "case_id": case_id,+ "run_id": run_id_str,+ "report_md": event.get("report_md"),+ "report_html": event.get("report_html"),+ "state": event_state,+ }+ return+ yield {+ **event,+ "case_id": case_id,+ "run_id": run_id_str,+ }+ continue++ # Forwards-compat: any future event type passes through with+ # caller identifiers attached.+ yield {+ **event,+ "case_id": event.get("case_id", case_id),+ "run_id": event.get("run_id", run_id_str),+ }+async def run_router_investigation(state: InvestigationState,diff --git a/services/agents/tests/test_investigate_router_flag.py b/services/agents/tests/test_investigate_router_flag.pynew file mode 100644index 000000000..62d71f075--- /dev/null+++ b/services/agents/tests/test_investigate_router_flag.py@@ -0,0 +1,301 @@+"""+T2.2 — ``/investigate`` orchestrator selection via ``AISOC_INVESTIGATE_USE_ROUTER``.++These tests pin the call-time dispatcher in+:mod:`app.api.investigate` that routes traffic between the legacy+:class:`InvestigatorOrchestrator` and the four-agent+:class:`RouterOrchestrator` based on an environment flag. They cover:++* Default-off behaviour (no env var → investigator path).+* Truthy / falsey parsing of the env var, including case insensitivity.+* The flag is re-read **on every call**, so operators can flip it+ without restarting the agents service.+* Parameter pass-through is identical regardless of which orchestrator+ is selected — the swap must be transparent to callers.++We don't spin up the FastAPI app here: the dispatcher is a pure+selector, and end-to-end behaviour of each orchestrator already has+dedicated test files. Patching the two ``stream`` / ``stream_kwargs``+entry points and asserting which one ran is a tighter spec for the+flag itself.+"""++from __future__ import annotations++import asyncio+import sys+from pathlib import Path+from typing import Any+from uuid import UUID, uuid4++import pytest++_AGENTS_ROOT = Path(__file__).resolve().parents[1]+if str(_AGENTS_ROOT) not in sys.path:+ sys.path.insert(0, str(_AGENTS_ROOT))++from app.api import investigate as investigate_mod # noqa: E402++FLAG = investigate_mod.USE_ROUTER_FLAG+++# ---------------------------------------------------------------------------+# Flag parsing+# ---------------------------------------------------------------------------+++def test_flag_defaults_off_when_env_unset(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv(FLAG, raising=False)+ assert investigate_mod.is_router_investigate_enabled() is False+++ "value",+ ["1", "true", "TRUE", "True", "yes", "YES", "on", "On", "enabled", "ENABLED"],+)+def test_flag_truthy_values(monkeypatch: pytest.MonkeyPatch, value: str) -> None:+ monkeypatch.setenv(FLAG, value)+ assert investigate_mod.is_router_investigate_enabled() is True+++ "value",+ ["", "0", "false", "no", "off", "disabled", "FALSE", "anything-else", " "],+)+def test_flag_falsey_values(monkeypatch: pytest.MonkeyPatch, value: str) -> None:+ monkeypatch.setenv(FLAG, value)+ assert investigate_mod.is_router_investigate_enabled() is False+++def test_flag_tolerates_whitespace(monkeypatch: pytest.MonkeyPatch) -> None:+ """Operators often paste with trailing whitespace; treat ``" true "`` as+ truthy so a stray newline in a .env file doesn't silently flip the path."""+ monkeypatch.setenv(FLAG, " true ")+ assert investigate_mod.is_router_investigate_enabled() is True+++# ---------------------------------------------------------------------------+# Dispatch+# ---------------------------------------------------------------------------+++def patched_orchestrators(monkeypatch: pytest.MonkeyPatch) -> dict[str, list[dict[str, Any]]]:+ """Replace both orchestrator entry points with recording shims.++ Each shim returns an empty async generator so callers can iterate+ the result like a real stream. The list captured per orchestrator+ is the kwargs that arrived at that path.+ """+ calls: dict[str, list[dict[str, Any]]] = {"investigator": [], "router": []}++ async def _empty() -> Any:+ if False: # pragma: no cover - generator stub+ yield {}++ def _fake_investigator_stream(**kwargs: Any):+ calls["investigator"].append(kwargs)+ return _empty()++ def _fake_router_stream_kwargs(**kwargs: Any):+ calls["router"].append(kwargs)+ return _empty()++ monkeypatch.setattr(investigate_mod._orch, "stream", _fake_investigator_stream, raising=True)+ monkeypatch.setattr(+ investigate_mod._router_orch,+ "stream_kwargs",+ _fake_router_stream_kwargs,+ raising=True,+ )+ return calls+++def _exhaust(stream: Any) -> None:+ async def _go() -> None:+ async for _ in stream:+ pass++ asyncio.run(_go())+++def test_dispatch_uses_investigator_when_flag_unset(+ monkeypatch: pytest.MonkeyPatch,+ patched_orchestrators: dict[str, list[dict[str, Any]]],+) -> None:+ monkeypatch.delenv(FLAG, raising=False)++ run_id = uuid4()+ stream = investigate_mod._investigate_stream(+ case_id="case-1",+ alert_summary="Suspicious OAuth consent",+ raw_alert={"sender": "[email protected]"},+ tenant_id="tenant-a",+ run_id=run_id,+ )+ _exhaust(stream)++ assert patched_orchestrators["investigator"], "investigator path should fire"+ assert not patched_orchestrators["router"], "router path must stay quiet"+ (call,) = patched_orchestrators["investigator"]+ assert call == {+ "case_id": "case-1",+ "alert_summary": "Suspicious OAuth consent",+ "raw_alert": {"sender": "[email protected]"},+ "tenant_id": "tenant-a",+ "run_id": run_id,+ }+++def test_dispatch_uses_router_when_flag_set(+ monkeypatch: pytest.MonkeyPatch,+ patched_orchestrators: dict[str, list[dict[str, Any]]],+) -> None:+ monkeypatch.setenv(FLAG, "1")++ run_id = uuid4()+ stream = investigate_mod._investigate_stream(+ case_id="case-2",+ alert_summary="Phishing → identity → cloud",+ raw_alert={"urls": ["https://bad.example"]},+ tenant_id="tenant-b",+ run_id=run_id,+ )+ _exhaust(stream)++ assert patched_orchestrators["router"], "router path should fire"+ assert not patched_orchestrators["investigator"], "investigator must stay quiet"+ (call,) = patched_orchestrators["router"]+ assert call == {+ "case_id": "case-2",+ "alert_summary": "Phishing → identity → cloud",+ "raw_alert": {"urls": ["https://bad.example"]},+ "tenant_id": "tenant-b",+ "run_id": run_id,+ }+++def test_flag_is_read_each_call_not_at_import(+ monkeypatch: pytest.MonkeyPatch,+ patched_orchestrators: dict[str, list[dict[str, Any]]],+) -> None:+ """Flipping the env var mid-process must take effect on the next call.++ If the flag were cached at import time, operators couldn't gradually+ cut traffic over to the router without restarting the service.+ """+ monkeypatch.delenv(FLAG, raising=False)+ _exhaust(+ investigate_mod._investigate_stream(+ case_id="c-a",+ alert_summary="first",+ raw_alert={},+ tenant_id="t",+ )+ )++ monkeypatch.setenv(FLAG, "true")+ _exhaust(+ investigate_mod._investigate_stream(+ case_id="c-b",+ alert_summary="second",+ raw_alert={},+ tenant_id="t",+ )+ )++ monkeypatch.delenv(FLAG, raising=False)+ _exhaust(+ investigate_mod._investigate_stream(+ case_id="c-c",+ alert_summary="third",+ raw_alert={},+ tenant_id="t",+ )+ )++ investigator_ids = [c["case_id"] for c in patched_orchestrators["investigator"]]+ router_ids = [c["case_id"] for c in patched_orchestrators["router"]]+ assert investigator_ids == ["c-a", "c-c"]+ assert router_ids == ["c-b"]+++def test_dispatch_omits_run_id_when_not_supplied(+ monkeypatch: pytest.MonkeyPatch,+ patched_orchestrators: dict[str, list[dict[str, Any]]],+) -> None:+ """Both paths must accept ``run_id=None`` and let the orchestrator mint one.++ The endpoint passes ``run_uuid`` straight through from a freshly+ minted ``uuid4()`` today, but the WebSocket path doesn't supply+ one. Make sure the dispatcher doesn't accidentally drop the kwarg.+ """+ monkeypatch.setenv(FLAG, "1")+ _exhaust(+ investigate_mod._investigate_stream(+ case_id="c-router-no-run",+ alert_summary="x",+ raw_alert={},+ tenant_id="t",+ )+ )++ monkeypatch.delenv(FLAG, raising=False)+ _exhaust(+ investigate_mod._investigate_stream(+ case_id="c-inv-no-run",+ alert_summary="x",+ raw_alert={},+ tenant_id="t",+ )+ )++ (router_call,) = patched_orchestrators["router"]+ (inv_call,) = patched_orchestrators["investigator"]+ assert router_call["run_id"] is None+ assert inv_call["run_id"] is None+++def test_module_state_unchanged_by_flag(monkeypatch: pytest.MonkeyPatch) -> None:+ """Sanity: the flag never re-instantiates the orchestrators (they're+ process-singletons), and both module attributes survive a flag flip."""+ orig_investigator = investigate_mod._orch+ orig_router = investigate_mod._router_orch++ monkeypatch.setenv(FLAG, "1")+ assert investigate_mod.is_router_investigate_enabled() is True+ monkeypatch.delenv(FLAG, raising=False)+ assert investigate_mod.is_router_investigate_enabled() is False++ assert investigate_mod._orch is orig_investigator+ assert investigate_mod._router_orch is orig_router+++# ---------------------------------------------------------------------------+# Defensive: signature should accept the kwargs the endpoint actually passes+# ---------------------------------------------------------------------------+++def test_dispatcher_accepts_uuid_run_id(+ monkeypatch: pytest.MonkeyPatch,+ patched_orchestrators: dict[str, list[dict[str, Any]]],+) -> None:+ """``_run_and_store`` always supplies ``run_id`` as a UUID instance.++ Regression guard against a future refactor that types ``run_id``+ too narrowly (e.g. ``str``).+ """+ monkeypatch.delenv(FLAG, raising=False)+ run_id: UUID = uuid4()+ _exhaust(+ investigate_mod._investigate_stream(+ case_id="case",+ alert_summary="x",+ raw_alert={},+ tenant_id="default",+ run_id=run_id,+ )+ )+ (call,) = patched_orchestrators["investigator"]+ assert isinstance(call["run_id"], UUID)+ assert call["run_id"] == run_iddiff --git a/services/agents/tests/test_orchestrator_router_stream_kwargs.py b/services/agents/tests/test_orchestrator_router_stream_kwargs.pynew file mode 100644index 000000000..a569564a8--- /dev/null+++ b/services/agents/tests/test_orchestrator_router_stream_kwargs.py@@ -0,0 +1,507 @@+"""+T2.2 — RouterOrchestrator.stream_kwargs() investigator-compatible adapter.++These tests pin the adapter that lets ``/investigate`` swap between+``InvestigatorOrchestrator.stream()`` and ``RouterOrchestrator.stream_kwargs()``+behind a feature flag without touching the endpoint. They cover:++* Signature parity with :meth:`InvestigatorOrchestrator.stream`.+* String → UUID coercion for ``case_id`` / ``tenant_id`` (deterministic+ via :func:`_coerce_uuid`, accepted as canonical UUID strings too).+* ``run_id`` honoured when caller supplies one; minted otherwise.+* Original caller strings preserved on every yielded event so+ realtime / ledger consumers can correlate against the inputs they+ already hold.+* ``step`` events enriched with the ``kind`` / ``node`` / ``ts``+ envelope fields the investigator stream carries.+* Failure mode: a router that ends in ``status=FAILED`` produces an+ out-of-band ``{"type": "error"}`` event, and the original ``done``+ is suppressed.+* Alert text actually lands on the internal :class:`InvestigationState`+ (regression guard for the field-name mismatch that bit on first cut).++Sub-agent runners are monkeypatched to deterministic shims — same+pattern as :mod:`tests.test_orchestrator_router_stream`.+"""++from __future__ import annotations++import asyncio+import sys+import uuid+from pathlib import Path+from typing import Any+from uuid import UUID++import pytest++_AGENTS_ROOT = Path(__file__).resolve().parents[1]+if str(_AGENTS_ROOT) not in sys.path:+ sys.path.insert(0, str(_AGENTS_ROOT))++import inspect # noqa: E402++from app.investigator.orchestrator import InvestigatorOrchestrator # noqa: E402+from app.models.state import AgentStatus, InvestigationState # noqa: E402+from app.orchestrator.router import ( # noqa: E402+ _AISOC_ROUTER_NAMESPACE,+ RouterOrchestrator,+ _coerce_uuid,+)++SUBAGENT_SLEEP_MS = 5+++# ---------------------------------------------------------------------------+# Fixtures — mirror test_orchestrator_router_stream._patch_runners+# ---------------------------------------------------------------------------+++def _patch_runners(monkeypatch: pytest.MonkeyPatch, *, auto_close: bool = False) -> dict[str, list[str]]:+ call_log: dict[str, list[str]] = {+ "auto_triage": [],+ "phishing": [],+ "identity": [],+ "cloud": [],+ "insider": [],+ }++ async def fake_auto_triage(state: InvestigationState) -> InvestigationState:+ await asyncio.sleep(SUBAGENT_SLEEP_MS / 1000.0)+ state.iteration_count += 1+ state.status = AgentStatus.COMPLETED if auto_close else AgentStatus.RUNNING+ state.verdict = "benign" if auto_close else "true_positive"+ state.confidence = 0.95 if auto_close else 0.6+ state.confidence_basis = ["fake auto-triage rationale"]+ state.add_finding(f"Auto-triage (fake): verdict={state.verdict}")+ call_log["auto_triage"].append(str(state.incident_id))+ return state++ def _make_runner(name: str, technique: str):+ async def _runner(state: InvestigationState) -> InvestigationState:+ await asyncio.sleep(SUBAGENT_SLEEP_MS / 1000.0)+ state.add_finding(f"{name} (fake): triggered")+ if technique not in state.mitre_mappings:+ state.mitre_mappings.append(technique)+ state.verdict = "true_positive"+ state.confidence = max(state.confidence, 0.7)+ call_log[name].append(str(state.incident_id))+ return state++ return _runner++ targets: list[tuple[str, object]] = [+ ("app.agents.run_auto_triage", fake_auto_triage),+ ("app.agents.auto_triage_agent.run_auto_triage", fake_auto_triage),+ ("app.agents.run_phishing", _make_runner("phishing", "T1566.001")),+ (+ "app.agents.phishing_agent.run_phishing",+ _make_runner("phishing", "T1566.001"),+ ),+ ("app.agents.run_identity", _make_runner("identity", "T1078")),+ ("app.agents.identity_agent.run_identity", _make_runner("identity", "T1078")),+ ("app.agents.run_cloud", _make_runner("cloud", "T1078.004")),+ ("app.agents.cloud_agent.run_cloud", _make_runner("cloud", "T1078.004")),+ ("app.agents.run_insider_threat", _make_runner("insider", "T1567.002")),+ (+ "app.agents.insider_threat_agent.run_insider_threat",+ _make_runner("insider", "T1567.002"),+ ),+ ]+ for path, fn in targets:+ monkeypatch.setattr(path, fn, raising=False)++ return call_log+++def _stub_ledger(monkeypatch: pytest.MonkeyPatch) -> None:+ """No-op ledger so streaming runs end-to-end without persistence."""+ import app.investigator.ledger as ledger_module++ async def _none(**_: Any) -> None:+ return None++ monkeypatch.setattr(ledger_module, "start_run", _none, raising=True)+ monkeypatch.setattr(ledger_module, "record_event", _none, raising=True)+ monkeypatch.setattr(ledger_module, "record_artifact", _none, raising=True)+ monkeypatch.setattr(ledger_module, "complete_run", _none, raising=True)+++async def _collect(stream) -> list[dict[str, Any]]:+ return [event async for event in stream]+++def _raw_alert() -> dict[str, Any]:+ """Trigger all four signal classes so the parallel topology fans out fully."""+ return {+ "sender": "[email protected]",+ "subject": "Action required: contract renewal",+ "urls": ["https://contract-renewal[.]example/login"],+ "username": "[email protected]",+ "user_email": "[email protected]",+ "source_ip": "203.0.113.42",+ "auth_method": "saml",+ "mfa_status": "challenged",+ "cloud_provider": "aws",+ "region": "eu-west-1",+ "account_id": "111122223333",+ "principal_arn": "arn:aws:iam::111122223333:role/DataAnalyst",+ "data_volume_mb": 4096,+ "file_count": 871,+ "destination_domain": "attacker[.]example",+ "is_off_hours": True,+ }+++# ---------------------------------------------------------------------------+# Signature & helper parity+# ---------------------------------------------------------------------------+++def test_stream_kwargs_signature_matches_investigator() -> None:+ """Adapter must accept every parameter ``InvestigatorOrchestrator.stream`` accepts.++ The endpoint calls ``await orch.stream(case_id=..., alert_summary=...,+ raw_alert=..., tenant_id=..., run_id=...)``. If the parameter names+ drift, the feature-flag swap silently breaks. Pin them here.+ """+ inv_params = set(inspect.signature(InvestigatorOrchestrator.stream).parameters)+ inv_params.discard("self")+ router_params = set(inspect.signature(RouterOrchestrator.stream_kwargs).parameters)+ router_params.discard("self")++ # Adapter must cover every investigator param. Extras (``topology``) are fine.+ assert inv_params.issubset(router_params), f"missing params: {inv_params - router_params}"+++def test_coerce_uuid_is_deterministic_across_calls() -> None:+ """Same opaque string must always hash to the same UUID — required so the+ ledger row and the realtime stream agree on the case id across processes."""+ first = _coerce_uuid("case-42")+ second = _coerce_uuid("case-42")+ assert first == second+ assert first == uuid.uuid5(_AISOC_ROUTER_NAMESPACE, "case-42")+++def test_coerce_uuid_passes_through_real_uuid() -> None:+ real = uuid.uuid4()+ assert _coerce_uuid(real) is real+ assert _coerce_uuid(str(real)) == real+++def test_coerce_uuid_differs_by_input() -> None:+ """Two distinct opaque strings must not collide."""+ assert _coerce_uuid("case-1") != _coerce_uuid("case-2")+ assert _coerce_uuid("default") != _coerce_uuid("tenant-a")+++# ---------------------------------------------------------------------------+# Event-shape parity with InvestigatorOrchestrator+# ---------------------------------------------------------------------------+++async def test_step_events_carry_investigator_envelope(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Every ``step`` event must carry case_id / run_id / kind / node / ts."""+ _patch_runners(monkeypatch)+ _stub_ledger(monkeypatch)++ run_id = uuid.uuid4()+ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-stream-1",+ alert_summary="Spear-phish → OAuth → cloud creds",+ raw_alert=_raw_alert(),+ tenant_id="tenant-a",+ run_id=run_id,+ topology="parallel",+ )+ )++ steps = [e for e in events if e["type"] == "step"]+ assert steps, "expected step events"++ for ev in steps:+ # Caller-supplied strings are surfaced as-is, not the internal UUID.+ assert ev["case_id"] == "case-stream-1"+ # run_id is the supplied UUID, serialized.+ assert ev["run_id"] == str(run_id)+ # Envelope fields the WebSocket layer reads.+ assert "kind" in ev, f"missing kind: {ev}"+ assert ev["node"], f"missing node: {ev}"+ assert ev["ts"], f"missing ts: {ev}"+ # ts is ISO-formattable.+ assert "T" in ev["ts"], ev["ts"]+++async def test_done_event_preserves_caller_ids(monkeypatch: pytest.MonkeyPatch) -> None:+ """``done`` must reference the caller's strings, not the coerced UUIDs."""+ _patch_runners(monkeypatch)+ _stub_ledger(monkeypatch)++ run_id = uuid.uuid4()+ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-done-1",+ alert_summary="Trigger all four signals",+ raw_alert=_raw_alert(),+ tenant_id="default",+ run_id=run_id,+ topology="parallel",+ )+ )++ done = events[-1]+ assert done["type"] == "done"+ assert done["case_id"] == "case-done-1"+ assert done["run_id"] == str(run_id)+ # State payload still survives the adapter — the endpoint reads+ # report_md / report_html off this.+ inner = done["state"]+ assert inner["status"] == "completed"+ assert inner["report_md"], "report_md must be non-empty"+ assert inner["report_html"], "report_html must be non-empty"+++async def test_run_id_minted_when_not_supplied(monkeypatch: pytest.MonkeyPatch) -> None:+ """Adapter mints a fresh UUID for run_id when the caller omits it."""+ _patch_runners(monkeypatch)+ _stub_ledger(monkeypatch)++ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-fresh",+ alert_summary="Trigger all four signals",+ raw_alert=_raw_alert(),+ topology="parallel",+ )+ )++ run_ids = {e["run_id"] for e in events if "run_id" in e}+ assert len(run_ids) == 1, "all events must share one run_id"+ (only,) = run_ids+ # Parses as a UUID, and is not the namespace itself (defensive).+ parsed = UUID(only)+ assert parsed != _AISOC_ROUTER_NAMESPACE+++async def test_canonical_uuid_string_passes_through_unchanged(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A caller that already has UUIDs as strings shouldn't get them rehashed."""+ _patch_runners(monkeypatch)+ _stub_ledger(monkeypatch)++ case_uuid = uuid.uuid4()+ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id=str(case_uuid),+ alert_summary="Trigger all four signals",+ raw_alert=_raw_alert(),+ tenant_id=str(uuid.uuid4()),+ topology="parallel",+ )+ )++ # Round-trip: the case_id surfaced on every event matches the string+ # the caller passed in, not a hash of it.+ case_ids = {e["case_id"] for e in events if "case_id" in e}+ assert case_ids == {str(case_uuid)}+++# ---------------------------------------------------------------------------+# Error synthesis+# ---------------------------------------------------------------------------+++async def test_failed_done_is_translated_to_error_event(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """When the router reports ``status=FAILED`` inside ``done``, the adapter+ must emit an explicit ``{"type": "error"}`` event and suppress the done."""+ _stub_ledger(monkeypatch)++ async def _fake_stream(+ self: RouterOrchestrator,+ state: InvestigationState,+ *,+ topology: str | None = None,+ ):+ yield {+ "type": "step",+ "agent": "auto_triage",+ "summary": "auto-triage probing",+ "seq": 1,+ "state": {"status": "running"},+ }+ yield {+ "type": "done",+ "case_id": state.incident_id,+ "run_id": str(state.run_id),+ "state": {+ "status": AgentStatus.FAILED.value,+ "error": "ledger blew up",+ },+ "info": {"topology": topology or "parallel"},+ }++ monkeypatch.setattr(RouterOrchestrator, "stream", _fake_stream, raising=True)++ run_id = uuid.uuid4()+ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-fail-1",+ alert_summary="something exploded",+ tenant_id="default",+ run_id=run_id,+ topology="parallel",+ )+ )++ types = [e["type"] for e in events]+ # Step survives, done is suppressed in favour of error.+ assert types == ["step", "error"], types++ err = events[-1]+ assert err["case_id"] == "case-fail-1"+ assert err["run_id"] == str(run_id)+ assert "ledger blew up" in err["error"]+++async def test_failed_error_event_carries_partial_report(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Synthesised error event must include the partial ``report_md`` /+ ``report_html`` / ``state`` snapshot the router assembled before the+ failure, so the UI can still render the in-progress narrative instead+ of losing every finding the sub-agents already produced."""+ _stub_ledger(monkeypatch)++ partial_md = "# Partial report\n\nauto_triage finding: suspicious"+ partial_html = "<h1>Partial report</h1><p>auto_triage finding: suspicious</p>"+ partial_state = {+ "status": AgentStatus.FAILED.value,+ "error": "phishing sub-agent crashed mid-fanout",+ "findings": ["auto_triage finding: suspicious"],+ }++ async def _fake_stream(+ self: RouterOrchestrator,+ state: InvestigationState,+ *,+ topology: str | None = None,+ ):+ yield {+ "type": "done",+ "case_id": state.incident_id,+ "run_id": str(state.run_id),+ "state": partial_state,+ "report_md": partial_md,+ "report_html": partial_html,+ "info": {"topology": "parallel"},+ }++ monkeypatch.setattr(RouterOrchestrator, "stream", _fake_stream, raising=True)++ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-partial-1",+ alert_summary="partial fanout",+ )+ )++ assert [e["type"] for e in events] == ["error"]+ err = events[0]+ assert err["report_md"] == partial_md+ assert err["report_html"] == partial_html+ assert err["state"] == partial_state+ assert "phishing sub-agent crashed" in err["error"]+++async def test_failed_done_without_error_message_still_emits_error(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """If FAILED state has no ``error`` field, the adapter still produces an+ error event with a sensible default — the endpoint must never see a+ silently-failed done."""+ _stub_ledger(monkeypatch)++ async def _fake_stream(+ self: RouterOrchestrator,+ state: InvestigationState,+ *,+ topology: str | None = None,+ ):+ yield {+ "type": "done",+ "case_id": state.incident_id,+ "run_id": str(state.run_id),+ "state": {"status": AgentStatus.FAILED.value},+ "info": {"topology": "parallel"},+ }++ monkeypatch.setattr(RouterOrchestrator, "stream", _fake_stream, raising=True)++ events = await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-fail-default",+ alert_summary="boom",+ )+ )++ assert [e["type"] for e in events] == ["error"]+ assert events[0]["error"], "must include a non-empty error message"+++# ---------------------------------------------------------------------------+# Field-name regression — alert_summary lands on the state+# ---------------------------------------------------------------------------+++async def test_alert_summary_lands_on_internal_state(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Regression guard: the field is ``alert_summary``, not ``alert_text``.++ Pydantic silently drops unknown fields, so a typo here would leave+ the agents running against an empty alert. Verify the runner sees+ the real text.+ """+ seen: dict[str, str] = {}++ async def fake_auto_triage(state: InvestigationState) -> InvestigationState:+ seen["alert_summary"] = state.alert_summary+ state.status = AgentStatus.COMPLETED # short-circuit to keep the test tight+ state.verdict = "benign"+ state.confidence = 0.99+ state.add_finding("auto-closed")+ return state++ monkeypatch.setattr("app.agents.run_auto_triage", fake_auto_triage, raising=False)+ monkeypatch.setattr(+ "app.agents.auto_triage_agent.run_auto_triage",+ fake_auto_triage,+ raising=False,+ )+ _stub_ledger(monkeypatch)++ expected = "Spear-phish → OAuth consent → cloud creds; impossible travel."+ await _collect(+ RouterOrchestrator().stream_kwargs(+ case_id="case-alert",+ alert_summary=expected,+ raw_alert={"sender": "[email protected]"},+ tenant_id="default",+ )+ )++ assert seen.get("alert_summary") == expected