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
"""ChatOps user-verification executor.
Wave 1 of the AiSOC v6 capability roadmap. The executor:
1. Mints three HMAC-signed callback tokens — one per choice
(``acknowledge`` / ``deny`` / ``escalate``) — using
:mod:`app.security.chatops_token`. Each token carries the action,
case, tenant, user reference, and an expiry derived from
``AISOC_CHATOPS_TIMEOUT_SECONDS``.
2. Builds three callback URLs against ``AISOC_ACTIONS_PUBLIC_URL``.
3. Posts the interactive prompt into the configured transport
(``slack`` via Block Kit, ``teams`` via Connector Card) using the
credential-vault-aware helpers in :mod:`app.services.chatops_prompt`.
4. Writes a ``chatops.verify.prompted`` event onto the case timeline so
analysts see the question was asked, and returns ``ActionStatus.RUNNING``
to signal that the analyst is now waiting on the user.
The actual user response lands on the callback endpoint (added in
``app/api/router.py``) and produces a second timeline event; this executor
deliberately does not block the request loop on a human reply.
Failure modes:
* Feature flag off — returns ``ActionStatus.FAILED`` with a clear error
rather than silently no-op'ing, so misconfiguration is visible in tests.
* No webhook configured — same: the action exists to ask a person a
question, so an unreachable transport is a hard fail.
* Timeline write fails — we log and surface a non-fatal warning on the
result, but keep the action ``RUNNING`` because the prompt was already
delivered. Losing the timeline write is recoverable, the prompt is not.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
import structlog
from app.core.config import get_settings
from app.executors.base import BaseExecutor
from app.models.action import ActionRequest, ActionResult, ActionStatus, BlastRadius
from app.security.chatops_token import ChatOpsTokenError, mint_token
from app.services.branding_lookup import product_name_for_tenant
from app.services.chatops_prompt import (
ChatOpsButton,
ChatOpsPromptError,
send_slack_prompt,
send_teams_prompt,
)
from app.services.timeline_client import TimelineClientError, post_timeline_event
logger = structlog.get_logger()
# Stable button order (acknowledge, deny, escalate) — keeps the prompt
# predictable across transports and makes screenshots/tests deterministic.
_CHOICES: tuple[tuple[str, str, str], ...] = (
("acknowledge", "Yes, that was me", "primary"),
("deny", "No, that wasn't me", "danger"),
("escalate", "I'm not sure — escalate", "default"),
)
def _build_callback_url(
*,
base_url: str,
token: str,
) -> str:
"""Compose the callback URL the user clicks in chat.
The callback path is mounted by ``app/api/router.py`` and accepts a
single ``token`` query parameter — see the route handler for the
matching contract.
"""
return f"{base_url.rstrip('/')}/api/v1/chatops/callback?token={token}"
class ChatOpsVerifyExecutor(BaseExecutor):
"""Send an interactive verification prompt to the affected user."""
async def execute(self, request: ActionRequest) -> ActionResult:
settings = get_settings()
if not settings.AISOC_FEATURE_CHATOPS_VERIFY:
return ActionResult(
action_id=request.id,
status=ActionStatus.FAILED,
blast_radius=BlastRadius.MINIMAL,
error="ChatOps verification is disabled (AISOC_FEATURE_CHATOPS_VERIFY=False)",
)
params: dict[str, Any] = request.parameters or {}
# Resolved once, before the question is built: the default question
# names the product too, so resolving it only at delivery would brand
# the card's title and leave the sentence inside it unbranded.
product_name = await product_name_for_tenant(request.tenant_id)
transport = str(params.get("transport", "slack")).lower()
webhook_url = params.get("webhook_url") or ""
bot_token = params.get("bot_token") or None
channel = params.get("channel") or None
question = str(
params.get(
"question",
f"{product_name} needs to confirm activity on your account ({request.target}).",
)
)
context = str(
params.get(
"context",
f"Incident `{request.incident_id}` — rationale: {request.rationale or 'n/a'}",
)
)
user_ref = str(params.get("user_ref", request.target))
if transport not in {"slack", "teams"}:
return ActionResult(
action_id=request.id,
status=ActionStatus.FAILED,
blast_radius=BlastRadius.MINIMAL,
error=f"unsupported ChatOps transport: {transport!r}",
)
if not webhook_url:
return ActionResult(
action_id=request.id,
status=ActionStatus.FAILED,
blast_radius=BlastRadius.MINIMAL,
error="parameters.webhook_url is required for ChatOps verification",
)
# Mint one signed callback token per choice. Failures here are
# configuration errors (missing HMAC secret), surface them up.
try:
buttons = [
ChatOpsButton(
label=label,
url=_build_callback_url(
base_url=settings.AISOC_ACTIONS_PUBLIC_URL,
token=mint_token(
action_id=request.id,
case_id=request.incident_id,
tenant_id=request.tenant_id,
choice=choice,
user_ref=user_ref,
secret=settings.AISOC_CHATOPS_RESPONSE_SECRET,
ttl_seconds=settings.AISOC_CHATOPS_TIMEOUT_SECONDS,
),
),
style=style,
)
for choice, label, style in _CHOICES
]
except ChatOpsTokenError as exc:
return ActionResult(
action_id=request.id,
status=ActionStatus.FAILED,
blast_radius=BlastRadius.MINIMAL,
error=f"failed to mint ChatOps token: {exc}",
)
# Deliver the prompt. If this fails, the whole action fails — there
# is no value in marking RUNNING when no one will ever see the
# question.
try:
if transport == "slack":
delivery = await send_slack_prompt(
webhook_url=webhook_url,
question=question,
context=context,
buttons=buttons,
bot_token=bot_token,
channel=channel,
product_name=product_name,
)
else:
delivery = await send_teams_prompt(
webhook_url=webhook_url,
question=question,
context=context,
buttons=buttons,
product_name=product_name,
)
except ChatOpsPromptError as exc:
logger.warning(
"ChatOps prompt delivery failed",
action_id=str(request.id),
transport=transport,
error=str(exc),
)
return ActionResult(
action_id=request.id,
status=ActionStatus.FAILED,
blast_radius=BlastRadius.MINIMAL,
error=str(exc),
)
# Best-effort timeline write — see module docstring for why we don't
# fail the action when this errors.
timeline_warning: str | None = None
try:
await post_timeline_event(
case_id=request.incident_id,
event_type="chatops.verify.prompted",
content=(
f"ChatOps verification sent to {user_ref} via {transport}. "
f"Awaiting response (TTL {settings.AISOC_CHATOPS_TIMEOUT_SECONDS}s)."
),
metadata={
"action_id": str(request.id),
"tenant_id": str(request.tenant_id),
"transport": transport,
"channel": channel,
"user_ref": user_ref,
"question": question,
"expires_in_seconds": settings.AISOC_CHATOPS_TIMEOUT_SECONDS,
},
)
except TimelineClientError as exc:
timeline_warning = f"timeline prompt-event write failed: {exc}"
logger.warning(
"ChatOps timeline write failed",
action_id=str(request.id),
case_id=str(request.incident_id),
error=str(exc),
)
logger.info(
"ChatOps prompt delivered",
action_id=str(request.id),
case_id=str(request.incident_id),
transport=transport,
channel=channel,
)
return ActionResult(
action_id=request.id,
status=ActionStatus.RUNNING,
blast_radius=BlastRadius.MINIMAL,
output={
"transport": transport,
"channel": channel,
"user_ref": user_ref,
"delivery": delivery,
"expires_in_seconds": settings.AISOC_CHATOPS_TIMEOUT_SECONDS,
**({"timeline_warning": timeline_warning} if timeline_warning else {}),
},
executed_at=datetime.now(UTC),
)
__all__ = ["ChatOpsVerifyExecutor"]