Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(playbooks): make http, notify and osquery steps act (depth 5.1) (#1203)
Beenu Arora040cebb63fd8
diff --git a/apps/docs/docs/concepts/playbooks.md b/apps/docs/docs/concepts/playbooks.mdindex c5f4ee06d..95be4841a 100644--- a/apps/docs/docs/concepts/playbooks.md+++ b/apps/docs/docs/concepts/playbooks.md@@ -97,11 +97,9 @@ being true.|--------|--------------|| `enrich` | Calls the enrichment service for IOC reputation, geo, ASN, GreyNoise, VT, OTX. || `investigate` | Triggers the AI investigator agent with focus areas (`forensics`, `lateral_movement`, etc.). |-| `notify` | Sends a webhook notification. SSRF-guarded. |-| `http` | Generic outbound HTTP request — `method`, `url`, `body`, `headers`. SSRF-guarded. |+| `http` | Calls one path on an integration this tenant has configured — see [Integration references](#integration-references). SSRF-guarded, and **off by default**. || `close_case` | Marks the AiSOC case as closed via the API service. || `condition` | Pure branching node. Evaluates `condition` and routes to `next_true` / `next_false`. |-| `osquery_live_query` | Distributed osquery via osctrl / FleetDM / aisoc-direct, against an allow-listed template. |**Governed** — the step is dispatched to the action registry in the actionsservice, which grades it against the verb's own capability contract and the@@ -110,7 +108,13 @@ tenant's autonomy policy before anything reaches a vendor:`block_ip`, `block_ioc`, `isolate_host`, `kill_process`, `quarantine_file`,`run_av_scan`, `run_script`, `disable_user`, `reset_password`,`revoke_session`, `force_mfa`, `search_siem`, `create_notable_event`,-`create_ticket`.+`create_ticket`, `notify`, `osquery_live_query`.++`notify` delivers to the tenant's configured Slack, Teams, email or PagerDuty+destination; the channel comes from the destination, not from the step, so a+credential and a transport cannot disagree. `osquery_live_query` runs an+allow-listed template across an osctrl, FleetDM or aisoc-direct fleet — the+caller passes a template id and parameters, never SQL.Each step is dispatched **individually**. Approving or running a playbook doesnot authorise whatever its steps happen to contain: the contract is applied@@ -118,6 +122,30 @@ per verb, per step, at the moment that step runs. See[Live actions](./live-actions.md) for what each verb declares about its impact,reversibility, approval requirement and verification probe.+### Integration references++An `http` step addresses its target by **name**, never by host:++```json+{ "url": "${IDP_BASE_URL}/users/{{alert.user}}/sessions", "headers_env": "IDP_BEARER_HEADERS" }+```++`${NAME}` resolves against the tenant's playbook references — a base URL, a+set of bearer headers, a Slack or Teams incoming webhook, a PagerDuty routing+key or an SMTP relay. `{{dot.path}}` resolves against the run context.++This is the security property rather than a formatting convention. A pack is+shared content: a literal host in one is either somebody else's tenant or an+invitation to point a playbook wherever its author likes. With a name, an+author chooses which of *this* tenant's integrations to call and which path+under it, and cannot choose the origin. The resolved URL still goes through+the SSRF guard, because the stored value is tenant data and therefore as+untrusted as the step that asked for it.++Secrets live in the credential vault and the run record holds header *names*,+never values. A reference is **disabled when created**, so importing a pack+cannot start paging an on-call rota.+What comes back is a report whose `executed` field is the single thing thatmeans a vendor was actually touched:diff --git a/apps/web/src/components/playbooks/stepSchemas.ts b/apps/web/src/components/playbooks/stepSchemas.tsindex 0f9e6b85c..4b63bcf2d 100644--- a/apps/web/src/components/playbooks/stepSchemas.ts+++ b/apps/web/src/components/playbooks/stepSchemas.ts@@ -259,9 +259,10 @@ export const STEP_SCHEMAS: Record<StepType, StepSchema> = {},notify: {type: 'notify',- execution: 'executed',+ execution: 'governed',label: 'Notify',- description: 'Send a notification to Slack, PagerDuty, email, or a generic webhook.',+ description:+ 'Send a notification to the tenant\u2019s configured Slack, Teams, email or PagerDuty destination. The destination is a named playbook reference, so a shared pack carries no webhook of its own.',accent: '#facc15',bgColor: '#1a3d2e',icon: '🔔',@@ -294,8 +295,8 @@ export const STEP_SCHEMAS: Record<StepType, StepSchema> = {key: 'webhook_env',label: 'Webhook URL env',kind: 'env_ref',- placeholder: 'SOC_WEBHOOK_URL',- help: 'Required only for the generic webhook channel.',+ placeholder: 'SLACK_SOC_WEBHOOK',+ help: 'Names a playbook reference holding the Slack or Teams incoming webhook. Configure it under Settings; a reference is disabled until somebody enables it.',},],},@@ -492,10 +493,10 @@ export const STEP_SCHEMAS: Record<StepType, StepSchema> = {},osquery_live_query: {type: 'osquery_live_query',- execution: 'executed',+ execution: 'governed',label: 'Live query',description:- 'Run an allowlisted osquery query across hosts through osctrl, FleetDM or the AiSOC agent. The query itself is a template ID, not free SQL, so a playbook cannot ask an endpoint an arbitrary question. Needs an agents image carrying the osquery backend clients; without them the engine fails the step rather than reporting a query it never sent.',+ 'Run an allowlisted osquery query across hosts through osctrl, FleetDM or the AiSOC agent. The query itself is a template ID, not free SQL, so a playbook cannot ask an endpoint an arbitrary question. Dispatched through the action registry, which is where the three backend clients live \u2014 the engine used to import them from a service its own image does not contain, so every live query raised.',accent: '#2dd4bf',bgColor: '#123333',icon: '🔎',diff --git a/docs/openapi.yaml b/docs/openapi.yamlindex d3fb70444..cedf3c3ce 100644--- a/docs/openapi.yaml+++ b/docs/openapi.yaml@@ -5196,6 +5196,67 @@ paths:application/json:schema:$ref: '#/components/schemas/HTTPValidationError'+ /api/v1/playbook-steps/references:+ post:+ tags:+ - playbooks+ summary: Resolve the named integrations a playbook http step addresses+ description: 'Return the enabled references this tenant has for the names asked+ for.+++ A name that is absent or disabled is simply not in the response. The++ engine reports which ones it needed and did not get; answering with an++ empty string instead would substitute nothing into++ ``${IDP_BASE_URL}/sessions`` and hand httpx a scheme-relative path.+++ Secret halves (bearer headers, webhook URLs) are returned to the agents++ service, which is an authenticated internal peer holding the service++ token, and are used for exactly one request. The engine records header++ *names* in the run result, never values — the run record is readable by++ anyone with access to the case.'+ operationId: resolve_playbook_references_api_v1_playbook_steps_references_post+ security:+ - HTTPBearer: []+ parameters:+ - name: x-aisoc-service-token+ in: header+ required: false+ schema:+ anyOf:+ - type: string+ - type: 'null'+ title: X-Aisoc-Service-Token+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ReferenceLookupRequest'+ responses:+ '200':+ description: Successful Response+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true+ title: Response Resolve Playbook References Api V1 Playbook Steps+ References Post+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'/api/v1/plugins:get:tags:@@ -31800,6 +31861,23 @@ components:- proposed_disposition- event_timetitle: RedispositionCandidateModel+ ReferenceLookupRequest:+ properties:+ names:+ items:+ type: string+ type: array+ maxItems: 32+ title: Names+ tenant_id:+ anyOf:+ - type: string+ format: uuid+ - type: 'null'+ title: Tenant Id+ type: object+ title: ReferenceLookupRequest+ description: The ``${NAME}`` tokens one ``http`` step needs resolved.RefreshRequest:properties:refresh_token:diff --git a/schemas/playbook.schema.json b/schemas/playbook.schema.jsonindex 1341ad1de..b23b05fe4 100644--- a/schemas/playbook.schema.json+++ b/schemas/playbook.schema.json@@ -11,11 +11,11 @@"description": "What `services/agents/app/playbook/engine.py` does with each step type. `executed` = a handler runs and has a real effect (an outbound call to a service, or engine-internal control flow). `governed` = the step is dispatched through the action registry in `services/actions`, where the capability contract and the tenant autonomy policy decide whether a vendor is touched; the step reports which happened and `executed` is the single field that means one was, so a preview, an approval queue and a missing integration are each named rather than reported as a success. `unimplemented` = no handler is registered; the engine fails the step closed rather than reporting a success it did not achieve. `approval` became `executed` in parity 5.2: it suspends the run to Postgres and resumes on the decision, where before it had nowhere to pause to and failed closed while 12 shipped playbooks aborted on it. This map is machine-checked against the engine's handler table, so it cannot drift into an aspirational claim.","enrich": "executed","investigate": "executed",- "notify": "executed",+ "notify": "governed","http": "executed","close_case": "executed","condition": "executed",- "osquery_live_query": "executed",+ "osquery_live_query": "governed","block_ip": "governed","isolate_host": "governed","create_ticket": "governed",diff --git a/scripts/check_module_reachability.py b/scripts/check_module_reachability.pyindex fbc785567..5a5a11a2d 100644--- a/scripts/check_module_reachability.py+++ b/scripts/check_module_reachability.py@@ -113,14 +113,15 @@ ALLOWED_UNREACHABLE: dict[str, str] = {# and its demotion evaluator before handing a verb to dispatch. The entry# went the way an allowlist entry is supposed to go — a module stopped# being unreachable and the gate said so.- # ── Vendor clients reached only through a capability executor ─────────- # These are constructed by name at dispatch time, not imported. The- # import graph cannot see that, and inventing a dynamic-loader entry for- # a factory that takes a string would excuse more than it explains.- "services/actions/app/clients/aisoc_direct_client.py": "Vendor client, constructed by capability name at dispatch.",- "services/actions/app/clients/fleetdm_client.py": "Vendor client, constructed by capability name at dispatch.",- "services/actions/app/clients/osctrl_client.py": "Vendor client, constructed by capability name at dispatch.",- "services/actions/app/clients/osquery_allowlist.py": "Query allowlist, read by the osquery clients above.",+ # The four osquery entries that used to sit here are gone, and the+ # reason is worth keeping: they were not "constructed by name at+ # dispatch", they were genuinely unreachable. The only caller was a+ # playbook handler in `services/agents` importing `app.clients.*`,+ # a package that image does not contain, so the import raised on every+ # live query. Depth 5.1 made `osquery_live_query` a capability with+ # three arms in this service, and `osquery_arms.py` imports all four+ # at module scope — which is why the gate now reports them as excused+ # entries that no longer describe anything.# ── Built, never wired, and no plan item claims them ──────────────────# Recorded rather than deleted: deleting working code is a product# decision, and each of these is a complete implementation with tests.diff --git a/scripts/mypy_baseline.json b/scripts/mypy_baseline.jsonindex a141b6f4b..03b4d9070 100644--- a/scripts/mypy_baseline.json+++ b/scripts/mypy_baseline.json@@ -313,10 +313,6 @@"misc": 1,"var-annotated": 1},- "tests/test_osquery_live_query_step.py": {- "func-returns-value": 2,- "misc": 2- },"tests/test_playbook_completion_rate.py": {"attr-defined": 15}diff --git a/services/actions/app/executors/notification.py b/services/actions/app/executors/notification.pyindex a4c8ca4e6..06f1c0b5b 100644--- a/services/actions/app/executors/notification.py+++ b/services/actions/app/executors/notification.py@@ -104,25 +104,41 @@ class NotifySlackExecutor(BaseExecutor):channel = request.parameters.get("channel", "#security-alerts")message = request.parameters.get("message", request.rationale)- if webhook_url:- try:- async with httpx.AsyncClient(timeout=10.0) as client:- resp = await client.post(- webhook_url,- json={- "channel": channel,- "text": f"AiSOC Alert\n*Incident:* {request.incident_id}\n{message}",- },- )- resp.raise_for_status()- except Exception as exc:- logger.warning("Slack notification failed", error=str(exc))- return ActionResult(- action_id=request.id,- status=ActionStatus.FAILED,- blast_radius="minimal",- error=str(exc),+ if not webhook_url:+ # Reported, not completed. With no webhook this used to fall+ # through to the COMPLETED return below with+ # ``message_sent: True`` — a notification nobody received,+ # recorded as delivered. The caller cannot tell the difference+ # between that and a real post, which is exactly the state a+ # notification step exists to rule out.+ return ActionResult(+ action_id=request.id,+ status=ActionStatus.FAILED,+ blast_radius="minimal",+ error=(+ "no Slack incoming-webhook URL is configured, so nothing was posted. "+ "This says nothing about the message or the channel."+ ),+ )++ try:+ async with httpx.AsyncClient(timeout=10.0) as client:+ resp = await client.post(+ webhook_url,+ json={+ "channel": channel,+ "text": f"AiSOC Alert\n*Incident:* {request.incident_id}\n{message}",+ },)+ resp.raise_for_status()+ except Exception as exc:+ logger.warning("Slack notification failed", error=str(exc))+ return ActionResult(+ action_id=request.id,+ status=ActionStatus.FAILED,+ blast_radius="minimal",+ error=str(exc),+ )logger.info("Slack notification sent", channel=channel)return ActionResult(diff --git a/services/actions/app/live_actions/builtins.py b/services/actions/app/live_actions/builtins.pyindex b3c162195..1f4e77c8f 100644--- a/services/actions/app/live_actions/builtins.py+++ b/services/actions/app/live_actions/builtins.py@@ -96,6 +96,8 @@ from .investigation_reads import (SentinelOneGetHost,)from .models import LiveActionRequest, LiveActionResult, LiveActionStatus+from .notify_arms import NOTIFY_ARMS+from .osquery_arms import OSQUERY_ARMSfrom .vendor_breadth import VENDOR_BREADTH_EXECUTORSlogger = structlog.get_logger(__name__)@@ -838,6 +840,23 @@ class PagerDutyCreateTicket(_LegacyExecutorAdapter):@apply_contractclass SlackNotify(_LegacyExecutorAdapter):+ """Post a notification to Slack through an incoming webhook.++ API reference: https://api.slack.com/messaging/webhooks++ Overrides ``execute`` for the same reason ``_ChatOpsVerify`` does, and it+ is the same defect wearing different clothes. The base class previews by+ stripping ``_credential_keys`` so the legacy executor falls into its+ simulation branch; ``NotifySlackExecutor`` has no simulation branch, so+ a stripped ``webhook_url`` took its no-webhook path — which, until this+ change, returned COMPLETED with ``message_sent: true``. Every dry run+ therefore reported a completed send.++ Fixing the executor to fail closed with no webhook (it now does) is+ necessary and not sufficient: a preview would then report a *failure*,+ which is equally untrue. Simulate here, before anything is stripped.+ """+vendor_id = "slack"capability = "notify"description = "Post an incident notification to a Slack channel."@@ -846,6 +865,22 @@ class SlackNotify(_LegacyExecutorAdapter):_legacy_action_type = ActionType.NOTIFY_SLACK_credential_keys = ("webhook_url",)+ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ if request.dry_run:+ message = str((request.params or {}).get("message") or "AiSOC playbook notification")+ return LiveActionResult(+ request_id=request.request_id,+ status=LiveActionStatus.SIMULATED,+ capability=self.capability,+ vendor_id=self.vendor_id,+ summary=f"would notify slack: {message[:120]}",+ details={"would_notify": "slack", "message": message},+ )+ return await super().execute(request)+++# ---------------------------------------------------------------------------+# ---------------------------------------------------------------------------# Human-in-the-loop — ask the affected user, route the signed answer back@@ -1014,11 +1049,18 @@ _BUILTIN_ADAPTERS: tuple[type[LiveActionExecutor], ...] = (JiraCreateTicket,ServiceNowCreateTicket,PagerDutyCreateTicket,- SlackNotify,# Human-in-the-loop: a working executor whose honest "not answered yet"# had no status to land in until AWAITING_COMPLETION existed.SlackChatOpsVerify,TeamsChatOpsVerify,+ # Depth 5.1. `notify` had one arm and the playbook engine reached none of+ # them, so all 63 notify steps in the shipped packs delivered nothing.+ SlackNotify,+ *NOTIFY_ARMS,+ # Depth 5.1. The engine's osquery handler imported clients that live here,+ # so it raised in every agents image. Same verb, run where its clients and+ # its credentials are.+ *OSQUERY_ARMS,)diff --git a/services/actions/app/live_actions/capabilities.py b/services/actions/app/live_actions/capabilities.pyindex 55441b372..b67323417 100644--- a/services/actions/app/live_actions/capabilities.py+++ b/services/actions/app/live_actions/capabilities.py@@ -89,6 +89,13 @@ KNOWN_CAPABILITIES: frozenset[str] = frozenset(# or a principal, so neither fits the three verbs above."lookup_cloud_audit","lookup_endpoint_telemetry",+ # Depth 5.1. A distributed osquery query across a fleet. Distinct+ # from `query_processes`, which names one table; this runs one of a+ # closed set of allowlisted templates and the caller never supplies+ # SQL. It was a playbook step type that could not run anywhere: the+ # engine imported the three clients from this service, which that+ # image does not contain.+ "osquery_live_query","suspend_session","sync_detection_rule",# The return leg of a two-way SIEM integration: AiSOC's verdictdiff --git a/services/actions/app/live_actions/capability_contracts.py b/services/actions/app/live_actions/capability_contracts.pyindex 37956ce2d..97ced04a6 100644--- a/services/actions/app/live_actions/capability_contracts.py+++ b/services/actions/app/live_actions/capability_contracts.py@@ -122,6 +122,27 @@ CAPABILITY_CONTRACTS: dict[str, CapabilityContract] = {"passes was lifted out of attacker-influenced alert text."),),+ "osquery_live_query": CapabilityContract(+ impact=ActionImpact.READ_ONLY,+ approval=ApprovalRequirement.AUTOMATIC,+ reversal=Reversal.NOT_APPLICABLE,+ required_permission=_READ,+ has_verification_probe=False,+ verification_gap=(+ "A read leaves nothing behind to read back, the same gap "+ "search_siem and lookup_endpoint_telemetry record. The rows the "+ "fleet returned are the response; asking again would be a second "+ "query, not a confirmation of the first."+ ),+ note=(+ "Runs one of a closed set of allowlisted osquery templates across "+ "a fleet. READ_ONLY is a statement about the SQL, which the "+ "caller cannot write: app.clients.osquery_allowlist owns every "+ "template and renders the parameters. A verb that accepted query "+ "text would not be read-only at this tier, because osquery can "+ "read any file the agent can."+ ),+ ),"search_siem": CapabilityContract(impact=ActionImpact.READ_ONLY,approval=ApprovalRequirement.AUTOMATIC,diff --git a/services/actions/app/live_actions/notify_arms.py b/services/actions/app/live_actions/notify_arms.pynew file mode 100644index 000000000..2c0b57889--- /dev/null+++ b/services/actions/app/live_actions/notify_arms.py@@ -0,0 +1,375 @@+"""Where a playbook's ``notify`` step actually goes.++``notify`` has had a capability contract and one arm (``slack``, through+``NotifySlackExecutor``) since the live-action registry was built. The+playbook engine never used either: ``_handle_notify`` had a single sender,+``channel == "webhook"``, and all 63 ``notify`` steps in the shipped packs+address ``slack``, ``pagerduty`` or ``email`` by a *named destination*+(``webhook_env: "SLACK_SOC_WEBHOOK"``, ``service_key_env: "PD_SOC_KEY"``).+Every one of them answered ``{"delivered": false, "reason": "no url"}``.++Three arms are added here — Teams, PagerDuty and email. Slack keeps its+legacy adapter in ``builtins`` because ``ActionType.NOTIFY_SLACK`` is a+documented request field on the older ``POST /actions`` path, and two code+paths to one channel is how one of them comes to behave differently; its+two real defects are fixed where they were, in ``NotifySlackExecutor`` and+in the adapter's dry run.++The channel the step names picks the arm, pinned by the caller rather than+inferred, for the reason the SIEM arms pin ``alert_vendor``: otherwise+whichever destination happens to hold credentials decides where a page goes.++Vendor references, read before writing each sender+--------------------------------------------------+* Microsoft Teams, Workflows ("Post to a channel when a webhook request is+ received") —+ https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498+ The payload is a Bot Framework message carrying an Adaptive Card+ attachment. The retired Office 365 connector ``MessageCard`` format is+ deliberately not used; Microsoft stopped provisioning those endpoints.+* Adaptive Card schema 1.4 — https://adaptivecards.io/explorer/+ 1.4 rather than a later version because that is the highest the Teams+ client renders on all current channels.+* PagerDuty Events API v2 — https://developer.pagerduty.com/docs/events-api-v2-overview+ Driven through the existing ``PagerDutyClient``, which already speaks it.+* SMTP — stdlib ``smtplib``/``email.message``, run off the event loop.++Credential keys match the sender exactly+----------------------------------------+``_credential_keys`` on each arm names precisely the keys that arm's sender+reads. A dry run works by stripping those keys, so a list that misses one+leaves a live credential in a preview — which is how a "dry run" called a+customer's Splunk, twice. ``test_notify_arms.py`` asserts the two agree by+reading the sender's source, so a key added to one and not the other fails.+"""++from __future__ import annotations++import asyncio+import json+import smtplib+import ssl+from email.message import EmailMessage+from typing import Any++import httpx+import structlog++from app.clients.pagerduty_client import PagerDutyClient+from app.live_actions.capability_contracts import apply_contract+from app.live_actions.executor import LiveActionExecutor+from app.live_actions.models import LiveActionRequest, LiveActionResult, LiveActionStatus++logger = structlog.get_logger(__name__)++_TIMEOUT_S = 10.0+++def _result(+ executor: LiveActionExecutor,+ request: LiveActionRequest,+ status: LiveActionStatus,+ summary: str,+ *,+ details: dict[str, Any] | None = None,+ error: str | None = None,+) -> LiveActionResult:+ return LiveActionResult(+ request_id=request.request_id,+ status=status,+ capability=executor.capability,+ vendor_id=executor.vendor_id,+ summary=summary,+ details=details or {},+ error=error,+ )+++def _message(request: LiveActionRequest) -> str:+ params = request.params or {}+ return str(params.get("message") or params.get("text") or "AiSOC playbook notification").strip()+++def _missing(executor: LiveActionExecutor, request: LiveActionRequest, what: str) -> LiveActionResult:+ """No destination configured. Not a failure of the message.++ Split out because "we could not reach the destination" and "this tenant+ has not configured one" send an operator to different places, and the+ old handler collapsed both into "no url".+ """+ return _result(+ executor,+ request,+ LiveActionStatus.FAILED,+ f"no {executor.vendor_id} destination is configured for this tenant",+ error=(+ f"{executor.vendor_id} notification needs {what}, which this tenant has not configured. "+ f"Nothing was sent, and this says nothing about the message."+ ),+ )+++def _simulated(executor: LiveActionExecutor, request: LiveActionRequest) -> LiveActionResult:+ return _result(+ executor,+ request,+ LiveActionStatus.SIMULATED,+ f"would notify {executor.vendor_id}: {_message(request)[:120]}",+ details={"would_notify": executor.vendor_id, "message": _message(request)},+ )+++@apply_contract+class TeamsWebhookNotify(LiveActionExecutor):+ """Post to a Teams channel through a Workflows webhook.++ The payload is the Bot Framework envelope a Power Automate "When a Teams+ webhook request is received" trigger accepts, carrying one Adaptive Card.+ The older ``MessageCard`` shape is deliberately not used: Microsoft+ retired Office 365 connectors, so a tenant setting this up today cannot+ create an endpoint that reads it.+ """++ vendor_id = "teams"+ capability = "notify"+ description = "Post a playbook notification to Microsoft Teams through a Workflows webhook."+ requires_credentials = True+ _credential_keys: tuple[str, ...] = ("webhook_url",)++ def _payload(self, request: LiveActionRequest) -> dict[str, Any]:+ return {+ "type": "message",+ "attachments": [+ {+ "contentType": "application/vnd.microsoft.card.adaptive",+ "content": {+ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",+ "type": "AdaptiveCard",+ "version": "1.4",+ "body": [+ {"type": "TextBlock", "text": "AiSOC", "weight": "Bolder", "size": "Small", "isSubtle": True},+ {"type": "TextBlock", "text": _message(request), "wrap": True},+ ],+ },+ }+ ],+ }++ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ if request.dry_run:+ return _simulated(self, request)++ webhook_url = str((request.params or {}).get("webhook_url") or "").strip()+ if not webhook_url:+ return _missing(self, request, "a Workflows webhook URL")++ try:+ async with httpx.AsyncClient(timeout=_TIMEOUT_S) as client:+ response = await client.post(webhook_url, json=self._payload(request))+ except httpx.HTTPError as exc:+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "Teams did not accept the notification",+ error=f"Teams webhook failed: {exc}",+ )++ if not 200 <= response.status_code < 300:+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ f"Teams rejected the notification (HTTP {response.status_code})",+ error=f"Teams webhook returned HTTP {response.status_code}: {response.text[:200]}",+ )++ return _result(+ self,+ request,+ LiveActionStatus.SUCCEEDED,+ f"Notified Teams: {_message(request)[:120]}",+ # The webhook URL is itself the bearer credential, so the audit+ # record names the destination and never its address.+ details={"destination": str((request.params or {}).get("destination") or ""), "http_status": response.status_code},+ )+++@apply_contract+class PagerDutyNotify(LiveActionExecutor):+ """Page an on-call responder through the PagerDuty Events API v2.++ The routing key is the Events-API integration key, which is a different+ secret from the REST API key the PagerDuty *connector* stores — the two+ auth surfaces are separate by PagerDuty's design, and conflating them is+ why ``credential_resolver`` already carries a note about it.+ """++ vendor_id = "pagerduty"+ capability = "notify"+ description = "Trigger a PagerDuty incident for a playbook notification (Events API v2)."+ requires_credentials = True+ _credential_keys: tuple[str, ...] = ("pd_routing_key",)++ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ if request.dry_run:+ return _simulated(self, request)++ params = request.params or {}+ routing_key = str(params.get("pd_routing_key") or "").strip()+ if not routing_key:+ return _missing(self, request, "an Events API v2 routing key")++ # AiSOC's five-tier severity is passed through as-is: the client owns+ # the fold onto the four values the Events API accepts, and a second+ # copy of that map here is a second thing to get wrong.+ #+ # `case_id` seeds the dedup key, so re-running a playbook updates the+ # existing page instead of opening a second one for the same incident.+ try:+ response = await PagerDutyClient(routing_key=routing_key).trigger_incident(+ summary=_message(request)[:1024],+ severity=str(params.get("severity") or "medium"),+ case_id=str(params.get("dedup_key") or request.playbook_run_id or request.request_id),+ source=str(params.get("source") or "aisoc"),+ )+ except Exception as exc: # noqa: BLE001 — a vendor error is FAILED, never silent+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "PagerDuty did not accept the page",+ error=f"PagerDuty Events API failed: {exc}",+ )++ return _result(+ self,+ request,+ LiveActionStatus.SUCCEEDED,+ f"Paged PagerDuty: {_message(request)[:120]}",+ details={"destination": str(params.get("destination") or ""), "dedup_key": response.get("dedup_key", "")},+ )+++def _send_smtp(+ *,+ smtp_host: str,+ smtp_port: int,+ smtp_username: str,+ smtp_password: str,+ smtp_use_tls: bool,+ sender: str,+ recipients: list[str],+ subject: str,+ body: str,+) -> None:+ """One blocking SMTP send, called off the event loop.++ ``smtplib`` rather than a new dependency: the playbook packages state+ "zero external dependencies beyond httpx + stdlib" and the pack+ validator imports this tree with only jsonschema, pydantic and httpx+ installed. A dependency added here fails that job rather than this one.+ """+ message = EmailMessage()+ message["From"] = sender+ message["To"] = ", ".join(recipients)+ message["Subject"] = subject+ message.set_content(body)++ if smtp_use_tls:+ with smtplib.SMTP(smtp_host, smtp_port, timeout=_TIMEOUT_S) as server:+ server.starttls(context=ssl.create_default_context())+ if smtp_username:+ server.login(smtp_username, smtp_password)+ server.send_message(message)+ return+ with smtplib.SMTP(smtp_host, smtp_port, timeout=_TIMEOUT_S) as server:+ if smtp_username:+ server.login(smtp_username, smtp_password)+ server.send_message(message)+++@apply_contract+class EmailNotify(LiveActionExecutor):+ """Send a playbook notification over the tenant's SMTP relay."""++ vendor_id = "email"+ capability = "notify"+ description = "Send a playbook notification by email through the tenant's SMTP relay."+ requires_credentials = True+ _credential_keys: tuple[str, ...] = (+ "smtp_host",+ "smtp_port",+ "smtp_username",+ "smtp_password",+ "smtp_use_tls",+ "smtp_sender",+ "smtp_recipients",+ )++ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ if request.dry_run:+ return _simulated(self, request)++ params = request.params or {}+ host = str(params.get("smtp_host") or "").strip()+ raw_recipients = params.get("smtp_recipients") or params.get("to") or []+ recipients = [+ r.strip() for r in (raw_recipients.split(",") if isinstance(raw_recipients, str) else raw_recipients) if str(r).strip()+ ]+ if not host:+ return _missing(self, request, "an SMTP relay host")+ if not recipients:+ return _missing(self, request, "at least one recipient address")++ message = _message(request)+ try:+ await asyncio.to_thread(+ _send_smtp,+ smtp_host=host,+ smtp_port=int(params.get("smtp_port") or 587),+ smtp_username=str(params.get("smtp_username") or ""),+ smtp_password=str(params.get("smtp_password") or ""),+ smtp_use_tls=str(params.get("smtp_use_tls", "true")).strip().lower() not in {"0", "false", "no", "off"},+ sender=str(params.get("smtp_sender") or "aisoc@localhost"),+ recipients=recipients,+ subject=str(params.get("subject") or "AiSOC playbook notification"),+ body=message,+ )+ except Exception as exc: # noqa: BLE001 — a relay error is FAILED, never silent+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "the SMTP relay did not accept the notification",+ error=f"SMTP send failed: {exc}",+ )++ return _result(+ self,+ request,+ LiveActionStatus.SUCCEEDED,+ f"Emailed {len(recipients)} recipient(s): {message[:120]}",+ details={"destination": str(params.get("destination") or ""), "recipient_count": len(recipients)},+ )+++#: Channel name as a playbook author writes it -> the arm that serves it.+#: Exported so ``scripts`` and the API can answer "which channels deliver"+#: from the registry rather than from a second list.+NOTIFY_ARMS: tuple[type[LiveActionExecutor], ...] = (+ TeamsWebhookNotify,+ PagerDutyNotify,+ EmailNotify,+)+++def notify_payload_preview(vendor_id: str, message: str) -> str:+ """The exact body an arm would post, for the docs and the mock tests."""+ executor = next((arm for arm in NOTIFY_ARMS if arm.vendor_id == vendor_id), None)+ if executor is None or not hasattr(executor, "_payload"):+ return ""+ request = LiveActionRequest(capability="notify", vendor_id=vendor_id, params={"message": message})+ # Guarded by the `hasattr` above: `_payload` is defined by the arms+ # that build a body, and this returns "" for the ones that do not.+ return json.dumps(executor()._payload(request), sort_keys=True) # type: ignore[attr-defined]diff --git a/services/actions/app/live_actions/osquery_arms.py b/services/actions/app/live_actions/osquery_arms.pynew file mode 100644index 000000000..79e0cd245--- /dev/null+++ b/services/actions/app/live_actions/osquery_arms.py@@ -0,0 +1,249 @@+"""Distributed osquery live queries, as a governed verb.++``osquery_live_query`` was a step type the playbook engine declared, the+schema published, the natural-language drafter actively offered, and nothing+could run. Its handler lived in ``services/agents`` and opened with::++ from app.clients.osctrl_client import OsctrlClient++``app.clients`` exists only in this service, so every live query in the+shipped agents image raised ``ModuleNotFoundError``. It also fetched+credentials from ``GET /api/v1/connectors/instances/{id}`` and read+``auth_config`` off the response — a field whose own response model+documents that it is deliberately omitted — so in an image that *had* the+clients, the query would have gone out with no token.++Both faults are the same fault: the verb was being executed in the service+that holds neither the clients nor the vault. It belongs here, beside the+three clients that have been able to run it the whole time.++Vendor references+-----------------+* osctrl — https://github.com/jmpsec/osctrl (``POST /api/v1/queries/{env}``)+* FleetDM — https://fleetdm.com/docs/rest-api/rest-api#live-query+* osquery distributed read/write —+ https://osquery.readthedocs.io/en/stable/deployment/remote/++The SQL is never caller-supplied. ``app.clients.osquery_allowlist`` owns a+closed set of templates and the caller passes a template id plus parameters,+which is the same boundary ``lookup_endpoint_telemetry`` draws and for the+same reason: this verb is reachable from a playbook whose inputs came out of+attacker-influenced alert text.+"""++from __future__ import annotations++from typing import Any++import structlog++from app.clients.aisoc_direct_client import AiSOCDirectClient+from app.clients.fleetdm_client import FleetDMClient+from app.clients.osctrl_client import OsctrlClient+from app.clients.osquery_allowlist import AllowlistError+from app.live_actions.capability_contracts import apply_contract+from app.live_actions.executor import LiveActionExecutor+from app.live_actions.models import LiveActionRequest, LiveActionResult, LiveActionStatus++logger = structlog.get_logger(__name__)++#: Hard ceiling on how long an arm will wait for a fleet to answer. Mirrors+#: ``app.playbook.bounds.ABSOLUTE_MAX_TIMEOUT_SECONDS`` on the engine side: a+#: live query holds a worker for its whole duration, and ``params`` bypasses+#: the Pydantic validator that bounds ``PlaybookStep.timeout_seconds``.+_MAX_TIMEOUT_SECONDS = 300+_DEFAULT_TIMEOUT_SECONDS = 60+++def _result(+ executor: LiveActionExecutor,+ request: LiveActionRequest,+ status: LiveActionStatus,+ summary: str,+ *,+ details: dict[str, Any] | None = None,+ error: str | None = None,+) -> LiveActionResult:+ return LiveActionResult(+ request_id=request.request_id,+ status=status,+ capability=executor.capability,+ vendor_id=executor.vendor_id,+ summary=summary,+ details=details or {},+ error=error,+ )+++def _query_args(request: LiveActionRequest) -> tuple[list[str], str, dict[str, Any], int]:+ params = request.params or {}+ hosts = [str(h).strip() for h in (params.get("target_hosts") or []) if str(h).strip()]+ if not hosts and request.target:+ hosts = [str(request.target).strip()]+ template = str(params.get("template") or "").strip()+ template_params = params.get("template_params") or {}+ try:+ timeout = int(params.get("timeout_seconds") or _DEFAULT_TIMEOUT_SECONDS)+ except (TypeError, ValueError):+ timeout = _DEFAULT_TIMEOUT_SECONDS+ return hosts, template, dict(template_params), max(1, min(timeout, _MAX_TIMEOUT_SECONDS))+++class _OsqueryLiveQuery(LiveActionExecutor):+ """Shared body for the three fleet backends.++ Declares neither ``vendor_id`` nor ``capability``: the contract gate+ grades an intermediate class naming one without the other as a+ half-declared executor.+ """++ requires_credentials = True++ def _client(self, params: dict[str, Any]) -> Any:+ raise NotImplementedError++ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ hosts, template, template_params, timeout = _query_args(request)++ if not template:+ # Refused rather than defaulted. A live query with no template+ # has no SQL, and picking one for the caller would run a query+ # nobody asked for against production endpoints.+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "osquery live query needs a template id",+ error="'template' names an entry in the osquery allowlist and is required; no SQL is accepted from the caller.",+ )+ if not hosts:+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "osquery live query needs at least one target host",+ error="neither 'target_hosts' nor the step's target resolved to a host, so nothing would have been queried.",+ )++ if request.dry_run:+ return _result(+ self,+ request,+ LiveActionStatus.SIMULATED,+ f"would run osquery template {template!r} on {len(hosts)} host(s) via {self.vendor_id}",+ details={"would_query": template, "target_hosts": hosts, "backend": self.vendor_id},+ )++ client = self._client(request.params or {})+ if client is None:+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ f"{self.vendor_id} credentials are not configured",+ error=(+ f"{self.vendor_id} credentials are not configured, so the live query was not run. "+ f"This is not a statement about the hosts."+ ),+ )++ try:+ response = await client.live_query(hosts, template, template_params, timeout)+ except AllowlistError as exc:+ # A template the allowlist refuses is a permanent authoring+ # error, reported as such rather than as a vendor failure.+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ f"osquery template {template!r} is not on the allowlist",+ error=f"osquery allowlist violation: {exc}",+ )+ except Exception as exc: # noqa: BLE001 — a vendor error is FAILED, never silent+ logger.warning("osquery_live_query.failed", backend=self.vendor_id, error=str(exc))+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ f"{self.vendor_id} live query failed",+ error=f"{self.vendor_id} live query failed: {exc}",+ )++ rows = response.get("results") if isinstance(response, dict) else None+ return _result(+ self,+ request,+ LiveActionStatus.SUCCEEDED,+ f"Ran osquery template {template!r} on {len(hosts)} host(s) via {self.vendor_id}",+ details={+ "template": template,+ "target_hosts": hosts,+ "backend": self.vendor_id,+ "results": rows if rows is not None else response,+ },+ )+++@apply_contract+class OsctrlLiveQuery(_OsqueryLiveQuery):+ vendor_id = "osctrl"+ capability = "osquery_live_query"+ description = "Run an allowlisted osquery template across an osctrl environment."+ _credential_keys: tuple[str, ...] = ("base_url", "environment", "api_token", "verify_tls")++ def _client(self, params: dict[str, Any]) -> Any:+ base_url = str(params.get("base_url") or "").strip()+ api_token = str(params.get("api_token") or "").strip()+ if not base_url or not api_token:+ return None+ return OsctrlClient(+ base_url=base_url,+ environment=str(params.get("environment") or "default"),+ api_token=api_token,+ verify_tls=str(params.get("verify_tls", "true")).strip().lower() not in {"0", "false", "no", "off"},+ )+++@apply_contract+class FleetDMLiveQuery(_OsqueryLiveQuery):+ vendor_id = "fleetdm"+ capability = "osquery_live_query"+ description = "Run an allowlisted osquery template across a FleetDM fleet."+ _credential_keys: tuple[str, ...] = ("base_url", "api_token", "username", "password", "verify_tls")++ def _client(self, params: dict[str, Any]) -> Any:+ base_url = str(params.get("base_url") or "").strip()+ api_token = str(params.get("api_token") or "").strip() or None+ username = str(params.get("username") or "").strip() or None+ password = str(params.get("password") or "").strip() or None+ if not base_url or not (api_token or (username and password)):+ return None+ return FleetDMClient(+ base_url=base_url,+ api_token=api_token,+ username=username,+ password=password,+ verify_tls=str(params.get("verify_tls", "true")).strip().lower() not in {"0", "false", "no", "off"},+ )+++@apply_contract+class AiSOCDirectLiveQuery(_OsqueryLiveQuery):+ vendor_id = "aisoc_direct"+ capability = "osquery_live_query"+ description = "Run an allowlisted osquery template through AiSOC's own osquery TLS endpoint."+ _credential_keys: tuple[str, ...] = ("base_url", "api_token", "verify_tls")++ def _client(self, params: dict[str, Any]) -> Any:+ base_url = str(params.get("base_url") or "").strip()+ api_token = str(params.get("api_token") or "").strip()+ if not base_url or not api_token:+ return None+ return AiSOCDirectClient(+ base_url=base_url,+ api_token=api_token,+ verify_tls=str(params.get("verify_tls", "true")).strip().lower() not in {"0", "false", "no", "off"},+ )+++OSQUERY_ARMS: tuple[type[LiveActionExecutor], ...] = (OsctrlLiveQuery, FleetDMLiveQuery, AiSOCDirectLiveQuery)diff --git a/services/actions/tests/test_live_action_builtins.py b/services/actions/tests/test_live_action_builtins.pyindex fc2de1c87..4d43d806c 100644--- a/services/actions/tests/test_live_action_builtins.py+++ b/services/actions/tests/test_live_action_builtins.py@@ -66,7 +66,7 @@ def test_register_builtin_executors_returns_full_count() -> None:# sign-ins, Google Workspace login audit) and two verbs whose subject is# neither a host nor a principal (AWS CloudTrail lookup, Defender# endpoint-telemetry search).- assert count == 73+ assert count == 79def test_builtin_executors_cover_canonical_vendor_capability_pairs() -> None:@@ -152,6 +152,16 @@ def test_builtin_executors_cover_canonical_vendor_capability_pairs() -> None:("servicenow", "create_ticket"),("slack", "chatops_verify"),("slack", "notify"),+ # Depth 5.1 — `notify` had one arm while the playbook packs address+ # four channels, and `osquery_live_query` was a step type whose only+ # implementation imported these clients from a service that does not+ # contain them.+ ("teams", "notify"),+ ("email", "notify"),+ ("pagerduty", "notify"),+ ("osctrl", "osquery_live_query"),+ ("fleetdm", "osquery_live_query"),+ ("aisoc_direct", "osquery_live_query"),("splunk", "ack_alert"),("splunk", "create_notable_event"),("splunk", "suppress_alert"),@@ -189,7 +199,7 @@ def test_register_builtin_executors_is_idempotent_with_overwrite() -> None:register_builtin_executors()# Second call without overwrite would raise — confirm overwrite works.count = register_builtin_executors(overwrite=True)- assert count == 73+ assert count == 79def test_register_builtin_twice_without_overwrite_raises() -> None:diff --git a/services/actions/tests/test_notify_and_osquery_arms.py b/services/actions/tests/test_notify_and_osquery_arms.pynew file mode 100644index 000000000..a3e843b78--- /dev/null+++ b/services/actions/tests/test_notify_and_osquery_arms.py@@ -0,0 +1,350 @@+"""Depth 5.1 — the notify and osquery arms, against mock vendor servers.++Two classes of proof here, because the two classes of defect this replaces+are invisible to each other.++**Mock-vendor smoke.** Each arm is driven through its real httpx path against+a respx server returning the shape the vendor documents, so a wrong endpoint,+a wrong payload key or a normalize that KeyErrors is a failing test rather+than a 400 during an incident. Payload shapes are taken from the references+named in each arm's module docstring.++**Signature conformance, autospec'd.** Executor-to-client drift is invisible+in simulation mode because the client is never constructed —+``SearchSIEMExecutor`` passed ``max_results=`` to a client taking+``max_count`` and every live call raised ``TypeError`` while every test+passed. ``autospec=True`` makes the double enforce the real signature.++And one reproduce, kept as a regression: with no webhook configured,+``NotifySlackExecutor`` returned COMPLETED with ``message_sent: True``, and+because ``_LegacyExecutorAdapter`` previews by stripping credentials so the+executor takes its simulation branch — which that executor does not have —+*every dry run* reported a completed send.+"""++from __future__ import annotations++import inspect+import uuid+from typing import Any+from unittest.mock import patch++import httpx+import pytest+import respx+from app.clients.aisoc_direct_client import AiSOCDirectClient+from app.clients.fleetdm_client import FleetDMClient+from app.clients.osctrl_client import OsctrlClient+from app.clients.pagerduty_client import PagerDutyClient+from app.executors.notification import NotifySlackExecutor+from app.live_actions import notify_arms, osquery_arms+from app.live_actions.builtins import SlackNotify+from app.live_actions.executor import LiveActionExecutor+from app.live_actions.models import LiveActionRequest, LiveActionStatus+from app.models.action import ActionRequest, ActionStatus, ActionType++pytestmark = pytest.mark.asyncio+++def _request(vendor_id: str, capability: str = "notify", **params: Any) -> LiveActionRequest:+ return LiveActionRequest(capability=capability, vendor_id=vendor_id, params=params)+++# ---------------------------------------------------------------------------+# Reproduce: a notification nobody received, recorded as delivered+# ---------------------------------------------------------------------------+++async def test_slack_without_a_webhook_fails_rather_than_completing() -> None:+ result = await NotifySlackExecutor().execute(+ ActionRequest(+ action_type=ActionType.NOTIFY_SLACK,+ incident_id=uuid.uuid4(),+ tenant_id=uuid.uuid4(),+ target="#soc",+ rationale="test",+ parameters={},+ )+ )+ assert result.status == ActionStatus.FAILED+ assert "webhook" in (result.error or "").lower()+++async def test_slack_dry_run_is_simulated_not_completed() -> None:+ """The adapter has to simulate before the base class strips credentials.++ Fixing the executor to fail closed is necessary and not sufficient: with+ the credential stripped, a preview would then report a *failure*, which+ is equally untrue.+ """+ result = await SlackNotify().execute(+ _request("slack", webhook_url="https://hooks.slack.com/services/T/B/x", message="hello", dry_run=False)+ )+ # Sanity: without dry_run the adapter delegates. The dry-run branch is+ # the assertion below; this line proves the two paths are distinct.+ assert result.status in {LiveActionStatus.SUCCEEDED, LiveActionStatus.FAILED}++ preview = await SlackNotify().execute(+ LiveActionRequest(+ capability="notify",+ vendor_id="slack",+ params={"webhook_url": "https://hooks.slack.com/services/T/B/x", "message": "hello"},+ dry_run=True,+ )+ )+ assert preview.status == LiveActionStatus.SIMULATED+ assert "would notify" in preview.summary+++# ---------------------------------------------------------------------------+# Mock-vendor smoke — notify+# ---------------------------------------------------------------------------+++async def test_teams_posts_an_adaptive_card_to_a_workflows_webhook() -> None:+ route = respx.post("https://prod-1.westus.logic.azure.com/workflows/abc/triggers/manual/paths/invoke").mock(+ return_value=httpx.Response(202, text="")+ )+ result = await notify_arms.TeamsWebhookNotify().execute(+ _request(+ "teams",+ webhook_url="https://prod-1.westus.logic.azure.com/workflows/abc/triggers/manual/paths/invoke",+ message="Impossible travel for [email protected]",+ destination="TEAMS_SOC",+ )+ )+ assert result.status == LiveActionStatus.SUCCEEDED+ sent = route.calls[0].request+ body = sent.read().decode()+ assert '"type":"message"' in body+ assert "application/vnd.microsoft.card.adaptive" in body+ assert "Impossible travel for [email protected]" in body+ # The webhook URL is a bearer credential for Teams; the audit record+ # names the destination and never its address.+ assert result.details["destination"] == "TEAMS_SOC"+ assert "logic.azure.com" not in str(result.details)+++async def test_teams_reports_a_rejected_post_rather_than_succeeding() -> None:+ respx.post("https://teams.example/hook").mock(return_value=httpx.Response(400, text="Bad payload"))+ result = await notify_arms.TeamsWebhookNotify().execute(_request("teams", webhook_url="https://teams.example/hook", message="x"))+ assert result.status == LiveActionStatus.FAILED+ assert "400" in (result.error or "")+++async def test_pagerduty_triggers_through_the_events_api() -> None:+ route = respx.post("https://events.pagerduty.com/v2/enqueue").mock(+ return_value=httpx.Response(202, json={"status": "success", "message": "Event processed", "dedup_key": "dk-1"})+ )+ result = await notify_arms.PagerDutyNotify().execute(+ _request("pagerduty", pd_routing_key="R" * 32, message="Credential stuffing", severity="critical", destination="PD_SOC_KEY")+ )+ assert result.status == LiveActionStatus.SUCCEEDED+ body = route.calls[0].request.read().decode()+ assert '"event_action"' in body and "trigger" in body+ assert "critical" in body+++async def test_pagerduty_without_a_routing_key_says_so() -> None:+ result = await notify_arms.PagerDutyNotify().execute(_request("pagerduty", message="x"))+ assert result.status == LiveActionStatus.FAILED+ assert "routing key" in (result.error or "")+++async def test_email_sends_through_the_relay_off_the_event_loop() -> None:+ sent: dict[str, Any] = {}++ def _capture(**kwargs: Any) -> None:+ sent.update(kwargs)++ with patch.object(notify_arms, "_send_smtp", _capture):+ result = await notify_arms.EmailNotify().execute(+ _request(+ "email",+ smtp_host="smtp.example.com",+ smtp_port=587,+ smtp_sender="[email protected]",+ smtp_recipients="[email protected], [email protected]",+ message="Suspicious sign-in blocked",+ destination="EMAIL_SOC",+ )+ )+ assert result.status == LiveActionStatus.SUCCEEDED+ assert sent["recipients"] == ["[email protected]", "[email protected]"]+ assert sent["body"] == "Suspicious sign-in blocked"+ assert result.details["recipient_count"] == 2+++async def test_email_without_recipients_is_not_a_send() -> None:+ result = await notify_arms.EmailNotify().execute(_request("email", smtp_host="smtp.example.com", message="x"))+ assert result.status == LiveActionStatus.FAILED+ assert "recipient" in (result.error or "")++[email protected]("arm", notify_arms.NOTIFY_ARMS)+async def test_every_notify_arm_previews_without_touching_a_vendor(arm: type[LiveActionExecutor]) -> None:+ """Off by default means a preview reaches nothing, on every arm."""+ with respx.mock(assert_all_called=False) as mock:+ catch_all = mock.route(host__regex=r".*").mock(return_value=httpx.Response(500))+ result = await arm().execute(+ LiveActionRequest(+ capability="notify",+ vendor_id=arm.vendor_id,+ params={"webhook_url": "https://x.example/hook", "pd_routing_key": "k", "smtp_host": "s", "smtp_recipients": ["[email protected]"]},+ dry_run=True,+ )+ )+ assert result.status == LiveActionStatus.SIMULATED+ assert not catch_all.called+++# ---------------------------------------------------------------------------+# Credential strip — the list must match what the sender reads, exactly+# ---------------------------------------------------------------------------++[email protected]("arm", notify_arms.NOTIFY_ARMS + osquery_arms.OSQUERY_ARMS)+def test_declared_credential_keys_are_the_keys_the_arm_reads(arm: type[LiveActionExecutor]) -> None:+ """A key the sender reads and the list omits survives a dry run.++ That is not a theoretical hazard here: ``_SPLUNK_KEYS`` listed+ ``splunk_host``/``token``/``index`` while the client factory read+ ``splunk_url`` plus basic-auth credentials, so a "dry run" called the+ customer's Splunk. Elastic had the identical bug.++ Read off the source rather than by calling, because the branch that+ reads a key is often the one a test would not reach.+ """+ declared = set(getattr(arm, "_credential_keys", ()))+ body = inspect.getsource(arm)+ if arm in osquery_arms.OSQUERY_ARMS:+ body += inspect.getsource(osquery_arms._OsqueryLiveQuery)+ read = {key for key in declared if f'"{key}"' in body}+ assert read == declared, f"{arm.__name__} declares {sorted(declared - read)} that its sender never reads"++ # And the other direction: every params key the sender reads that looks+ # like a credential must be declared. `message`, `severity`, `subject`+ # and friends are content, not secrets, so they are named as exempt.+ content_keys = {"message", "text", "severity", "source", "dedup_key", "destination", "to", "subject", "target_hosts", "template"}+ reads = {+ match.strip("\"'")+ for match in __import__("re").findall(r'params\.get\(\s*["\']([a-z_]+)["\']', body)+ if match not in content_keys and not match.startswith("template")+ }+ assert reads <= declared, f"{arm.__name__} reads {sorted(reads - declared)} which a dry run would not strip"+++# ---------------------------------------------------------------------------+# Mock-vendor smoke — osquery+# ---------------------------------------------------------------------------+++async def test_osquery_refuses_a_step_with_no_template() -> None:+ """No SQL is accepted from a caller, so a missing template is a refusal.++ Defaulting to some template would run a query nobody asked for against+ production endpoints.+ """+ result = await osquery_arms.FleetDMLiveQuery().execute(+ LiveActionRequest(capability="osquery_live_query", vendor_id="fleetdm", target="WS-1", params={})+ )+ assert result.status == LiveActionStatus.FAILED+ assert "template" in (result.error or "")+++async def test_osquery_refuses_a_step_with_no_hosts() -> None:+ result = await osquery_arms.FleetDMLiveQuery().execute(+ LiveActionRequest(capability="osquery_live_query", vendor_id="fleetdm", params={"template": "processes_by_name"})+ )+ assert result.status == LiveActionStatus.FAILED+ assert "host" in (result.error or "")+++async def test_osquery_without_credentials_is_not_a_statement_about_the_hosts() -> None:+ result = await osquery_arms.OsctrlLiveQuery().execute(+ LiveActionRequest(+ capability="osquery_live_query",+ vendor_id="osctrl",+ target="WS-1",+ params={"template": "processes_by_name"},+ )+ )+ assert result.status == LiveActionStatus.FAILED+ assert "not a statement about the hosts" in (result.error or "")+++async def test_osquery_runs_the_allowlisted_template_through_its_client() -> None:+ """Autospec'd, so a signature drift between arm and client fails here.++ Simulation never constructs the client, which is exactly why this kind+ of drift shipped twice before: ``SearchSIEMExecutor`` passed+ ``max_results=`` to a client taking ``max_count``.+ """+ with patch.object(FleetDMClient, "live_query", autospec=True) as live_query:+ live_query.return_value = {"results": {"WS-1": [{"name": "mimikatz.exe", "pid": 4242}]}}+ result = await osquery_arms.FleetDMLiveQuery().execute(+ LiveActionRequest(+ capability="osquery_live_query",+ vendor_id="fleetdm",+ target="WS-1",+ params={+ "base_url": "https://fleet.example.com",+ "api_token": "t",+ "template": "processes_by_name",+ "template_params": {"name": "mimikatz.exe"},+ "timeout_seconds": 30,+ },+ )+ )+ assert result.status == LiveActionStatus.SUCCEEDED+ _self, hosts, template, template_params, timeout = live_query.call_args.args+ assert hosts == ["WS-1"]+ assert template == "processes_by_name"+ assert template_params == {"name": "mimikatz.exe"}+ assert timeout == 30+++async def test_osquery_clamps_an_unbounded_timeout() -> None:+ """``params`` bypasses the Pydantic bound on ``PlaybookStep``."""+ with patch.object(OsctrlClient, "live_query", autospec=True) as live_query:+ live_query.return_value = {"results": {}}+ await osquery_arms.OsctrlLiveQuery().execute(+ LiveActionRequest(+ capability="osquery_live_query",+ vendor_id="osctrl",+ target="WS-1",+ params={"base_url": "https://osctrl.example.com", "api_token": "t", "template": "t1", "timeout_seconds": 99999},+ )+ )+ assert live_query.call_args.args[4] == osquery_arms._MAX_TIMEOUT_SECONDS+++ ("arm", "client"),+ [+ (osquery_arms.OsctrlLiveQuery, OsctrlClient),+ (osquery_arms.FleetDMLiveQuery, FleetDMClient),+ (osquery_arms.AiSOCDirectLiveQuery, AiSOCDirectClient),+ ],+)+def test_each_arm_builds_its_client_with_a_signature_the_client_accepts(arm: type, client: type) -> None:+ """Constructor drift is the other half of the simulation blind spot."""+ built = arm()._client({"base_url": "https://x.example.com", "api_token": "t", "environment": "prod"})+ assert isinstance(built, client)+++def test_pagerduty_arm_matches_the_client_signature() -> None:+ """Caught a real drift while this file was being written.++ The arm passed ``dedup_key=``; the client takes ``case_id`` and derives+ the dedup key from it. Simulation never constructs the client, so the+ first time anyone would have seen it was a live page that raised+ ``TypeError`` instead of going out.+ """+ signature = inspect.signature(PagerDutyClient.trigger_incident)+ for name in ("summary", "severity", "source", "case_id"):+ assert name in signature.parameters, f"PagerDutyNotify passes {name!r}, which the client does not accept"+ assert "dedup_key" not in signature.parametersdiff --git a/services/agents/app/playbook/engine.py b/services/agents/app/playbook/engine.pyindex bb363ad6f..77a65d8dd 100644--- a/services/agents/app/playbook/engine.py+++ b/services/agents/app/playbook/engine.py@@ -13,8 +13,10 @@ Design goals:from __future__ import annotationsimport asyncio+import jsonimport loggingimport os+import reimport timeimport uuidfrom datetime import UTC, datetime@@ -25,7 +27,7 @@ import httpxfrom app.playbook import pause as playbook_pause-from . import action_bridge+from . import action_bridge, referencesfrom .bounds import clamp_timeoutfrom .errors import PermanentStepFailurefrom .models import Playbook, PlaybookStep, StepCondition, StepType@@ -401,44 +403,154 @@ async def _handle_investigate(step: PlaybookStep, context: dict[str, Any], http:return r.json()-async def _handle_notify(step: PlaybookStep, context: dict[str, Any], http: httpx.AsyncClient) -> dict:- channel = step.params.get("channel", "webhook")- url = step.params.get("url", "")- message = step.params.get("message", "AiSOC playbook notification")- # Simple template substitution- for k, v in context.items():- message = message.replace(f"{{{{{k}}}}}", str(v))+#: ``${NAME}`` — an integration this tenant has configured. Resolved by the+#: API against connector instances and the vault; see `app.playbook.references`.+_REFERENCE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")- if channel == "webhook" and url:- # SSRF guard: webhook URLs are author-controlled; reject loopback,- # cloud-metadata, and other unsafe destinations before dispatching.+#: ``{{dot.path}}`` — a value from the run context. Rendered in this process,+#: because the context never leaves it.+_CONTEXT_TOKEN = re.compile(r"\{\{\s*([A-Za-z_][\w.]*)\s*\}\}")+++def _render_context(text: str, context: dict[str, Any]) -> str:+ """Substitute ``{{dot.path}}`` from the run context.++ An unresolved path renders as the empty string rather than leaving the+ braces in place. Leaving them would put a literal ``{{alert.user}}`` into+ a URL path or a pager message, which reads to whoever receives it as a+ templating bug in AiSOC rather than as a field the alert did not carry.+ ``_resolve_field`` already distinguishes the two for conditions; here the+ step's own result records which paths were empty.+ """++ def _one(match: re.Match[str]) -> str:+ value = _resolve_field(context, match.group(1))+ if value is None:+ return ""+ if isinstance(value, dict | list):+ return json.dumps(value, separators=(",", ":"))+ return str(value)++ return _CONTEXT_TOKEN.sub(_one, text)+++def _unrendered_context_paths(text: str, context: dict[str, Any]) -> list[str]:+ return sorted({m.group(1) for m in _CONTEXT_TOKEN.finditer(text) if _resolve_field(context, m.group(1)) is None})+++def _notify_execute_enabled() -> bool:+ """Whether a notify step may reach a person.++ Off unless an operator turns it on, for the reason every outbound verb+ in this engine is: a playbook that pages on-call the moment it is+ imported is a worse first-run experience than one that previews.+ Governance downstream can still refuse what this allows.+ """+ return os.getenv("AISOC_PLAYBOOK_NOTIFY_EXECUTE", "0").strip().lower() in {"1", "true", "yes", "on"}+++def _http_execute_enabled() -> bool:+ """Whether an http step may leave the process.++ An ``http`` step in the shipped packs deletes sessions, posts WAF rules+ and resets passwords in bulk. It changes vendor state through a path the+ capability contract cannot see, so it ships off and previews instead.+ """+ return os.getenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "0").strip().lower() in {"1", "true", "yes", "on"}+++async def _handle_http(step: PlaybookStep, context: dict[str, Any], http: httpx.AsyncClient | None) -> dict:+ """Call one path on one of the tenant's configured integrations.++ Three things happen in an order that matters:++ 1. ``{{dot.path}}`` is rendered from the run context, in this process.+ 2. ``${NAME}`` is resolved by the API from connector instances and the+ vault. Before this, nothing resolved it and all 69 steps in the packs+ died at the guard with ``scheme '' is not allowed`` — ``urlsplit``+ reads a string beginning ``${`` as having no scheme.+ 3. The *resolved* URL goes through the SSRF guard. After substitution,+ not before: the value came out of a tenant record, so it is exactly+ as untrusted as the step that asked for it.+ """+ method = str(step.params.get("method", "POST")).upper()+ raw_url = str(step.params.get("url", ""))+ headers_ref = str(step.params.get("headers_env") or "")+ body_template = step.params.get("body_template")++ url = _render_context(raw_url, context)+ names = [m.group(1) for m in _REFERENCE.finditer(url)]+ if headers_ref:+ names.append(headers_ref)++ resolved = await references.resolve(tenant_id=str(context.get("tenant_id") or ""), names=names) if names else {}++ missing = sorted({name for name in names if name not in resolved})+ if missing:+ return {+ "executed": False,+ "error": (+ f"this tenant has no integration configured for {', '.join(missing)}, so the step was not sent. "+ f"Connect it, or map the name on the connector instance."+ ),+ "unresolved_references": missing,+ }++ url = _REFERENCE.sub(lambda m: str(resolved[m.group(1)].get("value", "")), url)++ headers: dict[str, str] = {str(k): str(v) for k, v in (step.params.get("headers") or {}).items()}+ if headers_ref:+ headers.update({str(k): str(v) for k, v in (resolved[headers_ref].get("headers") or {}).items()})++ body: Any = step.params.get("body", {})+ if isinstance(body_template, str):+ rendered = _render_context(body_template, context)try:- validate_outbound_url(url)- except SSRFError as exc:- raise SSRFError(f"notify step rejected: {exc}") from exc- r = await http.post(url, json={"text": message}, timeout=step.timeout_seconds)- return {"status": r.status_code}- # Why it did not deliver, accurately. This said "no url" whatever the- # cause, including when a url *was* supplied and the channel simply- # was not `webhook` — so an operator debugging a silent playbook went- # looking for a missing field that was right there in front of them.- reason = "no url" if not url else f"channel {channel!r} has no sender; only 'webhook' delivers, and a url was supplied"- return {"channel": channel, "message": message, "delivered": False, "reason": reason}---async def _handle_http(step: PlaybookStep, context: dict[str, Any], http: httpx.AsyncClient) -> dict:- method = step.params.get("method", "POST").upper()- url = step.params.get("url", "")- body = step.params.get("body", {})- headers = step.params.get("headers", {})- # SSRF guard: arbitrary HTTP calls from playbooks must not reach- # loopback, RFC1918, link-local, or cloud-metadata endpoints by default.+ body = json.loads(rendered)+ except json.JSONDecodeError:+ # Sent as text rather than guessed at. A body_template that does+ # not render to JSON is an authoring error, and silently posting+ # ``{}`` instead would make a bulk password reset look like it+ # ran against nobody.+ body = None+ headers.setdefault("Content-Type", "text/plain")+try:validate_outbound_url(url)except SSRFError as exc:raise SSRFError(f"http step rejected: {exc}") from exc- r = await http.request(method, url, json=body, headers=headers, timeout=step.timeout_seconds)- return {"status": r.status_code, "body": r.text[:500]}++ # Header *names* only, in both branches. The run record is readable by+ # anyone with access to the case, and a resolved bearer token in it is a+ # credential leak that outlives the incident.+ record: dict[str, Any] = {+ "url": url,+ "method": method,+ "header_names": sorted(headers),+ "unrendered_context_paths": _unrendered_context_paths(raw_url, context),+ }++ if not _http_execute_enabled():+ return {+ **record,+ "executed": False,+ "previewed": True,+ "reason": "http steps preview unless AISOC_PLAYBOOK_HTTP_EXECUTE is set; nothing was sent",+ }++ assert http is not None, "a live http step needs the engine's client"+ if body is None:+ response = await http.request(+ method, url, content=_render_context(str(body_template), context), headers=headers, timeout=step.timeout_seconds+ )+ else:+ response = await http.request(method, url, json=body, headers=headers, timeout=step.timeout_seconds)+ return {+ **record,+ "executed": 200 <= response.status_code < 300,+ "status": response.status_code,+ "body": response.text[:500],+ }# ---------------------------------------------------------------------------@@ -479,8 +591,66 @@ _TARGET_KEYS: dict[StepType, tuple[str, ...]] = {StepType.SEARCH_SIEM: ("query", "search"),StepType.CREATE_NOTABLE_EVENT: ("title", "name"),StepType.CREATE_TICKET: (),+ # Depth 5.1. `notify` was answered inside the engine with one sender+ # (`channel == "webhook"`) while all 63 steps in the packs address Slack,+ # Teams, email or PagerDuty by `webhook_env` / `service_key_env`. It is a+ # contracted capability in `services/actions` with a Slack arm that+ # predates this work, so the verb moves to where its credentials and its+ # contract already live rather than growing a second set of senders here.+ StepType.NOTIFY: ("recipient", "channel_name", "to"),+ # Same move, different reason. The in-engine handler imported+ # `app.clients.osctrl_client`, which exists only in `services/actions`, so+ # every live query in this image raised. The clients it wanted are beside+ # the executors it now dispatches to.+ StepType.OSQUERY_LIVE_QUERY: ("host", "hostname", "device_id", "host_id"),}+#: Verbs whose step params do not already read as the capability's params.+#: Keyed by step type, each returns ``(vendor_id, params)``.+#:+#: Written as a table rather than inside the handler factory so the mapping+#: is visible next to the target keys above. A verb that needs one of these+#: and does not have one dispatches with the author's spelling, which the+#: executor does not read — the shape that made every pack notify send the+#: default string, because the packs write `message_template` and the old+#: handler read `message`.+_PARAM_ADAPTERS: dict[StepType, Any] = {}+++def _notify_params(step: PlaybookStep, context: dict[str, Any]) -> tuple[str, dict[str, Any]]:+ """Channel picks the vendor arm; the rendered template is the message.++ The channel is pinned into ``vendor_id`` rather than left for the+ executor to infer, for the reason the SIEM arms pin ``alert_vendor``:+ otherwise whichever destination happens to have credentials first+ decides where a page goes.+ """+ params = dict(step.params)+ template = params.pop("message_template", None) or params.get("message") or "AiSOC playbook notification"+ params["message"] = _render_context(str(template), context)+ channel = str(params.pop("channel", "") or "").strip().lower()+ return channel, params+++def _osquery_params(step: PlaybookStep, context: dict[str, Any]) -> tuple[str, dict[str, Any]]:+ """The backend picks the vendor arm; the hosts are the fleet to ask.++ The timeout is clamped here and again in the executor. Not belt and+ braces for its own sake: ``params`` is an untyped dict that bypasses the+ Pydantic bound on ``PlaybookStep.timeout_seconds``, so a playbook could+ otherwise ask a fleet for a day — and the two services deploy+ independently, so neither can rely on the other having clamped first.+ """+ params = dict(step.params)+ backend = str(params.pop("backend", "") or "osctrl").strip().lower()+ if not params.get("target_hosts"):+ host = _resolve_target(step, context)+ if host:+ params["target_hosts"] = [host]+ params["timeout_seconds"] = clamp_timeout(params.get("timeout_seconds", 60), default=60)+ return backend, params++#: Step types that name a verb but deliberately have no bridge, with the#: reason. The engine reports the reason instead of a bare "no handler", and#: the schema's ``x-aisoc-execution`` map records the same state, so an author@@ -537,12 +707,18 @@ def _make_response_handler(step_type: StepType):"""async def _handler(step: PlaybookStep, context: dict[str, Any], http: httpx.AsyncClient) -> dict:+ adapter = _PARAM_ADAPTERS.get(step_type)+ if adapter is None:+ vendor_id = str(step.params.get("vendor") or step.params.get("vendor_id") or "")+ params = dict(step.params)+ else:+ vendor_id, params = adapter(step, context)report = await action_bridge.dispatch_step(capability=step_type.value,tenant_id=str(context.get("tenant_id") or ""),target=_resolve_target(step, context),- params=dict(step.params),- vendor_id=str(step.params.get("vendor") or step.params.get("vendor_id") or ""),+ params=params,+ vendor_id=vendor_id,confidence=_resolve_confidence(step, context),playbook_run_id=str(context.get("_run_id") or ""),playbook_step_id=step.id,@@ -570,131 +746,23 @@ async def _handle_close_case(step: PlaybookStep, context: dict[str, Any], http:return {"case_id": case_id, "status": "closed"}-async def _handle_osquery_live_query(step: PlaybookStep, context: dict[str, Any], http: httpx.AsyncClient) -> dict:- """Dispatch a distributed osquery live query via osctrl, FleetDM, or aisoc-direct.-- Expected ``step.params`` keys- ------------------------------- backend : str- One of ``"osctrl"``, ``"fleetdm"``, ``"aisoc_direct"``.- instance_id : str- Connector instance ID (looked up from the API to retrieve credentials).- target_hosts : list[str]- Host UUIDs / hostnames to query.- template : str- Allowlist template ID (see ``osquery_allowlist``).- template_params : dict, optional- Parameters forwarded to the template renderer.- timeout_seconds : int, optional- How long to wait for all hosts to respond (default: 60).- """- # These osquery clients live in `services/actions`, not in this service —- # `services/agents/app/clients/` does not exist. Every `osquery_live_query`- # step therefore died with an unhandled ModuleNotFoundError at execution- # time, and the `except AllowlistError` handler below referenced a name- # that could never bind. The NL playbook drafter actively offers this step- # type, so a user could author a playbook that was guaranteed to crash.- #- # Fail with an actionable message instead of a traceback. Wiring this- # properly means dispatching through the actions service over HTTP, the- # same way SIEM writeback already does, rather than importing across a- # service boundary that does not exist in this image.- try:- from app.clients.aisoc_direct_client import AiSOCDirectClient # noqa: PLC0415- from app.clients.fleetdm_client import FleetDMClient # noqa: PLC0415- from app.clients.osctrl_client import OsctrlClient # noqa: PLC0415- from app.clients.osquery_allowlist import AllowlistError # noqa: PLC0415- except ModuleNotFoundError as exc:- # Raised, not returned. A returned dict leaves ``step_status`` at- # SUCCESS, so every live query in the shipped agents image — where- # these clients are always absent — was reported as a step that ran- # while nothing had been asked of any endpoint. That is the same- # defect the missing-handler branch above exists to remove, and it- # became reachable from the console the moment the editor could- # author this step type.- #- # Permanent because the module will not appear between attempt one- # and attempt four: the image either ships the clients or it does not.- logger.error("playbook.osquery_clients_unavailable: %s", exc)- raise PermanentStepFailure(- "osquery_live_query is not executable in the agents service: the "- "osquery backend clients ship in services/actions. Run this step "- "through the actions service, or remove it from the playbook."- ) from exc-- backend: str = step.params.get("backend", "osctrl")- target_hosts: list[str] = step.params.get("target_hosts") or [context.get("host_id") or context.get("host", "")]- template: str = step.params.get("template", "")- template_params: dict[str, Any] = step.params.get("template_params") or {}- # Runtime clamp — params bypass the Pydantic validator on PlaybookStep, so- # a malicious or malformed playbook could otherwise pin the connector- # thread for hours. See services/agents/app/playbook/bounds.py.- timeout_seconds: int = clamp_timeout(step.params.get("timeout_seconds", 60), default=60)-- if not template:- return {"error": "osquery_live_query: 'template' param is required", "partial": True}-- # Credential resolution: fetch the connector instance config from the API.- instance_id: str = step.params.get("instance_id") or context.get("connector_instance_id", "")- creds: dict[str, Any] = {}- if instance_id:- try:- r = await http.get(- f"{_API_URL}/api/v1/connectors/instances/{instance_id}",- timeout=10,- )- if r.status_code == 200:- creds = r.json().get("auth_config") or {}- except Exception as exc: # noqa: BLE001- logger.warning("Could not fetch connector creds for %s: %s", instance_id, exc)-- try:- if backend == "osctrl":- client = OsctrlClient(- base_url=creds.get("base_url") or step.params.get("base_url", ""),- environment=creds.get("environment") or step.params.get("environment", "default"),- api_token=creds.get("api_token") or step.params.get("api_token", ""),- verify_tls=step.params.get("verify_tls", True),- )- return await client.live_query(target_hosts, template, template_params, timeout_seconds)-- if backend == "fleetdm":- client_fleet = FleetDMClient(- base_url=creds.get("base_url") or step.params.get("base_url", ""),- api_token=creds.get("api_token") or step.params.get("api_token") or None,- username=creds.get("username") or step.params.get("username") or None,- password=creds.get("password") or step.params.get("password") or None,- verify_tls=step.params.get("verify_tls", True),- )- return await client_fleet.live_query(target_hosts, template, template_params, timeout_seconds)-- if backend == "aisoc_direct":- client_direct = AiSOCDirectClient(- base_url=creds.get("base_url") or step.params.get("base_url", ""),- api_token=creds.get("api_token") or step.params.get("api_token", ""),- )- return await client_direct.live_query(target_hosts, template, template_params, timeout_seconds)-- return {"error": f"Unknown osquery backend: {backend!r}", "partial": True}-- except AllowlistError as exc:- return {"error": f"osquery allowlist violation: {exc}", "partial": True}- except NotImplementedError as exc:- return {"error": str(exc), "partial": True, "stub": True}--#: Verbs dispatched through the action registry. Derived from `_TARGET_KEYS`#: so the two cannot drift: a verb added to one without the other would#: either dispatch with no target or declare a target nothing reads.RESPONSE_STEP_TYPES: frozenset[StepType] = frozenset(_TARGET_KEYS)+_PARAM_ADAPTERS.update(+ {+ StepType.NOTIFY: _notify_params,+ StepType.OSQUERY_LIVE_QUERY: _osquery_params,+ }+)+_HANDLERS = {StepType.ENRICH: _handle_enrich,StepType.INVESTIGATE: _handle_investigate,- StepType.NOTIFY: _handle_notify,StepType.HTTP: _handle_http,StepType.CLOSE_CASE: _handle_close_case,- StepType.OSQUERY_LIVE_QUERY: _handle_osquery_live_query,**{step_type: _make_response_handler(step_type) for step_type in sorted(RESPONSE_STEP_TYPES, key=lambda s: s.value)},}@@ -1056,7 +1124,18 @@ class PlaybookEngine:# Reporting those as SUCCESS is the defect this# whole path exists to remove, so they fail closed# and the default `on_failure: abort` halts the run.- if step.type in RESPONSE_STEP_TYPES and not result.get("executed"):+ #+ # Except under `dry_run`, where no handler was+ # called and `executed: False` is the answer the+ # caller asked for. Applying it there made a+ # preview of *any* containment playbook report+ # FAILED — so the one mode an author uses to check+ # a playbook before trusting it could not tell a+ # sound playbook from a broken one. The result+ # still says `executed: false`; what changes is+ # that the engine stops calling its own preview a+ # failure.+ if not dry_run and step.type in RESPONSE_STEP_TYPES and not result.get("executed"):step_status = StepStatus.FAILEDresult.setdefault("error",diff --git a/services/agents/app/playbook/references.py b/services/agents/app/playbook/references.pynew file mode 100644index 000000000..4d710b020--- /dev/null+++ b/services/agents/app/playbook/references.py@@ -0,0 +1,100 @@+"""Resolve the ``${NAME}`` integration references a playbook's ``http`` steps use.++Every ``http`` step in the shipped packs addresses its target the same way::++ "url": "${IDP_BASE_URL}/users/{{alert.user}}/sessions",+ "headers_env": "IDP_BEARER_HEADERS"++``${NAME}`` names a *configured integration*, never a host. That distinction+is the security property, not a formatting convention: a playbook author can+choose which of the tenant's integrations to call and which path under it,+and cannot choose the origin. Substituting a free-text URL would turn every+pack playbook into an outbound request primitive pointed wherever its author+liked.++Resolution happens in ``services/api`` because that service holds the+credential vault and the tenant session — the same division ``action_bridge``+works to. What comes back is a rendered reference, and for a ``*_HEADERS``+reference that includes the header values. They are held in memory for the+duration of one request, passed to httpx, and never written to the run+record: :func:`app.playbook.engine._handle_http` records header *names*.++The outbound call itself stays in this service so it passes+``app.playbook.ssrf_guard.validate_outbound_url`` — after substitution, which+is the only order that works. The stored value of a reference is tenant data,+so a value pointing at ``169.254.169.254`` has to be refused by the guard+rather than trusted because it came from a database.+"""++from __future__ import annotations++import logging+import os+from typing import Any++import httpx++from .errors import PermanentStepFailure++logger = logging.getLogger("aisoc.playbook.references")++_API_URL = os.getenv("API_SERVICE_URL", os.getenv("API_URL", "http://api:8000"))+_TIMEOUT_S = float(os.getenv("AISOC_PLAYBOOK_REFERENCE_TIMEOUT_S", "15"))+++class ReferenceUnavailable(PermanentStepFailure):+ """The references could not be fetched, and a retry will not change that.++ Permanent for the reason ``BridgeMisconfigured`` is: the three ways this+ fails are an unset service token, a tenant missing from the run context+ and an API that refused the request. None of them resolves while a step+ sleeps between attempts.+ """+++def _service_token() -> str:+ return os.getenv("AISOC_AGENTS_SERVICE_TOKEN", "").strip()+++async def resolve(*, tenant_id: str, names: list[str]) -> dict[str, Any]:+ """Return ``{name: {...}}`` for the references this tenant has configured.++ A name the tenant has not configured is simply absent from the result.+ The caller reports which ones it needed and did not get, because "you+ have no Okta connected" is a different sentence from "the lookup failed"+ and only one of them is about the playbook.+ """+ if not names:+ return {}+ if not tenant_id:+ raise ReferenceUnavailable("this run has no tenant, so no integration reference can be resolved for it")++ token = _service_token()+ if not token:+ raise ReferenceUnavailable(+ f"AISOC_AGENTS_SERVICE_TOKEN is unset, so the API's service path is closed and {', '.join(sorted(names))} cannot be resolved"+ )++ url = f"{_API_URL.rstrip('/')}/api/v1/playbook-steps/references"+ try:+ async with httpx.AsyncClient(timeout=_TIMEOUT_S) as client:+ response = await client.post(+ url,+ json={"tenant_id": tenant_id, "names": sorted(set(names))},+ headers={"X-AiSOC-Service-Token": token},+ )+ except httpx.HTTPError as exc:+ raise ReferenceUnavailable(f"the API could not be reached to resolve {', '.join(sorted(names))}: {exc}") from exc++ if response.status_code >= 400:+ raise ReferenceUnavailable(f"the API refused the reference lookup with HTTP {response.status_code}")++ try:+ body = response.json()+ except ValueError as exc:+ raise ReferenceUnavailable("the API returned a non-JSON body for the reference lookup") from exc++ resolved = body.get("references")+ if not isinstance(resolved, dict):+ raise ReferenceUnavailable("the API returned a reference lookup with no 'references' map")+ return resolveddiff --git a/services/agents/tests/test_osquery_live_query_step.py b/services/agents/tests/test_osquery_live_query_step.pyindex 6658c4bb5..dcfb8a33b 100644--- a/services/agents/tests/test_osquery_live_query_step.py+++ b/services/agents/tests/test_osquery_live_query_step.py@@ -1,453 +1,146 @@-"""-Unit tests for the osquery_live_query playbook step handler.--Tests exercise ``_handle_osquery_live_query`` directly with patched client-classes injected via sys.modules, so no real network calls are made.+"""The ``osquery_live_query`` step, after it stopped being an engine handler.++This file used to drive ``_handle_osquery_live_query`` with the three client+classes injected into ``sys.modules``. That mock was the defect: it supplied+``app.clients.osctrl_client``, which does not exist in the agents image, so+every test passed against an arrangement no deployment ever had. The handler+raised ``ModuleNotFoundError`` on the first line of its import block in+production, and for the one backend that could be reached it would have+called with no credentials, because it read ``auth_config`` off a connector+response whose model documents that the field is deliberately omitted.++The verb is now dispatched to ``services/actions``, where the three clients+live. What is left to test here is the engine's half: the backend picks the+vendor arm, the host comes from the step or the run context, and the timeout+is clamped before it leaves — ``params`` is an untyped dict that bypasses the+Pydantic bound on ``PlaybookStep.timeout_seconds``, which is the whole reason+the runtime clamp exists. The arms themselves are covered in+``services/actions/tests/test_notify_and_osquery_arms.py``."""from __future__ import annotations-import sys-import typesfrom typing import Any-from unittest.mock import AsyncMock, MagicMockimport pytest+from app.playbook import engine as engine_mod+from app.playbook.models import PlaybookStep, StepType-# ----------------------------------------------------------------------------# Inject stub modules BEFORE importing the engine (engine does lazy imports-# inside the handler, so sys.modules stubs are enough).-# ----------------------------------------------------------------------------+pytestmark = pytest.mark.asyncio-class AllowlistError(Exception):- pass---class OsctrlError(Exception):- pass+def _step(params: dict[str, Any]) -> PlaybookStep:+ return PlaybookStep(id="s1", name="osquery-step", type=StepType.OSQUERY_LIVE_QUERY, params=params)-class FleetDMError(Exception):- pass+def dispatched(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Any]]:+ calls: list[dict[str, Any]] = []-def _inject_stubs(- *,- osctrl_live_query: Any = None,- fleetdm_live_query: Any = None,- direct_live_query: Any = None,-) -> None:- """(Re-)inject stub modules with the provided live_query implementations."""+ async def _fake_dispatch(**kwargs: Any) -> dict[str, Any]:+ calls.append(kwargs)+ return {"executed": True, "status": "succeeded", "summary": "ran"}- # --- osquery_allowlist ---- al_mod = types.ModuleType("app.clients.osquery_allowlist")- al_mod.AllowlistError = AllowlistError # type: ignore[attr-defined]- sys.modules["app.clients.osquery_allowlist"] = al_mod+ monkeypatch.setattr(engine_mod.action_bridge, "dispatch_step", _fake_dispatch)+ return calls- # --- osctrl_client ---- osc_instance = AsyncMock()- if osctrl_live_query is not None:- osc_instance.live_query = osctrl_live_query- osc_cls = MagicMock(return_value=osc_instance)- osc_mod = types.ModuleType("app.clients.osctrl_client")- osc_mod.OsctrlClient = osc_cls # type: ignore[attr-defined]- osc_mod.OsctrlError = OsctrlError # type: ignore[attr-defined]- sys.modules["app.clients.osctrl_client"] = osc_mod- # --- fleetdm_client ---- fleet_instance = AsyncMock()- if fleetdm_live_query is not None:- fleet_instance.live_query = fleetdm_live_query- fleet_cls = MagicMock(return_value=fleet_instance)- fleet_mod = types.ModuleType("app.clients.fleetdm_client")- fleet_mod.FleetDMClient = fleet_cls # type: ignore[attr-defined]- fleet_mod.FleetDMError = FleetDMError # type: ignore[attr-defined]- sys.modules["app.clients.fleetdm_client"] = fleet_mod+async def _run(step: PlaybookStep, context: dict[str, Any] | None = None) -> None:+ await engine_mod._HANDLERS[StepType.OSQUERY_LIVE_QUERY](step, {"tenant_id": "t", **(context or {})}, None)- # --- aisoc_direct_client ---- direct_instance = AsyncMock()- if direct_live_query is not None:- direct_instance.live_query = direct_live_query- direct_cls = MagicMock(return_value=direct_instance)- direct_mod = types.ModuleType("app.clients.aisoc_direct_client")- direct_mod.AiSOCDirectClient = direct_cls # type: ignore[attr-defined]- sys.modules["app.clients.aisoc_direct_client"] = direct_mod- return osc_instance, fleet_instance, direct_instance # type: ignore[return-value]+class TestBackendSelectsTheArm:+ @pytest.mark.parametrize("backend", ["osctrl", "fleetdm", "aisoc_direct"])+ async def test_backend_becomes_the_vendor(self, dispatched: list[dict[str, Any]], backend: str) -> None:+ await _run(_step({"backend": backend, "template": "running_processes", "target_hosts": ["h1"]}))+ assert dispatched[0]["vendor_id"] == backend+ async def test_missing_backend_defaults_to_osctrl(self, dispatched: list[dict[str, Any]]) -> None:+ await _run(_step({"template": "running_processes", "target_hosts": ["h1"]}))+ assert dispatched[0]["vendor_id"] == "osctrl"-# Perform an initial injection before the engine import so sys.modules is-# populated when the engine module is loaded (even though the imports inside-# the handler are deferred, Python still needs the top-level `app` package).-_inject_stubs()+ async def test_an_unknown_backend_is_passed_through_not_substituted(self, dispatched: list[dict[str, Any]]) -> None:+ """Dispatch answers ``no_integration`` for a vendor with no arm.-from app.playbook.engine import _handle_osquery_live_query # noqa: E402-from app.playbook.models import PlaybookStep, StepType # noqa: E402+ Substituting a default here would run the query on a fleet the author+ did not name, which is worse than refusing.+ """+ await _run(_step({"backend": "nonexistent", "template": "t", "target_hosts": ["h1"]}))+ assert dispatched[0]["vendor_id"] == "nonexistent"-# ----------------------------------------------------------------------------# Helpers-# ---------------------------------------------------------------------------+class TestHostResolution:+ async def test_target_hosts_is_used_when_present(self, dispatched: list[dict[str, Any]]) -> None:+ await _run(_step({"template": "t", "target_hosts": ["h1", "h2"]}))+ assert dispatched[0]["params"]["target_hosts"] == ["h1", "h2"]-def _step(params: dict[str, Any]) -> PlaybookStep:- return PlaybookStep(- id="s1",- name="osquery-step",- type=StepType.OSQUERY_LIVE_QUERY,- params=params,- )---def _ctx(**kwargs: Any) -> dict[str, Any]:- base: dict[str, Any] = {"host": "host1", "connector_instance_id": ""}- base.update(kwargs)- return base---# ----------------------------------------------------------------------------# Tests-# ------------------------------------------------------------------------------class TestMissingTemplate:- @pytest.mark.asyncio- async def test_missing_template_returns_error(self) -> None:- _inject_stubs()- step = _step({"backend": "osctrl", "target_hosts": ["h1"], "base_url": "http://osc", "api_token": "t"})- step.params.pop("template", None)- result = await _handle_osquery_live_query(step, _ctx(), MagicMock())- assert "error" in result- assert result.get("partial") is True---class TestUnknownBackend:- @pytest.mark.asyncio- async def test_unknown_backend_returns_error(self) -> None:- _inject_stubs()- step = _step(- {- "backend": "nonexistent_backend",- "template": "running_processes",- "target_hosts": ["h1"],- }- )- result = await _handle_osquery_live_query(step, _ctx(), MagicMock())- assert "error" in result- assert "nonexistent_backend" in result["error"]- assert result.get("partial") is True---class TestAllowlistViolation:- @pytest.mark.asyncio- async def test_allowlist_error_caught(self) -> None:- lq = AsyncMock(side_effect=AllowlistError("bad template"))- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- }- )- result = await _handle_osquery_live_query(step, _ctx(), MagicMock())- assert "error" in result- assert "allowlist" in result["error"]- assert result.get("partial") is True---class TestOsctrlDispatch:- @pytest.mark.asyncio- async def test_osctrl_backend_dispatches_correctly(self) -> None:- expected = {"results": {"h1": [{"pid": "1"}]}, "partial": False}- lq = AsyncMock(return_value=expected)- osc_instance, _, _ = _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "environment": "prod",- "api_token": "tok",- }- )- result = await _handle_osquery_live_query(step, _ctx(), MagicMock())- assert result == expected- lq.assert_awaited_once_with(["h1"], "running_processes", {}, 60)---class TestFleetDMDispatch:- @pytest.mark.asyncio- async def test_fleetdm_backend_dispatches_correctly(self) -> None:- expected = {"results": {"h1": [{"user": "root"}]}, "partial": False}- lq = AsyncMock(return_value=expected)- _, fleet_instance, _ = _inject_stubs(fleetdm_live_query=lq)-- step = _step(- {- "backend": "fleetdm",- "template": "logged_in_users",- "target_hosts": ["h1"],- "base_url": "http://fleet",- "api_token": "fleet-tok",- }- )- result = await _handle_osquery_live_query(step, _ctx(), MagicMock())- assert result == expected- lq.assert_awaited_once_with(["h1"], "logged_in_users", {}, 60)---class TestAiSOCDirectStub:- @pytest.mark.asyncio- async def test_aisoc_direct_not_implemented_is_safe(self) -> None:- lq = AsyncMock(side_effect=NotImplementedError("PR4: not yet implemented"))- _inject_stubs(direct_live_query=lq)-- step = _step(- {- "backend": "aisoc_direct",- "template": "active_connections",- "target_hosts": ["h1"],- "base_url": "http://tls",- "api_token": "x",- }- )- result = await _handle_osquery_live_query(step, _ctx(), MagicMock())- assert result.get("stub") is True- assert result.get("partial") is True- assert "PR4" in result.get("error", "")---class TestTemplateParams:- @pytest.mark.asyncio- async def test_template_params_forwarded(self) -> None:- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "template_params": {"limit": 5},- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": 30,- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())- lq.assert_awaited_once_with(["h1"], "running_processes", {"limit": 5}, 30)---class TestHostFallback:- @pytest.mark.asyncio- async def test_host_from_context_when_no_target_hosts(self) -> None:- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "base_url": "http://osc",- "api_token": "tok",- # No target_hosts — should fall back to context["host"]- }- )- ctx = _ctx(host="context-host")- await _handle_osquery_live_query(step, ctx, MagicMock())-- call_args = lq.call_args- assert "context-host" in call_args[0][0]---# ----------------------------------------------------------------------------# H-7 / Batch 10 — runtime clamp tests for params.timeout_seconds.-#-# These exercise the *runtime* defence (engine.clamp_timeout) rather than the-# Pydantic field cap, because params is an untyped dict and a malicious or-# malformed playbook can bypass the Pydantic validator entirely. See-# ``test_playbook_models_bounds.py::TestParamsAreNotValidated`` for the-# matching failure case at the model layer.-# ---------------------------------------------------------------------------+ async def test_host_from_context_when_no_target_hosts(self, dispatched: list[dict[str, Any]]) -> None:+ await _run(_step({"template": "t"}), {"host": "context-host"})+ assert dispatched[0]["params"]["target_hosts"] == ["context-host"]+ assert dispatched[0]["target"] == "context-host"class TestRuntimeTimeoutClamp:- @pytest.mark.asyncio- async def test_pathological_timeout_is_clamped_to_default_max(self) -> None:- """An attacker passes ``timeout_seconds: 86400`` (1 day).+ """``params`` bypasses the Pydantic validator on ``PlaybookStep``.- Without the runtime clamp, the connector thread would pin for 24h.- With the clamp, the value collapses to DEFAULT_MAX_TIMEOUT_SECONDS.- """+ Kept from the previous version of this file, retargeted at the function+ that now owns the clamp. See ``test_playbook_models_bounds.py``'s+ ``TestParamsAreNotValidated`` for the matching failure at the model layer.+ """++ async def test_pathological_timeout_is_clamped(self, dispatched: list[dict[str, Any]]) -> None:from app.playbook.bounds import DEFAULT_MAX_TIMEOUT_SECONDS- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": 86_400, # pathological- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- # Backend client must be called with the clamped value, not 86400.- call_args = lq.call_args- forwarded_timeout = call_args[0][3] # 4th positional arg- assert forwarded_timeout == DEFAULT_MAX_TIMEOUT_SECONDS-- @pytest.mark.asyncio- async def test_negative_timeout_is_clamped_to_min(self) -> None:+ await _run(_step({"template": "t", "target_hosts": ["h1"], "timeout_seconds": 86_400}))+ assert dispatched[0]["params"]["timeout_seconds"] == DEFAULT_MAX_TIMEOUT_SECONDS++ async def test_negative_timeout_is_clamped_to_min(self, dispatched: list[dict[str, Any]]) -> None:from app.playbook.bounds import MIN_TIMEOUT_SECONDS- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": -5,- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- call_args = lq.call_args- forwarded_timeout = call_args[0][3]- assert forwarded_timeout == MIN_TIMEOUT_SECONDS-- @pytest.mark.asyncio- async def test_missing_timeout_uses_handler_default(self) -> None:- """When params omits timeout_seconds, the handler default (60) wins."""- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- # No timeout_seconds in params at all.- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- call_args = lq.call_args- forwarded_timeout = call_args[0][3]- assert forwarded_timeout == 60-- @pytest.mark.asyncio- async def test_in_range_timeout_passes_through(self) -> None:- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": 120,- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- call_args = lq.call_args- forwarded_timeout = call_args[0][3]- assert forwarded_timeout == 120-- @pytest.mark.asyncio- async def test_string_timeout_is_parsed_not_dropped(self) -> None:+ await _run(_step({"template": "t", "target_hosts": ["h1"], "timeout_seconds": -5}))+ assert dispatched[0]["params"]["timeout_seconds"] == MIN_TIMEOUT_SECONDS++ async def test_missing_timeout_uses_the_handler_default(self, dispatched: list[dict[str, Any]]) -> None:+ await _run(_step({"template": "t", "target_hosts": ["h1"]}))+ assert dispatched[0]["params"]["timeout_seconds"] == 60++ async def test_in_range_timeout_passes_through(self, dispatched: list[dict[str, Any]]) -> None:+ await _run(_step({"template": "t", "target_hosts": ["h1"], "timeout_seconds": 120}))+ assert dispatched[0]["params"]["timeout_seconds"] == 120++ async def test_string_timeout_is_parsed_not_dropped(self, dispatched: list[dict[str, Any]]) -> None:"""YAML may surface numeric strings; the clamp must parse them."""- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": "90", # string from YAML- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- call_args = lq.call_args- forwarded_timeout = call_args[0][3]- assert forwarded_timeout == 90-- @pytest.mark.asyncio- async def test_bool_timeout_does_not_become_one(self) -> None:- """``timeout_seconds: true`` MUST NOT coerce to 1 — that would silently- cause every osquery to time out immediately, which is a sneaky DoS.- """- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": True, # malformed- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- call_args = lq.call_args- forwarded_timeout = call_args[0][3]- # Falls back to the handler default, NOT to int(True) == 1.- assert forwarded_timeout == 60-- @pytest.mark.asyncio- async def test_param_cap_is_runtime_ceiling_not_field_cap(self, monkeypatch: pytest.MonkeyPatch) -> None:- """The runtime ceiling is the *param* cap (15 min), not the looser- Pydantic field cap (1h). This pins the layered defence: approval- steps may declare timeout=3600 on the typed field, but params-driven- values cannot exceed the runtime cap.+ await _run(_step({"template": "t", "target_hosts": ["h1"], "timeout_seconds": "90"}))+ assert dispatched[0]["params"]["timeout_seconds"] == 90++ async def test_bool_timeout_does_not_become_one(self, dispatched: list[dict[str, Any]]) -> None:+ """``timeout_seconds: true`` must not coerce to 1.++ Every query would time out immediately, which is a quiet denial of+ service wearing a configuration typo."""+ await _run(_step({"template": "t", "target_hosts": ["h1"], "timeout_seconds": True}))+ assert dispatched[0]["params"]["timeout_seconds"] == 60++ async def test_an_operator_cannot_uncap_the_runtime_ceiling(+ self, dispatched: list[dict[str, Any]], monkeypatch: pytest.MonkeyPatch+ ) -> None:from app.playbook.bounds import ABSOLUTE_MAX_PARAM_TIMEOUT_SECONDS- # Operator typo: setting AISOC_PLAYBOOK_MAX_TIMEOUT_SECONDS=100000 must- # NOT silently uncap the runtime guard.monkeypatch.setenv("AISOC_PLAYBOOK_MAX_TIMEOUT_SECONDS", "100000")+ await _run(_step({"template": "t", "target_hosts": ["h1"], "timeout_seconds": 50_000}))+ assert dispatched[0]["params"]["timeout_seconds"] == ABSOLUTE_MAX_PARAM_TIMEOUT_SECONDS+++async def test_the_agents_image_no_longer_imports_the_actions_clients() -> None:+ """A negative control for the defect this item removed.++ ``app.clients`` is the package the old handler imported, and it has never+ existed in this service. Asserting it is still absent is what makes the+ rest of this file a statement about production rather than about a+ ``sys.modules`` arrangement a test set up.+ """+ import importlib.util- lq = AsyncMock(return_value={"results": {}, "partial": False})- _inject_stubs(osctrl_live_query=lq)-- step = _step(- {- "backend": "osctrl",- "template": "running_processes",- "target_hosts": ["h1"],- "base_url": "http://osc",- "api_token": "tok",- "timeout_seconds": 50_000, # would exceed the param cap- }- )- await _handle_osquery_live_query(step, _ctx(), MagicMock())-- call_args = lq.call_args- forwarded_timeout = call_args[0][3]- assert forwarded_timeout == ABSOLUTE_MAX_PARAM_TIMEOUT_SECONDS+ assert importlib.util.find_spec("app.clients") is None+ assert "app.clients" not in engine_mod.__dict__diff --git a/services/agents/tests/test_playbook_engine_correctness.py b/services/agents/tests/test_playbook_engine_correctness.pyindex 7ff39581e..556166f7b 100644--- a/services/agents/tests/test_playbook_engine_correctness.py+++ b/services/agents/tests/test_playbook_engine_correctness.py@@ -365,7 +365,11 @@ class TestEngineConditionGate:async def handler(step: PlaybookStep, ctx: dict, http: Any) -> dict:called["hit"] = True- return {"ok": True}+ # `notify` is dispatched through the action registry since depth+ # 5.1, and the engine reads `executed` rather than "the handler+ # returned" — a double that answers `{"ok": True}` would be a+ # double more capable than the real report.+ return {"ok": True, "executed": True}patch_handlers({StepType.NOTIFY: handler})@@ -391,7 +395,11 @@ class TestEngineConditionGate:async def handler(step: PlaybookStep, ctx: dict, http: Any) -> dict:called["hit"] = True- return {"ok": True}+ # `notify` is dispatched through the action registry since depth+ # 5.1, and the engine reads `executed` rather than "the handler+ # returned" — a double that answers `{"ok": True}` would be a+ # double more capable than the real report.+ return {"ok": True, "executed": True}patch_handlers({StepType.NOTIFY: handler})diff --git a/services/agents/tests/test_playbook_ssrf_guard.py b/services/agents/tests/test_playbook_ssrf_guard.pyindex c020fef19..32133cf82 100644--- a/services/agents/tests/test_playbook_ssrf_guard.py+++ b/services/agents/tests/test_playbook_ssrf_guard.py@@ -8,7 +8,8 @@ from collections.abc import Iterablefrom unittest.mock import AsyncMock, MagicMockimport pytest-from app.playbook.engine import _handle_http, _handle_notify+from app.playbook import engine as engine_mod+from app.playbook.engine import _handle_httpfrom app.playbook.models import PlaybookStep, StepTypefrom app.playbook.ssrf_guard import SSRFError, validate_outbound_url@@ -286,7 +287,36 @@ class TestOperatorExtensions:@pytest.mark.asyncioclass TestHandlerIntegration:- async def test_handle_http_blocks_metadata(self) -> None:+ """The guard, exercised through the step handler that calls it.++ ``notify`` is no longer here. It used to have a sender of its own in the+ engine — one channel, ``webhook``, which none of the 63 shipped notify+ steps use — and it is now dispatched through the action registry, where+ the destination is a vault-held tenant reference rather than a URL in+ the playbook. There is no author-controlled URL left for this guard to+ check, so a test here would be asserting over a path that no longer+ exists. The arms' own outbound calls are covered in+ ``services/actions/tests/test_notify_and_osquery_arms.py``.+ """++ @staticmethod+ def _no_references(monkeypatch: pytest.MonkeyPatch) -> None:+ """These URLs carry no ``${NAME}``, so nothing should be looked up.++ Patched to raise rather than to return ``{}``: a handler that asked+ the API to resolve an empty list would be a network round trip per+ step, and the silent version of that is a performance bug nobody+ sees until a pack has sixty steps in it.+ """++ async def _refuse(*, tenant_id: str, names: list[str]):+ raise AssertionError(f"no reference lookup expected, got {names!r}")++ monkeypatch.setattr(engine_mod.references, "resolve", _refuse)++ async def test_handle_http_blocks_metadata(self, monkeypatch: pytest.MonkeyPatch) -> None:+ self._no_references(monkeypatch)+ monkeypatch.setenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "1")step = PlaybookStep(name="http-bad",type=StepType.HTTP,@@ -298,7 +328,9 @@ class TestHandlerIntegration:await _handle_http(step, {}, client)client.request.assert_not_awaited()- async def test_handle_http_blocks_empty_url(self) -> None:+ async def test_handle_http_blocks_empty_url(self, monkeypatch: pytest.MonkeyPatch) -> None:+ self._no_references(monkeypatch)+ monkeypatch.setenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "1")step = PlaybookStep(name="http-empty", type=StepType.HTTP, params={"url": ""})client = MagicMock()client.request = AsyncMock()@@ -306,7 +338,9 @@ class TestHandlerIntegration:await _handle_http(step, {}, client)client.request.assert_not_awaited()- async def test_handle_http_blocks_loopback(self) -> None:+ async def test_handle_http_blocks_loopback(self, monkeypatch: pytest.MonkeyPatch) -> None:+ self._no_references(monkeypatch)+ monkeypatch.setenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "1")step = PlaybookStep(name="http-loop",type=StepType.HTTP,@@ -318,7 +352,22 @@ class TestHandlerIntegration:await _handle_http(step, {}, client)client.request.assert_not_awaited()+ async def test_handle_http_is_guarded_before_the_execute_switch(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """A preview must refuse a blocked destination, not quietly report it.++ Running the guard only on the live branch would let a playbook that+ previews cleanly fail the moment somebody enables execution — the+ opposite of what a preview is for.+ """+ self._no_references(monkeypatch)+ monkeypatch.delenv("AISOC_PLAYBOOK_HTTP_EXECUTE", raising=False)+ step = PlaybookStep(name="http-bad", type=StepType.HTTP, params={"url": "http://169.254.169.254/"})+ with pytest.raises(SSRFError):+ await _handle_http(step, {}, MagicMock())+async def test_handle_http_passes_for_public(self, monkeypatch: pytest.MonkeyPatch) -> None:+ self._no_references(monkeypatch)+ monkeypatch.setenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "1")_patch_dns(monkeypatch, {"ok.example": ["8.8.8.8"]})step = PlaybookStep(name="http-good",@@ -332,48 +381,9 @@ class TestHandlerIntegration:client.request = AsyncMock(return_value=response)out = await _handle_http(step, {}, client)assert out["status"] == 202+ assert out["executed"] is Trueclient.request.assert_awaited_once()- async def test_handle_notify_no_url_passthrough(self) -> None:- step = PlaybookStep(- name="notify-empty",- type=StepType.NOTIFY,- params={"channel": "webhook", "url": "", "message": "hi"},- )- client = MagicMock()- client.post = AsyncMock()- out = await _handle_notify(step, {}, client)- # Empty URL → handler returns informational stub; never calls http.- assert out["delivered"] is False- client.post.assert_not_awaited()-- async def test_handle_notify_blocks_bad_webhook(self) -> None:- step = PlaybookStep(- name="notify-bad",- type=StepType.NOTIFY,- params={"channel": "webhook", "url": "http://10.0.0.1/hook", "message": "x"},- )- client = MagicMock()- client.post = AsyncMock()- with pytest.raises(SSRFError):- await _handle_notify(step, {}, client)- client.post.assert_not_awaited()-- async def test_handle_notify_passes_for_public(self, monkeypatch: pytest.MonkeyPatch) -> None:- _patch_dns(monkeypatch, {"hooks.example": ["1.1.1.1"]})- step = PlaybookStep(- name="notify-good",- type=StepType.NOTIFY,- params={"channel": "webhook", "url": "https://hooks.example/x", "message": "hi"},- )- response = MagicMock()- response.status_code = 200- client = MagicMock()- client.post = AsyncMock(return_value=response)- out = await _handle_notify(step, {}, client)- assert out["status"] == 200- client.post.assert_awaited_once()-# ---------------------------------------------------------------------------# Defence in depth: _is_disallowed_address direct testsdiff --git a/services/agents/tests/test_playbook_steps_act.py b/services/agents/tests/test_playbook_steps_act.pyindex 5aa9491cd..81d7f0d04 100644--- a/services/agents/tests/test_playbook_steps_act.py+++ b/services/agents/tests/test_playbook_steps_act.py@@ -125,9 +125,22 @@ def _step(step_type: str, **params: Any): # noqa: ANN202)+def http_execute(monkeypatch: pytest.MonkeyPatch): # noqa: ANN201+ """Turn the http step on.++ It previews by default since depth 5.1: an `http` step in the shipped+ packs deletes sessions and resets passwords in bulk, through a path the+ capability contract cannot see. A suite that asserts a request arrived+ has to opt in, which is the same shape as `allow_loopback` above.+ """+ monkeypatch.setenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "1")+ yield++@pytest.mark.asyncioclass TestTheHttpStepActs:- async def test_it_reaches_the_endpoint(self, endpoint, allow_loopback) -> None: # noqa: ANN001+ async def test_it_reaches_the_endpoint(self, endpoint, allow_loopback, http_execute) -> None: # noqa: ANN001"""The claim: an `http_request` step makes a request."""import httpxfrom app.playbook.engine import _handle_http@@ -143,7 +156,7 @@ class TestTheHttpStepActs:assert _Endpoint.received[0]["path"] == "/hook"assert result.get("status") == 200- async def test_the_body_arrives(self, endpoint, allow_loopback) -> None: # noqa: ANN001+ async def test_the_body_arrives(self, endpoint, allow_loopback, http_execute) -> None: # noqa: ANN001"""A request with an empty body would satisfy the test above whiledelivering nothing the recipient can act on."""import httpx@@ -160,62 +173,60 @@ class TestTheHttpStepActs:@pytest.mark.asyncio-class TestTheNotifyStepActs:- async def test_a_webhook_notify_reaches_the_endpoint(self, endpoint, allow_loopback) -> None: # noqa: ANN001- import httpx- from app.playbook.engine import _handle_notify+class TestTheNotifyStepDoesNotInventADelivery:+ """`notify` no longer sends from this process, and that is the fix.++ It had one sender here — `channel == "webhook"` — which none of the 63+ notify steps in the shipped packs use, so every one of them answered+ `{"delivered": false, "reason": "no url"}`. It is now dispatched to+ `services/actions`, where the destination is a vault-held tenant+ reference rather than a URL written into shared pack content, and where+ the capability contract and the tenant's autonomy policy apply.++ The "did a request arrive" question this file exists to ask is asked of+ the arms themselves, over a mock vendor server, in+ `services/actions/tests/test_notify_and_osquery_arms.py`. What belongs+ here is the negative: the engine must not answer for them.+ """- async with httpx.AsyncClient() as client:- result = await _handle_notify(- _step("notify", channel="webhook", url=f"{endpoint}/hook", message="contained"),- {},- client,- )+ async def test_the_engine_has_no_notify_sender_of_its_own(self) -> None:+ from app.playbook import engine as engine_mod- assert _Endpoint.received, "the notify step produced a result and sent no request"- assert result.get("status") == 200+ assert not hasattr(engine_mod, "_handle_notify")- async def test_a_notify_with_no_url_says_it_delivered_nothing(self, endpoint) -> None: # noqa: ANN001- """The honest branch.+ async def test_a_notify_step_is_dispatched_and_never_posted_from_here(self, endpoint, allow_loopback, monkeypatch) -> None: # noqa: ANN001+ """Even handed a reachable URL, the step must not post it.- A notify step with nowhere to send must not report success — an- analyst who believes a page went out and finds later that it did- not is worse off than one told immediately.+ The old handler would have: `channel: webhook` plus a `url` was its+ one delivering combination. A step that still sent from here would+ bypass the contract, the approval matrix and the audit record."""- import httpx- from app.playbook.engine import _handle_notify-- async with httpx.AsyncClient() as client:- result = await _handle_notify(_step("notify", channel="webhook", message="hi"), {}, client)+ from app.playbook import engine as engine_mod+ from app.playbook.models import StepType- assert result.get("delivered") is False- assert result.get("reason") == "no url", result- assert not _Endpoint.received+ seen: dict[str, Any] = {}- async def test_a_channel_with_no_sender_says_so_rather_than_no_url(self, endpoint) -> None: # noqa: ANN001- """The reason has to name the real cause.+ async def _fake_dispatch(**kwargs: Any) -> dict[str, Any]:+ seen.update(kwargs)+ return {"executed": True, "status": "succeeded"}- It said "no url" whatever happened, including when a url *was*- supplied and the channel simply had no sender — sending an- operator to look for a missing field that was right in front of- them.- """- import httpx- from app.playbook.engine import _handle_notify+ monkeypatch.setattr(engine_mod.action_bridge, "dispatch_step", _fake_dispatch)- async with httpx.AsyncClient() as client:- result = await _handle_notify(_step("notify", channel="slack", url=f"{endpoint}/slack", message="hi"), {}, client)+ await engine_mod._HANDLERS[StepType.NOTIFY](+ _step("notify", channel="webhook", url=f"{endpoint}/hook", message="contained"),+ {"tenant_id": "t"},+ None,+ )- assert result.get("delivered") is False- assert "no url" not in (result.get("reason") or ""), f"a url was supplied and the reason still blames a missing one: {result!r}"- assert "slack" in (result.get("reason") or "")+ assert seen["capability"] == "notify"+ assert not _Endpoint.received, "the notify step posted from the engine instead of dispatching"@pytest.mark.asyncioclass TestTheGuardRefusesAndNothingArrives:"""A step that always calls out is as wrong as one that never does."""- async def test_loopback_is_refused_by_default(self, endpoint) -> None: # noqa: ANN001+ async def test_loopback_is_refused_by_default(self, endpoint, http_execute) -> None: # noqa: ANN001"""No `allow_loopback` here: this is the shipped default.Playbook URLs are author-controlled, and a playbook that can@@ -234,7 +245,7 @@ class TestTheGuardRefusesAndNothingArrives:"the guard refused and the request still arrived — a refusal in name only, since the side effect has already happened")- async def test_cloud_metadata_is_refused(self) -> None:+ async def test_cloud_metadata_is_refused(self, http_execute) -> None: # noqa: ANN001"""169.254.169.254 is refused even when private IPs are allowed:it is the one destination whose whole purpose is handing outcredentials."""diff --git a/services/agents/tests/test_playbook_steps_that_act.py b/services/agents/tests/test_playbook_steps_that_act.pynew file mode 100644index 000000000..95afd578b--- /dev/null+++ b/services/agents/tests/test_playbook_steps_that_act.py@@ -0,0 +1,383 @@+"""Depth 5.1 — the three step types that name an outbound effect and had none.++Each test here is a *reproduce* first and a regression second: before the+change in this commit, the first three fail against the shipped packs with+the exact counts recorded in their assertions.++Measured on the tree at the start of this work, over the 62 playbooks under+``playbooks/``:++* ``http`` — 69 of 69 steps raised ``SSRFError: scheme '' is not allowed``.+ Every pack URL begins with a ``${NAME}`` placeholder naming an integration+ (``${IDP_BASE_URL}/users/{{alert.user}}/sessions``), nothing resolved it,+ and ``urlsplit`` reads a string starting ``${`` as having no scheme.+* ``notify`` — 63 of 63 steps answered ``{"delivered": false, "reason": "no+ url"}``. The handler had one sender, ``channel == "webhook"``, and the+ packs use ``slack`` (49), ``pagerduty`` (63 across both copies) and+ ``email``, addressed by ``webhook_env`` / ``service_key_env`` rather than+ a literal URL.+* ``osquery_live_query`` — raised ``PermanentStepFailure`` in this image,+ because its three clients live in ``services/actions`` and+ ``app.clients`` does not exist here.++The counts are asserted as "none remain", not as a number, so the test keeps+working when a pack is added. The pre-change numbers live in this docstring+because a test that asserts the broken count has to be deleted to fix the+defect, and then nothing records what was wrong.+"""++from __future__ import annotations++import json+import socket+from pathlib import Path+from typing import Any++import pytest+from app.playbook import engine as engine_mod+from app.playbook import ssrf_guard+from app.playbook.models import PlaybookStep, StepType++_PACKS = Path(__file__).resolve().parents[3] / "playbooks"++[email protected](autouse=True)+def _resolvable_test_hosts(monkeypatch: pytest.MonkeyPatch) -> None:+ """Answer DNS for the documentation hostnames these tests use.++ The guard is left entirely in the path — it still classifies whatever+ address comes back. Only the lookup is stubbed, because a unit test that+ depends on ``example.com`` resolving is a unit test that fails on a+ runner with no egress, and the thing under test is the classification.++ The address has to be one Python's ``ipaddress`` calls public, which+ rules out every documentation range: ``203.0.113.0/24``, ``192.0.2.0/24``+ and ``100.64.0.0/10`` all answer ``is_private`` True, and ``240.0.0.0/4``+ answers ``is_reserved``. Nothing is sent to it — every test here either+ previews or expects the guard to raise first.+ """+ real = socket.getaddrinfo++ def _fake(host: str, *args: Any, **kwargs: Any) -> Any:+ if isinstance(host, str) and host.endswith(".example.com"):+ return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 0))]+ return real(host, *args, **kwargs)++ monkeypatch.setattr(ssrf_guard.socket, "getaddrinfo", _fake)+++def _pack_steps(step_type: str) -> list[tuple[str, PlaybookStep]]:+ """Every step of one type across the shipped packs, with its file."""+ found: list[tuple[str, PlaybookStep]] = []+ for path in sorted(_PACKS.rglob("*.playbook.json")):+ for raw in json.loads(path.read_text()).get("steps", []):+ if raw.get("type") == step_type:+ found.append((path.name, PlaybookStep.model_validate(raw)))+ return found+++def test_the_packs_are_present() -> None:+ """A gate that scanned nothing would pass every assertion below."""+ assert len(list(_PACKS.rglob("*.playbook.json"))) >= 60+++# ---------------------------------------------------------------------------+# http+# ---------------------------------------------------------------------------+++def test_every_pack_http_url_names_an_integration_reference() -> None:+ """The shape the resolver has to handle, pinned so it cannot drift.++ Fails loudly if a pack ever hardcodes a vendor hostname, which is the+ thing ``${NAME}`` exists to stop: a playbook that ships with somebody+ else's Okta tenant in it.+ """+ steps = _pack_steps("http")+ assert steps, "no http steps in the packs; the rest of this file proves nothing"+ for name, step in steps:+ url = str(step.params.get("url", ""))+ assert url.startswith("${"), f"{name}: http url {url!r} does not start with an integration reference"+++async def test_pack_http_steps_resolve_and_are_guarded(monkeypatch: pytest.MonkeyPatch) -> None:+ """Reproduce: 69 of 69 were rejected before a reference could resolve."""+ references = {+ name: {"value": "https://vendor.example.com", "secret": False}+ for name in (+ "AWS_URL",+ "AZURE_URL",+ "BACKUP_URL",+ "CI_URL",+ "CLOUD_MGMT_URL",+ "CLOUD_URL",+ "DDOS_URL",+ "DLP_URL",+ "DNS_URL",+ "EDGE_URL",+ "EDR_URL",+ "EMAIL_GATEWAY_URL",+ "ERP_URL",+ "FW_URL",+ "GCP_URL",+ "IAC_URL",+ "IDP_BASE_URL",+ "K8S_API_URL",+ "MAIL_URL",+ "PLATFORM_URL",+ "PROXY_URL",+ "REGISTRY_URL",+ "SAAS_URL",+ "SCA_URL",+ "SIEM_URL",+ "WAF_URL",+ )+ }+ references["IDP_BEARER_HEADERS"] = {"headers": {"Authorization": "SSWS test"}, "secret": True}++ async def _fake_references(*, tenant_id: str, names: list[str]) -> dict[str, Any]: # noqa: ARG001+ return {name: references[name] for name in names if name in references}++ monkeypatch.setattr(engine_mod.references, "resolve", _fake_references)+ # Preview, so nothing leaves the process. The reference still has to+ # resolve and the URL still has to clear the guard — a preview that+ # skipped both would prove the opposite of what this test is for.+ monkeypatch.delenv("AISOC_PLAYBOOK_HTTP_EXECUTE", raising=False)++ context = {"tenant_id": "11111111-1111-1111-1111-111111111111", "alert": {"user": "[email protected]", "source_ip": "203.0.113.9"}}+ unresolved: list[str] = []+ for name, step in _pack_steps("http"):+ result = await engine_mod._handle_http(step, dict(context), None)+ if result.get("error"):+ unresolved.append(f"{name}/{step.id}: {result['error']}")+ assert not unresolved, "http steps still cannot resolve:\n" + "\n".join(unresolved)+++async def test_http_step_previews_by_default_and_names_the_switch(monkeypatch: pytest.MonkeyPatch) -> None:+ """Off by default: an http step reaches nothing until an operator says so."""++ async def _fake_references(*, tenant_id: str, names: list[str]) -> dict[str, Any]: # noqa: ARG001+ return {"IDP_BASE_URL": {"value": "https://idp.example.com", "secret": False}}++ monkeypatch.setattr(engine_mod.references, "resolve", _fake_references)+ monkeypatch.delenv("AISOC_PLAYBOOK_HTTP_EXECUTE", raising=False)++ step = PlaybookStep(name="revoke", type=StepType.HTTP, params={"url": "${IDP_BASE_URL}/sessions", "method": "DELETE"})+ result = await engine_mod._handle_http(step, {"tenant_id": "t"}, None)++ assert result["executed"] is False+ assert result["previewed"] is True+ assert "AISOC_PLAYBOOK_HTTP_EXECUTE" in result["reason"]+ assert result["url"] == "https://idp.example.com/sessions"+++async def test_http_step_refuses_an_unresolved_reference(monkeypatch: pytest.MonkeyPatch) -> None:+ """Negative control: an unknown reference must not fall through as a URL.++ Substituting the empty string would hand ``/sessions`` to httpx, which+ reads a scheme-relative path against whatever base it has. The step has+ to say which name it could not resolve.+ """++ async def _no_references(*, tenant_id: str, names: list[str]) -> dict[str, Any]: # noqa: ARG001+ return {}++ monkeypatch.setattr(engine_mod.references, "resolve", _no_references)++ step = PlaybookStep(name="revoke", type=StepType.HTTP, params={"url": "${NOT_CONFIGURED}/sessions"})+ result = await engine_mod._handle_http(step, {"tenant_id": "t"}, None)+ assert result["executed"] is False+ assert "NOT_CONFIGURED" in result["error"]+++async def test_http_step_still_refuses_a_metadata_endpoint(monkeypatch: pytest.MonkeyPatch) -> None:+ """Negative control: resolution must not become an SSRF bypass.++ A reference whose stored value points at the cloud metadata service is+ the attack this check exists for — the value comes from a tenant record,+ not from the playbook, so the guard has to run *after* substitution.+ """++ async def _metadata_reference(*, tenant_id: str, names: list[str]) -> dict[str, Any]: # noqa: ARG001+ return {"EVIL": {"value": "http://169.254.169.254", "secret": False}}++ monkeypatch.setattr(engine_mod.references, "resolve", _metadata_reference)+ monkeypatch.setenv("AISOC_PLAYBOOK_HTTP_EXECUTE", "1")++ step = PlaybookStep(name="steal", type=StepType.HTTP, params={"url": "${EVIL}/latest/meta-data/"})+ with pytest.raises(engine_mod.SSRFError):+ await engine_mod._handle_http(step, {"tenant_id": "t"}, None)+++async def test_http_step_never_records_a_secret_header_value(monkeypatch: pytest.MonkeyPatch) -> None:+ """The run record is read by anyone with case access, so it holds names."""++ async def _secret_reference(*, tenant_id: str, names: list[str]) -> dict[str, Any]: # noqa: ARG001+ return {+ "IDP_BASE_URL": {"value": "https://idp.example.com", "secret": False},+ "IDP_BEARER_HEADERS": {"headers": {"Authorization": "SSWS super-secret-token"}, "secret": True},+ }++ monkeypatch.setattr(engine_mod.references, "resolve", _secret_reference)+ monkeypatch.delenv("AISOC_PLAYBOOK_HTTP_EXECUTE", raising=False)++ step = PlaybookStep(+ name="revoke",+ type=StepType.HTTP,+ params={"url": "${IDP_BASE_URL}/sessions", "headers_env": "IDP_BEARER_HEADERS"},+ )+ result = await engine_mod._handle_http(step, {"tenant_id": "t"}, None)+ assert "super-secret-token" not in json.dumps(result)+ assert result["header_names"] == ["Authorization"]+++# ---------------------------------------------------------------------------+# notify+# ---------------------------------------------------------------------------+++async def test_pack_notify_steps_reach_governed_dispatch(monkeypatch: pytest.MonkeyPatch) -> None:+ """Reproduce: 63 of 63 answered ``delivered: false, reason: 'no url'``.++ ``notify`` is a contracted capability in ``services/actions`` with a+ Slack arm that predates this work, so the fix is to stop answering it+ inside the engine rather than to grow a second set of senders here.+ """+ dispatched: list[dict[str, Any]] = []++ async def _fake_dispatch(**kwargs: Any) -> dict[str, Any]:+ dispatched.append(kwargs)+ return {"executed": True, "status": "succeeded", "summary": "posted"}++ monkeypatch.setattr(engine_mod.action_bridge, "dispatch_step", _fake_dispatch)++ steps = _pack_steps("notify")+ assert steps+ for _name, step in steps:+ handler = engine_mod._HANDLERS[step.type]+ await handler(step, {"tenant_id": "t", "alert": {"source_ip": "203.0.113.9"}}, None)++ assert len(dispatched) == len(steps)+ assert {d["capability"] for d in dispatched} == {"notify"}+ # The channel decides the vendor arm. Guessing it downstream is the+ # credential-order roulette the SIEM arms had to pin away.+ assert {d["vendor_id"] for d in dispatched} <= {"slack", "teams", "email", "pagerduty"}+++async def test_notify_renders_the_pack_message_template(monkeypatch: pytest.MonkeyPatch) -> None:+ """``message_template`` is the key the packs use; ``message`` was the key+ the handler read, so every pack message was the default string."""+ seen: dict[str, Any] = {}++ async def _fake_dispatch(**kwargs: Any) -> dict[str, Any]:+ seen.update(kwargs)+ return {"executed": True, "status": "succeeded"}++ monkeypatch.setattr(engine_mod.action_bridge, "dispatch_step", _fake_dispatch)++ step = PlaybookStep(+ name="page",+ type=StepType.NOTIFY,+ params={"channel": "pagerduty", "message_template": "Stuffing from {{alert.source_ip}}"},+ )+ await engine_mod._HANDLERS[StepType.NOTIFY](step, {"tenant_id": "t", "alert": {"source_ip": "203.0.113.9"}}, None)+ assert seen["params"]["message"] == "Stuffing from 203.0.113.9"+++# ---------------------------------------------------------------------------+# osquery_live_query+# ---------------------------------------------------------------------------+++async def test_osquery_step_is_dispatched_rather_than_imported(monkeypatch: pytest.MonkeyPatch) -> None:+ """Reproduce: this raised ``PermanentStepFailure`` in the agents image.++ The handler imported ``app.clients.osctrl_client``, which exists only in+ ``services/actions``. It also read credentials from+ ``GET /connectors/instances/{id}``, whose response model documents that+ ``auth_config`` is deliberately omitted — so even in an image that had+ the clients, the call would have been made with no token.+ """+ seen: dict[str, Any] = {}++ async def _fake_dispatch(**kwargs: Any) -> dict[str, Any]:+ seen.update(kwargs)+ return {"executed": True, "status": "succeeded", "rows": []}++ monkeypatch.setattr(engine_mod.action_bridge, "dispatch_step", _fake_dispatch)++ step = PlaybookStep(+ name="hunt",+ type=StepType.OSQUERY_LIVE_QUERY,+ params={"backend": "fleetdm", "template": "processes_by_name", "template_params": {"name": "mimikatz.exe"}},+ )+ result = await engine_mod._HANDLERS[StepType.OSQUERY_LIVE_QUERY](step, {"tenant_id": "t", "host": "WS-1"}, None)+ assert result["executed"] is True+ assert seen["capability"] == "osquery_live_query"+ assert seen["vendor_id"] == "fleetdm"+ assert seen["target"] == "WS-1"+++def test_osquery_is_a_governed_verb_not_an_engine_handler() -> None:+ """The in-engine handler is gone, not renamed."""+ assert StepType.OSQUERY_LIVE_QUERY in engine_mod.RESPONSE_STEP_TYPES+ assert not hasattr(engine_mod, "_handle_osquery_live_query")+++# ---------------------------------------------------------------------------+# Preview — the mode an author checks a playbook in+# ---------------------------------------------------------------------------+++async def test_every_pack_playbook_completes_in_preview(monkeypatch: pytest.MonkeyPatch) -> None:+ """Phase 5's done-when, for the part this item owns.++ Reproduce, and the finding that made this test worth writing: a preview+ of *any* response step reported FAILED on the tree this started from.+ The engine chose not to call the handler, wrote ``executed: false``+ itself, and then read its own field back as "the verb did not run" — so+ a containment playbook previewed as broken whether or not it was, and+ the one mode an author uses to check a playbook before trusting it+ could not distinguish a sound one. Measured before the fix: every one+ of the 62 packs failed here.++ A preview still reaches no vendor. ``_handle_http`` is the only+ remaining outbound path in the engine and it is off by default, so+ nothing here opens a socket.+ """+ from app.playbook.engine import PlaybookEngine, RunStatus+ from app.playbook.models import Playbook++ async def _no_references(*, tenant_id: str, names: list[str]) -> dict[str, Any]: # noqa: ARG001+ return {}++ monkeypatch.setattr(engine_mod.references, "resolve", _no_references)+ monkeypatch.delenv("AISOC_PLAYBOOK_HTTP_EXECUTE", raising=False)++ context = {+ "tenant_id": "11111111-1111-1111-1111-111111111111",+ "alert": {"user": "[email protected]", "source_ip": "203.0.113.9", "host": "WS-1"},+ "case_id": "22222222-2222-2222-2222-222222222222",+ }++ incomplete: list[str] = []+ for path in sorted(_PACKS.rglob("*.playbook.json")):+ raw = json.loads(path.read_text())+ # Authored documentation the runtime model does not bind. The gate+ # records both in INERT_AUTHORED_KEYS for the same reason.+ raw.pop("inputs", None)+ raw.pop("dry_run_support", None)+ run = await PlaybookEngine().run(Playbook.model_validate(raw), dict(context), dry_run=True)+ if run.status is not RunStatus.COMPLETED:+ incomplete.append(f"{path.name}: {run.status.value} — {run.error}")++ assert not incomplete, "pack playbooks that do not complete in preview:\n" + "\n".join(incomplete[:20])diff --git a/services/api/app/api/v1/endpoints/playbook_steps.py b/services/api/app/api/v1/endpoints/playbook_steps.pyindex 5a05378ad..f864843b6 100644--- a/services/api/app/api/v1/endpoints/playbook_steps.py+++ b/services/api/app/api/v1/endpoints/playbook_steps.py@@ -29,6 +29,7 @@ from sqlalchemy.ext.asyncio import AsyncSessionfrom app.api.v1.deps import CurrentUserfrom app.api.v1.endpoints.alert_writeback import optional_user, service_token_validfrom app.db.database import get_db+from app.services import playbook_referencesfrom app.services.playbook_step_dispatch import dispatch_steplogger = structlog.get_logger(__name__)@@ -115,3 +116,42 @@ async def dispatch_playbook_step(playbook_step_id=body.playbook_step_id,)return report.as_dict()+++class ReferenceLookupRequest(BaseModel):+ """The ``${NAME}`` tokens one ``http`` step needs resolved."""++ names: list[str] = Field(default_factory=list, max_length=32)+ #: Required from a service caller, which has no session to read it from.+ tenant_id: uuid.UUID | None = None++[email protected]("/references", summary="Resolve the named integrations a playbook http step addresses")+async def resolve_playbook_references(+ body: ReferenceLookupRequest,+ user: Annotated[CurrentUser | None, Depends(optional_user)],+ db: Annotated[AsyncSession, Depends(get_db)],+ x_aisoc_service_token: Annotated[str | None, Header()] = None,+) -> dict[str, Any]:+ """Return the enabled references this tenant has for the names asked for.++ A name that is absent or disabled is simply not in the response. The+ engine reports which ones it needed and did not get; answering with an+ empty string instead would substitute nothing into+ ``${IDP_BASE_URL}/sessions`` and hand httpx a scheme-relative path.++ Secret halves (bearer headers, webhook URLs) are returned to the agents+ service, which is an authenticated internal peer holding the service+ token, and are used for exactly one request. The engine records header+ *names* in the run result, never values — the run record is readable by+ anyone with access to the case.+ """+ tenant_id, _requested_by = _resolve_caller(body.tenant_id, user, x_aisoc_service_token)+ try:+ references = await playbook_references.resolve(db, tenant_id=tenant_id, names=list(body.names))+ except playbook_references.ReferenceError as exc:+ # A reference that exists and will not decrypt is reported, not+ # treated as absent: "you have not configured this" would send an+ # operator to add a row that is already there.+ raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc+ return {"references": references}diff --git a/services/api/app/models/playbook_reference.py b/services/api/app/models/playbook_reference.pynew file mode 100644index 000000000..2133c0529--- /dev/null+++ b/services/api/app/models/playbook_reference.py@@ -0,0 +1,45 @@+"""ORM model for the named handles a playbook step addresses.++See ``migrations/095_playbook_references.sql`` for why names and not hosts.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime++from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text+from sqlalchemy.dialects.postgresql import UUID+from sqlalchemy.orm import Mapped, mapped_column++from app.db.database import Base++#: Kinds a reference can take. Mirrors the CHECK constraint in migration 095;+#: a value here that the constraint rejects is an insert that fails at the+#: database rather than at validation, which is a worse error for an operator.+REFERENCE_KINDS: frozenset[str] = frozenset({"url", "headers", "webhook", "routing_key", "smtp"})++#: Channels a `notify` reference can serve. Empty for `url` and `headers`.+REFERENCE_CHANNELS: frozenset[str] = frozenset({"", "slack", "teams", "email", "pagerduty"})+++class PlaybookReference(Base):+ __tablename__ = "aisoc_playbook_references"++ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)+ tenant_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("tenants.id"), nullable=False, index=True)+ name: Mapped[str] = mapped_column(String(128), nullable=False)+ kind: Mapped[str] = mapped_column(String(32), nullable=False)+ channel: Mapped[str] = mapped_column(String(32), nullable=False, default="")+ connector_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("connectors.id"), nullable=True)+ value: Mapped[str] = mapped_column(Text, nullable=False, default="")+ #: A ``vault:`` token, never plaintext. Decrypted only inside+ #: ``playbook_references.resolve`` on the way to one step.+ secret_value: Mapped[str] = mapped_column(Text, nullable=False, default="")+ #: FALSE on creation. Existing is not the same as usable — see the+ #: migration's "off by default" note.+ enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)+ description: Mapped[str] = mapped_column(Text, nullable=False, default="")+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))+ updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))+ created_by: Mapped[str] = mapped_column(Text, nullable=False, default="")diff --git a/services/api/app/services/playbook_references.py b/services/api/app/services/playbook_references.pynew file mode 100644index 000000000..82deb6c93--- /dev/null+++ b/services/api/app/services/playbook_references.py@@ -0,0 +1,191 @@+"""Resolve the names a playbook step addresses into something it can use.++Two callers, one table:++* ``POST /api/v1/playbook-steps/references`` — the agents engine asking what+ ``${IDP_BASE_URL}`` and ``IDP_BEARER_HEADERS`` are, so it can render an+ ``http`` step and put the result through its SSRF guard.+* ``playbook_step_dispatch`` — resolving the destination a ``notify`` step+ names into the executor params that channel's arm reads.++Three rules this module keeps, each of which has an opposite that shipped+somewhere in this repository before:++**A disabled or missing reference is absent, and says which.** Not an empty+string. Substituting empty into ``${IDP_BASE_URL}/sessions`` hands httpx a+scheme-relative path, which it resolves against whatever base it has — a+request to somewhere nobody chose.++**A secret is decrypted on the way to one step and never stored in a run+record.** The caller is told the header *names*; the values go to httpx and+nowhere else.++**A value that will not decrypt is reported, never downgraded.** A step that+quietly became a preview because a key would not decrypt is the failure the+whole governed-dispatch path exists to remove.+"""++from __future__ import annotations++import json+import uuid+from typing import Any++import structlog+from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++from app.models.connector import Connector+from app.models.playbook_reference import PlaybookReference+from app.security.credential_vault import CredentialVaultError, get_vault++logger = structlog.get_logger(__name__)++#: Executor parameter names each notify kind produces. Kept here rather than+#: in the dispatcher so the three notify arms and this resolver agree in one+#: place — a webhook reference that produced ``url`` instead of+#: ``webhook_url`` would make every arm report "no destination configured"+#: while a destination sat right there, configured.+_WEBHOOK_PARAM = "webhook_url"+_ROUTING_KEY_PARAM = "pd_routing_key"+++class ReferenceError(RuntimeError):+ """A reference exists and could not be read. Distinct from absent."""+++def _decrypt(reference: PlaybookReference) -> dict[str, Any]:+ """The secret half of a reference, as a dict.++ Stored as a vault-encrypted JSON object for every kind, so one code path+ covers a single webhook URL and a whole SMTP configuration. A blank+ secret is an empty dict, not an error: a ``url`` reference has no secret.+ """+ if not reference.secret_value:+ return {}+ try:+ decrypted = get_vault().decrypt_dict({"payload": reference.secret_value})+ except CredentialVaultError as exc:+ raise ReferenceError(f"the stored secret for {reference.name!r} could not be decrypted: {exc}") from exc+ raw = decrypted.get("payload")+ if isinstance(raw, dict):+ return raw+ try:+ parsed = json.loads(raw) if isinstance(raw, str) else {}+ except json.JSONDecodeError as exc:+ raise ReferenceError(f"the stored secret for {reference.name!r} is not a JSON object") from exc+ return parsed if isinstance(parsed, dict) else {}+++async def _rows(db: AsyncSession, *, tenant_id: uuid.UUID, names: list[str]) -> dict[str, PlaybookReference]:+ if not names:+ return {}+ result = await db.execute(+ select(PlaybookReference)+ .where(PlaybookReference.tenant_id == tenant_id)+ .where(PlaybookReference.name.in_(sorted(set(names))))+ .where(PlaybookReference.enabled.is_(True))+ )+ return {row.name: row for row in result.scalars().all()}+++async def _connector_base_url(db: AsyncSession, *, tenant_id: uuid.UUID, connector_id: uuid.UUID) -> str:+ """A bound connector's base URL, scoped to the tenant that asked.++ Tenant-scoped in the WHERE clause rather than trusting the foreign key:+ the reference row carries a caller-editable id, and a row that named+ another tenant's connector would otherwise read its hostname.+ """+ connector = (+ await db.execute(+ select(Connector)+ .where(Connector.id == connector_id)+ .where(Connector.tenant_id == tenant_id)+ .where(Connector.is_enabled.is_(True))+ )+ ).scalar_one_or_none()+ if connector is None:+ return ""+ config = connector.connector_config or {}+ return str(config.get("base_url") or config.get("instance_url") or "")+++async def resolve(db: AsyncSession, *, tenant_id: uuid.UUID, names: list[str]) -> dict[str, dict[str, Any]]:+ """``{name: {...}}`` for the references this tenant has enabled.++ A name that is absent, disabled, or bound to a connector that no longer+ has a base URL is simply not in the result. The caller reports which+ names it needed and did not get, because "you have not configured this"+ is a different sentence from "the lookup failed".+ """+ resolved: dict[str, dict[str, Any]] = {}+ for name, row in (await _rows(db, tenant_id=tenant_id, names=names)).items():+ secret = _decrypt(row)+ if row.kind == "url":+ value = row.value+ if row.connector_id is not None:+ value = await _connector_base_url(db, tenant_id=tenant_id, connector_id=row.connector_id) or value+ if not value:+ continue+ resolved[name] = {"kind": "url", "value": value.rstrip("/"), "secret": False}+ elif row.kind == "headers":+ headers = {str(k): str(v) for k, v in secret.items()}+ if not headers:+ continue+ resolved[name] = {"kind": "headers", "headers": headers, "secret": True}+ elif row.kind == "webhook":+ url = str(secret.get("webhook_url") or row.value or "")+ if not url:+ continue+ resolved[name] = {"kind": "webhook", "channel": row.channel, _WEBHOOK_PARAM: url, "secret": True}+ elif row.kind == "routing_key":+ key = str(secret.get("routing_key") or secret.get(_ROUTING_KEY_PARAM) or "")+ if not key:+ continue+ resolved[name] = {"kind": "routing_key", "channel": row.channel or "pagerduty", _ROUTING_KEY_PARAM: key, "secret": True}+ elif row.kind == "smtp":+ if not secret.get("smtp_host"):+ continue+ resolved[name] = {"kind": "smtp", "channel": row.channel or "email", "secret": True, **{str(k): v for k, v in secret.items()}}+ return resolved+++#: Where a `notify` step names its destination, in the order the packs use.+#: `destination` is the spelling the console writes; the two `_env` keys are+#: what the 62 shipped packs carry and are read verbatim rather than+#: rewritten, because rewriting content to match code is how a pack stops+#: matching the schema it validates against.+NOTIFY_DESTINATION_KEYS: tuple[str, ...] = ("destination", "webhook_env", "service_key_env")+++def destination_name(params: dict[str, Any]) -> str:+ for key in NOTIFY_DESTINATION_KEYS:+ value = params.get(key)+ if isinstance(value, str) and value.strip():+ return value.strip()+ return ""+++async def notify_destination(db: AsyncSession, *, tenant_id: uuid.UUID, params: dict[str, Any]) -> tuple[str, dict[str, Any], str]:+ """Resolve a ``notify`` step's destination into executor params.++ Returns ``(channel, executor_params, reason_it_did_not_resolve)``. The+ channel comes from the stored destination rather than from the step, so+ a reference configured as Teams cannot be paged as PagerDuty because a+ playbook said so — the credential and the transport have to agree or the+ message goes somewhere that cannot read it.+ """+ name = destination_name(params)+ if not name:+ return "", {}, "the step names no destination (set `destination`, `webhook_env` or `service_key_env`)"++ resolved = await resolve(db, tenant_id=tenant_id, names=[name])+ reference = resolved.get(name)+ if reference is None:+ return "", {}, f"this tenant has no enabled playbook reference named {name!r}"++ channel = str(reference.get("channel") or "")+ executor_params = {k: v for k, v in reference.items() if k not in {"kind", "channel", "secret"}}+ if not channel:+ return "", {}, f"the playbook reference {name!r} does not say which channel it serves"+ return channel, {**executor_params, "destination": name}, ""diff --git a/services/api/app/services/playbook_step_dispatch.py b/services/api/app/services/playbook_step_dispatch.pyindex b2f63c09e..d8f7d41d9 100644--- a/services/api/app/services/playbook_step_dispatch.py+++ b/services/api/app/services/playbook_step_dispatch.py@@ -47,7 +47,7 @@ from sqlalchemy.ext.asyncio import AsyncSessionfrom app.models.connector import Connectorfrom app.security.credential_vault import CredentialVaultError, get_vault-from app.services import actions_client+from app.services import actions_client, playbook_referencesfrom app.services.agent_tools import vendor_aliaseslogger = structlog.get_logger(__name__)@@ -148,6 +148,28 @@ async def dispatch_step(detail=exc.upstream_detail,)+ if capability == "notify":+ # `notify` is the one verb whose credentials are not a connector's.+ # A Slack incoming webhook, a PagerDuty Events routing key and an+ # SMTP relay are destinations a tenant configures per playbook+ # reference, which is how the shipped packs address them+ # (`webhook_env: "SLACK_SOC_WEBHOOK"`). Routing it through+ # `_pick_connector` would look for a connector type that does not+ # exist and report `no_integration` for a destination the tenant+ # had configured.+ return await _dispatch_notify(+ db,+ tenant_id=tenant_id,+ params=dict(params or {}),+ pinned_channel=vendor_id,+ confidence=confidence,+ dry_run=dry_run,+ requested_by=requested_by,+ playbook_run_id=playbook_run_id,+ playbook_step_id=playbook_step_id,+ log=log,+ )+if not implementers:# Distinct from "this tenant has no integration": nothing in the# product can perform this verb, so no amount of configuration helps.@@ -225,6 +247,88 @@ async def dispatch_step(return report+async def _dispatch_notify(+ db: AsyncSession,+ *,+ tenant_id: uuid.UUID,+ params: dict[str, Any],+ pinned_channel: str,+ confidence: float | None,+ dry_run: bool,+ requested_by: str,+ playbook_run_id: str,+ playbook_step_id: str,+ log: Any,+) -> StepDispatchReport:+ """Send one notification to a destination the tenant has configured.++ The destination decides the channel, not the step. A playbook that says+ ``channel: pagerduty`` against a reference holding a Slack webhook is a+ page delivered to something that cannot read it, so the two have to+ agree and the mismatch is reported rather than resolved in favour of+ either.+ """+ try:+ channel, destination_params, reason = await playbook_references.notify_destination(db, tenant_id=tenant_id, params=params)+ except playbook_references.ReferenceError as exc:+ return StepDispatchReport(+ capability="notify",+ status="failed",+ executed=False,+ summary="The notification destination could not be read.",+ detail=str(exc)[:500],+ )++ if reason:+ return StepDispatchReport(+ capability="notify",+ status="no_integration",+ executed=False,+ summary=f"Nothing was sent: {reason}.",+ detail="Configure the destination under Settings → Playbook references and enable it.",+ )++ if pinned_channel and pinned_channel != channel:+ return StepDispatchReport(+ capability="notify",+ status="failed",+ executed=False,+ vendor_id=channel,+ summary=f"The step asked for {pinned_channel!r} and its destination serves {channel!r}.",+ detail="A credential and a transport that disagree deliver nowhere; neither side is guessed at.",+ )++ send_params = {k: v for k, v in params.items() if k not in playbook_references.NOTIFY_DESTINATION_KEYS}+ send_params.update(destination_params)++ try:+ body = await actions_client.dispatch_live_action(+ capability="notify",+ vendor_id=channel,+ target=str(params.get("recipient") or ""),+ tenant_id=str(tenant_id),+ params=send_params,+ auth_config=None,+ dry_run=dry_run,+ requested_by=requested_by,+ confidence=confidence,+ playbook_run_id=playbook_run_id or None,+ playbook_step_id=playbook_step_id or None,+ )+ except actions_client.ActionsServiceError as exc:+ log.warning("playbook_step.notify_refused", status_code=exc.status_code)+ return StepDispatchReport(+ capability="notify",+ status="failed",+ executed=False,+ vendor_id=channel,+ summary="The action service refused the notification.",+ detail=exc.upstream_detail,+ )++ return _interpret("notify", channel, body, dry_run=dry_run)++async def _pick_connector(db: AsyncSession,*,diff --git a/services/api/migrations/095_playbook_references.sql b/services/api/migrations/095_playbook_references.sqlnew file mode 100644index 000000000..6adad0b59--- /dev/null+++ b/services/api/migrations/095_playbook_references.sql@@ -0,0 +1,120 @@+-- 095_playbook_references.sql — the named destinations and endpoints a+-- playbook's `http` and `notify` steps address.+--+-- Every shipped pack addresses the outside world by *name*, never by host:+--+-- "url": "${IDP_BASE_URL}/users/{{alert.user}}/sessions"+-- "headers_env": "IDP_BEARER_HEADERS"+-- "webhook_env": "SLACK_SOC_WEBHOOK"+-- "service_key_env": "PD_SOC_KEY"+--+-- Nothing resolved any of them, so all 69 `http` steps died at the SSRF+-- guard with `scheme '' is not allowed` (urlsplit reads a string starting+-- `${` as having no scheme) and all 63 `notify` steps answered+-- `{"delivered": false, "reason": "no url"}`.+--+-- Why a name and not a URL in the playbook+-- ----------------------------------------+-- This is the security property, not a formatting convention. A pack is+-- shared content: a literal host in one is either somebody else's tenant or+-- an invitation to point a playbook wherever its author likes. With a name,+-- an author chooses which of *this tenant's* integrations to call and which+-- path under it, and cannot choose the origin. The resolved URL still goes+-- through the SSRF guard afterwards, because the stored value is tenant+-- data and therefore as untrusted as the step that asked for it.+--+-- Why one table for both halves+-- -----------------------------+-- `${IDP_BASE_URL}` and `SLACK_SOC_WEBHOOK` are the same idea twice: a+-- tenant-scoped, secret-aware, named handle on somewhere outside. Two tables+-- would be two sets of RLS policies, two CRUD surfaces and two places for a+-- credential to be stored in clear.+--+-- Off by default+-- --------------+-- `enabled` defaults FALSE. A reference that exists is not a reference a+-- playbook may use: importing a pack must not start paging an on-call rota+-- the moment somebody pastes a webhook in. The resolver treats a disabled+-- row as absent and says so.+--+-- Reversible: DROP TABLE IF EXISTS.++CREATE TABLE IF NOT EXISTS aisoc_playbook_references (+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),++ tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,++ -- The token a playbook writes, without the `${}`. Upper snake case by+ -- convention and by the engine's own pattern, which is why the CHECK is+ -- here: a name the engine cannot parse is a row nobody will ever reach.+ name TEXT NOT NULL CHECK (name ~ '^[A-Za-z_][A-Za-z0-9_]*$'),++ -- What the resolved value *is*, which decides how it is handed to the+ -- step. A closed set so a new kind has to be added deliberately rather+ -- than arriving as free text that the resolver silently ignores.+ -- url -> substituted into an `http` step's url+ -- headers -> merged into an `http` step's request headers+ -- webhook -> an incoming-webhook URL for slack or teams notify+ -- routing_key -> a PagerDuty Events API v2 integration key+ -- smtp -> relay host, port, credentials and recipients+ kind TEXT NOT NULL+ CHECK (kind IN ('url', 'headers', 'webhook', 'routing_key', 'smtp')),++ -- Which notification channel a `notify` reference serves, so the+ -- dispatcher can pick the vendor arm without guessing from the name.+ -- Empty for `url` and `headers`.+ channel TEXT NOT NULL DEFAULT ''+ CHECK (channel IN ('', 'slack', 'teams', 'email', 'pagerduty')),++ -- Optional binding to a connector instance. When set, a `url` reference+ -- follows that connector's configured base URL instead of carrying its+ -- own copy, so rotating a vendor's hostname is one edit rather than one+ -- per playbook. Not a cascade delete: removing a connector must not+ -- silently delete the reference and leave every playbook using it+ -- failing with "not configured" and no record of what it was.+ connector_id UUID REFERENCES connectors(id) ON DELETE SET NULL,++ -- The non-secret half. A base URL is configuration, not a credential,+ -- and encrypting it at rest would mean an operator cannot see which host+ -- a playbook will call without decrypting something.+ value TEXT NOT NULL DEFAULT '',++ -- The secret half, a `vault:` token from CredentialVault. Headers,+ -- webhook URLs (which are bearer credentials for both Slack and Teams),+ -- routing keys and SMTP passwords all live here.+ secret_value TEXT NOT NULL DEFAULT '',++ enabled BOOLEAN NOT NULL DEFAULT FALSE,++ description TEXT NOT NULL DEFAULT '',++ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),+ created_by TEXT NOT NULL DEFAULT ''+);++CREATE UNIQUE INDEX IF NOT EXISTS aisoc_playbook_references_tenant_name+ ON aisoc_playbook_references (tenant_id, name);++CREATE INDEX IF NOT EXISTS aisoc_playbook_references_tenant+ ON aisoc_playbook_references (tenant_id);++COMMENT ON TABLE aisoc_playbook_references IS+ 'Named, tenant-scoped handles a playbook http/notify step addresses: ${IDP_BASE_URL}, '+ 'SLACK_SOC_WEBHOOK, PD_SOC_KEY. Secrets are vault tokens in secret_value; enabled '+ 'defaults FALSE so importing a pack cannot start paging anybody.';++DO $$+BEGIN+ EXECUTE 'ALTER TABLE aisoc_playbook_references ENABLE ROW LEVEL SECURITY';+ EXECUTE 'ALTER TABLE aisoc_playbook_references FORCE ROW LEVEL SECURITY';+ EXECUTE 'DROP POLICY IF EXISTS tenant_isolation ON aisoc_playbook_references';+ EXECUTE+ 'CREATE POLICY tenant_isolation ON aisoc_playbook_references '+ 'USING (tenant_id = current_tenant_id() OR current_tenant_id() IS NULL) '+ 'WITH CHECK (tenant_id = current_tenant_id())';+ IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'aisoc_app') THEN+ EXECUTE 'GRANT SELECT, INSERT, UPDATE, DELETE ON aisoc_playbook_references TO aisoc_app';+ END IF;+END+$$;diff --git a/services/api/tests/test_playbook_references.py b/services/api/tests/test_playbook_references.pynew file mode 100644index 000000000..719c8a146--- /dev/null+++ b/services/api/tests/test_playbook_references.py@@ -0,0 +1,189 @@+"""Depth 5.1 — resolving the names a playbook step addresses.++The behaviour worth pinning is mostly about what the resolver *refuses*:++* a disabled reference is absent, so importing a pack cannot start paging;+* a reference bound to another tenant's connector reads nothing;+* a notify destination whose channel disagrees with the step is reported,+ not resolved in favour of either side;+* a secret that will not decrypt is an error, never "not configured" — the+ two send an operator to opposite places.+"""++from __future__ import annotations++import json+import uuid+from typing import Any++import pytest+from app.services import playbook_references+++class _Row:+ """A reference row. Not the ORM class: these tests are about the+ resolution rules, and a real row needs a session, a tenant and a+ migration to exist at all."""++ def __init__(self, **kwargs: Any) -> None:+ self.id = uuid.uuid4()+ self.tenant_id = kwargs.pop("tenant_id", uuid.uuid4())+ self.name = kwargs.pop("name")+ self.kind = kwargs.pop("kind")+ self.channel = kwargs.pop("channel", "")+ self.connector_id = kwargs.pop("connector_id", None)+ self.value = kwargs.pop("value", "")+ self.secret_value = kwargs.pop("secret_value", "")+ self.enabled = kwargs.pop("enabled", True)+++def rows(monkeypatch: pytest.MonkeyPatch) -> list[_Row]:+ """Stand in for the SELECT, applying the same two filters it does."""+ store: list[_Row] = []++ async def _fake_rows(db: Any, *, tenant_id: uuid.UUID, names: list[str]) -> dict[str, _Row]: # noqa: ARG001+ return {r.name: r for r in store if r.name in set(names) and r.enabled}++ monkeypatch.setattr(playbook_references, "_rows", _fake_rows)+ return store+++def plaintext_vault(monkeypatch: pytest.MonkeyPatch) -> None:+ """A vault that round-trips JSON, so these tests exercise the shape+ handling rather than Fernet."""++ class _Vault:+ def decrypt_dict(self, payload: dict[str, Any]) -> dict[str, Any]:+ return {"payload": json.loads(payload["payload"])}++ monkeypatch.setattr(playbook_references, "get_vault", lambda: _Vault())+++pytestmark = pytest.mark.asyncio+++async def test_a_url_reference_resolves_and_loses_its_trailing_slash(rows: list[_Row], plaintext_vault: None) -> None:+ """``${IDP_BASE_URL}/sessions`` must not become ``…com//sessions``."""+ rows.append(_Row(name="IDP_BASE_URL", kind="url", value="https://acme.okta.com/"))+ resolved = await playbook_references.resolve(None, tenant_id=uuid.uuid4(), names=["IDP_BASE_URL"])+ assert resolved["IDP_BASE_URL"]["value"] == "https://acme.okta.com"+ assert resolved["IDP_BASE_URL"]["secret"] is False+++async def test_a_disabled_reference_is_absent(rows: list[_Row], plaintext_vault: None) -> None:+ """Existing is not usable. The caller reports the name it could not get."""+ rows.append(_Row(name="IDP_BASE_URL", kind="url", value="https://acme.okta.com", enabled=False))+ resolved = await playbook_references.resolve(None, tenant_id=uuid.uuid4(), names=["IDP_BASE_URL"])+ assert resolved == {}+++async def test_a_url_reference_with_no_value_is_absent_not_empty(rows: list[_Row], plaintext_vault: None) -> None:+ """Substituting '' would hand httpx a scheme-relative path.++ ``/sessions`` resolves against whatever base the client has, which is a+ request to somewhere nobody chose — strictly worse than refusing.+ """+ rows.append(_Row(name="IDP_BASE_URL", kind="url", value=""))+ assert await playbook_references.resolve(None, tenant_id=uuid.uuid4(), names=["IDP_BASE_URL"]) == {}+++async def test_a_headers_reference_carries_its_values(rows: list[_Row], plaintext_vault: None) -> None:+ rows.append(_Row(name="IDP_BEARER_HEADERS", kind="headers", secret_value=json.dumps({"Authorization": "SSWS tok"})))+ resolved = await playbook_references.resolve(None, tenant_id=uuid.uuid4(), names=["IDP_BEARER_HEADERS"])+ assert resolved["IDP_BEARER_HEADERS"]["headers"] == {"Authorization": "SSWS tok"}+ assert resolved["IDP_BEARER_HEADERS"]["secret"] is True+++async def test_a_secret_that_will_not_decrypt_is_an_error_not_an_absence(rows: list[_Row], monkeypatch: pytest.MonkeyPatch) -> None:+ from app.security.credential_vault import CredentialVaultError++ class _BrokenVault:+ def decrypt_dict(self, payload: dict[str, Any]) -> dict[str, Any]:+ raise CredentialVaultError("key rotated out")++ monkeypatch.setattr(playbook_references, "get_vault", lambda: _BrokenVault())+ rows.append(_Row(name="IDP_BEARER_HEADERS", kind="headers", secret_value="vault:v1:xxx"))++ with pytest.raises(playbook_references.ReferenceError, match="IDP_BEARER_HEADERS"):+ await playbook_references.resolve(None, tenant_id=uuid.uuid4(), names=["IDP_BEARER_HEADERS"])+++# ---------------------------------------------------------------------------+# notify destinations+# ---------------------------------------------------------------------------+++async def test_a_webhook_destination_becomes_the_arms_credential_key(rows: list[_Row], plaintext_vault: None) -> None:+ """``webhook_url`` and not ``url``.++ The arms read ``webhook_url``; a resolver producing anything else makes+ every arm answer "no destination configured" while one sits configured.+ """+ rows.append(+ _Row(+ name="SLACK_SOC_WEBHOOK", kind="webhook", channel="slack", secret_value=json.dumps({"webhook_url": "https://hooks.slack.com/x"})+ )+ )+ channel, params, reason = await playbook_references.notify_destination(+ None, tenant_id=uuid.uuid4(), params={"webhook_env": "SLACK_SOC_WEBHOOK"}+ )+ assert reason == ""+ assert channel == "slack"+ assert params["webhook_url"] == "https://hooks.slack.com/x"+ assert params["destination"] == "SLACK_SOC_WEBHOOK"+++async def test_a_pagerduty_destination_resolves_its_routing_key(rows: list[_Row], plaintext_vault: None) -> None:+ rows.append(_Row(name="PD_SOC_KEY", kind="routing_key", channel="pagerduty", secret_value=json.dumps({"routing_key": "R" * 32})))+ channel, params, reason = await playbook_references.notify_destination(+ None, tenant_id=uuid.uuid4(), params={"service_key_env": "PD_SOC_KEY"}+ )+ assert reason == ""+ assert channel == "pagerduty"+ assert params["pd_routing_key"] == "R" * 32+++async def test_an_unconfigured_destination_names_itself(rows: list[_Row], plaintext_vault: None) -> None:+ _channel, _params, reason = await playbook_references.notify_destination(+ None, tenant_id=uuid.uuid4(), params={"webhook_env": "SLACK_SOC_WEBHOOK"}+ )+ assert "SLACK_SOC_WEBHOOK" in reason+++async def test_a_step_that_names_no_destination_says_which_keys_it_could_have_used(rows: list[_Row], plaintext_vault: None) -> None:+ _channel, _params, reason = await playbook_references.notify_destination(None, tenant_id=uuid.uuid4(), params={"channel": "slack"})+ assert "webhook_env" in reason and "service_key_env" in reason+++async def test_the_destination_decides_the_channel_not_the_step(rows: list[_Row], plaintext_vault: None) -> None:+ """A Slack webhook cannot be paged as PagerDuty because a playbook said so.++ Resolving in favour of either side delivers a message to something that+ cannot read it, so the mismatch is reported.+ """+ rows.append(_Row(name="SOC_DEST", kind="webhook", channel="teams", secret_value=json.dumps({"webhook_url": "https://teams/x"})))+ channel, _params, reason = await playbook_references.notify_destination(+ None, tenant_id=uuid.uuid4(), params={"destination": "SOC_DEST"}+ )+ assert reason == ""+ assert channel == "teams"+++def test_the_destination_keys_are_the_ones_the_packs_write() -> None:+ """Read off the shipped packs rather than restated.++ The packs are content and the resolver is code; a list in the code that+ the content does not use is a resolver nothing reaches.+ """+ import pathlib++ packs = pathlib.Path(__file__).resolve().parents[3] / "playbooks"+ used: set[str] = set()+ for path in packs.rglob("*.playbook.json"):+ for step in json.loads(path.read_text()).get("steps", []):+ if step.get("type") == "notify":+ used |= {k for k in step.get("params", {}) if k.endswith("_env")}+ assert used, "no notify step in the packs names a destination; this test proves nothing"+ assert used <= set(playbook_references.NOTIFY_DESTINATION_KEYS)diff --git a/services/connectors/app/connectors/base.py b/services/connectors/app/connectors/base.pyindex 97a8670e7..5409a1c62 100644--- a/services/connectors/app/connectors/base.py+++ b/services/connectors/app/connectors/base.py@@ -133,6 +133,11 @@ class Capability(str, Enum):GET_HOST = "get_host"GET_DETECTIONS = "get_detections"GET_USER_ACTIVITY = "get_user_activity"+ # A distributed osquery query across a fleet, through osctrl, FleetDM or+ # AiSOC's own TLS endpoint. Narrower than it looks: the caller names one+ # of a closed set of allowlisted templates and never writes SQL, which is+ # the same boundary LOOKUP_ENDPOINT_TELEMETRY draws.+ OSQUERY_LIVE_QUERY = "osquery_live_query"# Gap-closure Phase 4.2. Two reads that do not fit the three above# because their subject is neither a host nor a principal: a cloud# control-plane audit trail, and endpoint telemetry searched by