Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(agents,web): verify_user across the engine, schema and console palette

Beenu Arora213bbf10839a
diff --git a/apps/web/src/components/playbooks/packHelpers.ts b/apps/web/src/components/playbooks/packHelpers.ts
index 92773f10e..ef6a1fef4 100644
--- a/apps/web/src/components/playbooks/packHelpers.ts
+++ b/apps/web/src/components/playbooks/packHelpers.ts
@@ -263,6 +263,9 @@ const STEP_TYPE_TO_INTEGRATION: Record<StepType, IntegrationType | null> = {
loop: null,
// Not runnable at all — see `STEP_SCHEMAS.approval`.
approval: null,
+ // Depth 5.4. The prompt goes out through the same governed `notify`
+ // arms, so the integration a verification needs is the destination.
+ verify_user: 'Notification',
};
/**
diff --git a/apps/web/src/components/playbooks/stepSchemas.ts b/apps/web/src/components/playbooks/stepSchemas.ts
index 360fe010c..3e659c1f6 100644
--- a/apps/web/src/components/playbooks/stepSchemas.ts
+++ b/apps/web/src/components/playbooks/stepSchemas.ts
@@ -663,6 +663,61 @@ export const STEP_SCHEMAS: Record<StepType, StepSchema> = {
},
],
},
+ verify_user: {
+ type: 'verify_user',
+ execution: 'executed',
+ label: 'Verify with the user',
+ description:
+ 'Asks the affected person whether they recognise the activity, then their manager if ' +
+ 'nobody answers, and resumes the run with the signed answer so a later condition can ' +
+ 'branch on it. Never sent on a confirmed true positive, and auto-sent only for alert ' +
+ 'classes this tenant opted into.',
+ accent: '#a78bfa',
+ bgColor: '#2a2440',
+ icon: '🙋',
+ shortCode: 'vfy',
+ fields: [
+ USER_TARGET,
+ {
+ key: 'channel',
+ label: 'Ask over',
+ kind: 'select',
+ required: false,
+ options: ['slack', 'teams', 'email'],
+ help: 'Which configured destination the question goes out on. Defaults to Slack.',
+ },
+ {
+ key: 'message_template',
+ label: 'Question',
+ kind: 'textarea',
+ required: false,
+ placeholder: 'We saw a sign-in to your account from a new country. Was this you?',
+ help:
+ 'What the person reads. The three answer links are appended automatically; do not ' +
+ 'write your own, because only a signed link can be accepted.',
+ },
+ {
+ key: 'manager',
+ label: 'Escalate to',
+ kind: 'text',
+ required: false,
+ placeholder: 'Leave blank to use the directory',
+ help:
+ 'Who is asked if the person does not answer. Blank resolves the manager from SCIM; ' +
+ 'a name here overrides the directory.',
+ },
+ {
+ key: 'expires_in_hours',
+ label: 'Expires after (hours)',
+ kind: 'number',
+ required: false,
+ placeholder: '24',
+ help:
+ 'Leave blank for the deployment default. An unanswered question resumes the run ' +
+ 'with a `timed_out` outcome rather than leaving it waiting forever.',
+ },
+ ],
+ },
disable_user: {
type: 'disable_user',
execution: 'governed',
diff --git a/apps/web/src/components/playbooks/stepVocabulary.test.ts b/apps/web/src/components/playbooks/stepVocabulary.test.ts
index 5783ce604..2bcf4cc8b 100644
--- a/apps/web/src/components/playbooks/stepVocabulary.test.ts
+++ b/apps/web/src/components/playbooks/stepVocabulary.test.ts
@@ -64,6 +64,7 @@ const VALID_PARAMS: Record<StepType, Record<string, unknown>> = {
wait: { until: 'timer', seconds: 300 },
parallel: { join: 'all' },
loop: { over: 'sessions' },
+ verify_user: { user: '[email protected]', channel: 'slack' },
};
/**
@@ -111,6 +112,11 @@ const TARGET_KEY: Record<StepType, string | null> = {
wait: null,
parallel: null,
loop: null,
+ // Depth 5.4. Resolved by `engine._first_present(_VERIFY_SUBJECT_KEYS, ...)`
+ // rather than by `_resolve_target`: a verification is a question, not an
+ // action on an estate, so it is deliberately absent from `_TARGET_KEYS`
+ // — being in that table would make the engine grade it on `executed`.
+ verify_user: 'user',
};
/**
diff --git a/packages/types/src/playbook.ts b/packages/types/src/playbook.ts
index 6f3c56c49..cc477113c 100644
--- a/packages/types/src/playbook.ts
+++ b/packages/types/src/playbook.ts
@@ -44,6 +44,7 @@ export type StepType =
| "loop"
| "osquery_live_query"
| "approval"
+ | "verify_user"
| "disable_user"
| "reset_password"
| "revoke_session"
diff --git a/schemas/playbook.schema.json b/schemas/playbook.schema.json
index 6cd0f0db3..fd47c04f9 100644
--- a/schemas/playbook.schema.json
+++ b/schemas/playbook.schema.json
@@ -33,7 +33,8 @@
"create_notable_event": "governed",
"wait": "executed",
"parallel": "executed",
- "loop": "executed"
+ "loop": "executed",
+ "verify_user": "executed"
},
"properties": {
@@ -186,6 +187,7 @@
"isolate_host",
"create_ticket",
"approval",
+ "verify_user",
"block_ioc",
"disable_user",
"reset_password",
diff --git a/services/agents/app/api/playbooks.py b/services/agents/app/api/playbooks.py
index 49fc6ae19..7e5aca624 100644
--- a/services/agents/app/api/playbooks.py
+++ b/services/agents/app/api/playbooks.py
@@ -27,10 +27,10 @@ from app.playbook import (
PlaybookRun,
PlaybookStore,
draft_from_nl,
+ verification,
)
from app.playbook import engine as engine_module
from app.playbook import pause as playbook_pause
-from app.playbook import verification
from app.security.tenant_scope import require_console_or_service_auth
logger = logging.getLogger("aisoc.api.playbooks")
diff --git a/services/agents/app/playbook/engine.py b/services/agents/app/playbook/engine.py
index ae1f3a3e0..be3401e27 100644
--- a/services/agents/app/playbook/engine.py
+++ b/services/agents/app/playbook/engine.py
@@ -1120,11 +1120,16 @@ async def _time_out_verification(pause: Any) -> PlaybookRun | None:
async def _escalate_verification(pause: Any) -> PlaybookRun | None:
"""Ask the manager. Returns a run only when there was nobody to ask."""
subject = pause.verification_subject or ""
+ context = pause.run_context or {}
+ # The step's own params travelled with the pause, so an author who
+ # named a manager is honoured on the sweeper too. Reading `{}` here was
+ # the first version and it silently ignored the author.
+ step_params = dict(context.get("_verification_step_params") or {})
lookup = await verification.resolve_manager(
tenant_id=pause.tenant_id,
subject=subject,
- step_params={},
- context=pause.run_context or {},
+ step_params=step_params,
+ context=context,
)
if lookup.manager is None:
if lookup.source == "error":
@@ -1169,11 +1174,11 @@ async def _escalate_verification(pause: Any) -> PlaybookRun | None:
id=pause.step_id,
name="verification escalation",
type=StepType.VERIFY_USER,
- params=dict((pause.run_context or {}).get("_verification_step_params") or {}),
+ params=step_params,
)
delivery = await _deliver_verification_prompt(
step=step,
- context=pause.run_context or {},
+ context=context,
tenant_id=pause.tenant_id,
recipient=lookup.manager,
stage=verification.STAGE_MANAGER,
@@ -1540,6 +1545,25 @@ async def _control_loop(
return StepStatus.SUCCESS, payload
+#: Where the person being asked is found, params first then the run
+#: context. Deliberately *not* an entry in ``_TARGET_KEYS``:
+#: ``RESPONSE_STEP_TYPES`` is derived from that table, and a verb listed
+#: there is dispatched through the action registry and graded on
+#: ``executed``. A verification is a question, not an action on an estate,
+#: and adding it to the table would make the engine fail every unanswered
+#: prompt as an action that did not run.
+_VERIFY_SUBJECT_KEYS: tuple[str, ...] = ("subject", "user", "username", "user_id", "upn", "email")
+
+
+def _first_present(keys: tuple[str, ...], *sources: dict[str, Any]) -> str:
+ for key in keys:
+ for source in sources:
+ value = source.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return ""
+
+
async def _control_verify_user(
step: PlaybookStep,
pr: PlaybookRun,
@@ -1572,7 +1596,7 @@ async def _control_verify_user(
question nobody can answer; a pause written with no prompt expires
with a recorded outcome. Only one of those two orders is recoverable.
"""
- subject = _resolve_target(step, pr.context)
+ subject = _first_present(_VERIFY_SUBJECT_KEYS, step.params, pr.context)
if not subject:
return StepStatus.FAILED, {
"executed": False,
@@ -1630,9 +1654,7 @@ async def _control_verify_user(
"subject": subject,
"answers": [link["answer"] for link in links],
"reason": (
- "verify_user previews unless AISOC_PLAYBOOK_VERIFY_EXECUTE is set; nobody was messaged"
- if not dry_run
- else "dry run"
+ "verify_user previews unless AISOC_PLAYBOOK_VERIFY_EXECUTE is set; nobody was messaged" if not dry_run else "dry run"
),
}
diff --git a/services/agents/app/playbook/verification.py b/services/agents/app/playbook/verification.py
index f2452d9da..7627aaca4 100644
--- a/services/agents/app/playbook/verification.py
+++ b/services/agents/app/playbook/verification.py
@@ -393,8 +393,7 @@ async def may_auto_send(*, tenant_id: str, step_params: dict[str, Any], context:
if pool is None:
return SendDecision(
False,
- "the verification policy could not be read, so the prompt was not sent. Unreadable permission is not "
- "permission.",
+ "the verification policy could not be read, so the prompt was not sent. Unreadable permission is not permission.",
)
try:
diff --git a/services/agents/tests/test_playbook_control_flow.py b/services/agents/tests/test_playbook_control_flow.py
index 8784bd624..dc84af465 100644
--- a/services/agents/tests/test_playbook_control_flow.py
+++ b/services/agents/tests/test_playbook_control_flow.py
@@ -68,7 +68,16 @@ def enrich(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Any]]:
def test_the_three_types_exist_and_are_runnable() -> None:
for name in ("wait", "parallel", "loop"):
assert name in {s.value for s in StepType}
- assert set(engine_mod._CONTROL_FLOW) == {StepType.WAIT, StepType.PARALLEL, StepType.LOOP}
+ # Equality rather than a subset, so a type added to the table without a
+ # test is a failing build. `verify_user` (depth 5.4) is the fourth: it
+ # suspends to the same pause table and so needs the run, which is the
+ # property that puts a step in this table rather than in `_HANDLERS`.
+ assert set(engine_mod._CONTROL_FLOW) == {
+ StepType.WAIT,
+ StepType.PARALLEL,
+ StepType.LOOP,
+ StepType.VERIFY_USER,
+ }
def test_a_control_flow_step_is_not_in_the_handler_table() -> None:
@@ -552,18 +561,26 @@ class TestWaitsAreActuallyResumed:
called.append("resume")
return ["run-1"]
+ async def _verifications(**kwargs: Any) -> list[str]:
+ called.append("verify")
+ return []
+
async def _expire(**kwargs: Any) -> list[str]:
called.append("expire")
return []
monkeypatch.setattr(engine_mod, "resume_due_waits", _resume)
+ monkeypatch.setattr(engine_mod, "resume_due_verifications", _verifications)
monkeypatch.setattr(engine_mod.playbook_pause, "expire_due", _expire)
counts = await sweeper.sweep_once()
# Resume before expire: a pause whose timer came due in the same
- # tick that its TTL lapsed should run, not be cancelled.
- assert called == ["resume", "expire"]
- assert counts == {"resumed": 1, "expired": 0}
+ # tick that its TTL lapsed should run, not be cancelled. The
+ # verification sweep sits in the same half for the same reason — a
+ # question whose stage came due should escalate rather than be
+ # cancelled with no outcome for the run to read.
+ assert called == ["resume", "verify", "expire"]
+ assert counts == {"resumed": 1, "verifications": 0, "expired": 0}
async def test_the_sweeper_survives_a_failing_pass(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""A sweeper that dies on one bad pass stops resuming everything."""
diff --git a/services/agents/tests/test_playbook_verification.py b/services/agents/tests/test_playbook_verification.py
new file mode 100644
index 000000000..1895e8904
--- /dev/null
+++ b/services/agents/tests/test_playbook_verification.py
@@ -0,0 +1,618 @@
+"""A verification asks a person, then their manager, and the run branches.
+
+Depth plan 5.4. The "Done when" is one sentence — *a verification playbook
+asks a user and then a manager, waits, branches on a signed answer, and
+contains on "no" after approval* — and it is five separate properties, each
+with a way of looking satisfied while being broken:
+
+**Asks.** A prompt that was composed and not delivered. ``_deliver`` here
+reports what the action bridge was actually asked to send, so a test cannot
+pass on a message nobody sent.
+
+**Then a manager.** An escalation that fires on a timer the sweeper never
+reads, or one that messages the subject again because the manager lookup
+quietly returned nothing. ``no_manager`` is a distinct recorded outcome for
+exactly that reason, and a *failed* lookup leaves the row waiting rather
+than declaring that somebody has no manager.
+
+**Waits.** The one this file found a real defect in. A durable pause has to
+stop the run, and until this work only the ``approval`` branch knew that —
+so a durable ``wait`` wrote its pause and carried straight on.
+``test_a_durable_pause_stops_the_run`` is the regression.
+
+**Branches on a signed answer.** Not on *an* answer: the signature binds the
+answer to the stage, so a link minted for the user cannot answer for the
+manager an hour later.
+
+**Contains on "no".** Through the ordinary ``condition`` step and the
+ordinary governed dispatch, not a special path only this verb understands.
+"""
+
+from __future__ import annotations
+
+import uuid
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import pytest
+from app.playbook import engine as engine_module
+from app.playbook import pause as playbook_pause
+from app.playbook import verification
+from app.playbook.engine import PlaybookEngine, RunStatus
+from app.playbook.models import Playbook, PlaybookStep, StepType
+
+_SECRET = "verification-test-secret"
+
+
+# ---------------------------------------------------------------------------
+# A pause store that honours the predicates the real SQL uses
+# ---------------------------------------------------------------------------
+
+
+class _PauseRows:
+ """Stands in for ``aisoc_playbook_pauses``.
+
+ Every conditional ``UPDATE`` in ``pause.py`` carries predicates that are
+ the whole of its concurrency safety — ``status = 'waiting'``,
+ ``verification_stage = 'user'``, ``verification_outcome IS NULL``. A
+ double that ignored them would pass against an implementation that
+ ignored them too, which is how a double-answered prompt ships. So each
+ is honoured here, and the live-Postgres pass in
+ ``tests/isolation/test_verification_pause_live.py`` runs the same calls
+ against the real schema so the SQL itself is graded somewhere.
+ """
+
+ def __init__(self) -> None:
+ self.rows: list[dict[str, Any]] = []
+
+ async def execute(self, sql: str, *args: Any) -> str:
+ if "INSERT INTO aisoc_playbook_pauses" in sql:
+ self.rows.append(
+ {
+ "id": args[0],
+ "tenant_id": args[1],
+ "run_id": args[2],
+ "playbook_id": args[3],
+ "playbook_name": args[4],
+ "step_index": args[5],
+ "step_id": args[6],
+ "run_context": args[7],
+ "step_results": args[8],
+ "approval_id": args[9],
+ "expires_at": args[10],
+ "kind": args[11],
+ "resume_at": args[12],
+ "resume_token": args[13],
+ "verification_stage": args[14],
+ "verification_subject": args[15],
+ "verification_manager": args[16],
+ "verification_outcome": None,
+ "status": "waiting",
+ }
+ )
+ return "INSERT 0 1"
+
+ if "SET verification_stage = 'manager'" in sql:
+ for row in self._waiting(args[0], args[1]):
+ if row["kind"] != "verification" or row["verification_stage"] != "user":
+ continue
+ row["verification_stage"] = "manager"
+ row["verification_manager"] = args[2]
+ row["resume_at"] = args[3]
+ return "UPDATE 1"
+ return "UPDATE 0"
+
+ if "SET verification_outcome = $3" in sql:
+ for row in self._waiting(args[0], args[1]):
+ if row["kind"] != "verification" or row["verification_outcome"] is not None:
+ continue
+ row["verification_outcome"] = args[2]
+ return "UPDATE 1"
+ return "UPDATE 0"
+
+ if "UPDATE aisoc_playbook_pauses" in sql and "WHERE id =" in sql:
+ for row in self._waiting(args[0], args[3]):
+ row["status"] = args[1]
+ row["resolution"] = args[2]
+ return "UPDATE 1"
+ return "UPDATE 0"
+ return "OK"
+
+ def _waiting(self, pause_id: Any, tenant_id: Any) -> list[dict[str, Any]]:
+ return [r for r in self.rows if r["id"] == pause_id and str(r["tenant_id"]) == str(tenant_id) and r["status"] == "waiting"]
+
+ async def fetchrow(self, sql: str, *args: Any) -> dict[str, Any] | None:
+ if "aisoc_verification_policies" in sql:
+ opted_in = {c.lower() for c in _POLICY_CLASSES}
+ for candidate in args[1]:
+ if candidate in opted_in:
+ return {"alert_class": candidate}
+ return None
+ if "aisoc_scim_users" in sql:
+ manager = _SCIM_MANAGERS.get(str(args[1]).lower())
+ return {"manager_ref": manager} if manager else None
+ if "kind = 'verification'" in sql:
+ for row in self.rows:
+ if row.get("resume_token") == args[0] and row["kind"] == "verification" and row["status"] == "waiting":
+ return row
+ return None
+ return None
+
+ async def fetch(self, sql: str, *args: Any) -> list[dict[str, Any]]:
+ if "kind = 'verification'" in sql:
+ due = args[0]
+ return [
+ r
+ for r in self.rows
+ if r["status"] == "waiting" and r["kind"] == "verification" and r["resume_at"] is not None and r["resume_at"] <= due
+ ]
+ return []
+
+
+#: Mutated per test rather than passed in, because the policy and SCIM reads
+#: happen three call frames below the code under test.
+_POLICY_CLASSES: set[str] = set()
+_SCIM_MANAGERS: dict[str, str] = {}
+
+
[email protected](autouse=True)
+def _wire(monkeypatch: pytest.MonkeyPatch) -> _PauseRows:
+ rows = _PauseRows()
+
+ @asynccontextmanager
+ async def _acquire():
+ yield rows
+
+ class _Pool:
+ def acquire(self): # noqa: ANN202
+ return _acquire()
+
+ async def _pool() -> Any:
+ return _Pool()
+
+ monkeypatch.setattr(playbook_pause, "_pool", _pool)
+ monkeypatch.setattr(verification, "_pool", _pool)
+ monkeypatch.setenv("AISOC_CHATOPS_RESPONSE_SECRET", _SECRET)
+ monkeypatch.setenv("AISOC_PLAYBOOK_VERIFY_EXECUTE", "1")
+ monkeypatch.setenv("AISOC_AGENTS_PUBLIC_URL", "https://agents.example.test")
+ _POLICY_CLASSES.clear()
+ _SCIM_MANAGERS.clear()
+ return rows
+
+
+def sent() -> list[dict[str, Any]]:
+ return []
+
+
[email protected](autouse=True)
+def _capture_dispatch(monkeypatch: pytest.MonkeyPatch, sent: list[dict[str, Any]]) -> None:
+ """Record what the action bridge was asked to send.
+
+ Returns ``executed: True`` because the question under test is the
+ workflow, not the Slack arm. The arm's own failure path is covered by
+ ``test_a_prompt_that_did_not_deliver_fails_the_step``, which flips this.
+ """
+
+ async def _dispatch(**kwargs: Any) -> dict[str, Any]:
+ sent.append(kwargs)
+ return {"executed": True, "status": "executed"}
+
+ monkeypatch.setattr(engine_module.action_bridge, "dispatch_step", _dispatch)
+
+
+# ---------------------------------------------------------------------------
+# The signature
+# ---------------------------------------------------------------------------
+
+
+def test_a_user_stage_link_does_not_answer_for_the_manager() -> None:
+ """The stale-link case the stage binding exists for.
+
+ Without the stage in the signature, the subject's own "yes, that was me"
+ link would still verify after the question escalated — so the subject
+ could answer on their manager's behalf, which is precisely the
+ separation the escalation exists to create.
+ """
+ token = verification.mint_resume_token()
+ user_sig = verification.sign_answer(resume_token=token, answer="acknowledged", stage="user", secret=_SECRET)
+
+ assert verification.signature_valid(resume_token=token, answer="acknowledged", stage="user", signature=user_sig, secret=_SECRET)
+ assert not verification.signature_valid(resume_token=token, answer="acknowledged", stage="manager", signature=user_sig, secret=_SECRET)
+
+
+def test_an_answer_cannot_be_swapped_for_another() -> None:
+ """A link for one answer must not verify as a different answer."""
+ token = verification.mint_resume_token()
+ yes = verification.sign_answer(resume_token=token, answer="acknowledged", stage="user", secret=_SECRET)
+ assert not verification.signature_valid(resume_token=token, answer="denied", stage="user", signature=yes, secret=_SECRET)
+
+
+def test_no_secret_refuses_to_mint_rather_than_minting_an_unsigned_link(monkeypatch: pytest.MonkeyPatch) -> None:
+ """An unsigned link would take an answer from anybody who reached it."""
+ monkeypatch.delenv("AISOC_CHATOPS_RESPONSE_SECRET", raising=False)
+ with pytest.raises(verification.VerificationConfigError):
+ verification.sign_answer(resume_token="t", answer="denied", stage="user")
+
+
+# ---------------------------------------------------------------------------
+# The two refusals
+# ---------------------------------------------------------------------------
+
+
+def _verify_step(**params: Any) -> PlaybookStep:
+ return PlaybookStep(id="verify", name="Ask the user", type=StepType.VERIFY_USER, params={"user": "[email protected]", **params})
+
+
+def _playbook(*steps: PlaybookStep) -> Playbook:
+ return Playbook(id="pb-verify", name="verification", steps=list(steps))
+
+
+def _context(**extra: Any) -> dict[str, Any]:
+ return {"tenant_id": str(uuid.uuid4()), "alert_class": "impossible_travel", **extra}
+
+
+async def test_a_confirmed_true_positive_is_never_asked(sent: list[dict[str, Any]]) -> None:
+ """No opt-out, and not even for a class the tenant opted into.
+
+ Messaging the account an attacker holds tells them they are seen.
+ """
+ _POLICY_CLASSES.add("impossible_travel")
+ run = await PlaybookEngine().run(_playbook(_verify_step()), _context(disposition="true_positive"))
+
+ assert sent == []
+ result = run.step_results[0]["result"]
+ assert result["sent"] is False
+ assert result["verification"]["outcome"] == "refused"
+ assert "confirmed true positive" in result["reason"]
+
+
+async def test_a_class_the_tenant_did_not_opt_into_is_not_asked(sent: list[dict[str, Any]]) -> None:
+ """Default-deny. An empty policy table asks nobody."""
+ run = await PlaybookEngine().run(_playbook(_verify_step()), _context())
+
+ assert sent == []
+ assert run.step_results[0]["result"]["verification"]["outcome"] == "refused"
+ assert "has not opted into" in run.step_results[0]["result"]["reason"]
+
+
+async def test_an_unreadable_policy_refuses_rather_than_proceeding(monkeypatch: pytest.MonkeyPatch, sent: list[dict[str, Any]]) -> None:
+ """Unreadable permission is not permission."""
+
+ async def _no_pool() -> Any:
+ return None
+
+ monkeypatch.setattr(verification, "_pool", _no_pool)
+ run = await PlaybookEngine().run(_playbook(_verify_step()), _context())
+
+ assert sent == []
+ assert "could not be read" in run.step_results[0]["result"]["reason"]
+
+
+async def test_an_analyst_initiated_run_does_not_need_the_opt_in(sent: list[dict[str, Any]]) -> None:
+ """The opt-in governs the *automatic* path.
+
+ A playbook a human started is a human decision; requiring a policy row
+ for it would make the control a blocker rather than a default.
+ """
+ run = await PlaybookEngine().run(_playbook(_verify_step()), _context(initiated_by_human=True))
+
+ assert len(sent) == 1
+ assert run.status is RunStatus.PAUSED
+
+
+# ---------------------------------------------------------------------------
+# The wait, and the defect it uncovered
+# ---------------------------------------------------------------------------
+
+
+async def test_a_durable_pause_stops_the_run(sent: list[dict[str, Any]]) -> None:
+ """The regression for the defect this item found in 5.3's `wait`.
+
+ Only the ``approval`` branch broke out of the run loop, so a step that
+ suspended to Postgres and returned PENDING had its pause written and
+ then ran everything after it — and ran it again when the callback
+ resumed from ``step_index + 1``. Reverting the ``paused``/``pause_id``
+ break in ``PlaybookEngine.run`` makes this fail with the second step
+ recorded.
+ """
+ _POLICY_CLASSES.add("impossible_travel")
+ after = PlaybookStep(id="after", name="should not run yet", type=StepType.CLOSE_CASE, params={})
+ run = await PlaybookEngine().run(_playbook(_verify_step(), after), _context())
+
+ assert run.status is RunStatus.PAUSED
+ assert [r["step_id"] for r in run.step_results] == ["verify"]
+
+
+async def test_a_prompt_that_did_not_deliver_fails_the_step(monkeypatch: pytest.MonkeyPatch) -> None:
+ """A question nobody received is not a question that was asked."""
+ _POLICY_CLASSES.add("impossible_travel")
+
+ async def _refuse(**_kwargs: Any) -> dict[str, Any]:
+ return {"executed": False, "error": "no Slack destination configured"}
+
+ monkeypatch.setattr(engine_module.action_bridge, "dispatch_step", _refuse)
+ run = await PlaybookEngine().run(_playbook(_verify_step()), _context())
+
+ assert run.status is RunStatus.FAILED
+ assert run.step_results[0]["result"]["sent"] is False
+
+
+async def test_a_preview_names_who_would_be_asked(monkeypatch: pytest.MonkeyPatch, sent: list[dict[str, Any]]) -> None:
+ """Off by default, and the preview is useful rather than reassuring."""
+ monkeypatch.setenv("AISOC_PLAYBOOK_VERIFY_EXECUTE", "0")
+ _POLICY_CLASSES.add("impossible_travel")
+ run = await PlaybookEngine().run(_playbook(_verify_step()), _context())
+
+ assert sent == []
+ result = run.step_results[0]["result"]
+ assert result["previewed"] is True
+ assert result["subject"] == "[email protected]"
+ assert result["answers"] == ["acknowledged", "denied", "unsure"]
+
+
+# ---------------------------------------------------------------------------
+# The whole workflow
+# ---------------------------------------------------------------------------
+
+
+def _containment_playbook() -> Playbook:
+ """Ask, branch on the answer, and contain on "no" behind an approval."""
+ return Playbook(
+ id="pb-verify",
+ name="verify then contain",
+ steps=[
+ _verify_step(),
+ PlaybookStep(
+ id="branch",
+ name="Was it them?",
+ type=StepType.CONDITION,
+ condition={"expression": "verification_outcome == 'denied'"},
+ next_true="approve",
+ next_false="done",
+ ),
+ PlaybookStep(id="approve", name="Approve containment", type=StepType.APPROVAL, params={"prompt": "Disable the account?"}),
+ PlaybookStep(id="disable", name="Disable the account", type=StepType.DISABLE_USER, params={"user": "[email protected]"}),
+ PlaybookStep(id="done", name="Close", type=StepType.CLOSE_CASE, params={}),
+ ],
+ )
+
+
+async def _store_returns(monkeypatch: pytest.MonkeyPatch, playbook: Playbook) -> None:
+ from app.playbook import store as store_module
+
+ class _Store:
+ def get(self, _id: str) -> Playbook:
+ return playbook
+
+ monkeypatch.setattr(store_module.PlaybookStore, "default", classmethod(lambda _cls: _Store()))
+
+
+async def test_denied_resumes_into_the_approval_that_gates_containment(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+ sent: list[dict[str, Any]],
+) -> None:
+ """The plan's sentence, end to end.
+
+ Asks, pauses, takes a signed "no", resumes, branches to the approval
+ step and stops there — because containment is gated on a human and this
+ test must not be able to pass by containing without one.
+ """
+ _POLICY_CLASSES.add("impossible_travel")
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ first = await PlaybookEngine().run(playbook, _context())
+ assert first.status is RunStatus.PAUSED
+ token = _wire.rows[0]["resume_token"]
+
+ signature = verification.sign_answer(resume_token=token, answer="denied", stage="user", secret=_SECRET)
+ resumed = await engine_module.resume_verification(resume_token=token, answer="denied", signature=signature)
+
+ assert resumed is not None
+ assert resumed.run_id == first.run_id
+ assert resumed.context["verification"]["outcome"] == "denied"
+ # Branched to the approval, and stopped there: `disable` never ran.
+ #
+ # The resumed record starts at `branch` rather than at `verify`, which
+ # is the engine's existing resume shape and not a quirk of this verb: a
+ # pause stores the results captured *before* the suspending step, so
+ # `approval` and `wait` lose their own record the same way. What the
+ # verification contributes to the resumed run is the context the branch
+ # reads, asserted above.
+ assert [r["step_id"] for r in resumed.step_results] == ["branch", "approve"]
+ assert resumed.status is RunStatus.PAUSED
+
+
+async def test_acknowledged_takes_the_other_branch(monkeypatch: pytest.MonkeyPatch, _wire: _PauseRows) -> None:
+ """ "Yes, that was me" must not reach the containment branch."""
+ _POLICY_CLASSES.add("impossible_travel")
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ token = _wire.rows[0]["resume_token"]
+ signature = verification.sign_answer(resume_token=token, answer="acknowledged", stage="user", secret=_SECRET)
+ resumed = await engine_module.resume_verification(resume_token=token, answer="acknowledged", signature=signature)
+
+ assert resumed is not None
+ assert "approve" not in [r["step_id"] for r in resumed.step_results]
+
+
+async def test_a_second_click_resumes_once(monkeypatch: pytest.MonkeyPatch, _wire: _PauseRows) -> None:
+ """A double-tap, or a chat client prefetching the link."""
+ _POLICY_CLASSES.add("impossible_travel")
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ token = _wire.rows[0]["resume_token"]
+ signature = verification.sign_answer(resume_token=token, answer="denied", stage="user", secret=_SECRET)
+
+ assert await engine_module.resume_verification(resume_token=token, answer="denied", signature=signature) is not None
+ assert await engine_module.resume_verification(resume_token=token, answer="denied", signature=signature) is None
+
+
+async def test_an_unsigned_answer_is_refused(monkeypatch: pytest.MonkeyPatch, _wire: _PauseRows) -> None:
+ """The token alone is not the credential."""
+ _POLICY_CLASSES.add("impossible_travel")
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ token = _wire.rows[0]["resume_token"]
+
+ assert await engine_module.resume_verification(resume_token=token, answer="denied", signature="") is None
+ assert _wire.rows[0]["status"] == "waiting"
+
+
+# ---------------------------------------------------------------------------
+# The escalation
+# ---------------------------------------------------------------------------
+
+
+async def test_an_unanswered_prompt_escalates_to_the_manager_from_scim(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+ sent: list[dict[str, Any]],
+) -> None:
+ """The second question, to a different person, on the same pause."""
+ _POLICY_CLASSES.add("impossible_travel")
+ _SCIM_MANAGERS["[email protected]"] = "[email protected]"
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ assert sent[-1]["target"] == "[email protected]"
+
+ later = datetime.now(UTC) + timedelta(hours=1)
+ resumed = await engine_module.resume_due_verifications(now=later)
+
+ # Nothing resumed — a second question was asked.
+ assert resumed == []
+ assert _wire.rows[0]["verification_stage"] == "manager"
+ assert _wire.rows[0]["verification_manager"] == "[email protected]"
+ assert sent[-1]["target"] == "[email protected]"
+
+
+async def test_the_manager_answers_and_the_run_branches(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+ sent: list[dict[str, Any]],
+) -> None:
+ """A manager-stage link verifies where the user-stage one no longer does."""
+ _POLICY_CLASSES.add("impossible_travel")
+ _SCIM_MANAGERS["[email protected]"] = "[email protected]"
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ token = _wire.rows[0]["resume_token"]
+ await engine_module.resume_due_verifications(now=datetime.now(UTC) + timedelta(hours=1))
+
+ stale = verification.sign_answer(resume_token=token, answer="denied", stage="user", secret=_SECRET)
+ assert await engine_module.resume_verification(resume_token=token, answer="denied", signature=stale) is None
+
+ fresh = verification.sign_answer(resume_token=token, answer="denied", stage="manager", secret=_SECRET)
+ resumed = await engine_module.resume_verification(resume_token=token, answer="denied", signature=fresh)
+
+ assert resumed is not None
+ assert resumed.context["verification"]["stage"] == "manager"
+ assert resumed.context["verification"]["manager"] == "[email protected]"
+ assert "approve" in [r["step_id"] for r in resumed.step_results]
+
+
+async def test_nobody_answers_and_the_run_resumes_with_timed_out(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+) -> None:
+ """A timeout is an outcome, not an absence of one."""
+ _POLICY_CLASSES.add("impossible_travel")
+ _SCIM_MANAGERS["[email protected]"] = "[email protected]"
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ await engine_module.resume_due_verifications(now=datetime.now(UTC) + timedelta(hours=1))
+ resumed_ids = await engine_module.resume_due_verifications(now=datetime.now(UTC) + timedelta(hours=10))
+
+ assert len(resumed_ids) == 1
+ assert _wire.rows[0]["verification_outcome"] == "timed_out"
+ assert _wire.rows[0]["status"] == "resumed"
+
+
+async def test_a_subject_with_no_manager_resumes_with_no_manager(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+) -> None:
+ """There is nobody to escalate to, and the run is told so.
+
+ Distinct from ``timed_out``: a playbook may reasonably contain on "the
+ person did not answer and there is nobody above them" while waiting out
+ a second deadline for a manager who exists.
+ """
+ _POLICY_CLASSES.add("impossible_travel")
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ resumed_ids = await engine_module.resume_due_verifications(now=datetime.now(UTC) + timedelta(hours=1))
+
+ assert len(resumed_ids) == 1
+ assert _wire.rows[0]["verification_outcome"] == "no_manager"
+
+
+async def test_a_failed_manager_lookup_leaves_the_pause_waiting(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+) -> None:
+ """A database blip must not become a statement about a reporting line."""
+ _POLICY_CLASSES.add("impossible_travel")
+ playbook = _containment_playbook()
+ await _store_returns(monkeypatch, playbook)
+ await PlaybookEngine().run(playbook, _context())
+
+ async def _error(**_kwargs: Any) -> verification.ManagerLookup:
+ return verification.ManagerLookup(None, "error")
+
+ monkeypatch.setattr(verification, "resolve_manager", _error)
+ assert await engine_module.resume_due_verifications(now=datetime.now(UTC) + timedelta(hours=1)) == []
+ assert _wire.rows[0]["status"] == "waiting"
+ assert _wire.rows[0]["verification_outcome"] is None
+
+
+async def test_a_manager_named_on_the_step_beats_the_directory(
+ monkeypatch: pytest.MonkeyPatch,
+ _wire: _PauseRows,
+ sent: list[dict[str, Any]],
+) -> None:
+ """An author who named one has made a decision."""
+ _POLICY_CLASSES.add("impossible_travel")
+ _SCIM_MANAGERS["[email protected]"] = "[email protected]"
+ playbook = _playbook(_verify_step(manager="[email protected]"))
+ await _store_returns(monkeypatch, playbook)
+
+ await PlaybookEngine().run(playbook, _context())
+ await engine_module.resume_due_verifications(now=datetime.now(UTC) + timedelta(hours=1))
+
+ assert _wire.rows[0]["verification_manager"] == "[email protected]"
+ assert sent[-1]["target"] == "[email protected]"