Claude Media
Claude CodeにCrowdSecスキルを入れて導入と障害調査を任せる
Claude Codeチュートリアル

Claude CodeにCrowdSecスキルを入れて導入と障害調査を任せる

CrowdSec公式のClaude Codeプラグインは、導入・bouncer・WAF・allowlistの設定と「ブロックされない」の切り分けを担います。入れ方、権限の絞り方、守備範囲の外を解説します。

読了目安 約12分

CrowdSecの導入や障害調査は、Claude Codeに任せられます。CrowdSec自身が公開している公式プラグインを入れると、cscliの使い分けや設定ファイルの置き場所、失敗しやすい箇所を知った状態でClaudeが動きます。

プラグインは「crowdsec」と「crowdsec-service-api」の2つのスキルを束ねています。ここでは入れ方、守備範囲、本番サーバーで使うときの権限の絞り方を順に見ます。

入れる前に知っておくこと: 2つのスキルの役割

名前が似ていて混同しやすいので、先に区別します。リポジトリの表記では、マーケットプレイスがcrowdsecurity、その中のプラグインがcrowdsec、プラグインが運ぶスキルがcrowdsecとcrowdsec-service-apiです。

くらべる

2つのスキルの担当範囲

手元のエンジンを扱う

crowdsec

エンジンの導入、cscliの操作、bouncer、WAF(AppSec)、ハブ、allowlist、障害の切り分けを担当します。ローカルのLAPIやログが対象です。

クラウドのConsoleを扱う

crowdsec-service-api

プレミアムのService APIを、利用者のAPIキーで操作します。ブロックリストやallowlistの作成、ファイアウォール製品との連携、効果の指標、組織単位のdecisionが対象です。

日常の運用で触るのはほとんど前者です。後者はConsoleの有料機能をスクリプト無しで動かしたい場合に使います。

インストールとスキルの読み込み

Claude Codeでは、マーケットプレイスを追加してからプラグインを入れます。

/plugin marketplace add crowdsecurity/crowdsec-skill
/plugin install crowdsec@crowdsecurity

更新は/plugin marketplace update crowdsecurityです。/plugin installはセッション内では詳細パネルを開く動きになり、読み込みには/reload-pluginsか再起動を使います。この挙動はClaude Code側の仕様で、プラグインごとに共通です。

スキルは入れるだけで有効になり、スラッシュコマンドは不要です。プロンプトにCrowdSecの話題が出ると、スキルの説明文に書かれた条件(導入、設定、運用、デバッグ、cscli、bouncer、WAF、fail2banからの移行など)に当たって読み込まれます。

プラグインを入れるとコンテキストを使います。常時載るぶんの大きさはclaude plugin detailsでの測り方で確かめられます。使わなくなったら導入済みプラグインの棚卸しで外す候補に載せてください。

Codexやclaude.aiでも使えます。claude.aiでは、リリースのzipをスキルのアップロード画面から入れます。

何を任せられるか

READMEの対応表を、作業のまとまりごとに並べ直します。

作業守備範囲
導入守備範囲systemd / Docker / Kubernetes(Helm) / pfSense、Console登録
bouncer守備範囲iptables・nftables・ipset、nginx、traefik、caddy、apacheなど
WAF(AppSec)守備範囲配備、設定、トラブル対応、bot検知
ハブ守備範囲collection・parser・scenarioの導入、更新、デバッグ
設定守備範囲acquisition、profileとban期間、通知、allowlist
運用守備範囲ヘルスチェック、アップグレードとロールバック、複数サーバー、リモートLAPI、mTLS
デバッグ守備範囲ログが解析されない、アラートが出ない、bouncerが止めない、個別のエラー
移行守備範囲fail2banのjailからの移行

WAFとAppSecは同じコンポーネントを指す語で、設定やコマンドではAppSec、利用者向けの呼び方がWAFです。スキルはこの2語を同義として扱います。

環境の自動判定

スキルは最初に環境を調べます。systemdのサービス、実行中のDockerコンテナ、Kubernetesのpodを順に探し、最初に当たったものを対象にします。どれにも当たらず、CrowdSecが入っていると利用者が言う場合は、ベンダーのアプライアンスか自作イメージか別ホストかを聞き返します。pfSenseはuname -iで判定され、パスやサービス名がLinuxと別物なので専用の手順に進みます。

古いパッケージの検査

Linuxではまずバージョンとインストール元のAPT/dnfリポジトリを確かめます。公式のリポジトリはpackagecloudで、ディストリビューション標準のパッケージから入れた場合はかなり古いバージョンのことがあります。その場合、設定の調査より先に公式リポジトリへの移行を勧める作りです。「cscliのサブコマンドが無い」「ハブの項目が入らない」といった症状の原因が、設定ではなくバージョンにあることが多いからです。

試せるプロンプトと、スキルが回す手順

READMEには次のようなプロンプトが載っています。

  • 「このサーバーにCrowdSecを入れて、nginxのbouncerを設定して」
  • 「KubernetesクラスタにCrowdSecを入れてConsoleに登録して」
  • 「CrowdSecがnginxへの攻撃を検知しない。なぜ？」
  • 「このIPにはdecisionがあるのにブロックされない」
  • 「fail2banのjailをCrowdSecに移して」

障害調査では、スキルは最初に診断スクリプトdiagnose.shを走らせるのが基本です(SKILL.mdに「最初の一手はほぼこれ」と書かれています)。スキル本体のcscli早見表に載る確認コマンドは次のとおりです。

cscli metrics                 # 取り込み・解析・bouncerの状況を一表で見る
cscli alerts list -l 50       # 直近のアラート
cscli decisions list          # 有効なban
cscli bouncers list           # bouncerと最終pull時刻
cscli lapi status             # エージェントからLAPIへ届くか
cscli explain --file <log> --type nginx   # ログを解析器に通す(読み取りのみ)
crowdsec -t                   # 設定ファイルの検証

「アラートはあるのにブロックされない」なら、decisions listにIPがあるか、bouncers listで最終pull時刻が新しいかを順に見るのが切り分けの基本です。スキルはこの順序を症状別の資料(解析されない・アラートが出ない・ブロックされない)として持っています。

本番サーバーで使うときの安全策

ベアメタルのsystemd環境では、cscliとcrowdsecが/etc/crowdsec/や/var/lib/crowdsec/を読み、systemdのユニットを操作するためroot権限が要ります。スキルは設定や状態に触れる前にid -uで、rootかsudoが使えるかを確かめます。どちらでもなければ推測で進めず、権限の付与を依頼して止まります。DockerとKubernetesはコンテナやpodの中で実行するので、この前提は不要です。

スキルは危険な操作の前に確認を取るよう書かれています。確認が必要な操作として明記されているのは次の5つです。

  1. cscli decisions delete --all(CAPIから取り込んだブロックリストも含め、有効なbanを全消去する)
  2. ハブが管理するファイルの直接編集(_custom/ディレクトリで上書きするのが正しい)
  3. 誤検知を消すためにシグネチャのcollectionごと無効にすること
  4. ホストのファイアウォールを変える操作(firewall bouncerの導入、ipsetのflush、iptablesとnftablesの切り替え)
  5. helm upgrade crowdsecを--reset-then-reuse-values無しで実行すること(値が黙って落ちる)

ただし、確認を取るかどうかはスキルの文面に頼る部分です。Claude Code側の権限でも固定しておくと確実です。たとえば.claude/settings.jsonに次のように書くと、banの削除は毎回承認画面を通り、全消去は拒否されます。ルールは拒否、確認、許可の順に評価されます。

{
  "permissions": {
    "deny": ["Bash(cscli decisions delete --all*)"],
    "ask": [
      "Bash(cscli decisions delete *)",
      "Bash(sudo cscli decisions delete *)",
      "Bash(ipset *)"
    ]
  }
}

Bash(cscli decisions delete *)はスペースの後ろにだけワイルドカードを置いた形で、--all付きの呼び出しも含みます。denyが先に評価されるので、全消去だけは確認画面すら出ません。ベアメタルではsudo付きで実行されることが多いため、sudo付きの呼び出しも確実に止めるように同じルールを並べています。

CLAUDE.mdには、スキルだけでは決まらない現場の約束を書きます。

## CrowdSec運用の約束
- 本番ホストで設定を変える前に、変更内容を差分で示してから実行する
- allowlistに入れるIPは、追加の理由と有効期限を必ず添える
- ハブ管理のファイルは触らず、`_custom/`側で上書きする
- 作業後は`cscli metrics`と`crowdsec -t`の結果を貼って報告する

allowlistの追加を例にすると、Claudeに任せる作業は「理由を聞いてcscli allowlists add <name> <ip>を実行し、cscli allowlists check <ip>で効いたことを確認する」ところまでです。実行の前後で確認コマンドを走らせる流れまでを、約束として固定しておくと手戻りが減ります。

Service APIスキルの扱い

crowdsec-service-apiはベースURLhttps://admin.api.crowdsec.net/v1に対し、リクエストごとにx-api-keyヘッダーを付けて叩きます。キーは環境変数CROWDSEC_SAPI_KEYか~/.config/crowdsec/sapi_keyから読む作りで、ファイルはchmod 0600にするよう書かれています。

最初の操作は/v1/infoでキーの検証をし、所属組織と契約の種類を見ることです。状態を変える操作(IPの追加、ブロックリストの購読など)は、実行するURLとJSON本文を示して明示的に承認を取ってから行います。購読したエンジンはそのリストを強制するので、誤ったIPを入れると本番の通信が止まります。承認前に本文を読む理由はここにあります。

プライバシーの方針も確認しておきます。プラグインは個人データを集めず、ローカルで動く文書と補助スクリプトだけで構成されています。通信が起こるのは、利用者が渡した資格情報で自分のエンジン、CAPI、ハブ、Service API、Consoleに向かうときだけです。

守備範囲の外

このスキルは運用のためのもので、検知ルールは書きません。parser、scenario、WAF(AppSec)のルールの作成は対象外で、スキルは検知ルール作成用のcrowdsec-local-mcpというMCPサーバーを案内しています。ルールを書く作業が必要なら、先にそちらを用意してください。MCPサーバーを自分で作る側の手順はmcp-server-devプラグインの記事が参考になります。

もう1つの注意点はバージョン依存です。bot検知(AppSecのchallengeモード)はエンジン1.8.0以降が必要で、READMEでは公開前の機能として扱われています。bouncer側も対応が必要で、nginx、OpenResty、HAProxy SPOA、Traefik、Envoyが挙がっています。設定が合っているのに動かないときは、まずエンジンの版を疑います。

スキルの資料は37本あり、それぞれ実際のCrowdSec環境で検証してから載せると説明されています。とはいえ、本番に当てる前に検証環境で同じ手順を流すのが無難です。Claudeに任せる場合でも、実行ログとcscli metricsの結果を読んで、期待どおりに取り込みとブロックが動いているかを自分の目で確かめてください。

まとめ

CrowdSecスキルの価値は、cscliの知識そのものより、環境の判定、版の検査、確認が要る操作の線引きをあらかじめ持っている点にあります。入れる作業は2コマンドで済みます。一方、Claude Code側の権限とCLAUDE.mdでdecisions deleteとファイアウォール操作を絞っておけば、本番でも安心して任せられる範囲が広がります。検知ルールの作成だけは別の道具が要ります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →