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): 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.pynew file mode 100644index 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.pynew file mode 100644index 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