Security Automation Playbooks

A Security Automation Playbook enables you to customize and automate your app’s response to threats. Without manually coding the logic, you can use playbooks to extend Sqreen’s ability to monitor for more than just generic threats and vulnerabilities; you can observe and protect your app’s business logic.

For example, you can use the "Free plan abuse" playbook, one of Sqreen's pre-defined playbooks, to gain visibility into user activity. As a SaaS business, you may offer customers a free plan that lets new users discover your service and experience its potential. Such a plan likely skips the business logic that enforces your pricing structure and potentially lets users abuse the intent of the free plan. If you enable this playbook on your app, Sqreen automatically takes action: every time a user triggers the playbook -- When user.invited is performed 2 or more times over a period of 5 minutes by a user -- Sqreen records the details and sends a daily email digest and Slack notification to your team.

Support for playbooks

Playbooks rely on on both built-in and custom events that track and monitor user activity in your app.

  • Automatic: The Sqreen Microagent supports several HTTP authentication tools that automatically establish user context in your app. If the authentication tool your app uses is one that Sqreen supports, the microagent can track user activity in your app using built-in events. You can set the User Monitoring setting to "Automatic" and begin monitoring users and using playbooks right away.

  • Advanced: If the authentication tool your app uses is not one that Sqreen supports, or you want to customize the events a playbook uses, you set the User Monitoring setting to "Advanced", then install and integrate the Sqreen SDK for user monitoring. This enables the microagent inside your app to track user activity using custom events. To use Advanced user monitoring, you must take the small extra steps to install the SDK and add three methods to your app, but it enables you to extend the scope of Sqreen's user monitoring.

Sqreen Microagent Supports Automatic user monitoring Supports Advanced user monitoring
Node.js yes, using passport-local or passport-http yes, with the SDK for user monitoring
Ruby yes, using devise yes, with the SDK for user monitoring
PHP no yes, with the SDK for user monitoring
Java no yes, with the SDK for user monitoring
Go no yes, with the SDK for user monitoring
Python yes, using django yes, with the SDK for user monitoring

Create a playbook

To create a playbook, navigate to Sqreen Dashboard > Playbooks > Create a playbook and define a trigger, a security response, and a notification.


A trigger is a condition (or multiple conditions) that you set based on a threshold of events that occur in a specific timeframe by a specific actor (user or IP address). For example, When app.sqreen.plugins.attack is performed 3 or more times over a period of 10 minutes by an IP. When user activity in your app meets the conditions, Sqreen activates the playbook.

The trigger is made up of four parts:

  • an event, built-in or custom
  • a detection threshold
  • a period of time, minutes or hours
  • a type of actor, IP address or user

Refer to the following example of a trigger.



Playbooks can use both built-in events and custom events.

  • built-in: Sqreen tracks events in your app using the app.sqreen reserved namespace. Sqreen automatically displays the built-in events available for you to use when you are creating a new playbook. Refer to the sample below for an example of a built-in event. Refer to Built-in events for further details.
  • custom: After you install the SDK for user monitoring, you can define custom events in your app that Sqreen tracks and makes available for you to use when you are creating a new playbook. Refer to the "Track custom events" documentation in your Sqreen microagent's guide.

Detection threshold

When using threshold-based detection, it can be tricky to determine a value to set.

Use the Events Explorer to examine event trends and determine a normal volume of activity for your use case. Use these trends to set an informed threshold for the trigger.

Security responses

A security response is an action that you define to instruct Sqreen to block or redirect the bad actor (user or IP address) when they activate the playbook. For example, Block the IP for 5 minutes.

When user activity triggers a playbook, the Security Engine inside the Sqreen Microagent inside your app can take one of three actions:

  • No security response: The Security Engine takes no action.
  • Block: The Security Engine blocks the IP address or user from accessing your app permanently, or for a select period of time, like 24 hours. Blocked users see a message that reads:

    "Uh oh! Sqreen has detected an attack. If you are the application owner, check the Sqreen dashboard for more information."

    If you wish to customize this message, use the Redirect security response to send suspicious users to your own customized URL.

  • Redirect: The Security Engine redirects the IP address or user to a URL or path you define, either permanently, or for a select period of time, like 24 hours. If you redirect to a path, you need to passlist that path to avoid infinite redirection loops.

Read more about how the Security Engine works.

Critical IPs

By default, activity from a critical IPs does not trigger playbooks. A critical IP is an IP address that is either private, or belongs to a cloud provider's public load balancer. You can change this behavior by setting "Allow Playbooks to block attacks from critical IPs" to "On" in Sqreen Dashboard > Settings.


A notification is an action that you customize to instruct Sqreen on how to notify you when user activity in your app activates the playbook. For example, Send a Slack notification to sec-admin-channel immediately. When user activity triggers a playbook, Sqreen can send a notification to your team according to the settings you define.

  • Alert mode: Defines the severity of condition (High, Medium, Low, Custom) which triggers the type of notification that Sqreen sends (email and/or Slack message) and the frequency with which to send it (immediately, daily, or weekly). Define recipients, notification type, and delivery frequency in Sqreen Dashboard > Settings > Notifications.
  • Post to webhook: Toggle to "on" or "off" to send customized notifications using a webhook. When user activity triggers the playbook, Sqreen sends a POST request to the URL you provide. Set up webhooks in Sqreen Dashboard > Settings > Integrations. Read more about Sqreen Webhooks.

Event sample

    "name": "app.sqreen.foobar",
    "request": {
        "referer": null,
        "remote_port": "",
        "port": "80",
        "headers": {
            "HTTP_X_FORWARDED_FOR": ",",
            "HTTP_X_REAL_IP": ""
        "scheme": "http",
        "path": "/foo/bar",
        "parameters": {
            "json": {},
            "query": {
                "lang": "<script>foo</script>"
            "form": [],
            "other": {}
        "remote_ip": "",
        "rid": "03ec31ad9f5e5776866327357890b58d",
        "user_agent": "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.1; Trident/4.0)",
        "host": "",
        "verb": "GET"
    "properties": {
        "plugin": "sql_injection_pg",
        "category": "injection"
    "client_ip": "",
    "timestamp": "2018-07-11T14:48:23.698699+00:00",
    "ip_meta": {
        "is_tor": false,
        "date_resolved": "2018-08-31T08:33:18.963281+00:00",
        "proxy": false,
        "metadata": {
            "private": false,
            "global": true,
            "loopback": false,
            "unspecified": false,
            "version": 4,
            "reserved": false,
            "multicast": false
        "geo": {
            "code": "DEU",
            "point": [
            "city": "Aachen"
        "hostname": "",
        "vpn": false,
        "address": "",
        "tags": [],
        "datacenter": false