crowdsec-service-api

CrowdSec Service API (SAPI) — 云端阻止列表 / 允许列表 / 集成自动化

SAPI 是 CrowdSec Console 背后的 高级 REST API。它管理 云端对象（私有阻止列表、允许列表、决策、防火墙集成）， 这些对象随后会下发到已注册的引擎和 bouncer。它不是本地 引擎 API —— 这里没有 cscli，只有 HTTPS。

• Base 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

边界 —— 本 skill 与 crowdsec skill

你想要…	使用
在云端创建/管理私有阻止列表，通过 API 向其推送 IP	本 skill
将防火墙/设备（Palo Alto、Fortinet…）接入云集成	本 skill
管理云允许列表，将引擎/标签/组织订阅到列表	本 skill
创建/管理组织级决策（定向或临时封禁、非 IP 范围、按标签/实体）	本 skill
拉取修复 ROI 指标	本 skill
安装 / 运行 / 调试本地引擎、cscli、bouncer、WAF	crowdsec skill
将引擎注册到 Console（cscli console enroll）	crowdsec skill → references/install/console.md
在单个引擎上配置本地允许列表/白名单	crowdsec skill → references/configure/allowlists.md

这里的云允许列表/阻止列表只有在引擎已注册并且订阅了该列表后， 才会在该引擎上生效。注册部分位于 crowdsec skill 中。

操作契约

这里的每次调用都会触达生产环境，并可能改变已订阅引擎所执行的内容。

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 — 操作前先验证 —— 一次读取调用即可确认密钥，并显示即将变更哪个 租户：

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

3 — 区分读取与变更。 GET / download / POST …/search 是安全的 —— 直接运行它们。每个会改变状态的 POST / PATCH / DELETE 都需要先获得明确确认：展示确切的 URL 和 JSON 请求体， 然后等待确认。

4 — 额外危险的操作 —— 在确认之前用直白的话说明后果， 因为已订阅的引擎会执行这些列表，所以 一次变更可能阻止或放行真实流量，且很难撤销：

操作	危险原因
POST …/ips/bulk_overwrite	替换整个阻止列表内容。
DELETE /blocklists/{id} · /allowlists/{id} · /integrations/{id}	删除该对象以及所有人的订阅/feed。
POST …/ips/delete	在全舰队范围内解除对 IP 的阻止。
POST /decisions 且 target.type: org	在组织内所有已注册引擎上全舰队封禁。
…/shares / unshare	授予/撤销另一个组织的访问权限。
任何 …/subscribers 变更	改变哪些引擎/bouncer 执行该列表。

5 — 清理任何仅为测试配方而创建的对象。任何在传输过程中 暴露过的密钥都必须轮换。

步骤 — 识别意图

用户线索	前往
"test my key"、"what org / plan am I on"	references/authentication.md
"create a blocklist"、"push IPs from my SIEM/SOAR"、"expire IPs"、"share a blocklist with another org"、"subscribe my engine to a list"	references/blocklists.md
"cloud allowlist via API"、"allow my office/CDN across the fleet"	references/allowlists.md
"connect Palo Alto / Fortinet / Cisco / F5 / Sophos / pfSense / OPNsense"、"firewall integration"、"pull IP list in vendor format"、"paginate the feed"	references/integrations.md
"remediation metrics"、"how much did CrowdSec save / block"、"ROI dashboard"	references/metrics.md
"org-level decisions via API"、"aggregated decisions"	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 操作。