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.

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.yml
index 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/v1
ATTCK_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:
- aisoc
restart: unless-stopped
@@ -756,6 +762,13 @@ services:
AISOC_WEB_BASE_URL: ${AISOC_WEB_BASE_URL:-http://localhost:3000}
AISOC_SLACK_BOT_PORT: 8089
AISOC_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:
- aisoc
restart: unless-stopped
diff --git a/services/actions/app/api/router.py b/services/actions/app/api/router.py
index 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_approver
from app.security.chatops_token import ChatOpsTokenError, verify_token
+from app.services import action_store
+from app.services.approval_gate import apply_matrix
from app.services.blast_radius import BlastRadiusGate
from app.services.executor_registry import EXECUTOR_REGISTRY
from 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_se
raise HTTPException(status_code=403, detail=str(exc)) from exc
status, 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 approved
if status == ActionStatus.APPROVED:
@@ -102,6 +113,9 @@ async def submit_action(request: ActionRequest, _auth: None = Depends(require_se
record["status"] = ActionStatus.FAILED
record["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 cannot
be 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.FAILED
record["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 as
the 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_id
record["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 = None
try:
diff --git a/services/actions/app/models/action.py b/services/actions/app/models/action.py
index 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 = False
rollback_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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.reason
diff --git a/services/actions/tests/test_approval_gate_wiring.py b/services/actions/tests/test_approval_gate_wiring.py
new file mode 100644
index 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.MEDIUM
diff --git a/services/agents/app/investigator/chatops_notify.py b/services/agents/app/investigator/chatops_notify.py
new file mode 100644
index 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 True
diff --git a/services/agents/app/investigator/ledger.py b/services/agents/app/investigator/ledger.py
index c5b2164dc..696e5277d 100644
--- a/services/agents/app/investigator/ledger.py
+++ b/services/agents/app/investigator/ledger.py
@@ -33,6 +33,8 @@ from typing import Any
import asyncpg
import 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_id
except Exception as exc: # noqa: BLE001 — an approval write must not fail triage
logger.warning(
"ledger.raise_approval_failed",
diff --git a/services/api/migrations/055_action_records.sql b/services/api/migrations/055_action_records.sql
new file mode 100644
index 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.py
index 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.py
index 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_router
from app.services.aisoc_clients import AisocActionsClient, AisocApiClient
from app.services.approval_audit import StructlogAuditSink
from 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_ready
diff --git a/services/slack-bot/app/notify.py b/services/slack-bot/app/notify.py
new file mode 100644
index 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.py
new file mode 100644
index 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()