> For the complete documentation index, see [llms.txt](https://help.aikido.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aikido.dev/zen-firewall/zen-features/playbooks.md).

# Playbooks

Automatically block IPs when Zen sees suspicious behavior in your app.

Playbooks are automation rules for Zen Firewall. Each playbook pairs an event with an action: when Zen sees the event, it takes the action for you. No one has to be watching the dashboard.

A playbook reads as one sentence: **Attack wave detected → Block IP for 30 minutes**.

{% hint style="info" %}
Playbooks are an early access feature. [Contact support](/miscellaneous-info/contact-support.md) to have it enabled for your workspace.
{% endhint %}

## Create a playbook

1. Open a Zen Firewall app and go to the **Playbooks** tab.
2. Click **Add Playbook**.
3. Under **When**, pick the event that should trigger the playbook.
4. Under **Configure**, pick the action and how long it should last.
5. Click **Create Playbook**.

![Create Playbook dialog with a When trigger and a Configure action.](https://3149773201-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyKbzcQGrx7UtrG0nPZZ7%2Fuploads%2Fgit-blob-1d4d43c9ef0edb8eb1d2deeed1742faaab6d48a6%2FScreenshot%202026-09-07%20at%2016.55.26.png?alt=media)

The playbook is active as soon as you create it.

![Playbooks tab listing an active playbook that blocks an IP for 30 minutes after an attack wave.](https://3149773201-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyKbzcQGrx7UtrG0nPZZ7%2Fuploads%2Fgit-blob-95fc1101681f003fad34e319a6f2395152c7e634%2FScreenshot%202026-09-07%20at%2016.55.18.png?alt=media)

## Events

**Attack wave detected.** An IP is systematically probing your app, for example scanning for `.env` files or hidden directories. See [Attack Wave Protection](/zen-firewall/zen-features/attack-wave-protection.md) for how Zen detects this.

## Actions

**Block IP.** The IP that caused the event is added to the blocklist for this app. You choose how long: 30 minutes, 1 hour, 24 hours, or permanently.

Temporary blocks expire on their own. When a block expires, Zen also resets the event count for that IP, so the playbook starts from zero again.

Playbooks never block IPs on your [bypass list](/zen-firewall/zen-features/bypassed-ips.md).

## See what a playbook did

The **Activity** view on the Playbooks tab logs every action a playbook took: when it happened, which playbook fired, the IP it targeted, and how much of the block is left. Use the dropdown to filter by playbook.

Blocks made by a playbook also show up as **Playbook rule** in [Why is this IP blocked?](/zen-firewall/zen-features/why-is-this-ip-blocked.md)

## Turn a playbook off, edit, or delete it

Use the actions menu on the right of a playbook row:

* **Disable Playbook** stops it from taking action. Existing blocks stay in place.
* **Edit Playbook** changes the event, action, or duration.
* **Remove Playbook** deletes it.

## Reacting to events from your own code

{% hint style="info" %}
This part of Playbooks is still in development and not available yet.
{% endhint %}

Zen will let you report events from your application code with `track`, so playbooks can react to things only your app knows about, like a failed login.

```javascript
const Zen = require("@aikidosec/firewall");

app.post("/login", async (req, res) => {
  const user = await authenticate(req.body.username, req.body.password);

  if (!user) {
    Zen.track("user.login_failed");
    return res.status(401).json({ error: "Invalid credentials" });
  }

  Zen.setUser({ id: user.id });
  res.json({ token: createToken(user) });
});
```

Zen picks up the IP address and the current user from the request, so you only pass the event name. You can then build a playbook like **`user.login_failed` 3 times in 5 minutes → Block IP for 1 hour**. The count is per IP, not across your whole app.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.aikido.dev/zen-firewall/zen-features/playbooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.