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
"""
Adaptive Card callback dispatch.
When a Teams user clicks Approve / Deny / Need-Info on an AiSOC
approval card, Teams POSTs an ``invoke`` activity carrying the card's
signed ``data`` payload. This module:
1. Verifies the HMAC signature + freshness window
(:func:`app.services.hmac_signer.verify_card_data`).
2. Forwards the decision to ``services/actions`` (Approve / Deny) or
records a structured audit row (Need-Info — no upstream state
change).
3. Returns a replacement Adaptive Card so the original message reflects
the decision and the buttons can't be clicked twice.
The dispatch is intentionally framework-agnostic. The FastAPI handler in
:mod:`app.main` extracts the payload from the Bot Framework activity
shape and hands it to :func:`handle_card_action` — the same function
can be reused under a fastapi-route, an Outlook Actionable Message
endpoint, or in a unit test.
"""
from __future__ import annotations
import os
from dataclasses import dataclass
from typing import Any, Protocol
import structlog
from app.cards import decision_card
from app.services.hmac_signer import HmacVerificationError, verify_card_data
log = structlog.get_logger(__name__)
class _ActionsClient(Protocol):
# Protocol method bodies use ``pass`` rather than ``...`` to silence
# CodeQL ``py/ineffectual-statement`` (it flags ellipsis as a
# discarded expression statement). Semantically identical for an
# unimplemented Protocol contract.
async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:
pass
async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:
pass
def _chatops_approver(client: Any, approver_id: str | None) -> dict[str, Any] | None:
"""Build the approver payload, tolerating a client without the helper.
`build_actions_client` may return the Slack bot's client, this package's
fallback, or a test double. All of the real ones expose
`chatops_approver`; a double may not, so fall back to constructing the
payload directly rather than dropping the identity — silently omitting it
is what made approvals authorize nobody in the first place.
"""
if not approver_id:
return None
helper = getattr(client, "chatops_approver", None)
if callable(helper):
return helper("teams", approver_id)
return {"chatops_approver": {"platform": "teams", "platform_user_id": approver_id}}
@dataclass(slots=True, frozen=True)
class _AuditEvent:
case_id: str
action_id: str
approver_id: str
decision: str
channel: str | None = None
actor_ip: str | None = None
source: str = "teams"
error: str | None = None
class _AuditSink(Protocol):
# See ``_ActionsClient`` — ``pass`` instead of ``...`` to keep
# CodeQL ``py/ineffectual-statement`` quiet on Protocol stubs.
async def record(self, event: _AuditEvent) -> None:
pass
class CallbackResult(dict):
"""
Typed convenience wrapper so callers can ``result["card"]`` /
``result["decision"]`` without inventing a parallel class. We
subclass ``dict`` so the JSON-shape stays trivial to serialise out
of the FastAPI handler.
"""
async def handle_card_action(
*,
payload: dict[str, Any],
approver_id: str,
secret: str,
max_age_seconds: int,
actions_client: _ActionsClient,
audit_sink: _AuditSink | None = None,
channel_id: str | None = None,
actor_ip: str | None = None,
) -> CallbackResult:
"""
Resolve a Teams Action.Submit click into an Adaptive Card response.
Never raises — every failure becomes a small "could not record"
decision card so the analyst sees actionable feedback in Teams.
"""
try:
verify_card_data(payload, secret=secret, max_age_seconds=max_age_seconds)
except HmacVerificationError as exc:
log.warning("teams_callback.hmac_failed", error=str(exc))
return CallbackResult(
decision="rejected_invalid_signature",
ok=False,
card=decision_card(
decision="rejected",
action_id=str(payload.get("action_id") or "?"),
decided_by=approver_id or "?",
),
error=str(exc),
)
verb = str(payload.get("verb") or "")
action_id = str(payload.get("action_id") or "")
case_id = str(payload.get("case_id") or "")
decision_label = {"approve": "approved", "reject": "rejected", "need_info": "need_info"}.get(verb)
if decision_label is None:
log.warning("teams_callback.unknown_verb", verb=verb)
return CallbackResult(
decision="rejected_unknown_verb",
ok=False,
card=decision_card(decision="rejected", action_id=action_id, decided_by=approver_id),
error=f"unknown verb {verb!r}",
)
if decision_label == "need_info":
if audit_sink is not None:
await audit_sink.record(
_AuditEvent(
case_id=case_id,
action_id=action_id,
approver_id=approver_id,
decision="need_info",
channel=channel_id,
actor_ip=actor_ip,
)
)
return CallbackResult(
decision="need_info",
ok=True,
card=decision_card(decision="need_info", action_id=action_id, decided_by=approver_id),
)
try:
# `approver_id` was verified by the inbound HMAC check above, so it is
# attested rather than claimed. Passing it is what lets the actions
# service enforce the permission tier and separation of duties; the
# callback previously recorded it in the audit event only.
approver = _chatops_approver(actions_client, approver_id)
if decision_label == "approved":
await actions_client.approve_action(action_id, approver=approver)
else:
await actions_client.reject_action(action_id, approver=approver)
except Exception as exc: # noqa: BLE001 — surfaced as audit error
log.warning(
"teams_callback.upstream_failed",
action_id=action_id,
decision=decision_label,
error=str(exc),
)
if audit_sink is not None:
await audit_sink.record(
_AuditEvent(
case_id=case_id,
action_id=action_id,
approver_id=approver_id,
decision=decision_label,
channel=channel_id,
actor_ip=actor_ip,
error=str(exc),
)
)
return CallbackResult(
decision=decision_label,
ok=False,
error=str(exc),
card=decision_card(decision=decision_label, action_id=action_id, decided_by=approver_id),
)
if audit_sink is not None:
await audit_sink.record(
_AuditEvent(
case_id=case_id,
action_id=action_id,
approver_id=approver_id,
decision=decision_label,
channel=channel_id,
actor_ip=actor_ip,
)
)
return CallbackResult(
decision=decision_label,
ok=True,
card=decision_card(decision=decision_label, action_id=action_id, decided_by=approver_id),
)
def callback_max_age_seconds() -> int:
"""Resolve the replay window. Defaults to 600s (10 minutes)."""
raw = os.environ.get("AISOC_TEAMS_CALLBACK_MAX_AGE_SECONDS")
if not raw:
return 600
try:
value = int(raw)
return value if value > 0 else 600
except ValueError:
return 600