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): scored specialist planner for bounded agent selection (Wave 4b) (#551)

Beenu Arorafb36434f0921
diff --git a/services/agents/app/orchestrator/planner.py b/services/agents/app/orchestrator/planner.py
new file mode 100644
index 000000000..ade849d12
--- /dev/null
+++ b/services/agents/app/orchestrator/planner.py
@@ -0,0 +1,90 @@
+"""Specialist planner — scored, bounded agent selection (Wave 4b).
+
+``classify_signals`` fans out to ALL FOUR specialists whenever no keyword
+matches, and runs every keyword-matched specialist with no ranking. That is
+both imprecise (a novel alert brute-forces the whole roster) and expensive.
+
+This planner scores each specialist by weighted signal strength (raw structured
+fields count more than free-text keyword hits, and MITRE tactics add signal),
+returns the top-N scoring specialists, and on a genuinely ambiguous alert picks
+a single conservative default instead of the whole roster. It is pure and
+deterministic, so it is cheap to run ahead of the (expensive) specialist LLMs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from app.models.state import InvestigationState
+from app.orchestrator.router import (
+ _CLOUD_KEYWORDS,
+ _CLOUD_RAW_FIELDS,
+ _IDENTITY_KEYWORDS,
+ _IDENTITY_RAW_FIELDS,
+ _INSIDER_KEYWORDS,
+ _INSIDER_RAW_FIELDS,
+ _PHISHING_KEYWORDS,
+ _PHISHING_RAW_FIELDS,
+)
+
+_SPECIALISTS: dict[str, tuple[set[str], set[str]]] = {
+ "phishing": (_PHISHING_KEYWORDS, _PHISHING_RAW_FIELDS),
+ "identity": (_IDENTITY_KEYWORDS, _IDENTITY_RAW_FIELDS),
+ "cloud": (_CLOUD_KEYWORDS, _CLOUD_RAW_FIELDS),
+ "insider": (_INSIDER_KEYWORDS, _INSIDER_RAW_FIELDS),
+}
+
+# A raw structured field is a much stronger routing signal than a free-text
+# keyword mention, so it is weighted higher.
+_KEYWORD_WEIGHT = 1.0
+_RAW_FIELD_WEIGHT = 3.0
+
+# When nothing scores, route to identity first: credential/access abuse is the
+# most common cross-cutting root cause and the cheapest specialist to run.
+_DEFAULT_ON_AMBIGUOUS = "identity"
+
+
+@dataclass(frozen=True)
+class Plan:
+ specialists: list[str]
+ scores: dict[str, float]
+ ambiguous: bool = False
+ rationale: list[str] = field(default_factory=list)
+
+
+def _haystack(state: InvestigationState) -> str:
+ parts = [state.alert_summary or ""]
+ parts.extend(str(f) for f in (state.findings or []))
+ raw = state.raw_alert or {}
+ parts.append(" ".join(f"{k}:{v}" for k, v in raw.items() if isinstance(v, str | int | float)))
+ return " ".join(parts).lower()
+
+
+def plan_specialists(state: InvestigationState, *, max_agents: int = 2) -> Plan:
+ """Return the top-scoring specialists to run for this alert (bounded)."""
+ haystack = _haystack(state)
+ raw_keys = {str(k).lower() for k in (state.raw_alert or {})}
+ scores: dict[str, float] = {}
+ for name, (keywords, raw_fields) in _SPECIALISTS.items():
+ kw_hits = sum(1 for kw in keywords if kw in haystack)
+ raw_hits = len(raw_keys & {f.lower() for f in raw_fields})
+ score = kw_hits * _KEYWORD_WEIGHT + raw_hits * _RAW_FIELD_WEIGHT
+ if score > 0:
+ scores[name] = score
+
+ if not scores:
+ return Plan(
+ specialists=[_DEFAULT_ON_AMBIGUOUS],
+ scores={},
+ ambiguous=True,
+ rationale=[f"no specialist signal; conservative default '{_DEFAULT_ON_AMBIGUOUS}'"],
+ )
+
+ ranked = sorted(scores, key=lambda n: (scores[n], n), reverse=True)
+ chosen = ranked[: max(1, max_agents)]
+ return Plan(
+ specialists=chosen,
+ scores=scores,
+ ambiguous=False,
+ rationale=[f"{n}={scores[n]:.0f}" for n in ranked],
+ )
diff --git a/services/agents/tests/test_specialist_planner.py b/services/agents/tests/test_specialist_planner.py
new file mode 100644
index 000000000..47dcda913
--- /dev/null
+++ b/services/agents/tests/test_specialist_planner.py
@@ -0,0 +1,47 @@
+"""Wave 4b — scored specialist planner: bounded, ranked selection that does not
+brute-force all four specialists on an ambiguous alert."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from app.models.state import AgentStatus, InvestigationState
+from app.orchestrator.planner import plan_specialists
+
+
+def _state(summary: str = "", raw: dict | None = None) -> InvestigationState:
+ return InvestigationState(
+ incident_id=uuid4(),
+ tenant_id=uuid4(),
+ alert_summary=summary,
+ raw_alert=raw or {},
+ status=AgentStatus.PENDING,
+ )
+
+
+def test_raw_fields_outrank_keywords_and_pick_phishing():
+ plan = plan_specialists(_state("email reported", raw={"sender": "[email protected]", "subject": "urgent", "urls": ["h"]}))
+ assert plan.specialists[0] == "phishing"
+ assert plan.scores["phishing"] >= 3.0
+ assert plan.ambiguous is False
+
+
+def test_ambiguous_alert_does_not_fan_out_to_all_four():
+ plan = plan_specialists(_state("something happened with no clear signal"))
+ assert plan.ambiguous is True
+ assert plan.specialists == ["identity"]
+ assert len(plan.specialists) == 1 # NOT the whole roster
+
+
+def test_selection_is_bounded_by_max_agents():
+ # An alert that trips many specialists is still capped.
+ raw = {"sender": "a", "username": "u", "cloud_provider": "aws", "data_volume_mb": 999}
+ plan = plan_specialists(_state("phishing login to aws with large data transfer exfil", raw=raw), max_agents=2)
+ assert len(plan.specialists) == 2
+ # The two highest-scoring win.
+ assert set(plan.specialists) <= {"phishing", "identity", "cloud", "insider"}
+
+
+def test_cloud_keyword_routes_to_cloud():
+ plan = plan_specialists(_state("suspicious AWS IAM privilege escalation in the cloud console"))
+ assert "cloud" in plan.specialists