crowdsec

CrowdSec — 運用、デプロイ、設定、デバッグ

用語集： AppSec はエンジンコンポーネントの名称です（設定、ハブのパス、 cscli appsec-*、Helm ワークロードで使用されます）。WAF は同じものを指す ユーザー向けの用語です。このスキルでは両方を同じ意味で使用します。

対象範囲 — このスキルで行うこと、行わないこと

目的	使用するもの
CrowdSec をインストール／アップグレード／アンインストールする	このスキル
アクイジション、ハブ、プロファイル、通知を設定する	このスキル
バウンサー（ファイアウォール、nginx、traefik、caddy）をインストールして接続する	このスキル
WAF（AppSec コンポーネント）をデプロイする	このスキル
ボット検出（AppSec チャレンジモード）をデプロイして調整する	このスキル
「ログがパースされない」／「アラートがない」／「バウンサーがブロックしない」をデバッグする	このスキル
fail2ban から移行する	このスキル
パーサー、シナリオ、または WAF（AppSec）ルールを作成する	crowdsec-local-mcp mcp
クラウド Service API を操作する（ブロックリスト／許可リスト／ファイアウォール連携／メトリクス／判定をプログラムで管理する）	crowdsec-service-api スキル

ステップ 1 — 環境を検出する

次の順にプローブを実行します。最初に一致した時点で停止します。

# systemd / bare-metal
systemctl list-unit-files crowdsec.service >/dev/null 2>&1 && systemctl is-enabled crowdsec >/dev/null 2>&1
# docker
docker ps --format '{{.Names}} {{.Image}}' 2>/dev/null | grep -E '(^|/)(crowdsec)([: ]|$)'
# kubernetes
kubectl get pods -A 2>/dev/null | grep -i crowdsec

何も一致せず、ユーザーが CrowdSec をインストール済みだと報告した場合は、インストール先を確認します。ベンダー製アプライアンス、カスタムイメージ、/opt/ 内のバイナリ、リモートホストのいずれかを尋ねてください。それ以外の場合はインストールに進みます。references/install/ を参照してください。

pfSense の検出：

uname -i   # → pfSense  (pfSense CE or Plus)

pfSense であることが確認できた場合は、直接 references/install/pfsense.md に進みます。パス、サービス名、アクティベーションの手順は Linux/systemd とはまったく異なります。

権限 — ベアメタル／systemd の前提条件

ベアメタル／systemd では、cscli と crowdsec の実行に root 権限が必要です（/etc/crowdsec/、/var/lib/crowdsec/ 配下の DB を読み取り、systemd ユニットを制御します）。設定や状態に触れる操作を実行する前に、ユーザーが root または sudo を使えることを確認してください。

id -u   # 0 = root; otherwise the user needs sudo

root でも sudoer でもない場合は、権限を付与してもらうよう依頼して停止してください。推測で進めてはいけません。確認できたら、ベアメタルのコマンドは root として実行するか、sudo を付けて実行します。Docker／k8s のコマンドはコンテナ／ポッド内で実行するため、この権限は必要ありません。

ステップ 1.5 — バージョンとインストール元の確認（Linux）

インストール作業、および「挙動がおかしい」という報告（cscli のコマンド／フラグが見つからない、ハブの項目をインストールできない、ドキュメントと挙動が一致しない）では、必ず最初に確認します。誤ったソースからインストールされたエンジンは、何年も古い可能性があります。これは Linux ディストリビューション限定の落とし穴です。

稼働中のエンジンと最新の公開リリースを比較します。

curl -s https://version.crowdsec.net/latest    # → {"tag_name":"v1.7.8",...}; parse tag_name
cscli version                                  # bare-metal: prefix sudo

次に、パッケージの入手元を確認します。

# Debian/Ubuntu
apt-cache policy crowdsec                       # read the *** installed line's origin
ls /etc/apt/sources.list.d/ | grep -i crowdsec
# RHEL-family
dnf info crowdsec ; dnf repolist | grep -i crowdsec

公式ソースは packagecloud リポジトリ（packagecloud.io/crowdsec/crowdsec、リポジトリ ID crowdsec_crowdsec）です。ディストリビューション由来（archive.ubuntu.com、deb.debian.org、ports.ubuntu.com）、または crowdsec のリポジトリファイル自体がない場合は、そのディストリビューション独自の古いパッケージからインストールされたことを意味します。

ルール： ソースが公式リポジトリではないか、バージョンが tag_name より大幅に古い場合は、インストールが古い可能性が高いものとして扱います。設定のデバッグを中止し、まず公式リポジトリに移行します。references/operate/upgrades.md § 古い／ディストリビューションパッケージ版のインストールを検出して修正する を参照してください。

Docker／Kubernetes： リポジトリ元に関する落とし穴はありません。バージョンは Docker Hub から取得したイメージタグで決まります。version.crowdsec.net/latest より大幅に古い場合は、新しいタグを取得します（references/operate/upgrades.md の通常の手順）。

ステップ 1.6 — 機能の互換性

一部の機能は特定のエンジンバージョン以降でのみ利用でき、さらに対応するバウンサーが必要な機能もあります。「設定は正しいのに何も起きない」という問題を調査する前に、ここを確認してください。古いエンジンの場合、設定の変更ではなくアップグレードが必要です。

機能	最小エンジンバージョン	追加要件	ドキュメント
ボット検出（AppSec チャレンジモード） — アルファ版	1.8.0	ボット検出に対応するバウンサー（nginx、OpenResty、HAProxy SPOA、Traefik、Envoy）と、コンパイラーモードで WASM を実行できるホスト	references/appsec/bot-detection/
appsec_configs での Glob パターン	1.8.0	—	references/appsec/bot-detection/deploy.md § 2

バージョンによって異なる動作は、各リファレンスドキュメントで繰り返すのではなく、ここに記載します。機能を追加する際は、本文中に「x.y 以降」と散りばめるのではなく、行を追加してください。

ステップ 2 — 意図を検出する

ユーザーの手がかり	参照先
"install", "set up", "fresh box", "how do I start"	references/install/（環境に応じてファイルを選択）
"pfsense", "pfSense", "netgate"	references/install/pfsense.md
"configure logs / acquisition", "read journald / syslog / docker logs"	references/configure/acquisition.md
"install a collection / parser / scenario", "hub", "tainted"	references/configure/hub.md
"ban duration", "captcha", "decisions", "simulation", "alerts but no bans"	references/configure/profiles.md
"allowlist my office / CDN / monitoring IP", "I'm getting blocked by CAPI", "exclude IP from any ban"	references/configure/allowlists.md
"whitelist vs allowlist vs postoverflow", "which suppression layer should I use"	references/configure/allowlists.md § 抑制メカニズム
"test my whitelist works", "is my postoverflow / dynamic-IP whitelist actually firing"	references/configure/allowlists.md § 検証 — ホワイトリストは実際に機能していますか？
"notifications", "alert me on slack/email/webhook", "notification not firing"	references/configure/notifications.md
"block at the firewall", "iptables", "nftables", "ipset"	references/configure/bouncers/firewall.md
"nginx bouncer", "lua / openresty module"	references/configure/bouncers/web-servers.md § nginx
"haproxy bouncer", "SPOA / SPOE"	references/configure/bouncers/web-servers.md § haproxy
"apache bouncer", "mod_crowdsec"	references/configure/bouncers/web-servers.md § apache
"traefik bouncer", "traefik plugin / middleware"	references/configure/bouncers/web-servers.md § Traefik
"caddy bouncer", "caddy module / xcaddy"	references/configure/bouncers/web-servers.md § Caddy
"wrong source IP", "real client IP", "behind Cloudflare / reverse proxy / NPM", "X-Forwarded-For", "everyone shows as the proxy IP"	references/configure/bouncers/web-servers.md — 各バウンサーの実 IP／信頼済みプロキシのセクション
"AppSec", "WAF", "virtual patching", "block by request shape"	references/appsec/ — 概要、デプロイ、設定、トラブルシューティング
"bot detection", "challenge mode", "JS challenge", "proof of work", "block headless browsers / puppeteer / selenium / scrapers", "let Googlebot through"	references/appsec/bot-detection/ — 概要、デプロイ、設定、カスタマイズ、トラブルシューティング
"Console", "enroll", "share signals"	references/install/console.md
"upgrade", "back up", "roll back", "new version", "tainted items after upgrade"	references/operate/upgrades.md
"old/outdated version", "cscli command or flag missing", "hub item won't install", "behavior doesn't match the docs", "installed from the distro package"	references/operate/upgrades.md § 古いバージョン／ディストリビューションのパッケージからインストールした場合の検出と修正（上記のステップ 1.5を参照）
"multiple agents", "remote LAPI", "mTLS", "postgres backend"	references/operate/multi-server.md (一部のみ — マシンのクリーンアップは完了、残りはスタブ)
"cscli machines list に表示される古いマシン／ログプロセッサー", "停止したエージェントを整理する", "一時的な k8s ポッドが増え続ける"	references/operate/multi-server.md § 古いマシンの登録解除
"is it working?", "smoke test", "validate install", "verify setup", "did detection / WAF / blocking actually wire up?"	references/operate/health-check.md
デバッグ — 共通 · "it's broken" / "not working" / 一般的な診断	references/debug/common/triage.md → bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh を実行
デバッグ — 共通 · 特定のエラーメッセージ	references/debug/common/errors.md
デバッグ — 共通 · "container can't see logs", "mount", "SELinux/AppArmor denied", "k8s RBAC / DaemonSet"	references/debug/common/platform-gotchas.md
デバッグ — 症状別 · "logs not parsed", "0 parsed"	references/debug/symptoms/parsing.md
デバッグ — 症状別 · "no alerts firing"	references/debug/symptoms/no-alerts.md
デバッグ — 症状別 · "decision exists but not blocked"	references/debug/symptoms/not-blocked.md
デバッグ — 症状別 · "bouncer blocks everything", "locked out of all services", "every request 403 after adding the bouncer"	references/debug/symptoms/not-blocked.md § 7 — 逆の症状
デバッグ — 機能別 · AppSec／WAF がブロックしない、誤検知、captcha	references/appsec/troubleshoot.md
デバッグ — 機能別 · チャレンジが表示されない、チャレンジが終わらない、実際のクローラーにチャレンジが表示される、ボット検出を有効にした後すべてがブロックされる	references/appsec/bot-detection/troubleshoot.md
"switch from fail2ban"	references/migrate/from-fail2ban.md (TODO — スタブ)
デバッグ関連のことなら、まずはほぼ必ず次を実行します。

bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh

（または --env docker --container <name> ／ --env k8s --namespace ... --pod ...）。

ステップ 3 — 汎用 cscli チートシート

以下はどの環境でも使えます。ベアメタル／systemd では、（root でない場合）先頭に sudo を付けてください。上記の権限を参照してください。docker／k8s では、先頭に docker exec <name> ／ kubectl exec -n <ns> <pod> -- を付けてください（コンテナー／Pod 内で root として実行されます）。

目的	コマンド
エンジンのバージョン	cscli version
有効な設定（パス、LAPI URL、DB タイプ）	cscli config show
一括トリアージテーブル	cscli metrics
最近のアラート	cscli alerts list -l 50
有効な BAN	cscli decisions list
BAN を 1 件削除	cscli decisions delete -i <ip>
Hub の状態（インストール済み＋改変／不足フラグ）	cscli hub list
Hub インデックスを更新してから、項目をアップグレード	cscli hub update && cscli hub upgrade
許可リスト — 一覧表示／IP を 1 件確認／追加	cscli allowlists list、cscli allowlists check <ip>、cscli allowlists add <name> <ip>
Bouncer と最終取得時刻を一覧表示	cscli bouncers list
この LAPI に登録されたエージェントを一覧表示	cscli machines list
LAPI に到達可能か確認（エージェント→LAPI）	cscli lapi status
CAPI／Console の接続状況（登録済み、取得／共有）	cscli capi status
Console の機能切り替え（custom/manual/tainted/context/console_management）	cscli console status
このエンジンを Console に登録	cscli console enroll <key> を実行してから再読み込みします（references/install/console.md を参照）
パーサーを通してログファイルを再生（読み取り専用）	cscli explain --file <path> --type <syslog|nginx|...>
ログ行を 1 件再生	cscli explain --log '<line>' --type <type>
YAML を編集した後に設定を検証（acquisition／profiles／config）	crowdsec -t（ベアメタルの場合。systemctl reload 時にも自動実行されます）。その後、cscli metrics show acquisition でソースが読み取られていることを確認します
シミュレーションの状態を確認（アラートは発生するが、判定は行わない）	cscli simulation status
判定プロファイルを確認（フィルター／BAN の期間）	cat /etc/crowdsec/profiles.yaml — cscli profiles コマンドはありません（v1.7.8 まで）。references/configure/profiles.md を参照してください

ベアメタルのデフォルトインストールでの各ファイルの場所：

• バイナリ：/usr/bin/crowdsec、/usr/bin/cscli
• 設定ルート：/etc/crowdsec/
• Acquisition：/etc/crowdsec/acquis.yaml および／または /etc/crowdsec/acquis.d/*.yaml
• Hub 項目：/etc/crowdsec/hub/、有効なシンボリックリンクは /etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/ の下にあります
• ローカルオーバーライド：*/parsers/*/_custom/、*/scenarios/*/_custom/ など
• データ（sqlite DB、geoip）：/var/lib/crowdsec/data/
• ログ：/var/log/crowdsec.log（エージェント）および /var/log/crowdsec_api.log（LAPI）
• LAPI のデフォルト待ち受け先：127.0.0.1:8080
• Systemd ユニット：crowdsec.service

ステップ 4 — 絶対に避けること

以下を行う前に、必ずユーザーに確認してください。

• cscli decisions delete --all — CAPI から取得したブロックリストを含む、すべての有効な BAN を消去します。対象を指定して delete -i、delete -r、delete --id、delete --origin lists --scenario <name> を使ってください。
• /etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/ の Hub 管理ファイルを編集する（代わりに同階層の _custom/ ディレクトリを使ってください）。references/debug/common/triage.md の「絶対に避けること」を参照してください。
• 誤検知を抑えるために署名コレクション全体を無効化する — references/configure/allowlists.md の「抑制メカニズム」に従い、適切な抑制レイヤー（許可リスト／ホワイトリストパーサー／postoverflow）を選んでください。
• 確認せずにホストのファイアウォール状態を変更する（firewall bouncer のインストール、ipset のフラッシュ、iptables と nftables の切り替えなど）— firewall bouncer は、他のツールが依存するルールチェーンを消去することがあります。
• helm upgrade crowdsec で --reset-then-reuse-values を省略する — 値が警告なしに失われます。

ドキュメント

正式なリファレンス：https://docs.crowdsec.net/。`references/` 内の各ファイルには、参照元の具体的なページが記載されています。記憶に頼って言い換えるのではなく、リンク先を確認してください。