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): RouterOrchestrator gains stream + ledger + report (T2.2, v8.0) (#141)

Beenu Arora00cc9ee0f2df
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0bffe92fa..1a833bda1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Router orchestrator gains streaming + ledger + report (T2.2, v8.0)
+
+`RouterOrchestrator` (`services/agents/app/orchestrator/router.py`) now matches
+the surface of the legacy `InvestigatorOrchestrator` on three axes — streamed
+progress events, ledger persistence, and a deterministic Markdown / HTML
+report on the `done` event — so the `/investigate` endpoint can be swapped
+over to the router without losing operator-visible behaviour. The existing
+`run()` entry point is unchanged; the new `stream(state, *, topology=...)`
+async generator yields `step` events at each stage boundary (auto-triage,
+signal classification, sub-agent dispatch, per-sub-agent completion in
+`as_completed` order, join, responder summary) and a single terminal `done`
+event carrying the full state plus the report. Step `seq` numbers are
+monotonic across both parallel and sequential topologies. Auto-close paths
+short-circuit after auto-triage with a single step and a `done` event so the
+UI doesn't paint a half-empty timeline.
+
+Ledger writes are best-effort: every `step` becomes a `record_event` row,
+the final state becomes a `record_artifact` (Markdown + HTML), and
+`complete_run` closes the row with verdict / confidence / latency / cost. A
+ledger outage (missing `asyncpg`, dropped connection, write failure)
+downgrades to a `warn`-level structured log and the stream still completes
+end-to-end — the persistence layer is observability, not a hard dependency.
+
+Report synthesis lives in the new `services/agents/app/orchestrator/report.py`
+module. `render_router_report(state)` returns `(report_md, report_html)`
+without any extra LLM call: it walks `InvestigationState` (verdict,
+confidence, sub-agent findings, attack chain, responder recovery steps) and
+renders deterministic templates. HTML conversion falls back to a `<pre>`
+block if the optional `markdown` package isn't installed, so the worker
+image stays slim.
+
+Coverage: `services/agents/tests/test_orchestrator_router_stream.py` (8
+tests) asserts the event contract — step ordering, monotonic `seq`,
+parallel vs sequential paths, auto-close short-circuit, `done` payload
+shape, ledger call ordering, and graceful degradation when ledger writes
+fail. `services/agents/tests/test_router_report.py` covers the
+deterministic renderer. Together with the existing parallel-topology
+suite all 34 router-adjacent tests pass clean.
+
### LangGraph parallel topology — HTTP surface (T2.2, v8.0)
`RouterOrchestrator` (the parallel fan-out / Join LangGraph topology landed
diff --git a/services/agents/app/orchestrator/report.py b/services/agents/app/orchestrator/report.py
new file mode 100644
index 000000000..23f92938c
--- /dev/null
+++ b/services/agents/app/orchestrator/report.py
@@ -0,0 +1,284 @@
+"""
+Router report synthesis — T2.2 expansion (v8.0).
+
+Renders ``(report_md, report_html)`` from the router's
+:class:`app.models.state.InvestigationState` so the streaming surface and
+the future ``/api/v1/cases/{case_id}/investigate`` swap can ship the same
+artifact shape the legacy ``InvestigatorOrchestrator`` already emits.
+
+The router state is flatter than ``InvestigatorState`` (no per-agent
+structured outputs, no audit log), so the report is built deterministically
+from the joined ``findings`` / ``mitre_mappings`` / ``proposed_actions``
+slots. No LLM call is needed at this stage — the substrate already paid
+for one LLM round-trip per sub-agent during fan-out and another in
+auto-triage; we don't burn another one just to format the artifact.
+
+The HTML output uses the same lightweight ``markdown`` library shell as
+``app.investigator.report_writer_agent`` so reports look consistent across
+both orchestrators. If ``markdown`` isn't importable for any reason we
+fall back to wrapping the source in ``<pre>``; the substrate suite covers
+both branches.
+"""
+
+from __future__ import annotations
+
+import html
+from datetime import datetime
+from typing import Any
+
+from app.models.state import AgentStatus, InvestigationState, ProposedAction
+
+
+def _md_escape(value: Any) -> str:
+ """HTML-escape a value before it is embedded in the Markdown body.
+
+ The rendered Markdown is later piped through ``markdown.markdown``,
+ which preserves raw HTML by default. Any of ``state.findings``,
+ ``state.error``, ``state.confidence_basis``, ``proposed_actions``
+ fields, etc. can carry adversary-influenced strings sourced from the
+ underlying alert. Escaping ``<``, ``>``, ``&``, ``"``, ``'`` upstream
+ means a finding like ``<script>alert(1)</script>`` reaches the
+ rendered HTML as literal text rather than executable script.
+
+ Returns the empty string for ``None`` so callers can blindly substitute.
+ """
+ if value is None:
+ return ""
+ return html.escape(str(value), quote=True)
+
+
+def _fmt_confidence(value: float) -> str:
+ """Render a 0.0–1.0 confidence as a two-decimal string."""
+ try:
+ return f"{float(value):.2f}"
+ except (TypeError, ValueError):
+ return "0.00"
+
+
+def _proposed_actions_table(actions: list[ProposedAction]) -> list[str]:
+ """Render the proposed-actions section as a Markdown table.
+
+ Returns the section body as a list of lines (so the caller can decide
+ whether to emit a heading above it). Returns an empty list when the
+ state has no proposed actions, so the caller can skip the section
+ entirely rather than rendering an empty table.
+ """
+ if not actions:
+ return []
+
+ def _cell(raw: Any) -> str:
+ """Escape a cell value: HTML-escape, then escape Markdown table delimiters.
+
+ Per security review, every table cell — not just ``rationale`` —
+ needs ``|`` + newline escaping so an adversary-controlled
+ ``target`` or ``action_type`` can't break the table layout.
+ """
+ cleaned = _md_escape(raw).replace("|", "\\|").replace("\n", " ").strip()
+ return cleaned or "—"
+
+ lines: list[str] = []
+ lines.append("| # | Action | Target | Risk | Approval | Rationale |")
+ lines.append("|---|--------|--------|------|----------|-----------|")
+ for idx, action in enumerate(actions, start=1):
+ action_type = _cell(getattr(action, "action_type", ""))
+ target = _cell(getattr(action, "target", ""))
+ risk_level = getattr(action, "risk_level", None)
+ risk_raw = getattr(risk_level, "value", risk_level)
+ risk = _cell(risk_raw)
+ approval = "yes" if getattr(action, "requires_approval", False) else "no"
+ rationale = _cell(getattr(action, "rationale", ""))
+ lines.append(f"| {idx} | {action_type} | {target} | {risk} | {approval} | {rationale} |")
+ return lines
+
+
+def _bullets(items: list[str]) -> list[str]:
+ """Render a list of strings as Markdown bullets.
+
+ Newlines inside any item are flattened into spaces so the bullet stays
+ on one logical line, which keeps the Markdown→HTML conversion stable.
+ Each item is HTML-escaped before emission — see ``_md_escape``.
+ """
+ out: list[str] = []
+ for item in items:
+ cleaned = " ".join(_md_escape(item).splitlines()).strip()
+ if cleaned:
+ out.append(f"- {cleaned}")
+ return out
+
+
+def render_router_report_md(
+ state: InvestigationState,
+ *,
+ info: dict[str, Any] | None = None,
+) -> str:
+ """Synthesise a Markdown incident report from the router's final state.
+
+ Sections (each is skipped when its source is empty):
+
+ 1. ``# Incident Report — <case_id>``
+ 2. ``## Summary`` — verdict, confidence, status, topology, wall-clock
+ 3. ``## Triage Rationale`` — ``confidence_basis``
+ 4. ``## Findings`` — ``state.findings`` as bullets
+ 5. ``## MITRE ATT&CK Mappings`` — ``state.mitre_mappings`` as inline codes
+ 6. ``## Proposed Actions`` — table of ``state.proposed_actions``
+ 7. ``## Errors`` — ``state.error`` if set
+ 8. Footer — generation timestamp
+
+ Args:
+ state: the final :class:`InvestigationState` after the router
+ (parallel or sequential) has run.
+ info: optional substrate telemetry dict from
+ :meth:`RouterOrchestrator.run` — adds topology / wall-clock /
+ signals to the Summary section when provided.
+
+ Returns:
+ A Markdown string ready to ship as a ``report_md`` artifact.
+ """
+ info = info or {}
+ case_id = str(state.incident_id)
+
+ lines: list[str] = []
+ lines.append(f"# Incident Report — {case_id}")
+ lines.append("")
+
+ # 2. Summary -----------------------------------------------------------
+ lines.append("## Summary")
+ lines.append("")
+ summary_rows: list[tuple[str, str]] = [
+ ("Verdict", _md_escape(state.verdict or "uncertain")),
+ ("Confidence", _fmt_confidence(state.confidence)),
+ ("Status", _md_escape(state.status.value if isinstance(state.status, AgentStatus) else str(state.status))),
+ ]
+ topology = info.get("topology")
+ if topology:
+ summary_rows.append(("Topology", _md_escape(topology)))
+ signals = info.get("signals") or []
+ if signals:
+ summary_rows.append(("Signals", _md_escape(", ".join(str(s) for s in signals))))
+ wall_clock = info.get("wall_clock_ms")
+ if wall_clock is not None:
+ summary_rows.append(("Wall-clock (ms)", f"{float(wall_clock):.1f}"))
+ if info.get("auto_closed"):
+ summary_rows.append(("Auto-closed", "yes"))
+
+ lines.append("| Field | Value |")
+ lines.append("|-------|-------|")
+ for label, value in summary_rows:
+ lines.append(f"| {label} | {value} |")
+ lines.append("")
+
+ # 3. Triage rationale --------------------------------------------------
+ if state.confidence_basis:
+ lines.append("## Triage Rationale")
+ lines.append("")
+ lines.extend(_bullets(state.confidence_basis))
+ lines.append("")
+
+ # 4. Findings ----------------------------------------------------------
+ if state.findings:
+ lines.append("## Findings")
+ lines.append("")
+ lines.extend(_bullets(state.findings))
+ lines.append("")
+
+ # 5. MITRE ATT&CK mappings --------------------------------------------
+ if state.mitre_mappings:
+ lines.append("## MITRE ATT&CK Mappings")
+ lines.append("")
+ for technique in state.mitre_mappings:
+ cleaned = _md_escape(technique).strip()
+ if cleaned:
+ lines.append(f"- `{cleaned}`")
+ lines.append("")
+
+ # 6. Proposed actions --------------------------------------------------
+ actions_lines = _proposed_actions_table(state.proposed_actions)
+ if actions_lines:
+ lines.append("## Proposed Actions")
+ lines.append("")
+ lines.extend(actions_lines)
+ lines.append("")
+
+ # 7. Errors ------------------------------------------------------------
+ if state.error:
+ lines.append("## Errors")
+ lines.append("")
+ lines.append(f"```\n{_md_escape(state.error)}\n```")
+ lines.append("")
+
+ # 8. Footer ------------------------------------------------------------
+ generated_at = (state.completed_at or datetime.utcnow()).strftime("%Y-%m-%d %H:%M UTC")
+ lines.append(f"_Generated by AiSOC router on {generated_at}_")
+
+ return "\n".join(lines).rstrip() + "\n"
+
+
+def render_router_report_html(report_md: str, *, case_id: str) -> str:
+ """Convert a router-generated Markdown report into a styled HTML document.
+
+ Uses the optional ``markdown`` package (with ``tables`` + ``fenced_code``
+ extensions enabled) when available; falls back to wrapping the source
+ in ``<pre>`` so the artifact still ships even if the dependency is
+ missing in a minimal substrate runtime.
+
+ The Markdown input is produced by :func:`render_router_report_md`,
+ which HTML-escapes every value sourced from state before
+ interpolation, so adversary-controlled finding / action / error
+ text reaches the renderer as literal characters rather than tags.
+ The ``<pre>``-fallback branch escapes the body for the same reason.
+ The page title and case identifier are also escaped here so an
+ operator-supplied case ID can never break out of the ``<title>``.
+ """
+ try:
+ import markdown
+
+ body = markdown.markdown(report_md, extensions=["tables", "fenced_code"])
+ except ImportError:
+ # Fallback: keep the report ship-able even when ``markdown`` is
+ # unavailable. The unit tests exercise both branches. We escape
+ # the source here because the upstream Markdown writer escapes
+ # for the ``markdown.markdown`` path but a raw ``<pre>`` wrap
+ # would leak HTML through unchanged.
+ body = f"<pre>{html.escape(report_md)}</pre>"
+
+ safe_case_id = html.escape(str(case_id), quote=True)
+ timestamp = datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC")
+ return (
+ "<!DOCTYPE html>\n"
+ '<html lang="en">\n'
+ "<head>\n"
+ '<meta charset="utf-8"/>\n'
+ f"<title>AiSOC Incident Report \u2014 {safe_case_id}</title>\n"
+ "<style>\n"
+ " body { font-family: 'Segoe UI', Arial, sans-serif; max-width: 960px; margin: 40px auto; color: #1a1a1a; }\n"
+ " h1 { color: #c0392b; }\n"
+ " h2 { color: #2c3e50; border-bottom: 1px solid #eee; padding-bottom: 4px; }\n"
+ " table { border-collapse: collapse; width: 100%; }\n"
+ " th, td { border: 1px solid #ddd; padding: 8px; }\n"
+ " th { background: #2c3e50; color: white; }\n"
+ " code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; }\n"
+ " pre { background: #f4f4f4; padding: 16px; overflow-x: auto; border-radius: 4px; }\n"
+ " .footer { color: #999; font-size: 0.8em; margin-top: 40px; }\n"
+ "</style>\n"
+ "</head>\n"
+ "<body>\n"
+ f"{body}\n"
+ f'<div class="footer">Generated by AiSOC on {timestamp}</div>\n'
+ "</body>\n"
+ "</html>\n"
+ )
+
+
+def render_router_report(
+ state: InvestigationState,
+ *,
+ info: dict[str, Any] | None = None,
+) -> tuple[str, str]:
+ """Convenience wrapper — render both Markdown and HTML in one call.
+
+ Returns ``(report_md, report_html)`` for the streaming surface to
+ ship as ``done`` event fields and persist as ledger artifacts.
+ """
+ md = render_router_report_md(state, info=info)
+ html = render_router_report_html(md, case_id=str(state.incident_id))
+ return md, html
diff --git a/services/agents/app/orchestrator/router.py b/services/agents/app/orchestrator/router.py
index 49f13fa61..af6d43aa7 100644
--- a/services/agents/app/orchestrator/router.py
+++ b/services/agents/app/orchestrator/router.py
@@ -54,7 +54,8 @@ import asyncio
import os
import time
import uuid
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable
+from datetime import datetime
from typing import Any
import structlog
@@ -395,6 +396,189 @@ async def _run_parallel(state: InvestigationState, signals: list[str]) -> Invest
return _summarise_response(joined)
+# ---------------------------------------------------------------------------
+# Streaming helpers — used by ``RouterOrchestrator.stream()``
+# ---------------------------------------------------------------------------
+
+
+def _state_snapshot(state: InvestigationState) -> dict[str, Any]:
+ """Capture the volatile slots of ``state`` for inter-step diffing.
+
+ The router's stream surface emits a ``step`` event after every internal
+ stage (auto-triage, each sub-agent, join, responder). To describe what
+ that stage actually *did* we snapshot before/after and diff the four
+ growable slots (findings, MITRE, actions) plus the verdict/confidence
+ pair. The snapshot stays cheap — counts only — because the full state
+ rides on the ``done`` event at the end of the run anyway.
+ """
+ return {
+ "findings": len(state.findings),
+ "mitre": len(state.mitre_mappings),
+ "actions": len(state.proposed_actions),
+ "verdict": state.verdict,
+ "confidence": state.confidence,
+ }
+
+
+def _summarise_diff(
+ stage: str,
+ pre: dict[str, Any],
+ post: dict[str, Any],
+ *,
+ verdict: str | None,
+ confidence: float,
+) -> str:
+ """Render a one-line, human-readable summary of a stage transition.
+
+ Used as the ``summary`` field on the ``step`` event so a SOC analyst
+ watching the live stream sees which stage produced what (e.g.
+ ``"identity | +2 findings | +1 MITRE | verdict=true_positive | confidence=0.82"``).
+ """
+ fragments: list[str] = [stage]
+ df = post["findings"] - pre["findings"]
+ dm = post["mitre"] - pre["mitre"]
+ da = post["actions"] - pre["actions"]
+ if df:
+ fragments.append(f"+{df} findings" if df > 0 else f"{df} findings")
+ if dm:
+ fragments.append(f"+{dm} MITRE" if dm > 0 else f"{dm} MITRE")
+ if da:
+ fragments.append(f"+{da} actions" if da > 0 else f"{da} actions")
+ fragments.append(f"verdict={verdict or 'uncertain'}")
+ try:
+ fragments.append(f"confidence={float(confidence):.2f}")
+ except (TypeError, ValueError):
+ fragments.append("confidence=0.00")
+ return " | ".join(fragments)
+
+
+def _serialise_action(action: Any) -> dict[str, Any]:
+ """Convert a :class:`ProposedAction` into a JSON-safe dict for ``done``.
+
+ Falls back to a minimal shape if ``model_dump`` is unavailable so a
+ stray non-Pydantic object on ``state.proposed_actions`` doesn't break
+ the terminal event.
+ """
+ if hasattr(action, "model_dump"):
+ try:
+ return action.model_dump(mode="json")
+ except Exception: # noqa: BLE001
+ pass
+ return {
+ "action_type": getattr(action, "action_type", "unknown"),
+ "target": getattr(action, "target", ""),
+ "rationale": getattr(action, "rationale", ""),
+ }
+
+
+def _build_done_event(
+ state: InvestigationState,
+ *,
+ report_md: str,
+ report_html: str,
+ case_id: str,
+ run_id: uuid.UUID,
+ topology: str,
+ signals: list[str],
+ auto_closed: bool,
+ wall_clock_ms: float,
+) -> dict[str, Any]:
+ """Synthesise the terminal ``done`` event payload.
+
+ The state shape on this event is the router's flat
+ :class:`InvestigationState` (no per-agent ``recon`` / ``forensic`` /
+ ``responder`` blocks — those belong to the investigator pipeline).
+ The future ``/investigate`` swap will adapt this shape on the API
+ boundary; this PR only ships the substrate.
+ """
+ state.completed_at = state.completed_at or datetime.utcnow()
+ status = state.status.value if hasattr(state.status, "value") else str(state.status)
+ return {
+ "type": "done",
+ "case_id": case_id,
+ "run_id": str(run_id),
+ "state": {
+ "status": status,
+ "verdict": state.verdict,
+ "confidence": state.confidence,
+ "confidence_basis": list(state.confidence_basis),
+ "findings": list(state.findings),
+ "mitre_mappings": list(state.mitre_mappings),
+ "proposed_actions": [_serialise_action(a) for a in state.proposed_actions],
+ "report_md": report_md,
+ "report_html": report_html,
+ "started_at": state.started_at.isoformat() if state.started_at else None,
+ "completed_at": state.completed_at.isoformat() if state.completed_at else None,
+ "error": state.error,
+ },
+ "info": {
+ "topology": topology,
+ "signals": list(signals),
+ "auto_closed": auto_closed,
+ "wall_clock_ms": wall_clock_ms,
+ },
+ }
+
+
+async def _persist_report_artifact(
+ ledger_module: Any,
+ *,
+ run_id: uuid.UUID,
+ tenant_id: uuid.UUID | None,
+ report_md: str,
+) -> None:
+ """Best-effort persistence of the Markdown report as a ledger artifact.
+
+ Ledger writes are advisory: a failure here must not block the live
+ stream. The ``report_html`` companion isn't persisted — consumers can
+ re-render it deterministically from ``report_md`` via
+ :func:`app.orchestrator.report.render_router_report_html`.
+ """
+ if tenant_id is None or not report_md:
+ return
+ try:
+ await ledger_module.record_artifact(
+ run_id=run_id,
+ tenant_id=tenant_id,
+ kind="report_md",
+ content=report_md,
+ )
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "router.stream.ledger_artifact_failed",
+ run_id=str(run_id),
+ error=str(exc),
+ )
+
+
+async def _complete_run_safe(
+ ledger_module: Any,
+ *,
+ run_id: uuid.UUID,
+ tenant_id: uuid.UUID | None,
+ status: str,
+ error: str | None,
+ iterations: int,
+) -> None:
+ """Best-effort finalisation of the ledger row."""
+ if tenant_id is None:
+ return
+ try:
+ await ledger_module.complete_run(
+ run_id=run_id,
+ tenant_id=tenant_id,
+ status=status,
+ error=error,
+ iterations=iterations,
+ )
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "router.stream.ledger_complete_failed",
+ run_id=str(run_id),
+ error=str(exc),
+ )
+
+
# ---------------------------------------------------------------------------
# Public orchestrator
# ---------------------------------------------------------------------------
@@ -503,6 +687,410 @@ class RouterOrchestrator:
)
return state, info
+ async def stream(
+ self,
+ state: InvestigationState,
+ *,
+ topology: str | None = None,
+ ) -> AsyncIterator[dict[str, Any]]:
+ """Execute the topology and yield ``step`` / ``done`` events.
+
+ Mirrors
+ :meth:`app.investigator.orchestrator.InvestigatorOrchestrator.stream`'s
+ event surface so the same WebSocket layer can carry router runs once
+ ``/investigate`` is swapped over. The terminal ``done`` event carries
+ a deterministically-rendered Markdown + HTML report and the full
+ :class:`InvestigationState` payload; no extra LLM call is issued
+ beyond the four sub-agents the router already invokes.
+
+ Ledger writes (``start_run`` / ``record_event`` / ``record_artifact``
+ / ``complete_run``) are best-effort: a database outage degrades
+ observability but never blocks the stream.
+ """
+ # Import locally so a missing asyncpg in unit tests doesn't break the
+ # module import path. Matches InvestigatorOrchestrator.stream.
+ from app.investigator import ledger as ledger_module
+ from app.orchestrator.report import render_router_report
+
+ if topology is None:
+ mode = "parallel" if is_parallel_topology_enabled() else "sequential"
+ else:
+ mode = topology
+ if mode not in {"parallel", "sequential"}:
+ raise ValueError(f"unknown topology: {mode!r}")
+
+ run_id = uuid.uuid4()
+ state.status = AgentStatus.RUNNING
+ state.iteration_count = max(state.iteration_count, 0)
+ state.started_at = state.started_at or datetime.utcnow()
+
+ t0 = time.perf_counter()
+ seq = 0
+ tenant_id: uuid.UUID | None = None
+
+ # ------------------------------------------------------------------
+ # Ledger: open the run row (best-effort).
+ # ------------------------------------------------------------------
+ try:
+ tenant_id = await ledger_module.start_run(
+ run_id=run_id,
+ case_id=state.incident_id,
+ tenant_ref=state.tenant_id or "default",
+ alert_summary=state.alert_summary or "",
+ raw_alert=state.raw_alert or {},
+ model_used=f"router:{mode}",
+ )
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "router.stream.ledger_start_failed",
+ run_id=str(run_id),
+ error=str(exc),
+ )
+ tenant_id = None
+
+ async def _yield_step(
+ *,
+ agent: str,
+ summary: str,
+ pre: dict[str, Any] | None,
+ post: dict[str, Any],
+ payload: dict[str, Any] | None = None,
+ duration_ms: float = 0.0,
+ ) -> dict[str, Any]:
+ """Build, persist, and return a ``step`` event payload.
+
+ The closure captures ``seq``-by-reference via the outer scope
+ via a ``nonlocal``-style list trick to keep the call sites
+ readable.
+ """
+ nonlocal seq
+ seq += 1
+ event = {
+ "type": "step",
+ "seq": seq,
+ "agent": agent,
+ "summary": summary,
+ "delta": (
+ {
+ "findings": post["findings"] - (pre["findings"] if pre else 0),
+ "mitre": post["mitre"] - (pre["mitre"] if pre else 0),
+ "actions": post["actions"] - (pre["actions"] if pre else 0),
+ }
+ if pre is not None
+ else {
+ "findings": post["findings"],
+ "mitre": post["mitre"],
+ "actions": post["actions"],
+ }
+ ),
+ "verdict": post["verdict"],
+ "confidence": post["confidence"],
+ "duration_ms": round(duration_ms, 2),
+ }
+ if tenant_id is not None:
+ try:
+ await ledger_module.record_event(
+ run_id=run_id,
+ tenant_id=tenant_id,
+ seq=seq,
+ kind="step",
+ agent=agent,
+ summary=summary,
+ payload=payload or {},
+ duration_ms=int(duration_ms),
+ )
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "router.stream.ledger_event_failed",
+ run_id=str(run_id),
+ seq=seq,
+ agent=agent,
+ error=str(exc),
+ )
+ return event
+
+ # ------------------------------------------------------------------
+ # Stage 1: auto-triage.
+ # ------------------------------------------------------------------
+ try:
+ pre = _state_snapshot(state)
+ stage_t0 = time.perf_counter()
+ state = await _run_auto_triage_step(state)
+ stage_ms = (time.perf_counter() - stage_t0) * 1000.0
+ post = _state_snapshot(state)
+ yield await _yield_step(
+ agent="auto_triage",
+ summary=_summarise_diff(
+ "auto_triage",
+ pre,
+ post,
+ verdict=state.verdict,
+ confidence=state.confidence,
+ ),
+ pre=pre,
+ post=post,
+ payload={"verdict": state.verdict, "confidence": state.confidence},
+ duration_ms=stage_ms,
+ )
+ except Exception as exc: # noqa: BLE001
+ state.status = AgentStatus.FAILED
+ state.error = f"auto_triage failed: {exc}"
+ logger.exception("router.stream.auto_triage_failed", run_id=str(run_id))
+
+ # ------------------------------------------------------------------
+ # Early exit: auto-triage closed the alert.
+ # ------------------------------------------------------------------
+ if state.status == AgentStatus.COMPLETED:
+ elapsed_ms = (time.perf_counter() - t0) * 1000.0
+ report_md, report_html = render_router_report(state)
+ await _persist_report_artifact(
+ ledger_module,
+ run_id=run_id,
+ tenant_id=tenant_id,
+ report_md=report_md,
+ )
+ await _complete_run_safe(
+ ledger_module,
+ run_id=run_id,
+ tenant_id=tenant_id,
+ status="completed",
+ error=None,
+ iterations=max(state.iteration_count, 1),
+ )
+ yield _build_done_event(
+ state,
+ report_md=report_md,
+ report_html=report_html,
+ case_id=state.incident_id,
+ run_id=run_id,
+ topology=mode,
+ signals=[],
+ auto_closed=True,
+ wall_clock_ms=elapsed_ms,
+ )
+ logger.info(
+ "router.stream.auto_closed",
+ run_id=str(run_id),
+ topology=mode,
+ wall_clock_ms=round(elapsed_ms, 2),
+ )
+ return
+
+ # ------------------------------------------------------------------
+ # Stage 2: signal classification.
+ # ------------------------------------------------------------------
+ try:
+ pre = _state_snapshot(state)
+ stage_t0 = time.perf_counter()
+ signals = classify_signals(state)
+ state.add_finding(f"Router: classified signals={signals}, topology={mode}")
+ stage_ms = (time.perf_counter() - stage_t0) * 1000.0
+ post = _state_snapshot(state)
+ yield await _yield_step(
+ agent="router",
+ summary=f"router | signals={signals} | topology={mode}",
+ pre=pre,
+ post=post,
+ payload={"signals": list(signals), "topology": mode},
+ duration_ms=stage_ms,
+ )
+ except Exception as exc: # noqa: BLE001
+ state.status = AgentStatus.FAILED
+ state.error = f"router classification failed: {exc}"
+ signals = []
+ logger.exception("router.stream.classify_failed", run_id=str(run_id))
+
+ # ------------------------------------------------------------------
+ # Stage 3: sub-agent fan-out — emit one step per agent.
+ # ------------------------------------------------------------------
+ branch_states: list[InvestigationState] = []
+ if signals:
+ if mode == "parallel":
+ # Launch all sub-agents concurrently but yield step events
+ # in completion order via ``as_completed``. Each branch sees
+ # a deep copy of the pre-router state — matching the join
+ # contract in ``_run_parallel``.
+ runners = [_resolve_runner(s) for s in signals]
+ branch_inputs = [state.model_copy(deep=True) for _ in runners]
+ pre_state = _state_snapshot(state)
+
+ async def _wrap(idx: int, signal: str, runner: _SubAgentRunner, branch: InvestigationState):
+ bt0 = time.perf_counter()
+ try:
+ result = await runner(branch)
+ except Exception as exc: # noqa: BLE001
+ logger.exception(
+ "router.stream.subagent_failed",
+ run_id=str(run_id),
+ agent=signal,
+ )
+ branch.add_finding(f"{signal} agent failed: {exc}")
+ result = branch
+ return idx, signal, result, (time.perf_counter() - bt0) * 1000.0
+
+ tasks = [
+ asyncio.create_task(_wrap(i, s, r, b)) for i, (s, r, b) in enumerate(zip(signals, runners, branch_inputs, strict=False))
+ ]
+ results_by_idx: dict[int, InvestigationState] = {}
+ for coro in asyncio.as_completed(tasks):
+ idx, signal, result, branch_ms = await coro
+ results_by_idx[idx] = result
+ branch_post = _state_snapshot(result)
+ yield await _yield_step(
+ agent=signal,
+ summary=_summarise_diff(
+ signal,
+ pre_state,
+ branch_post,
+ verdict=result.verdict,
+ confidence=result.confidence,
+ ),
+ pre=pre_state,
+ post=branch_post,
+ payload={
+ "signal": signal,
+ "verdict": result.verdict,
+ "confidence": result.confidence,
+ },
+ duration_ms=branch_ms,
+ )
+ # Preserve declared signal order for the join.
+ branch_states = [results_by_idx[i] for i in range(len(signals))]
+ else:
+ for signal in signals:
+ runner = _resolve_runner(signal)
+ branch_state = state.model_copy(deep=True)
+ pre_branch = _state_snapshot(branch_state)
+ bt0 = time.perf_counter()
+ try:
+ result = await runner(branch_state)
+ except Exception as exc: # noqa: BLE001
+ logger.exception(
+ "router.stream.subagent_failed",
+ run_id=str(run_id),
+ agent=signal,
+ )
+ branch_state.add_finding(f"{signal} agent failed: {exc}")
+ result = branch_state
+ branch_ms = (time.perf_counter() - bt0) * 1000.0
+ branch_post = _state_snapshot(result)
+ yield await _yield_step(
+ agent=signal,
+ summary=_summarise_diff(
+ signal,
+ pre_branch,
+ branch_post,
+ verdict=result.verdict,
+ confidence=result.confidence,
+ ),
+ pre=pre_branch,
+ post=branch_post,
+ payload={
+ "signal": signal,
+ "verdict": result.verdict,
+ "confidence": result.confidence,
+ },
+ duration_ms=branch_ms,
+ )
+ branch_states.append(result)
+
+ # Join the branches back into the base state.
+ try:
+ pre = _state_snapshot(state)
+ stage_t0 = time.perf_counter()
+ state = _join_states(state, branch_states)
+ stage_ms = (time.perf_counter() - stage_t0) * 1000.0
+ post = _state_snapshot(state)
+ yield await _yield_step(
+ agent="join",
+ summary=_summarise_diff(
+ "join",
+ pre,
+ post,
+ verdict=state.verdict,
+ confidence=state.confidence,
+ ),
+ pre=pre,
+ post=post,
+ payload={"branches": len(branch_states)},
+ duration_ms=stage_ms,
+ )
+ except Exception as exc: # noqa: BLE001
+ state.status = AgentStatus.FAILED
+ state.error = f"join failed: {exc}"
+ logger.exception("router.stream.join_failed", run_id=str(run_id))
+
+ # ------------------------------------------------------------------
+ # Stage 4: responder summary (deterministic).
+ # ------------------------------------------------------------------
+ try:
+ pre = _state_snapshot(state)
+ stage_t0 = time.perf_counter()
+ state = _summarise_response(state)
+ stage_ms = (time.perf_counter() - stage_t0) * 1000.0
+ post = _state_snapshot(state)
+ yield await _yield_step(
+ agent="responder",
+ summary=_summarise_diff(
+ "responder",
+ pre,
+ post,
+ verdict=state.verdict,
+ confidence=state.confidence,
+ ),
+ pre=pre,
+ post=post,
+ payload={"verdict": state.verdict, "confidence": state.confidence},
+ duration_ms=stage_ms,
+ )
+ except Exception as exc: # noqa: BLE001
+ state.status = AgentStatus.FAILED
+ state.error = f"responder failed: {exc}"
+ logger.exception("router.stream.responder_failed", run_id=str(run_id))
+
+ # ------------------------------------------------------------------
+ # Finalise: render report, persist, emit ``done``.
+ # ------------------------------------------------------------------
+ elapsed_ms = (time.perf_counter() - t0) * 1000.0
+ if state.status != AgentStatus.FAILED:
+ state.status = AgentStatus.COMPLETED
+ state.completed_at = datetime.utcnow()
+
+ report_md, report_html = render_router_report(state)
+ await _persist_report_artifact(
+ ledger_module,
+ run_id=run_id,
+ tenant_id=tenant_id,
+ report_md=report_md,
+ )
+ await _complete_run_safe(
+ ledger_module,
+ run_id=run_id,
+ tenant_id=tenant_id,
+ status="completed" if state.status == AgentStatus.COMPLETED else "failed",
+ error=state.error,
+ iterations=max(state.iteration_count, 1),
+ )
+ yield _build_done_event(
+ state,
+ report_md=report_md,
+ report_html=report_html,
+ case_id=state.incident_id,
+ run_id=run_id,
+ topology=mode,
+ signals=signals,
+ auto_closed=False,
+ wall_clock_ms=elapsed_ms,
+ )
+ logger.info(
+ "router.stream.completed",
+ run_id=str(run_id),
+ topology=mode,
+ signals=signals,
+ wall_clock_ms=round(elapsed_ms, 2),
+ substrate=True,
+ )
+
async def run_router_investigation(
state: InvestigationState,
diff --git a/services/agents/tests/test_orchestrator_router_stream.py b/services/agents/tests/test_orchestrator_router_stream.py
new file mode 100644
index 000000000..a8990b08b
--- /dev/null
+++ b/services/agents/tests/test_orchestrator_router_stream.py
@@ -0,0 +1,431 @@
+"""
+T2.2 — RouterOrchestrator.stream() behavioural tests.
+
+These tests exercise the streaming surface that the WebSocket layer will
+ride on once ``/investigate`` is swapped over to the router. They cover:
+
+* Step / done event emission for both topologies.
+* Monotonic ``seq`` numbering across the run.
+* Deterministic Markdown + HTML report carried on ``done``.
+* Best-effort ledger persistence: ``start_run`` → multiple
+ ``record_event`` calls → ``record_artifact`` → ``complete_run``.
+* Robustness: stream completes even when the ledger is unavailable
+ (``start_run`` returns ``None``).
+* Auto-triage early exit emits exactly one step + ``done`` with
+ ``auto_closed=True``.
+
+Sub-agent runners are monkeypatched to deterministic shims that
+``asyncio.sleep`` briefly — matches the pattern in
+``test_orchestrator_parallel.py``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import uuid
+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.models.state import AgentStatus, InvestigationState # noqa: E402
+from app.orchestrator import RouterOrchestrator # noqa: E402
+
+SUBAGENT_SLEEP_MS = 10
+AUTO_TRIAGE_SLEEP_MS = 5
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def _multi_signal_incident() -> InvestigationState:
+ """Phishing → identity → cloud → insider, all four signals triggered."""
+ return InvestigationState(
+ incident_id=uuid4(),
+ tenant_id=uuid4(),
+ alert_summary=(
+ "INC-PH-LATERAL-STREAM: Spear-phishing with OAuth consent led to "
+ "credential theft on aws_iam role; impossible-travel login from "
+ "Berlin then bulk download to attacker infra."
+ ),
+ raw_alert={
+ "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",
+ "source_geo": "Berlin, DE",
+ "auth_method": "saml",
+ "mfa_status": "challenged",
+ "cloud_provider": "aws",
+ "region": "eu-west-1",
+ "account_id": "111122223333",
+ "resource_arn": "arn:aws:s3:::corp-backups",
+ "principal_arn": "arn:aws:iam::111122223333:role/DataAnalyst",
+ "data_volume_mb": 4096,
+ "file_count": 871,
+ "destination_domain": "attacker[.]example",
+ "is_off_hours": True,
+ },
+ status=AgentStatus.PENDING,
+ )
+
+
+def _patch_runners(monkeypatch: pytest.MonkeyPatch, *, auto_close: bool = False) -> dict[str, list[str]]:
+ """Replace the five LLM-backed runners with deterministic shims.
+
+ Mirrors the helper in ``test_orchestrator_parallel.py`` but with the
+ shorter sleep budget appropriate to a streaming test (we care about
+ correctness, not wall-clock ratios).
+ """
+ call_log: dict[str, list[str]] = {
+ "auto_triage": [],
+ "phishing": [],
+ "identity": [],
+ "cloud": [],
+ "insider": [],
+ }
+
+ async def fake_auto_triage(state: InvestigationState) -> InvestigationState:
+ await asyncio.sleep(AUTO_TRIAGE_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 + 0.05 * len(call_log[name]))
+ call_log[name].append(str(state.incident_id))
+ return state
+
+ return _runner
+
+ fake_phishing = _make_runner("phishing", "T1566.001")
+ fake_identity = _make_runner("identity", "T1078")
+ fake_cloud = _make_runner("cloud", "T1078.004")
+ fake_insider = _make_runner("insider", "T1567.002")
+
+ 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", fake_phishing),
+ ("app.agents.phishing_agent.run_phishing", fake_phishing),
+ ("app.agents.run_identity", fake_identity),
+ ("app.agents.identity_agent.run_identity", fake_identity),
+ ("app.agents.run_cloud", fake_cloud),
+ ("app.agents.cloud_agent.run_cloud", fake_cloud),
+ ("app.agents.run_insider_threat", fake_insider),
+ ("app.agents.insider_threat_agent.run_insider_threat", fake_insider),
+ ]
+ for path, fn in targets:
+ monkeypatch.setattr(path, fn, raising=False)
+
+ return call_log
+
+
+class _LedgerSpy:
+ """Records every ledger interaction so the test can assert ordering.
+
+ Each entry is ``(method, kwargs)`` in call order. ``start_run``
+ returns a fixed tenant UUID so downstream writes can proceed.
+ """
+
+ def __init__(self, *, tenant_id: UUID | None) -> None:
+ self.calls: list[tuple[str, dict[str, Any]]] = []
+ self._tenant_id = tenant_id
+
+ async def start_run(self, **kwargs: Any) -> UUID | None:
+ self.calls.append(("start_run", kwargs))
+ return self._tenant_id
+
+ async def record_event(self, **kwargs: Any) -> UUID | None:
+ self.calls.append(("record_event", kwargs))
+ return uuid.uuid4() if self._tenant_id is not None else None
+
+ async def record_artifact(self, **kwargs: Any) -> UUID | None:
+ self.calls.append(("record_artifact", kwargs))
+ return uuid.uuid4() if self._tenant_id is not None else None
+
+ async def complete_run(self, **kwargs: Any) -> None:
+ self.calls.append(("complete_run", kwargs))
+
+ def methods_in_order(self) -> list[str]:
+ return [m for m, _ in self.calls]
+
+
+def _install_ledger_spy(
+ monkeypatch: pytest.MonkeyPatch,
+ *,
+ tenant_id: UUID | None,
+) -> _LedgerSpy:
+ """Replace the ledger surface that ``RouterOrchestrator.stream`` imports."""
+ spy = _LedgerSpy(tenant_id=tenant_id)
+ import app.investigator.ledger as ledger_module
+
+ monkeypatch.setattr(ledger_module, "start_run", spy.start_run, raising=True)
+ monkeypatch.setattr(ledger_module, "record_event", spy.record_event, raising=True)
+ monkeypatch.setattr(ledger_module, "record_artifact", spy.record_artifact, raising=True)
+ monkeypatch.setattr(ledger_module, "complete_run", spy.complete_run, raising=True)
+ return spy
+
+
+async def _collect(stream) -> list[dict[str, Any]]:
+ """Drain an async iterator into a list."""
+ return [event async for event in stream]
+
+
+# ---------------------------------------------------------------------------
+# Step / done event surface
+# ---------------------------------------------------------------------------
+
+
+async def test_stream_emits_step_events_per_stage_parallel(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Parallel topology emits: auto_triage, router, 4×sub-agent, join, responder, done."""
+ _patch_runners(monkeypatch)
+ _install_ledger_spy(monkeypatch, tenant_id=None) # no ledger writes; just exercise streaming
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ types = [e["type"] for e in events]
+ assert types[-1] == "done", f"final event must be 'done', got {types}"
+ assert types[:-1] == ["step"] * (len(types) - 1), f"all non-terminal events must be 'step', got {types}"
+
+ step_agents = [e["agent"] for e in events if e["type"] == "step"]
+ # The first two stages are deterministically ordered.
+ assert step_agents[0] == "auto_triage"
+ assert step_agents[1] == "router"
+ # Then a permutation of the four sub-agents (order depends on which
+ # task ``as_completed`` yields first — sleeps are equal so it's
+ # scheduling-dependent).
+ subagent_window = step_agents[2:6]
+ assert set(subagent_window) == {"phishing", "identity", "cloud", "insider"}, subagent_window
+ # Then join and responder.
+ assert step_agents[6] == "join"
+ assert step_agents[7] == "responder"
+ assert len(step_agents) == 8
+
+
+async def test_stream_emits_step_events_per_stage_sequential(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Sequential topology emits sub-agent steps in declared signal order."""
+ _patch_runners(monkeypatch)
+ _install_ledger_spy(monkeypatch, tenant_id=None)
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="sequential"))
+
+ step_agents = [e["agent"] for e in events if e["type"] == "step"]
+ assert step_agents == [
+ "auto_triage",
+ "router",
+ "phishing",
+ "identity",
+ "cloud",
+ "insider",
+ "join",
+ "responder",
+ ]
+ assert events[-1]["type"] == "done"
+
+
+async def test_stream_seq_is_monotonic(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Every step carries a strictly-increasing ``seq`` starting from 1."""
+ _patch_runners(monkeypatch)
+ _install_ledger_spy(monkeypatch, tenant_id=None)
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ step_seqs = [e["seq"] for e in events if e["type"] == "step"]
+ assert step_seqs == list(range(1, len(step_seqs) + 1)), step_seqs
+
+
+# ---------------------------------------------------------------------------
+# Done event payload
+# ---------------------------------------------------------------------------
+
+
+async def test_stream_done_carries_report_and_state(monkeypatch: pytest.MonkeyPatch) -> None:
+ """``done`` event must carry both report formats plus the final state."""
+ _patch_runners(monkeypatch)
+ _install_ledger_spy(monkeypatch, tenant_id=None)
+
+ state = _multi_signal_incident()
+ incident_id = state.incident_id
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ done = events[-1]
+ assert done["type"] == "done"
+ assert done["case_id"] == incident_id
+ assert UUID(done["run_id"]) # parses as UUID
+
+ # State payload — covers the fields the WebSocket layer surfaces.
+ inner = done["state"]
+ assert inner["status"] == "completed"
+ assert inner["verdict"] == "true_positive"
+ assert inner["confidence"] > 0.0
+ assert inner["report_md"], "report_md must be non-empty"
+ assert inner["report_html"], "report_html must be non-empty"
+ # Report should mention the case id so analysts can cross-ref.
+ assert str(incident_id) in inner["report_md"]
+ assert "<html" in inner["report_html"].lower()
+ # MITRE techniques from the four sub-agents survive the join.
+ assert set(inner["mitre_mappings"]) == {"T1566.001", "T1078", "T1078.004", "T1567.002"}
+
+ # Telemetry block.
+ info = done["info"]
+ assert info["topology"] == "parallel"
+ assert set(info["signals"]) == {"phishing", "identity", "cloud", "insider"}
+ assert info["auto_closed"] is False
+ assert info["wall_clock_ms"] >= 0
+
+
+# ---------------------------------------------------------------------------
+# Ledger ordering
+# ---------------------------------------------------------------------------
+
+
+async def test_stream_ledger_calls_in_order(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Ledger sees start_run → N×record_event → record_artifact → complete_run."""
+ _patch_runners(monkeypatch)
+ tenant_id = uuid.uuid4()
+ spy = _install_ledger_spy(monkeypatch, tenant_id=tenant_id)
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ methods = spy.methods_in_order()
+ # Boundaries: must open with start_run and close with complete_run.
+ assert methods[0] == "start_run"
+ assert methods[-1] == "complete_run"
+ # record_artifact lands after every record_event but before complete_run.
+ assert methods[-2] == "record_artifact"
+ # Between the bookends, only record_event is allowed.
+ middle = methods[1:-2]
+ assert middle and all(m == "record_event" for m in middle), middle
+ # One record_event per step yielded.
+ step_count = sum(1 for e in events if e["type"] == "step")
+ assert len(middle) == step_count, f"expected {step_count} events, got {len(middle)}"
+
+ # Sequence numbers on record_event match the seq carried on the stream.
+ recorded_seqs = [kw["seq"] for m, kw in spy.calls if m == "record_event"]
+ assert recorded_seqs == sorted(recorded_seqs)
+ assert recorded_seqs == list(range(1, len(recorded_seqs) + 1))
+
+ # Artifact is the Markdown report.
+ ((_, artifact_kwargs),) = (c for c in spy.calls if c[0] == "record_artifact")
+ assert artifact_kwargs["kind"] == "report_md"
+ assert artifact_kwargs["tenant_id"] == tenant_id
+ assert artifact_kwargs["content"] # non-empty
+ assert str(state.incident_id) in artifact_kwargs["content"]
+
+ # complete_run carries the terminal status.
+ ((_, complete_kwargs),) = (c for c in spy.calls if c[0] == "complete_run")
+ assert complete_kwargs["status"] == "completed"
+ assert complete_kwargs["tenant_id"] == tenant_id
+
+
+async def test_stream_continues_when_ledger_unavailable(monkeypatch: pytest.MonkeyPatch) -> None:
+ """When ``start_run`` returns ``None``, no downstream ledger writes are issued."""
+ _patch_runners(monkeypatch)
+ spy = _install_ledger_spy(monkeypatch, tenant_id=None) # start_run -> None
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ # Stream still produces step + done events.
+ assert any(e["type"] == "step" for e in events)
+ assert events[-1]["type"] == "done"
+ assert events[-1]["state"]["status"] == "completed"
+
+ # Ledger only saw the open attempt — every other helper short-circuits
+ # because tenant_id is None.
+ methods = spy.methods_in_order()
+ assert methods == ["start_run"], methods
+
+
+async def test_stream_survives_ledger_record_event_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+ """A blowing-up ``record_event`` must not break the stream."""
+ _patch_runners(monkeypatch)
+ tenant_id = uuid.uuid4()
+ spy = _install_ledger_spy(monkeypatch, tenant_id=tenant_id)
+
+ async def boom(**kwargs: Any) -> None:
+ raise RuntimeError("ledger offline")
+
+ import app.investigator.ledger as ledger_module
+
+ monkeypatch.setattr(ledger_module, "record_event", boom, raising=True)
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ # Stream completes despite every record_event raising.
+ assert events[-1]["type"] == "done"
+ assert events[-1]["state"]["status"] == "completed"
+ # complete_run still fires.
+ assert spy.methods_in_order()[-1] == "complete_run"
+
+
+# ---------------------------------------------------------------------------
+# Auto-triage early exit
+# ---------------------------------------------------------------------------
+
+
+async def test_stream_auto_close_short_circuits(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Auto-triage that closes the alert ends the run after the first step."""
+ call_log = _patch_runners(monkeypatch, auto_close=True)
+ tenant_id = uuid.uuid4()
+ spy = _install_ledger_spy(monkeypatch, tenant_id=tenant_id)
+
+ state = _multi_signal_incident()
+ events = await _collect(RouterOrchestrator().stream(state, topology="parallel"))
+
+ # No sub-agent should have run.
+ assert call_log["phishing"] == call_log["identity"] == []
+ assert call_log["cloud"] == call_log["insider"] == []
+ assert len(call_log["auto_triage"]) == 1
+
+ # Exactly one step (auto_triage), then done with auto_closed=True.
+ types = [e["type"] for e in events]
+ assert types == ["step", "done"]
+ assert events[0]["agent"] == "auto_triage"
+ assert events[1]["info"]["auto_closed"] is True
+ assert events[1]["info"]["signals"] == []
+ assert events[1]["state"]["status"] == "completed"
+
+ # Ledger sequence on the short path: start_run, one record_event,
+ # record_artifact, complete_run.
+ assert spy.methods_in_order() == [
+ "start_run",
+ "record_event",
+ "record_artifact",
+ "complete_run",
+ ]
diff --git a/services/agents/tests/test_router_report.py b/services/agents/tests/test_router_report.py
new file mode 100644
index 000000000..712868a01
--- /dev/null
+++ b/services/agents/tests/test_router_report.py
@@ -0,0 +1,355 @@
+"""
+Tests for ``app.orchestrator.report`` — router report synthesis (T2.2).
+
+Covers the deterministic Markdown + HTML render path that the
+``RouterOrchestrator.stream()`` surface will use to ship the same
+``report_md`` / ``report_html`` artifact shape the legacy
+``InvestigatorOrchestrator`` already emits.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+import pytest
+from app.models.state import (
+ ActionRisk,
+ AgentStatus,
+ InvestigationState,
+ ProposedAction,
+)
+from app.orchestrator.report import (
+ render_router_report,
+ render_router_report_html,
+ render_router_report_md,
+)
+
+
+def _build_state(**overrides) -> InvestigationState:
+ """Build a populated ``InvestigationState`` with sensible defaults.
+
+ Pinning identifiers and timestamps keeps assertions stable across runs.
+ """
+ base = {
+ "run_id": UUID("11111111-1111-1111-1111-111111111111"),
+ "incident_id": UUID("22222222-2222-2222-2222-222222222222"),
+ "tenant_id": UUID("33333333-3333-3333-3333-333333333333"),
+ "alert_summary": "Suspicious login from foreign IP",
+ "raw_alert": {"src_ip": "203.0.113.42"},
+ "findings": ["User [email protected] logged in from Russia", "Multiple failed MFA attempts"],
+ "mitre_mappings": ["T1078.004", "T1110.001"],
+ "verdict": "true_positive",
+ "confidence": 0.87,
+ "confidence_basis": ["High-entropy ASN", "Off-hours access"],
+ "status": AgentStatus.COMPLETED,
+ "started_at": datetime(2026, 5, 15, 9, 0, 0),
+ "completed_at": datetime(2026, 5, 15, 9, 2, 30),
+ }
+ base.update(overrides)
+ return InvestigationState(**base)
+
+
+def _build_action(
+ *,
+ action_type: str = "disable_user",
+ target: str = "[email protected]",
+ risk: ActionRisk = ActionRisk.HIGH,
+ requires_approval: bool = True,
+ rationale: str = "Account is showing clear takeover signals",
+) -> ProposedAction:
+ return ProposedAction(
+ action_type=action_type,
+ description=f"{action_type} for {target}",
+ risk_level=risk,
+ target=target,
+ requires_approval=requires_approval,
+ rationale=rationale,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Markdown shape
+# ---------------------------------------------------------------------------
+
+
+def test_markdown_contains_all_core_sections() -> None:
+ """A fully-populated state renders every optional section."""
+ state = _build_state(proposed_actions=[_build_action()])
+ md = render_router_report_md(
+ state,
+ info={"topology": "parallel", "signals": ["multi_agent"], "wall_clock_ms": 1234.5},
+ )
+
+ # Header references the incident id
+ assert md.startswith("# Incident Report \u2014 22222222-2222-2222-2222-222222222222")
+
+ # Each section heading is present
+ for heading in (
+ "## Summary",
+ "## Triage Rationale",
+ "## Findings",
+ "## MITRE ATT&CK Mappings",
+ "## Proposed Actions",
+ ):
+ assert heading in md, f"missing section heading: {heading}"
+
+ # Summary table picks up substrate telemetry from `info`
+ assert "| Verdict | true_positive |" in md
+ assert "| Confidence | 0.87 |" in md
+ assert "| Status | completed |" in md
+ assert "| Topology | parallel |" in md
+ assert "| Signals | multi_agent |" in md
+ assert "| Wall-clock (ms) | 1234.5 |" in md
+
+ # Findings rendered as bullets
+ assert "- User [email protected] logged in from Russia" in md
+ assert "- Multiple failed MFA attempts" in md
+
+ # MITRE techniques wrapped in inline code
+ assert "- `T1078.004`" in md
+ assert "- `T1110.001`" in md
+
+ # Proposed actions table has header + a populated row
+ assert "| # | Action | Target | Risk | Approval | Rationale |" in md
+ assert "| 1 | disable_user | [email protected] | high | yes |" in md
+
+ # Footer always emitted
+ assert "_Generated by AiSOC router on" in md
+
+
+def test_markdown_skips_optional_sections_when_empty() -> None:
+ """Sections backed by empty lists drop out cleanly."""
+ state = _build_state(
+ findings=[],
+ mitre_mappings=[],
+ confidence_basis=[],
+ proposed_actions=[],
+ )
+ md = render_router_report_md(state)
+
+ # Required sections still present
+ assert "## Summary" in md
+ # Optional sections dropped
+ assert "## Findings" not in md
+ assert "## MITRE ATT&CK Mappings" not in md
+ assert "## Triage Rationale" not in md
+ assert "## Proposed Actions" not in md
+ assert "## Errors" not in md
+
+
+def test_markdown_error_section_when_state_has_error() -> None:
+ """An error on the state surfaces as a fenced ``Errors`` section."""
+ state = _build_state(error="recon sub-agent timed out after 30s")
+ md = render_router_report_md(state)
+
+ assert "## Errors" in md
+ assert "recon sub-agent timed out after 30s" in md
+ # Fenced code block (triple backticks) wraps the error
+ assert "```" in md
+
+
+def test_markdown_escapes_pipes_in_action_rationale() -> None:
+ """Pipes inside a rationale must be escaped so the table stays valid."""
+ action = _build_action(rationale="alice|bob exfiltrated\nover SSH")
+ state = _build_state(proposed_actions=[action])
+ md = render_router_report_md(state)
+
+ # Backslash-escaped pipe + newline collapsed to space
+ assert "alice\\|bob exfiltrated over SSH" in md
+ # Newline inside rationale should not break out of the table row
+ actions_lines = [line for line in md.splitlines() if line.startswith("| 1 |")]
+ assert len(actions_lines) == 1
+
+
+def test_markdown_handles_invalid_confidence_gracefully() -> None:
+ """A non-numeric confidence shouldn't crash the renderer."""
+ state = _build_state()
+ # Bypass Pydantic validation by mutating after construction
+ object.__setattr__(state, "confidence", "not-a-number") # type: ignore[arg-type]
+ md = render_router_report_md(state)
+
+ assert "| Confidence | 0.00 |" in md
+
+
+def test_markdown_renders_without_info_dict() -> None:
+ """Substrate telemetry is optional — caller may omit ``info``."""
+ state = _build_state()
+ md = render_router_report_md(state)
+
+ assert "## Summary" in md
+ # Topology / signals / wall-clock rows skipped when info is missing
+ assert "| Topology |" not in md
+ assert "| Signals |" not in md
+ assert "| Wall-clock (ms) |" not in md
+
+
+# ---------------------------------------------------------------------------
+# HTML shape
+# ---------------------------------------------------------------------------
+
+
+def test_html_wraps_markdown_with_document_chrome() -> None:
+ """The HTML output is a full document with the case id in the title."""
+ md = "# Incident Report — case-42\n\n## Summary\n\n| Field | Value |\n|---|---|\n| Verdict | tp |\n"
+ html = render_router_report_html(md, case_id="case-42")
+
+ assert html.startswith("<!DOCTYPE html>")
+ assert "<title>AiSOC Incident Report \u2014 case-42</title>" in html
+ assert "Generated by AiSOC on" in html
+ # Markdown library should turn the H1 into an <h1>
+ assert "<h1>" in html
+ # Table extension should render the pipe-table as a real HTML table
+ assert "<table>" in html
+
+
+def test_html_fallback_when_markdown_module_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+ """If ``markdown`` can't be imported we still ship a usable document."""
+ import builtins
+
+ real_import = builtins.__import__
+
+ def fake_import(name, *args, **kwargs): # type: ignore[no-untyped-def]
+ if name == "markdown":
+ raise ImportError("forced failure for test")
+ return real_import(name, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "__import__", fake_import)
+
+ md = "# Hello\n\nsome body text"
+ html = render_router_report_html(md, case_id="case-1")
+
+ # Falls back to wrapping the raw Markdown in <pre>
+ assert "<pre># Hello\n\nsome body text</pre>" in html
+ # Still produces a complete HTML document
+ assert html.startswith("<!DOCTYPE html>")
+ assert "</html>" in html
+
+
+# ---------------------------------------------------------------------------
+# Convenience wrapper
+# ---------------------------------------------------------------------------
+
+
+def test_render_router_report_returns_md_and_html() -> None:
+ """The convenience wrapper returns both artifacts in one call."""
+ state = _build_state()
+ md, html = render_router_report(state, info={"topology": "sequential"})
+
+ assert md.startswith("# Incident Report \u2014")
+ assert html.startswith("<!DOCTYPE html>")
+ # The case id flows through to the HTML title
+ assert str(state.incident_id) in html
+ # Sequential topology surfaces in the summary table
+ assert "| Topology | sequential |" in md
+
+
+# ---------------------------------------------------------------------------
+# XSS / injection regression tests (review feedback on PR #141)
+# ---------------------------------------------------------------------------
+
+
+def test_findings_with_html_tags_are_escaped() -> None:
+ """A finding containing raw HTML never reaches the rendered HTML as a tag.
+
+ State fields like ``findings`` flow from sub-agent outputs that can in
+ turn carry adversary-influenced strings from the raw alert. The report
+ pipeline (``render_router_report_md`` → ``markdown.markdown``) must
+ escape these so a payload like ``<script>alert(1)</script>`` ships as
+ literal text rather than an executable script tag.
+ """
+ payload = "<script>alert('xss')</script>"
+ state = _build_state(findings=[payload])
+
+ md, html_out = render_router_report(state)
+
+ # Markdown body keeps the escaped form, not the raw tag
+ assert "<script>" not in md
+ assert "&lt;script&gt;" in md
+ # Rendered HTML must not contain an executable script tag derived
+ # from the finding
+ assert "<script>alert" not in html_out
+ assert "&lt;script&gt;" in html_out
+
+
+def test_error_field_with_html_is_escaped() -> None:
+ """``state.error`` is HTML-escaped before going into the fenced code block."""
+ state = _build_state(error="<img src=x onerror=alert(1)>")
+
+ md, html_out = render_router_report(state)
+
+ assert "<img src=x" not in md
+ assert "&lt;img src=x onerror=alert(1)&gt;" in md
+ assert "<img src=x onerror=" not in html_out
+
+
+def test_proposed_action_target_with_html_is_escaped() -> None:
+ """Every action-table cell — not just ``rationale`` — gets escaped."""
+ bad_action = ProposedAction(
+ action_type="isolate_host",
+ description="isolate host",
+ target="<svg onload=alert(1)>",
+ risk_level=ActionRisk.HIGH,
+ requires_approval=True,
+ rationale="standard",
+ )
+ state = _build_state(proposed_actions=[bad_action])
+
+ md, html_out = render_router_report(state)
+
+ assert "<svg onload" not in md
+ assert "&lt;svg onload=alert(1)&gt;" in md
+ assert "<svg onload" not in html_out
+
+
+def test_proposed_action_target_with_pipe_does_not_break_table() -> None:
+ """A ``|`` in any cell — not just ``rationale`` — gets escaped."""
+ bad_action = ProposedAction(
+ action_type="disable_user|forever",
+ description="disable user account",
+ target="alice|bob",
+ risk_level=ActionRisk.MEDIUM,
+ requires_approval=False,
+ rationale="cleanup",
+ )
+ state = _build_state(proposed_actions=[bad_action])
+
+ md = render_router_report_md(state)
+
+ assert "disable_user\\|forever" in md
+ assert "alice\\|bob" in md
+
+
+def test_html_fallback_branch_escapes_body(monkeypatch) -> None:
+ """The ``ImportError`` fallback branch must still escape adversary HTML.
+
+ The previous implementation wrapped raw Markdown in ``<pre>`` with no
+ escaping; a finding containing ``<script>`` would have reached the
+ browser intact when ``markdown`` was unavailable in the runtime.
+ """
+ import builtins
+
+ real_import = builtins.__import__
+
+ def fake_import(name, *args, **kwargs):
+ if name == "markdown":
+ raise ImportError("simulated missing dep")
+ return real_import(name, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "__import__", fake_import)
+
+ md = "# Hello\n\n<script>alert(1)</script>"
+ html_out = render_router_report_html(md, case_id="case-1")
+
+ assert "<script>alert(1)</script>" not in html_out
+ assert "&lt;script&gt;alert(1)&lt;/script&gt;" in html_out
+
+
+def test_case_id_with_html_is_escaped_in_title() -> None:
+ """An adversary-controlled case ID can't break out of the ``<title>``."""
+ md = "# Incident"
+ html_out = render_router_report_html(md, case_id="</title><script>alert(1)</script>")
+
+ assert "</title><script>alert(1)</script>" not in html_out
+ # Closing tag of title is the one the renderer itself emits
+ assert "&lt;/title&gt;&lt;script&gt;alert(1)&lt;/script&gt;" in html_out