Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(agents): RouterOrchestrator gains stream + ledger + report (T2.2, v8.0) (#141)
Beenu Arora00cc9ee0f2df
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 landeddiff --git a/services/agents/app/orchestrator/report.py b/services/agents/app/orchestrator/report.pynew file mode 100644index 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, htmldiff --git a/services/agents/app/orchestrator/router.py b/services/agents/app/orchestrator/router.pyindex 49f13fa61..af6d43aa7 100644--- a/services/agents/app/orchestrator/router.py+++ b/services/agents/app/orchestrator/router.py@@ -54,7 +54,8 @@ import asyncioimport osimport timeimport uuid-from collections.abc import Awaitable, Callable+from collections.abc import AsyncIterator, Awaitable, Callable+from datetime import datetimefrom typing import Anyimport structlog@@ -395,6 +396,189 @@ async def _run_parallel(state: InvestigationState, signals: list[str]) -> Investreturn _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.pynew file mode 100644index 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.pynew file mode 100644index 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 "<script>" in md+ # Rendered HTML must not contain an executable script tag derived+ # from the finding+ assert "<script>alert" not in html_out+ assert "<script>" 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 "<img src=x onerror=alert(1)>" 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 "<svg onload=alert(1)>" 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 "<script>alert(1)</script>" 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 "</title><script>alert(1)</script>" in html_out