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(agents): swap /investigate to RouterOrchestrator behind ROUTER_INVESTIGATE flag (re-open of #142) (#196)

Beenu Aroraa3deeeaeb0ca
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 matches
diff --git a/services/agents/app/api/investigate.py b/services/agents/app/api/investigate.py
index 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, PlainTextResponse
from pydantic import BaseModel
from app.investigator import InvestigatorOrchestrator
+from app.orchestrator.router import RouterOrchestrator
logger = 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):
break
await 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.py
index 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_id
state.status = AgentStatus.RUNNING
state.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.py
new file mode 100644
index 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_id
diff --git a/services/agents/tests/test_orchestrator_router_stream_kwargs.py b/services/agents/tests/test_orchestrator_router_stream_kwargs.py
new file mode 100644
index 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