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
The documented gate, a store that survives a restart, and a bot that can speak first (#735)
Beenu Aroraa4c06f163e33
diff --git a/docker-compose.yml b/docker-compose.ymlindex 7b7c880b5..23fda3ab4 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -432,6 +432,12 @@ services:# provider (unchanged behaviour).LLM_GATEWAY_URL: http://litellm:4000/v1ATTCK_DATA_PATH: /app/data/enterprise-attack.json+ # Where to post an approval card when triage raises one. Unset means+ # no ChatOps notification; the approval is still durable and visible in+ # the console and the responder app. slack-bot is a `chatops`-profile+ # service, so this only resolves when that profile is up.+ AISOC_SLACK_BOT_URL: ${AISOC_SLACK_BOT_URL:-}+ AISOC_INTERNAL_TOKEN: ${AISOC_INTERNAL_TOKEN:-}networks:- aisocrestart: unless-stopped@@ -756,6 +762,13 @@ services:AISOC_WEB_BASE_URL: ${AISOC_WEB_BASE_URL:-http://localhost:3000}AISOC_SLACK_BOT_PORT: 8089AISOC_HTTP_TIMEOUT_SECONDS: 10+ # Proactive approval cards. Empty channel disables posting, which is+ # the right default: a bot that posts into a channel nobody chose is+ # worse than one that posts nowhere.+ SLACK_APPROVALS_CHANNEL: ${SLACK_APPROVALS_CHANNEL:-}+ # Shared with the agents service, which calls /internal/approval-card.+ AISOC_INTERNAL_TOKEN: ${AISOC_INTERNAL_TOKEN:-}+ AISOC_DEV_MODE: ${AISOC_DEV_MODE:-1}networks:- aisocrestart: unless-stoppeddiff --git a/services/actions/app/api/router.py b/services/actions/app/api/router.pyindex 215178ae6..92d16d18c 100644--- a/services/actions/app/api/router.py+++ b/services/actions/app/api/router.py@@ -28,6 +28,8 @@ from app.security.authz import ()from app.security.chatops_identity import resolve_approverfrom app.security.chatops_token import ChatOpsTokenError, verify_token+from app.services import action_store+from app.services.approval_gate import apply_matrixfrom app.services.blast_radius import BlastRadiusGatefrom app.services.executor_registry import EXECUTOR_REGISTRYfrom app.services.timeline_client import TimelineClientError, post_timeline_event@@ -36,8 +38,12 @@ logger = structlog.get_logger()router = APIRouter()gate = BlastRadiusGate()-# In-memory action store (replace with DB in production)-_actions: dict[str, dict[str, Any]] = {}+# Kept as a module attribute because tests and other modules reach for it by+# name. It is now the in-memory *tier* of `app.services.action_store`, which+# persists to Postgres when a DSN is configured — a restart used to lose every+# action awaiting approval, so an analyst tapping Approve on a Slack card got+# "Action not found" for an incident that was still live.+_actions = action_store._MEMORY# Replay-protection set: action IDs that have already received a response.# Single-use enforcement is layered on top of HMAC + expiry. Anything more@@ -57,6 +63,11 @@ async def submit_action(request: ActionRequest, _auth: None = Depends(require_seraise HTTPException(status_code=403, detail=str(exc)) from excstatus, blast_radius, reason = gate.evaluate(request)+ # Second axis: confidence against the action's declared impact, under the+ # tenant's autonomy tier. The matrix that implements this was written,+ # tested, and called by nothing — so the gate the docs described was not+ # the gate that ran. It can only raise a requirement, never lower one.+ status, reason = await apply_matrix(request, status, blast_radius, reason)record = {"id": str(request.id),@@ -78,7 +89,7 @@ async def submit_action(request: ActionRequest, _auth: None = Depends(require_se# approval that silently changes what it approved is not an approval."parameters": dict(request.parameters or {}),}- _actions[str(request.id)] = record+ await action_store.save(record)# Auto-execute if approvedif status == ActionStatus.APPROVED:@@ -102,6 +113,9 @@ async def submit_action(request: ActionRequest, _auth: None = Depends(require_serecord["status"] = ActionStatus.FAILEDrecord["error"] = f"No executor found for action type: {request.action_type}"+ # Persist again so the executed status is durable, not just the pending one.+ await action_store.save(record)+logger.info("Action submitted",action_id=str(request.id),@@ -177,7 +191,7 @@ async def approve_action((``AISOC_ACTIONS_REQUIRE_APPROVER``), because separation of duties cannotbe evaluated against nobody. ChatOps callers send ``chatops_approver``(verified platform identity) and the mapping supplies the permissions."""- record = _actions.get(action_id)+ record = await action_store.get(action_id)if not record:raise HTTPException(status_code=404, detail="Action not found")if record["status"] != ActionStatus.AWAITING_APPROVAL:@@ -212,6 +226,7 @@ async def approve_action(record["status"] = ActionStatus.FAILEDrecord["error"] = "No executor available"+ await action_store.save(record)logger.info("Action approved and executed", action_id=action_id, status=record["status"])return record@@ -230,7 +245,7 @@ async def reject_action(host, and were they entitled to" had no answer — which matters as much asthe approve side during an incident review."""- record = _actions.get(action_id)+ record = await action_store.get(action_id)if not record:raise HTTPException(status_code=404, detail="Action not found")@@ -239,6 +254,7 @@ async def reject_action(record["rejected_by_user_id"] = bound.user_idrecord["status"] = ActionStatus.REJECTED+ await action_store.save(record)logger.info("Action rejected",action_id=action_id,@@ -250,7 +266,7 @@ async def reject_action(@router.get("/actions/{action_id}")async def get_action(action_id: str):"""Get action status and result."""- record = _actions.get(action_id)+ record = await action_store.get(action_id)if not record:raise HTTPException(status_code=404, detail="Action not found")return record@@ -344,10 +360,11 @@ async def chatops_callback(token: str = Query(..., min_length=8)):status_code=200,)- record = _actions.get(action_id_str)- # We still record on the timeline even if the in-memory record is gone- # (e.g. service restart). The case timeline is the durable store —- # losing the local record shouldn't lose the user's reply.+ record = await action_store.get(action_id_str)+ # We still record on the timeline even if the record is gone entirely+ # (no database configured, and this replica did not handle the submit).+ # The case timeline is durable either way — losing the local record+ # must not lose the user's reply.timeline_warning: str | None = Nonetry:diff --git a/services/actions/app/models/action.py b/services/actions/app/models/action.pyindex 9c9a59c95..1a3515e84 100644--- a/services/actions/app/models/action.py+++ b/services/actions/app/models/action.py@@ -179,6 +179,13 @@ class ActionRequest(BaseModel):rationale: str = ""auto_rollback: bool = Falserollback_after_seconds: int | None = None+ #: How sure the finding behind this action is, 0.0-1.0.+ #:+ #: The second axis of the approval matrix. ``None`` is the lowest band,+ #: not a free pass — a caller that omits it gets the most restrictive+ #: treatment, because the alternative is that a scoring bug becomes an+ #: autonomous containment.+ confidence: float | None = Field(default=None, ge=0.0, le=1.0)class ActionResult(BaseModel):diff --git a/services/actions/app/services/action_store.py b/services/actions/app/services/action_store.pynew file mode 100644index 000000000..883260f8f--- /dev/null+++ b/services/actions/app/services/action_store.py@@ -0,0 +1,134 @@+"""Where a pending action lives between submission and approval.++It lived in a module-global dict:++ # In-memory action store (replace with DB in production)+ _actions: dict[str, dict[str, Any]] = {}++Which means a restart lost every action awaiting approval, and a second+replica could not see the first one's. Both matter more here than for most+caches, because the thing being lost is a *pending containment*: an analyst+receives a Slack card, the pod is rescheduled, and the approve button returns+"Action not found" for an incident that is still live. There is no retry for+that — the agent already decided, and the record of what it wanted is gone.++Postgres when a DSN is configured, the in-memory dict when not. The fallback+is not a compromise: the unit suite has no database, and a store that cannot+run without one would push every test onto a mock of itself.++Writes are upserts on the action id, so a replay of the same submission is+idempotent rather than a duplicate pending approval.+"""++from __future__ import annotations++import json+import os+from typing import Any++import structlog++logger = structlog.get_logger()++#: Process-local fallback, and the store the unit suite exercises.+_MEMORY: dict[str, dict[str, Any]] = {}++#: Set once a DSN has been seen to work, so a database that disappears mid-run+#: surfaces as an error rather than silently reverting to per-replica memory.+_DB_CONFIRMED = False+++def _dsn() -> str | None:+ """An asyncpg-compatible DSN, or None when no database is configured.++ Accepts the SQLAlchemy spelling the API uses and the plain pgx spelling+ ``services/ingest`` uses, because both are present in deployed+ environments. Same resolution as ``tenant_policy._dsn``.+ """+ raw = (os.environ.get("DATABASE_DSN") or os.environ.get("DATABASE_URL") or "").strip()+ if not raw:+ return None+ return raw.replace("postgresql+asyncpg://", "postgresql://").replace("postgres+asyncpg://", "postgresql://")+++async def _connect(dsn: str):+ import asyncpg # noqa: PLC0415 — optional at import time; only needed with a DSN++ return await asyncpg.connect(dsn, timeout=5.0)+++async def save(record: dict[str, Any]) -> None:+ """Persist or update an action record."""+ action_id = str(record["id"])+ _MEMORY[action_id] = record++ dsn = _dsn()+ if dsn is None:+ return+ try:+ conn = await _connect(dsn)+ except Exception as exc: # noqa: BLE001 — an unreachable store must not drop the action+ logger.warning("action_store.connect_failed", action_id=action_id, error=str(exc))+ return+ try:+ await conn.execute(+ """+ INSERT INTO aisoc_action_records (id, tenant_id, status, record, created_at, updated_at)+ VALUES ($1, $2, $3, $4, now(), now())+ ON CONFLICT (id) DO UPDATE+ SET status = EXCLUDED.status,+ record = EXCLUDED.record,+ updated_at = now()+ """,+ action_id,+ str(record.get("tenant_id") or ""),+ str(record.get("status") or ""),+ json.dumps(record, default=str),+ )+ global _DB_CONFIRMED+ _DB_CONFIRMED = True+ except Exception as exc: # noqa: BLE001 — see above+ logger.warning("action_store.write_failed", action_id=action_id, error=str(exc))+ finally:+ await conn.close()+++async def get(action_id: str) -> dict[str, Any] | None:+ """Fetch an action record, preferring the durable copy.++ The in-memory copy is checked first only as a cache: on the replica that+ handled the submission it is the same object, and on any other replica it+ is absent and the database answers.+ """+ cached = _MEMORY.get(action_id)+ if cached is not None:+ return cached++ dsn = _dsn()+ if dsn is None:+ return None+ try:+ conn = await _connect(dsn)+ except Exception as exc: # noqa: BLE001+ logger.warning("action_store.connect_failed", action_id=action_id, error=str(exc))+ return None+ try:+ row = await conn.fetchrow("SELECT record FROM aisoc_action_records WHERE id = $1", action_id)+ except Exception as exc: # noqa: BLE001+ logger.warning("action_store.read_failed", action_id=action_id, error=str(exc))+ return None+ finally:+ await conn.close()++ if row is None:+ return None+ record = json.loads(row["record"])+ # Cache it so the approve path's subsequent mutation and save see one+ # object rather than two diverging copies.+ _MEMORY[action_id] = record+ return record+++def clear() -> None:+ """Drop the in-memory copy. Used by tests."""+ _MEMORY.clear()diff --git a/services/actions/app/services/approval_gate.py b/services/actions/app/services/approval_gate.pynew file mode 100644index 000000000..f079f3a7d--- /dev/null+++ b/services/actions/app/services/approval_gate.py@@ -0,0 +1,133 @@+"""The gate that actually runs on ``POST /actions``, combining both axes.++``BlastRadiusGate`` asks one question: is this verb's blast radius within the+auto-execute limit. That is a property of the verb alone, so the same answer+comes back for a 40%-confidence guess and a corroborated finding.++``approval_matrix.evaluate`` asks the other one — confidence against the+action's declared impact, under the tenant's autonomy tier — and it was+written, documented, unit-tested, listed in the claim-to-gate matrix as+GATED, and **called by nothing**. A repository-wide search for+``approval_matrix`` found the module, its own test, the contract checker and+two doc mentions. The gate the docs described was not the gate that ran.++This module runs both and takes the stricter, which is the composition rule+the matrix already states for its own three inputs: each can raise a+requirement, none can lower it. So switching it on cannot make anything+auto-execute that did not before.++Two honest limits, both logged rather than papered over:++Seven of the 25 ``ActionType`` members have no capability contract+(``ack_alert``, ``notify_slack``, ``run_playbook`` and four others). For+those the matrix has no impact to reason about and blast radius decides+alone. That is recorded at debug rather than guessed at, because inventing an+impact for an unmapped verb is how a gate starts certifying things it never+examined.++A request with no ``confidence`` is treated as the lowest band. For anything+above READ_ONLY impact that means analyst approval, which is a real tightening+of the previous behaviour and is the intended direction.+"""++from __future__ import annotations++import structlog++from app.live_actions.capability_contracts import CAPABILITY_CONTRACTS+from app.live_actions.contract import ApprovalRequirement+from app.models.action import ActionRequest, ActionStatus, BlastRadius+from app.services.approval_matrix import evaluate as evaluate_matrix++logger = structlog.get_logger()++#: Conservative default when no tenant policy can be read. Mirrors+#: ``dispatcher.configured_tier``: L1 notifies, it does not act.+_DEFAULT_TIER = "L1"+++def _tier_label(tier: object) -> str:+ """Map a ``MaturityTier`` (or anything tier-shaped) onto ``L0``..``L4``."""+ name = getattr(tier, "name", None)+ if isinstance(name, str) and name.startswith("L"):+ return name.split("_")[0]+ value = getattr(tier, "value", tier)+ if isinstance(value, int) and 0 <= value <= 4:+ return f"L{value}"+ return _DEFAULT_TIER+++async def _resolve_tier(tenant_id: object) -> str:+ """The tenant's autonomy tier, falling back to the deployment default.++ Imported lazily: ``resolve_tenant_policy`` reaches for a database, and the+ submit path has to keep working in the many tests and deployments that+ have none.+ """+ try:+ from app.services.tenant_policy import resolve_tenant_policy++ policy = await resolve_tenant_policy(tenant_id)+ except Exception as exc: # noqa: BLE001 — no policy store is a normal state+ logger.debug("approval_gate.tier_unresolved", error=str(exc))+ return _DEFAULT_TIER+ return _tier_label(getattr(policy, "tier", None))+++async def apply_matrix(+ request: ActionRequest,+ status: ActionStatus,+ blast_radius: BlastRadius,+ reason: str,+) -> tuple[ActionStatus, str]:+ """Raise the blast-radius verdict to whatever the matrix demands.++ Returns the (possibly unchanged) status and the reason that decided it.+ Never lowers: a blast-radius gate that already demands approval keeps+ demanding it whatever the confidence says.+ """+ contract = CAPABILITY_CONTRACTS.get(request.action_type.value)+ if contract is None:+ logger.debug(+ "approval_gate.no_capability_contract",+ action_type=request.action_type.value,+ note="blast radius decides alone; impact is unknown for this verb",+ )+ return status, reason++ decision = evaluate_matrix(+ impact=contract.impact,+ declared_approval=contract.approval,+ confidence=request.confidence,+ tier=await _resolve_tier(request.tenant_id),+ )++ if decision.is_blocked:+ logger.info(+ "Action prohibited by contract",+ action_type=request.action_type.value,+ impact=decision.impact.value,+ reason=decision.reason,+ )+ return ActionStatus.REJECTED, decision.reason++ if decision.requirement == ApprovalRequirement.AUTOMATIC:+ # The matrix is content. Blast radius may still have gated it, and+ # that verdict stands.+ return status, reason++ if status == ActionStatus.AWAITING_APPROVAL:+ # Already gated. Keep the matrix's reason, which names confidence and+ # impact — more use to the approver than "blast radius exceeded".+ return status, decision.reason++ logger.info(+ "Action requires approval (confidence x impact)",+ action_type=request.action_type.value,+ blast_radius=blast_radius,+ impact=decision.impact.value,+ confidence=decision.confidence,+ tier=decision.tier,+ reason=decision.reason,+ )+ return ActionStatus.AWAITING_APPROVAL, decision.reasondiff --git a/services/actions/tests/test_approval_gate_wiring.py b/services/actions/tests/test_approval_gate_wiring.pynew file mode 100644index 000000000..869279773--- /dev/null+++ b/services/actions/tests/test_approval_gate_wiring.py@@ -0,0 +1,195 @@+"""The documented gate has to be the gate that runs.++``approval_matrix.evaluate`` implements approval as confidence x impact under+the tenant's autonomy tier. It was written, documented, unit-tested and listed+in the claim-to-gate matrix as GATED — and a repository-wide search for+``approval_matrix`` found only the module, its own test, the contract checker+and two doc mentions. **Zero production callers.** ``POST /actions`` gated on+blast radius alone, which is a property of the verb, so the same answer came+back for a 40%-confidence guess and a corroborated finding.++A passing unit test on an uncalled function is indistinguishable from a+working control. These tests are about the wiring, not the matrix.+"""++from __future__ import annotations++from uuid import uuid4++import pytest+from app.live_actions.capability_contracts import CAPABILITY_CONTRACTS+from app.models.action import ActionRequest, ActionStatus, ActionType, BlastRadius+from app.services.approval_gate import apply_matrix+from app.services.blast_radius import BlastRadiusGate+++def _request(action_type: ActionType, confidence: float | None = None) -> ActionRequest:+ return ActionRequest(+ incident_id=uuid4(),+ tenant_id=uuid4(),+ action_type=action_type,+ target="WKSTN-01",+ confidence=confidence,+ )+++async def _gated(request: ActionRequest) -> tuple[ActionStatus, str]:+ status, blast_radius, reason = BlastRadiusGate().evaluate(request)+ return await apply_matrix(request, status, blast_radius, reason)+++class TestTheMatrixActuallyRuns:+ @pytest.mark.asyncio+ async def test_a_low_confidence_action_is_gated_that_blast_radius_alone_approved(self, monkeypatch: pytest.MonkeyPatch):+ """create_ticket is MINIMAL blast radius and its contract is+ AUTOMATIC, so nothing but confidence can gate it. Its declared impact+ is LOW, whose floor is 90%. At 40% the old gate approved it and the+ matrix does not."""+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L4")+ request = _request(ActionType.CREATE_TICKET, confidence=0.40)++ before, _, _ = BlastRadiusGate().evaluate(request)+ after, reason = await _gated(request)++ assert before == ActionStatus.APPROVED+ assert after == ActionStatus.AWAITING_APPROVAL+ assert "40%" in reason++ @pytest.mark.asyncio+ async def test_missing_confidence_is_the_lowest_band_not_a_free_pass(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L4")+ after, reason = await _gated(_request(ActionType.CREATE_TICKET))++ assert after == ActionStatus.AWAITING_APPROVAL+ assert "0%" in reason++ @pytest.mark.asyncio+ async def test_the_reason_names_confidence_and_impact(self, monkeypatch: pytest.MonkeyPatch):+ """'requires approval' with no reason is the kind of prompt people+ learn to click through."""+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L4")+ _, reason = await _gated(_request(ActionType.CREATE_TICKET, confidence=0.5))++ assert "low" in reason.lower()+ assert "confidence" in reason.lower()++ @pytest.mark.asyncio+ async def test_a_contract_that_demands_an_analyst_is_not_relaxed_by_confidence(self, monkeypatch: pytest.MonkeyPatch):+ """block_ip's blast radius is inside the auto-execute limit, so the+ old gate approved it outright — while its own contract says an+ analyst must sign off. That contract had no reader."""+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L4")+ request = _request(ActionType.BLOCK_IP, confidence=1.0)++ before, _, _ = BlastRadiusGate().evaluate(request)+ after, reason = await _gated(request)++ assert before == ActionStatus.APPROVED+ assert after == ActionStatus.AWAITING_APPROVAL+ assert "contract" in reason.lower()+++class TestItCanOnlyTighten:+ @pytest.mark.asyncio+ async def test_an_already_gated_action_stays_gated_at_full_confidence(self):+ """isolate_host is in APPROVAL_REQUIRED_ACTIONS. No confidence and no+ tier may lift that."""+ request = _request(ActionType.ISOLATE_HOST, confidence=1.0)++ after, _ = await _gated(request)++ assert after == ActionStatus.AWAITING_APPROVAL++ @pytest.mark.asyncio+ async def test_the_matrix_never_approves_what_blast_radius_refused(self, monkeypatch: pytest.MonkeyPatch):+ """Composition rule: each input raises, none lowers."""+ request = _request(ActionType.ISOLATE_HOST, confidence=1.0)+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L4")++ after, _ = await _gated(request)++ assert after == ActionStatus.AWAITING_APPROVAL+++class TestTheTierIsHonoured:+ @pytest.mark.asyncio+ async def test_a_high_tier_and_high_confidence_can_auto_execute(self, monkeypatch: pytest.MonkeyPatch):+ """Otherwise the gate would be a one-way ratchet that never lets+ anything through, and operators would turn it off."""+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L4")+ request = _request(ActionType.CREATE_TICKET, confidence=1.0)++ after, _ = await _gated(request)++ assert after == ActionStatus.APPROVED++ @pytest.mark.asyncio+ async def test_a_read_runs_at_l2_where_it_did_not_at_l1(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setenv("AISOC_MATURITY_TIER", "L2")+ after, _ = await _gated(_request(ActionType.SEARCH_SIEM, confidence=0.0))++ assert after == ActionStatus.APPROVED++ @pytest.mark.asyncio+ async def test_the_default_tier_executes_nothing(self, monkeypatch: pytest.MonkeyPatch):+ """L1 is notify-only, which is the platform's copilot-default posture.+ This is a real tightening of POST /actions, which was tier-unaware."""+ monkeypatch.delenv("AISOC_MATURITY_TIER", raising=False)+ request = _request(ActionType.SEARCH_SIEM, confidence=1.0)++ after, reason = await _gated(request)++ assert after == ActionStatus.AWAITING_APPROVAL+ assert "L1" in reason+++class TestVerbsWithNoContract:+ @pytest.mark.asyncio+ async def test_an_unmapped_verb_is_left_to_blast_radius(self):+ """Seven ActionType members have no capability contract. Inventing an+ impact for them is how a gate starts certifying things it never+ examined, so blast radius decides alone and the gap is logged."""+ assert ActionType.NOTIFY_SLACK.value not in CAPABILITY_CONTRACTS++ request = _request(ActionType.NOTIFY_SLACK, confidence=0.1)+ before, br, before_reason = BlastRadiusGate().evaluate(request)+ after, reason = await apply_matrix(request, before, br, before_reason)++ assert after == before+ assert reason == before_reason+++class TestTierLabelMapping:+ @pytest.mark.parametrize(+ ("name", "expected"),+ [("L0_OBSERVE", "L0"), ("L1_NOTIFY", "L1"), ("L4_AUTOMATE", "L4")],+ )+ def test_maturity_tier_names_map_onto_matrix_labels(self, name: str, expected: str):+ from app.services.approval_gate import _tier_label++ class _Tier:+ pass++ tier = _Tier()+ tier.name = name+ assert _tier_label(tier) == expected++ def test_an_unrecognisable_tier_falls_back_conservatively(self):+ from app.services.approval_gate import _tier_label++ assert _tier_label(None) == "L1"+ assert _tier_label("nonsense") == "L1"+++class TestConfidenceIsValidated:+ def test_a_confidence_outside_zero_to_one_is_refused_at_the_model(self):+ """Clamping silently would let a caller send 99 and mean 99%."""+ with pytest.raises(ValueError):+ _request(ActionType.BLOCK_IP, confidence=99.0)+++def test_the_blast_radius_limit_is_unchanged():+ """This wave adds an axis; it does not move the existing one."""+ from app.services.blast_radius import _AUTO_EXECUTE_LIMIT++ assert _AUTO_EXECUTE_LIMIT == BlastRadius.MEDIUMdiff --git a/services/agents/app/investigator/chatops_notify.py b/services/agents/app/investigator/chatops_notify.pynew file mode 100644index 000000000..eecc1f472--- /dev/null+++ b/services/agents/app/investigator/chatops_notify.py@@ -0,0 +1,86 @@+"""Tell a human an approval is waiting.++An approval row in Postgres is durable and useless until somebody looks at+it. The console shows it and the responder app pushes it, but the path the+documentation describes — an agent stops, Slack asks, an analyst taps — could+not start: the bot had no way to originate a message, only to reply inside an+inbound interaction.++Now that ``services/slack-bot`` exposes ``POST /internal/approval-card``,+this is the caller. It is deliberately best-effort and deliberately quiet+when unconfigured: an approval is already recorded by the time this runs, and+a deployment with no Slack should not log a warning per alert forever.+"""++from __future__ import annotations++import os+import uuid+from typing import Any++import httpx+import structlog++logger = structlog.get_logger()++_TIMEOUT_SECONDS = 5.0+++def _bot_url() -> str:+ return os.getenv("AISOC_SLACK_BOT_URL", "").strip().rstrip("/")+++def _internal_token() -> str:+ return os.getenv("AISOC_INTERNAL_TOKEN", "").strip()+++async def notify_chatops(+ approval_id: uuid.UUID,+ *,+ title: str,+ summary: str,+ risk_level: str,+ action: dict[str, Any],+) -> bool:+ """Post an approval card to ChatOps. Returns whether it was delivered.++ Unconfigured is not an error and not a warning: it is the default, and the+ approval is reachable in the console and the responder app regardless.+ """+ base = _bot_url()+ if not base:+ return False++ payload = {+ "action": {+ "id": str(approval_id),+ "action_type": action.get("action_type"),+ "target": action.get("target"),+ "risk_level": risk_level,+ "rationale": summary,+ "title": title,+ },+ "case": {"title": title, "description": summary},+ }+ headers = {"Accept": "application/json"}+ token = _internal_token()+ if token:+ headers["X-AiSOC-Internal-Token"] = token++ try:+ async with httpx.AsyncClient(timeout=_TIMEOUT_SECONDS) as client:+ response = await client.post(f"{base}/internal/approval-card", json=payload, headers=headers)+ except httpx.HTTPError as exc:+ logger.warning("chatops_notify.unreachable", approval_id=str(approval_id), error=str(exc))+ return False++ if response.status_code >= 400:+ logger.warning(+ "chatops_notify.refused",+ approval_id=str(approval_id),+ status=response.status_code,+ )+ return False++ logger.info("chatops_notify.posted", approval_id=str(approval_id))+ return Truediff --git a/services/agents/app/investigator/ledger.py b/services/agents/app/investigator/ledger.pyindex c5b2164dc..696e5277d 100644--- a/services/agents/app/investigator/ledger.py+++ b/services/agents/app/investigator/ledger.py@@ -33,6 +33,8 @@ from typing import Anyimport asyncpgimport structlog+from app.investigator.chatops_notify import notify_chatops+logger = structlog.get_logger()@@ -599,10 +601,13 @@ async def raise_approval(risk_level[:20],json.dumps(action),)- # The id is returned whether the insert landed or the conflict- # clause fired: either way this is the approval that governs this- # action, and a replay must point at the one already queued.- return approval_id+ # Outside the connection block: the approval is durable now, and+ # Slack being slow must not hold a database connection open.+ await notify_chatops(approval_id, title=title, summary=summary, risk_level=risk_level, action=action)+ # The id is returned whether the insert landed or the conflict+ # clause fired: either way this is the approval that governs this+ # action, and a replay must point at the one already queued.+ return approval_idexcept Exception as exc: # noqa: BLE001 — an approval write must not fail triagelogger.warning("ledger.raise_approval_failed",diff --git a/services/api/migrations/055_action_records.sql b/services/api/migrations/055_action_records.sqlnew file mode 100644index 000000000..19ffd0f78--- /dev/null+++ b/services/api/migrations/055_action_records.sql@@ -0,0 +1,33 @@+-- Durable storage for actions awaiting approval.+--+-- services/actions kept these in a module-global dict with the comment+-- "replace with DB in production". The consequence is specific: a restart or+-- a second replica loses every pending containment, so an analyst taps+-- Approve on a Slack card and gets "Action not found" for an incident that is+-- still live. There is no retry — the agent already decided, and the record of+-- what it wanted is gone.+--+-- The record is stored whole as JSONB rather than decomposed into columns.+-- The action record's shape is owned by services/actions and changes with the+-- executor contract; mirroring it as columns here would make every contract+-- change a migration, and the only queries this table serves are by primary+-- key and by tenant.++CREATE TABLE IF NOT EXISTS aisoc_action_records (+ id TEXT PRIMARY KEY,+ tenant_id TEXT NOT NULL DEFAULT '',+ status TEXT NOT NULL DEFAULT '',+ record JSONB NOT NULL,+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()+);++-- The operational question is "what is waiting on a human in this tenant",+-- which is the only access pattern beyond primary key.+CREATE INDEX IF NOT EXISTS ix_action_records_tenant_status+ ON aisoc_action_records (tenant_id, status);++-- Pending actions are the ones with a deadline attached, so ordering them by+-- age is how an approval-SLA view is built.+CREATE INDEX IF NOT EXISTS ix_action_records_created+ ON aisoc_action_records (created_at DESC);diff --git a/services/slack-bot/app/core/config.py b/services/slack-bot/app/core/config.pyindex df93a0160..9d9130e32 100644--- a/services/slack-bot/app/core/config.py+++ b/services/slack-bot/app/core/config.py@@ -79,6 +79,27 @@ class SlackBotSettings(BaseSettings):description="Public web app URL used to deep-link case cards.",)+ # --- Proactive notification -------------------------------------------++ SLACK_APPROVALS_CHANNEL: str = Field(+ default="",+ description=(+ "Channel the bot posts approval cards into when an agent raises "+ "one. Empty disables proactive posting, which is the correct "+ "default: a bot that posts into a channel nobody chose is worse "+ "than one that posts nowhere."+ ),+ )+ AISOC_INTERNAL_TOKEN: str = Field(+ default="",+ description=(+ "Shared secret for /internal/* routes. These are called by other "+ "AiSOC services, never by Slack, so they carry no Slack signature "+ "and need their own check. Empty refuses every internal call "+ "outside dev mode."+ ),+ )+# --- Service plumbing --------------------------------------------------AISOC_SLACK_BOT_PORT: int = Field(diff --git a/services/slack-bot/app/main.py b/services/slack-bot/app/main.pyindex c7eff344a..0550b4955 100644--- a/services/slack-bot/app/main.py+++ b/services/slack-bot/app/main.py@@ -61,6 +61,7 @@ from app.interactions import (NEED_INFO_ACTION_ID,handle_action_decision,)+from app.notify import router as notify_routerfrom app.services.aisoc_clients import AisocActionsClient, AisocApiClientfrom app.services.approval_audit import StructlogAuditSinkfrom app.services.approval_timeout import ApprovalTimeoutScheduler@@ -316,6 +317,12 @@ app = FastAPI(lifespan=_lifespan,)+# The bot's only outbound route: other AiSOC services call this to have a+# card posted into a channel. Every other route here is Slack calling in, and+# Bolt's respond() only works inside an inbound interaction — which is why an+# agent could not ask for approval until a human asked first.+app.include_router(notify_router)+# Phase 2.6 — k8s liveness + readiness probes (see app/_health.py)._mark_ready, _mark_not_ready = install_health_routes(app, service_name="aisoc-slack-bot")app.state.mark_ready = _mark_readydiff --git a/services/slack-bot/app/notify.py b/services/slack-bot/app/notify.pynew file mode 100644index 000000000..df53d65f7--- /dev/null+++ b/services/slack-bot/app/notify.py@@ -0,0 +1,142 @@+"""Let the bot start a conversation.++Every route this service had was inbound: Slack posts an interaction, the bot+replies through Bolt's ``respond()``, which writes to the ``response_url``+that came with the request. That URL only exists inside an inbound+interaction, so the bot could answer a question and could not ask one.++The consequence is the shape this wave keeps finding. The cards were already+written — ``blocks.approval_card_blocks`` and the richer+``rich_approval_card_blocks``, the latter with no production caller at all —+and the button handlers that receive Approve and Deny were already wired.+What was missing between them was the ability to put a card in front of+somebody who had not just typed a slash command. So the documented "an agent+stops and asks Slack for approval" flow could only ever start with a human+asking first.++This is one route and one Slack API call. It is deliberately internal:+callers are AiSOC services, not Slack, so the request carries no Slack+signature and is authenticated with a shared token instead.+"""++from __future__ import annotations++import hmac+import os+from typing import Any++import structlog+from fastapi import APIRouter, Header, HTTPException, Request, status+from pydantic import BaseModel, Field++from app.blocks import rich_approval_card_blocks+from app.core.config import get_settings++logger = structlog.get_logger(__name__)++router = APIRouter(prefix="/internal", tags=["internal"])+++class ApprovalCardRequest(BaseModel):+ """An approval an agent wants a human to decide."""++ action: dict[str, Any] = Field(+ ...,+ description="The action record: id, action_type, target, risk_level, rationale.",+ )+ case: dict[str, Any] = Field(default_factory=dict, description="Case context rendered into the card.")+ channel: str | None = Field(+ default=None,+ description="Override the configured approvals channel. Useful for per-tenant routing.",+ )+ requested_by_slack_id: str = Field(+ default="",+ description=(+ "Slack id of the requester, when there is one. An agent-raised "+ "approval has none, and the card says so rather than attributing "+ "it to whoever happens to be on call."+ ),+ )+ related_alerts: list[dict[str, Any]] | None = None+ timeout_seconds: int | None = None+++def _authorized(supplied: str | None) -> bool:+ """Compare the internal token in constant time, failing closed.++ An unset token refuses every internal call unless dev mode is on. The+ alternative — treating "no token configured" as "no auth needed" — makes+ a route that can post into a workspace channel open to anything that can+ reach the pod.+ """+ settings = get_settings()+ expected = settings.AISOC_INTERNAL_TOKEN.strip()+ if not expected:+ return os.environ.get("AISOC_DEV_MODE", "").strip().lower() in {"1", "true", "yes", "on"}+ return bool(supplied) and hmac.compare_digest(supplied.strip(), expected)++[email protected]("/approval-card", status_code=status.HTTP_202_ACCEPTED)+async def post_approval_card(+ body: ApprovalCardRequest,+ request: Request,+ x_internal_token: str | None = Header(default=None, alias="X-AiSOC-Internal-Token"),+) -> dict[str, Any]:+ """Post an approval card into the approvals channel.++ Returns 202 with a ``posted`` flag rather than failing when no channel is+ configured: an approval is already durable in Postgres by the time this is+ called, and the console and responder app can both act on it. Slack is one+ delivery route, not the record.+ """+ if not _authorized(x_internal_token):+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="internal token required")++ settings = get_settings()+ channel = (body.channel or settings.SLACK_APPROVALS_CHANNEL).strip()+ if not channel:+ logger.info(+ "slack_bot.approval_card_skipped",+ reason="SLACK_APPROVALS_CHANNEL is unset",+ action_id=body.action.get("id"),+ )+ return {"posted": False, "reason": "no approvals channel configured"}++ bolt = getattr(request.app.state, "bolt_app", None)+ if bolt is None:+ logger.error("slack_bot.no_bolt_app", action_id=body.action.get("id"))+ return {"posted": False, "reason": "slack client unavailable"}++ blocks = rich_approval_card_blocks(+ action=body.action,+ case=body.case,+ requested_by_slack_id=body.requested_by_slack_id,+ web_base=settings.AISOC_WEB_BASE_URL,+ timeout_seconds=body.timeout_seconds,+ related_alerts=body.related_alerts,+ )++ try:+ response = await bolt.client.chat_postMessage(+ channel=channel,+ blocks=blocks,+ # Notification text for clients that cannot render Block Kit, and+ # for the mobile push preview — which is often all an approver+ # sees before deciding whether to open it.+ text=f"Approval needed: {body.action.get('action_type', 'action')} on {body.action.get('target', 'a target')}",+ )+ except Exception as exc: # noqa: BLE001 — Slack being down must not fail the agent+ logger.warning(+ "slack_bot.approval_card_failed",+ action_id=body.action.get("id"),+ channel=channel,+ error=str(exc),+ )+ return {"posted": False, "reason": f"slack rejected the message ({type(exc).__name__})"}++ logger.info(+ "slack_bot.approval_card_posted",+ action_id=body.action.get("id"),+ channel=channel,+ )+ return {"posted": True, "channel": channel, "ts": response.get("ts") if hasattr(response, "get") else None}diff --git a/services/slack-bot/tests/test_notify.py b/services/slack-bot/tests/test_notify.pynew file mode 100644index 000000000..6df0f5734--- /dev/null+++ b/services/slack-bot/tests/test_notify.py@@ -0,0 +1,186 @@+"""The bot has to be able to start a conversation.++Every route this service had was inbound. Replies go through Bolt's+``respond()``, which writes to the ``response_url`` that arrives with an+interaction — so the bot could answer a question and could not ask one. The+documented flow where an agent stops and Slack asks an analyst for approval+could only begin with a human typing a slash command first.++``rich_approval_card_blocks`` had **no production caller at all** before this;+the renderer and the button handlers both existed, with nothing between them.+"""++from __future__ import annotations++from types import SimpleNamespace++import pytest+from app import notify+from app.core.config import get_settings+from fastapi import FastAPI+from fastapi.testclient import TestClient++TOKEN = "internal-secret"++ACTION = {+ "id": "act-1",+ "action_type": "isolate_host",+ "target": "WKSTN-01",+ "risk_level": "high",+ "rationale": "Confirmed C2 beacon.",+}+++class _Client:+ """Stands in for Bolt's Slack web client."""++ def __init__(self, *, fail: bool = False) -> None:+ self.calls: list[dict] = []+ self._fail = fail++ async def chat_postMessage(self, **kwargs):+ if self._fail:+ raise RuntimeError("channel_not_found")+ self.calls.append(kwargs)+ return {"ts": "1700000000.000100"}+++def slack():+ return _Client()+++def client(monkeypatch: pytest.MonkeyPatch, slack: _Client) -> TestClient:+ monkeypatch.setenv("AISOC_INTERNAL_TOKEN", TOKEN)+ monkeypatch.setenv("SLACK_APPROVALS_CHANNEL", "#soc-approvals")+ get_settings.cache_clear()++ app = FastAPI()+ app.include_router(notify.router)+ app.state.bolt_app = SimpleNamespace(client=slack)+ yield TestClient(app)+ get_settings.cache_clear()+++def _post(client: TestClient, *, token: str | None = TOKEN, **body):+ headers = {"X-AiSOC-Internal-Token": token} if token is not None else {}+ payload = {"action": ACTION, "case": {"title": "Beaconing on WKSTN-01"}}+ payload.update(body)+ return client.post("/internal/approval-card", json=payload, headers=headers)+++class TestItActuallyPosts:+ def test_a_card_reaches_the_configured_channel(self, client: TestClient, slack: _Client):+ response = _post(client)++ assert response.status_code == 202+ assert response.json()["posted"] is True+ assert len(slack.calls) == 1+ assert slack.calls[0]["channel"] == "#soc-approvals"++ def test_the_card_is_block_kit_not_a_plain_string(self, client: TestClient, slack: _Client):+ _post(client)++ blocks = slack.calls[0]["blocks"]+ assert isinstance(blocks, list) and blocks+ assert all("type" in block for block in blocks)++ def test_fallback_text_names_the_action_and_target(self, client: TestClient, slack: _Client):+ """Often all an approver sees is the mobile push preview."""+ _post(client)++ text = slack.calls[0]["text"]+ assert "isolate_host" in text+ assert "WKSTN-01" in text++ def test_a_caller_can_override_the_channel(self, client: TestClient, slack: _Client):+ _post(client, channel="#ir-warroom")++ assert slack.calls[0]["channel"] == "#ir-warroom"+++class TestAuthentication:+ def test_an_unauthenticated_call_is_refused(self, client: TestClient, slack: _Client):+ """This route can post into a workspace channel. It carries no Slack+ signature because Slack is not the caller."""+ assert _post(client, token=None).status_code == 401+ assert slack.calls == []++ def test_a_wrong_token_is_refused(self, client: TestClient, slack: _Client):+ assert _post(client, token="not-it").status_code == 401+ assert slack.calls == []++ def test_an_unset_token_fails_closed_outside_dev_mode(self, monkeypatch: pytest.MonkeyPatch, slack: _Client):+ """Treating 'no token configured' as 'no auth needed' would open this+ to anything that can reach the pod."""+ monkeypatch.setenv("AISOC_INTERNAL_TOKEN", "")+ monkeypatch.delenv("AISOC_DEV_MODE", raising=False)+ get_settings.cache_clear()++ app = FastAPI()+ app.include_router(notify.router)+ app.state.bolt_app = SimpleNamespace(client=slack)++ response = TestClient(app).post("/internal/approval-card", json={"action": ACTION})+ assert response.status_code == 401+ get_settings.cache_clear()+++class TestDegradation:+ def test_no_configured_channel_is_reported_not_crashed(self, monkeypatch: pytest.MonkeyPatch, slack: _Client):+ """An approval is durable in Postgres by the time this runs. Slack is+ one delivery route, not the record."""+ monkeypatch.setenv("AISOC_INTERNAL_TOKEN", TOKEN)+ monkeypatch.setenv("SLACK_APPROVALS_CHANNEL", "")+ get_settings.cache_clear()++ app = FastAPI()+ app.include_router(notify.router)+ app.state.bolt_app = SimpleNamespace(client=slack)++ response = TestClient(app).post(+ "/internal/approval-card",+ json={"action": ACTION},+ headers={"X-AiSOC-Internal-Token": TOKEN},+ )+ assert response.status_code == 202+ assert response.json()["posted"] is False+ assert slack.calls == []+ get_settings.cache_clear()++ def test_slack_rejecting_the_message_does_not_500(self, monkeypatch: pytest.MonkeyPatch):+ """A failed card must not fail the agent run that raised it."""+ monkeypatch.setenv("AISOC_INTERNAL_TOKEN", TOKEN)+ monkeypatch.setenv("SLACK_APPROVALS_CHANNEL", "#soc-approvals")+ get_settings.cache_clear()++ app = FastAPI()+ app.include_router(notify.router)+ app.state.bolt_app = SimpleNamespace(client=_Client(fail=True))++ response = TestClient(app).post(+ "/internal/approval-card",+ json={"action": ACTION},+ headers={"X-AiSOC-Internal-Token": TOKEN},+ )+ assert response.status_code == 202+ assert response.json()["posted"] is False+ get_settings.cache_clear()++ def test_no_slack_client_is_reported_not_crashed(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setenv("AISOC_INTERNAL_TOKEN", TOKEN)+ monkeypatch.setenv("SLACK_APPROVALS_CHANNEL", "#soc-approvals")+ get_settings.cache_clear()++ app = FastAPI()+ app.include_router(notify.router)++ response = TestClient(app).post(+ "/internal/approval-card",+ json={"action": ACTION},+ headers={"X-AiSOC-Internal-Token": TOKEN},+ )+ assert response.status_code == 202+ assert response.json()["posted"] is False+ get_settings.cache_clear()