# Playbooks

Playbooks は Zen Firewall の自動化ルールです。各 Playbook はイベントとアクションを組み合わせたもので、Zen がイベントを検知すると、そのアクションを自動で実行します。誰かがダッシュボードを監視している必要はありません。

Playbook は 1 つの文のように読めます：**攻撃ウェーブを検知 → IP を 30 分間ブロック**。

## Playbook を作成する

1. Zen Firewall のアプリを開き、**Playbooks** タブに移動します。
2. **Add Playbook** をクリックします。
3. **When** で、Playbook のトリガーとなるイベントを選択します。
4. **Configure** で、アクションとその継続時間を選択します。
5. **Create Playbook** をクリックします。

![When トリガーと Configure アクションを含む Create Playbook ダイアログ。](https://help.aikidogov.us/_assets/2368e939f150/Screenshot-2026-09-07-at-16.55.26.png)

Playbook は作成するとすぐに有効になります。

![攻撃ウェーブ後に IP を 30 分間ブロックする有効な Playbook が表示された Playbooks タブ。](https://help.aikidogov.us/_assets/c0d160a24b20/Screenshot-2026-09-07-at-16.55.18.png)

## イベント

Playbooks はイベントに反応します。アプリケーションコードから独自のイベントを送信することも、Zen が標準で検知するイベントを使用することもできます。

### カスタムイベント

`track` を使ってアプリケーションコードからイベントを報告すると、アプリだけが把握している事象に Playbooks が反応できるようになります。例としては、ログイン失敗、無効なクーポンコード、パスワードリセットのリクエスト、拒否された API キー、決済の失敗などがあります。

リクエスト処理の中で、そのイベントが発生する箇所でイベント名を指定して `track` を呼び出します：

{% tabs %}
{% tab title="Node.js" %}
```javascript
const Zen = require("@aikidosec/firewall");

// Inside any request handler
Zen.track("your.event_name");
```
{% endtab %}

{% tab title="Python" %}
```python
from aikido_zen import track

# Inside any request handler
track("your.event_name")
```
{% endtab %}

{% tab title="Go" %}
```go
// Inside any HTTP handler, pass the request context
zen.Track(r.Context(), "your.event_name")
```
{% endtab %}

{% tab title="Ruby" %}
```ruby
# Inside any request, for example a Rails controller action
Aikido::Zen.track("your.event_name")
```
{% endtab %}

{% tab title="PHP" %}
```php
// Inside any request handler
if (extension_loaded('aikido')) {
    \aikido\track('your.event_name');
}
```
{% endtab %}

{% tab title=".NET" %}
```csharp
// ASP.NET Core: using Aikido.Zen.DotNetCore;
// ASP.NET Framework: using Aikido.Zen.DotNetFramework;

// Inside any controller action or middleware
Zen.Track("your.event_name");
```
{% endtab %}
{% endtabs %}

イベント名には任意の形式を使用できます。`user.login_failed` や `coupon.invalid` のような、小文字でドット区切りの名前を推奨します。

`track` を追加したら、一度イベントを発生させてください。すると、Playbook の作成時に選択できるイベントとして表示されます。`track` を呼び出すだけでは何もブロックされません。

Zen はリクエストから IP アドレスを取得するため、渡す必要があるのはイベント名だけです。`track` を呼び出す前に[現在のユーザーを設定](https://help.aikidogov.us/docs/docs-ja/zen-firewall/zen-features/blocking-users-with-zen-firewall)しておくと、Zen はユーザー情報も含めます。これにより、**`coupon.invalid` が 5 分間に 10 回 → IP を 1 時間ブロック** のような Playbook を作成できます。カウントはアプリ全体ではなく、IP ごとに行われます。

### 組み込みイベント

**Attack wave detected（攻撃ウェーブを検知）。** ある IP がアプリを体系的に探索している状態です。たとえば、`.env` ファイルや隠しディレクトリのスキャンなどです。Zen がこれを検知する仕組みについては、[Attack Wave Protection](https://help.aikidogov.us/docs/docs-ja/zen-firewall/zen-features/attack-wave-protection) を参照してください。

**Injection attack detected（インジェクション攻撃を検知）。** ユーザー入力が、SQL インジェクション、コマンドインジェクション、パストラバーサル、またはサーバーサイドリクエストフォージェリ（SSRF）によってアプリを悪用しようとした状態です。Zen がこれを検知する仕組みについては、[How Does Zen Work?](https://help.aikidogov.us/docs/docs-ja/zen-firewall/how-does-zen-work) を参照してください。

## アクション

**Block IP（IP をブロック）。** イベントを引き起こした IP が、このアプリのブロックリストに追加されます。期間は 30 分、1 時間、24 時間、または無期限から選択できます。

一時的なブロックは自動的に期限切れになります。ブロックの期限が切れると、Zen はその IP のイベントカウントもリセットするため、Playbook は再びゼロからカウントを開始します。

Playbooks が[バイパスリスト](https://help.aikidogov.us/docs/docs-ja/zen-firewall/zen-features/bypassed-ips)にある IP をブロックすることはありません。

## Playbook の実行内容を確認する

Playbooks タブの **Activity** ビューには、Playbook が実行したすべてのアクションが記録されます。実行日時、発動した Playbook、対象となった IP、ブロックの残り時間を確認できます。ドロップダウンを使って Playbook ごとに絞り込めます。

Playbook によるブロックは、[Why is this IP blocked?](https://help.aikidogov.us/docs/docs-ja/zen-firewall/miscellaneous/why-is-this-ip-blocked) でも **Playbook rule** として表示されます。

## Playbook を無効化、編集、または削除する

Playbook の行の右側にあるアクションメニューを使用します：

* **Disable Playbook** は、アクションの実行を停止します。既存のブロックはそのまま維持されます。
* **Edit Playbook** は、イベント、アクション、または期間を変更します。
* **Remove Playbook** は、Playbook を削除します。