Auto-response playbooks

A playbook is a stored rule that says “when this alert fires, run these actions”. Playbooks turn Manage365 from a monitoring tool into a response tool — a risky sign-in raises an alert, the matching playbook disables the account, kills the sessions, and opens a PSA ticket, all before a technician reads the alert.

They compose the same primitives the Compromise remediation modal runs interactively, plus a handful of extras.

Anatomy of a playbook

A playbook has two halves:

1. Trigger conditions — which alerts this playbook should match
2. Actions — an ordered list of primitives to execute when the trigger matches

Trigger conditions

Four matchers, all optional, AND-combined:

• Alert category — e.g. security, compliance, identity, email, device
• Minimum severity — match alerts at or above the chosen level (low / medium / high / critical)
• Title regex — an optional regex tested against the alert title for fine-grained matching (e.g. ^Impossible travel)
• Tenant scope — run everywhere, for one tenant, or for a tenant group

If multiple playbooks match the same alert, they all run in parallel. Order within a playbook is sequential.

Action primitives

Ten primitives are available today:

User-scoped primitives

• disable_user — sets accountEnabled = false on the Entra user
• revoke_user_sessions — calls GraphrevokeSignInSessions — kills Outlook, Teams, OWA, mobile sessions within ~5–10 minutes
• force_password_reset — generates a random strong password, sets forceChangePasswordNextSignIn = true, returns the plaintext in the execution result
• reset_mfa_registration — clears all MFA methods for the user (they re-enrol on next sign-in)
• disable_user_and_revoke — the compromise-remediation preset: revoke + disable + reset password + remove forwarding rules in one call

Notification & ticketing primitives

• notify_email — send an email via your configured notifications channel (alert context injected)
• create_psa_ticket — open a ticket in your PSA (HaloPSA / ConnectWise / Autotask) with the alert payload

Mailbox primitives

• convert_to_shared_mailbox — useful for leaver workflows: turns the user's mailbox into a shared mailbox so delegates keep access without a licence being held

Network & device primitives

• block_sign_in_country — adds the country (or countries) named in the alert to a named location referenced by the tenant's block-countries CA policy
• terminate_devices — sends a wipe command to every Intune-enrolled device the user owns

Example playbook: BEC first response

“On any alert with severity >= high in category security, disable the user, revoke their sessions, and notify the service desk.”

POST /playbooks
{
  "name": "BEC first response",
  "trigger": {
    "category": "security",
    "minSeverity": "high",
    "titleRegex": null,
    "tenantScope": { "type": "all" }
  },
  "actions": [
    { "type": "disable_user_and_revoke" },
    {
      "type": "notify_email",
      "to": ["servicedesk@yourmsp.com.au"]
    }
  ],
  "enabled": true
}

When the Entra risky-sign-in ingestor raises a security alert at critical severity, this playbook fires. The user is disabled + sessions revoked + password reset + forwarding rules stripped in one atomic compromise-remediation call, then the service desk mailbox gets an email with the alert context and the result of each step.

Execution model

When an alert lands, Manage365 loads every enabled playbook matching the alert and runs each in its own job. Actions inside a playbook run sequentially — step 1 must complete (or fail) before step 2 starts. A failing step does not abort the remaining steps (the pattern is the same as the compromise-remediation playbook: get the user out of the seat, report what's left).

Each execution is audited as a single playbook.execute event with the triggering alert ID, the playbook ID, and per-step status + result metadata.

Manual execution

A playbook can be run on demand against a specific alert via theRun playbook action on the alerts page or via API:

POST /playbooks/:id/execute
{
  "alertId": "<alert-uuid>"
}

Manual execution skips the trigger match — useful for re-running a playbook after you've fixed the underlying issue, or for dry-running against a historical alert.

Endpoints

Common pitfalls

• Trigger too broad — setting minSeverity = low on a playbook that disables users will fire on every noisy alert. Start narrow (category + critical) and widen only after you've tuned dedupe on the upstream alerts.
• No tenant scope for destructive actions — tenant_scope: all + terminate_devices is a recipe for fleet-wide wipes on a false-positive. Scope destructive playbooks to specific tenants or groups until you're confident.
• Regex not matching — alert titles occasionally change when the upstream source version-bumps (Defender renamed “Anonymous IP address” between API versions). Test the regex against the live alert list first.
• Missing target user — playbook actions that operate on a user need the alert to carry a user resource reference. Compliance score alerts, service health alerts, and some Defender alerts don't — those actions silently skip with a logged error.

FAQ

Do playbooks run on acknowledged alerts? Only new alerts trigger. Ack-ing or resolving an already-processed alert doesn't re-fire playbooks.

Can I chain playbooks? Not directly. If two playbooks match the same alert they run in parallel. For sequential logic, put both sets of actions in one playbook.

What if a PSA ticket creation fails? The step fails; remaining steps still run. The execution audit entry records the failure. Alert → Related playbook runs on the alert page shows the failed step with the upstream error message.

Can playbooks modify standards or CA policies? No — playbooks are for per-user / per-incident response. Config-drift remediation lives on the MSP Library.