Recommended Actions
When an analyst opens an alert, the first question is always the same: what do we do about it? Recommended Actions answers that question directly on the alert. Every alert type in Surface Security carries an incident response playbook — a short, structured checklist covering immediate response, investigation, and escalation — that appears in a collapsible Recommended Actions panel on the alert detail page.
Surface Security ships with sensible built-in playbooks for its alert types, but every organization's process is different: your ticket queues, escalation contacts, takedown vendors, and communication channels are yours. The Settings > Recommended Actions page lets administrators replace any playbook with organization-specific guidance written in Markdown, with a live preview, and reset back to the built-in defaults at any time.
How it works
- Each alert type (Credential Reuse, Phishing Suspected, AiTM Attack Detected, Web Skimmer Detected, and so on) has exactly one playbook.
- A playbook is either Default (the built-in content) or Custom (your override). Customizing one alert type does not affect any other.
- Analysts see the effective playbook on every alert detail page for that alert type, rendered from Markdown. If a playbook has no content, the panel simply does not appear on those alerts.
- Resetting a customized playbook removes your override and restores the built-in default — the defaults themselves are never lost.
- Playbooks are plain Markdown, capped at 10 KB each. Raw HTML such as
<script>or<iframe>tags,javascript:links, and inline event handlers are rejected on save, and rendering is sanitized — playbooks cannot execute anything in an analyst's browser.
[SCREENSHOT PLACEHOLDER: The Recommended Actions settings page showing the searchable table of alert types with Alert Type, Status, and Preview columns, a mix of Default and Custom badges, and the Reset All to Defaults button in the header]
Using the page
Navigate to Settings > Recommended Actions in the admin dashboard.
The page shows a table of all alert types with three columns plus an action:
| Column | Meaning |
|---|---|
| Alert Type | The alert type the playbook applies to, for example "Phishing Suspected" or "Pwned Password". |
| Status | A Custom badge if your organization has overridden the playbook, otherwise Default. |
| Preview | The first line of the playbook content, with formatting stripped. |
| Edit | Opens the playbook editor for that alert type. |
Use the Search alert types... box above the table to filter the list by name.
If at least one playbook is customized, a Reset All to Defaults button appears in the page header. Clicking it asks for confirmation ("Reset ALL recommended actions to built-in defaults? This cannot be undone.") and then discards every custom playbook at once.
Editing a playbook
Click Edit on any row to open the playbook editor. The editor has two tabs:
- Write — a Markdown text area with a formatting toolbar: Bold, Italic, Heading 1, Heading 2, Bullet List, Numbered List, Inline Code, and Link. Toolbar buttons wrap or prefix the current selection with the corresponding Markdown.
- Preview — a live rendering of exactly what analysts will see on the alert detail page.
The footer notes "Supports Markdown formatting" and offers three actions:
- Save — stores the content as your organization's custom playbook for this alert type. The row's status changes to Custom.
- Reset to Default — shown only when the playbook is already customized. Asks for confirmation, then removes the override and restores the built-in content.
- Cancel — closes the editor without saving.
[SCREENSHOT PLACEHOLDER: The playbook editor modal on the Write tab, showing the formatting toolbar, Markdown content in the text area, and the Save, Reset to Default, and Cancel buttons in the footer]
[SCREENSHOT PLACEHOLDER: The same editor on the Preview tab, showing the rendered playbook with headings, numbered steps, and a blockquote escalation note]
What analysts see
On an alert detail page, the playbook appears as a collapsible panel labeled Recommended Actions, directly below the alert description. Analysts click the panel to expand the rendered playbook and work through it while triaging. Changes you save on the settings page take effect the next time an analyst loads an alert of that type — no extension update or endpoint change is involved. See Alerts for the full alert triage workflow.
[SCREENSHOT PLACEHOLDER: An alert detail page for a Phishing Suspected alert with the Recommended Actions panel expanded, showing the rendered playbook steps]
Alert types covered
Every Surface Security alert type appears in the table — around thirty in total, spanning credential hygiene, phishing, clipboard and ClickFix attacks, browser extension risk, GenAI data leakage, OAuth abuse, and device lifecycle. A few representative examples of what the built-in defaults cover:
| Alert type | Built-in playbook focus |
|---|---|
| Credential Reuse | Reset all affected accounts, review login history, escalate on confirmed access |
| Phishing Suspected | Block the URL, preserve evidence, reset credentials for anyone who submitted them |
| Pwned Password | Immediate reset, breach source identification, password manager guidance |
| AiTM Attack Detected | Revoke sessions, force MFA re-enrollment, block the proxy infrastructure |
| ClickFix/FileFix Attack | Isolate the endpoint, capture clipboard evidence, run malware scans |
| GenAI Data Leakage | Classify the leaked data, request deletion from the service, notify compliance |
| Web Skimmer Detected | Block the site and exfiltration endpoint, identify the injection vector |
| Stale Device | Verify device status, revoke certificates and enrollment if decommissioned |
A small number of newer alert types ship without built-in content; their playbooks are empty (and the panel hidden on their alerts) until you write one.
Content rules
Playbooks accept standard Markdown: headings, bold and italic text, bulleted and numbered lists, links, inline code, blockquotes, and tables. A few limits apply, enforced when you save:
| Rule | Detail |
|---|---|
| Maximum size | 10 KB per playbook |
| No script-capable HTML | Tags such as <script>, <iframe>, <object>, <embed>, <svg>, and <math> are rejected |
| No script URLs | javascript:, vbscript:, and data:text/html links are rejected |
| No event handlers | Inline handlers (for example onclick=) are rejected |
Rendering on the alert page is additionally sanitized, so even content that slips past validation cannot run code.
Worked example: customizing the phishing playbook
Contoso's SOC has its own process for phishing: containment goes through their secure email gateway team, evidence goes into a specific ticket queue, and takedowns are handled by an external vendor. The built-in "Phishing Suspected" playbook is generic, so an administrator tailors it.
- Open Settings > Recommended Actions and type "phishing" in the Search alert types... box.
- Click Edit on the Phishing Suspected row.
- On the Write tab, replace the default content with:
## Containment (first 15 minutes)
1. Block the phishing URL in Surface Security (deny the domain) **and** raise a
block request with the SEG team via the `#soc-containment` channel
2. Search the mail gateway for other recipients of the same lure
3. Preserve evidence: screenshot, page source, and full URL into the
`PHISH` ticket queue
## Investigation
- Check whether any user submitted credentials before the block landed
- Pull the hosting details and registrar for the phishing domain
- Cross-reference the alert's campaign context to see if this is part of a
tracked campaign
## Takedown and recovery
1. Open a takedown request with BrandShield (SLA: 4 business hours)
2. Force a password reset for any user who entered credentials
3. Enable step-up monitoring on affected accounts for 14 days
> Escalate to the on-call IR lead (`ir-oncall@contoso.com`) if credential
> submission is confirmed or more than 5 users received the lure.
- Switch to the Preview tab to confirm the headings, lists, and the escalation blockquote render correctly.
- Click Save. The row now shows a Custom badge.
The next time an analyst opens a Phishing Suspected alert, the Recommended Actions panel shows Contoso's process — including the ticket queue, the takedown vendor and its SLA, and the escalation contact — instead of the generic default.
Later, if Contoso overhauls its process, the administrator can click Edit > Reset to Default on that one playbook (confirming "Reset ... to the built-in default? This cannot be undone.") to start again from the built-in baseline.
FAQ
Do custom playbooks change what Surface Security detects or blocks? No. Playbooks are guidance for human analysts only. Detection, blocking, and alerting behavior are configured elsewhere and are unaffected by playbook content.
Who sees the playbooks? Anyone who can view alert detail pages in the dashboard. Keep that in mind before including sensitive contact details or internal procedures — playbooks are visible to all dashboard users with alert access, not just administrators.
Can I have different playbooks per team or per site? No. There is one playbook per alert type for the whole tenant. If different teams follow different processes, describe the branching inside the playbook (for example, "EMEA incidents: follow the EMEA runbook link below").
"Reset to Default" is not shown in the editor. That button only appears for playbooks that are currently customized. A playbook showing the Default badge is already at its built-in content.
My save was rejected. Check the content rules above — the most common causes are embedded HTML tags and content over the 10 KB limit. Playbooks are meant to be concise checklists; link out to your full runbook system for anything longer.