crowdsec-service-api

CrowdSec Service API (SAPI) — クラウドのブロックリスト／許可リスト／インテグレーションの自動化

SAPI は、CrowdSec Console の背後で動作するプレミアムREST API です。 クラウド側のオブジェクト（プライベートブロックリスト、許可リスト、判定、 ファイアウォールのインテグレーション）を管理し、登録済みのエンジンや バウンサーにプッシュします。これはローカルエンジンの API ではありません。 ここでは cscli は使わず、HTTPS のみを使用します。

• ベース URL： https://admin.api.crowdsec.net/v1
• 認証： すべての呼び出しで x-api-key: <key> ヘッダーを指定します。（例外は インテグレーションの content エンドポイントです。インテグレーションの作成時に 発行される認証情報を使った HTTP Basic 認証を使用します。references/integrations.md を参照してください。）
• 対話型 API ドキュメント： https://admin.api.crowdsec.net/v1/docs · 仕様 https://admin.api.crowdsec.net/v1/openapi.json

境界 — このスキルと crowdsec スキル

目的	使用するスキル
クラウドでプライベートブロックリストを作成・管理し、API 経由で IP を追加する	このスキル
ファイアウォール／アプライアンス（Palo Alto、Fortinet など）をクラウドのインテグレーションに接続する	このスキル
クラウドの許可リストを管理し、エンジン／タグ／組織をリストに登録する	このスキル
組織レベルの判定（対象指定または都度設定のバン、IP 以外のスコープ、タグ／エンティティ単位）を作成・管理する	このスキル
修復 ROI 指標を取得する	このスキル
ローカルエンジン、cscli、バウンサー、WAF をインストール／実行／デバッグする	crowdsec スキル
エンジンを Console に登録する（cscli console enroll）	crowdsec スキル → references/install/console.md
1 つのエンジンでローカルの許可リスト／ホワイトリストを設定する	crowdsec スキル → references/configure/allowlists.md

ここで扱うクラウドの許可リスト／ブロックリストは、エンジンが 登録され、かつリストを購読している場合にのみ、そのエンジンに適用されます。 登録については crowdsec スキルを参照してください。

運用上のルール

ここでのすべての呼び出しは本番環境に対して行われ、購読中のエンジンが適用する内容を 変更する可能性があります。

1 — キーを取得します。 キーを表示したり、以下のファイル以外の場所に 書き込んだりしないでください。

KEY="${CROWDSEC_SAPI_KEY:-$(cat ~/.config/crowdsec/sapi_key 2>/dev/null)}"
[ -n "$KEY" ] || echo "No key: export CROWDSEC_SAPI_KEY or store it in ~/.config/crowdsec/sapi_key (chmod 0600)"

2 — 実行前に検証します — 読み取り呼び出しを 1 回行ってキーを確認し、 変更対象となるテナントを表示します。

curl -s -H "x-api-key: $KEY" https://admin.api.crowdsec.net/v1/info
# → {"organization_id":"…","subscription_type":"…","api_key_name":"…"}

3 — 読み取りと変更を分類します。 GET／ダウンロード／POST …/search は安全です。 そのまま実行してください。状態を変更するすべての POST／PATCH／DELETE は、 事前に明示的な確認が必要です。正確な URL と JSON 本文を提示してから、 承認を待ってください。

4 — 特に危険な操作 — これらのリストは購読中のエンジンが適用するため、 変更によって実際のトラフィックがブロックまたはブロック解除され、元に戻すのも困難です。 そのため、確認を求める前に、平易な言葉で影響を説明してください。

操作	危険な理由
POST …/ips/bulk_overwrite	ブロックリストの内容をすべて置き換えます。
DELETE /blocklists/{id} · /allowlists/{id} · /integrations/{id}	オブジェクトを削除し、全員の購読／フィードを解除します。
POST …/ips/delete	全エンジンで IP のブロックを解除します。
target.type: org を指定した POST /decisions	組織内の登録済みエンジンすべてに対して、全体的にバンを適用します。
…/shares／共有解除	別の組織にアクセス権を付与／取り消します。
…/subscribers の変更すべて	リストを適用するエンジン／バウンサーを変更します。

5 — 後片付け レシピのテスト専用に作成したオブジェクトは削除してください。 転送中のどこかで露出したキーはローテーションする必要があります。

ステップ — 意図を判断する

ユーザーの手がかり	移動先
「キーをテストして」「自分がどの組織／プランを利用しているか」	references/authentication.md
「ブロックリストを作成して」「SIEM／SOAR から IP を送信して」「IP を期限切れにして」「別の組織とブロックリストを共有して」「エンジンをリストに登録して」	references/blocklists.md
「API 経由でクラウドの許可リストを設定して」「オフィス／CDN をすべての環境で許可して」	references/allowlists.md
「Palo Alto／Fortinet／Cisco／F5／Sophos／pfSense／OPNsense を接続して」「ファイアウォール連携」「ベンダー形式で IP リストを取得して」「フィードをページネーションして」	references/integrations.md
「修復メトリクス」「CrowdSec はどれくらい節約／ブロックしたか」「ROI ダッシュボード」	references/metrics.md
「API 経由の組織レベルの判定」「集約された判定」	references/decisions.md

ステップ — curl チートシート

以下はすべて KEY が設定されていることを前提とします（運用契約を参照）。見やすくするための jq の使用は任意です。

目的	コマンド
自分の情報を確認／キーを検証	curl -s -H "x-api-key: $KEY" $B/info
ブロックリストを一覧表示	curl -s -H "x-api-key: $KEY" "$B/blocklists"
許可リストを一覧表示	curl -s -H "x-api-key: $KEY" "$B/allowlists"
連携を一覧表示	curl -s -H "x-api-key: $KEY" "$B/integrations"
判定を一覧表示／検索	curl -s -H "x-api-key: $KEY" "$B/decisions" · …?ips=1.2.3.4
修復メトリクス	curl -s -H "x-api-key: $KEY" "$B/metrics/remediation?start_date=$FROM&end_date=$TO"
ブロックリストに IP を追加 (変更を伴う操作 — 確認すること)	curl -s -H "x-api-key: $KEY" -H 'Content-Type: application/json' -X POST "$B/blocklists/$ID/ips" -d '{"ips":["1.2.3.4"]}'
判定を作成 (変更を伴う操作 — 確認すること)	curl -s -H "x-api-key: $KEY" -H 'Content-Type: application/json' -X POST "$B/decisions" -d '{"duration":"4h","origin":"cscli","scenario":"manual","scope":"Ip","type":"ban","value":"1.2.3.4","target":{"type":"org","value":"<org>"}}'

ここで B=https://admin.api.crowdsec.net/v1 です。

絶対にしてはいけないこと

• URL と本文を表示して承認を得る前に、変更を伴うリクエストを送信しないでください （運用契約 §3–4 を参照）。
• ユーザーが「IP をいくつか追加したい」と言っている場合に …/ips/bulk_overwrite を使用しないでください。その場合は …/ips を使います。bulk_overwrite は最初にリストを消去します。
• API キーを ~/.config/crowdsec/sapi_key 以外の場所に表示、ログ記録、保存しないでください。 キーはそこ、または環境変数からのみ取得してください。
• API 呼び出しが成功しただけで、クラウドの許可リスト／ブロックリストが適用されていると決めつけないでください。エンジンが登録され、リストを購読している必要があり、ポーリングサイクルで取得されます（crowdsec スキルを使ってローカルで確認してください）。

ドキュメント

正式なドキュメント：https://docs.crowdsec.net/u/console/service_api/getting_started。各 references/ ファイルには、参照元の特定のアップストリームページと、そのページに基づくライブ OpenAPI オペレーションが記載されています。