Apache Caldera 快速入门与集成示例

目标：面向第一次上手 Caldera 5.3.0 的开发/运维人员，给出「启动服务 → 登录 WebUI → 查询插件 → 调用 REST API → 模拟 agent/operation 集成」的完整可执行示例。所有命令与回显均在 Ubuntu 22.04 + Caldera 5.3.0 服务器上实测通过（CentOS 8 回显一致）。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS / CentOS 8.4.2105
Caldera 版本	5.3.0
部署目录	/opt/caldera
Web/API 地址	http://127.0.0.1:8888
管理账号	admin / q1w2e3r4（red 组，首次登录后请修改）
API 密钥	ADMIN123（HTTP 头 `KEY:`，生产请修改）

二、前置条件（依赖与构建工具）

完成 0→1 安装（源码在 /opt/caldera、Python 依赖已装、Node.js 16+ 可用），安装过程见《CentOS 8 安装 Apache Caldera 指南》或《Ubuntu 22.04 安装 Apache Caldera 指南》篇；
端口 8888 未被占用；
curl 可用（系统自带或 apt install curl / yum install curl）。

确认依赖版本：

python3 --version
node --version
npm --version

回显：

Python 3.10.12
v18.20.8
10.8.2

三、依赖引入与启动

Caldera 以 Python 源码 + VueJS 前端方式交付，无独立 SDK 包；「依赖引入」即安装 Python 依赖与前端依赖（前端由 --build 在首次启动时自动安装构建）：

cd /opt/caldera
python3 -m pip install -r requirements.txt

回显（节选）：

Successfully installed … aiohttp-3.10.11 … cryptography-44.0.1 … websockets-15.0 …

启动（首次带 --build 构建前端）：

nohup python3 server.py --insecure > /tmp/caldera.log 2>&1 &

回显（无输出，日志写入 /tmp/caldera.log；确认启动成功的验证命令见 5.1 节）。

💡 说明：--insecure 等价 -E default，使用 conf/default.yml 默认配置；生产环境建议去掉该参数并显式配置安全项（见《Apache Caldera 配置参数详解》篇）。

四、核心 API/配置

Caldera 提供两套 REST API，均支持两种认证方式：

API	基路径	说明
v2 REST API	/api/v2/…	当前主推，按资源分组（health/config/agents/operations/adversaries/plugins…）
legacy REST API	/api/rest（POST JSON）	旧版统一入口，body 携带 `index` 指定资源

认证方式（二选一）：

API 密钥头：-H "KEY: ADMIN123"（对应 default.yml 的 api_key_red）；
会话 Cookie：POST /enter 表单登录后携带 API_SESSION Cookie。

v2 API 常见端点速查：

端点	方法	作用
/api/v2/health	GET	健康检查（应用名/版本/权限/插件）
/api/v2/config/main	PATCH	热更新配置（body: {"prop","value"}）
/api/v2/agents	GET	查询已注册 agent
/api/v2/operations	GET/POST	查询/创建行动
/api/v2/adversaries	GET	查询对手模型
/api/plugins	GET	插件列表
/api/agents	GET	agent 列表（legacy）
/api/operations	GET	行动列表（legacy）

五、集成示例（可独立执行）

以下示例均从「服务已启动」状态开始，可直接逐条复制执行。

5.1 启动/停止服务

启动（前端已构建过，无需再带 --build）：

cd /opt/caldera
nohup python3 server.py --insecure > /tmp/caldera.log 2>&1 &

验证服务就绪（端口 + 页面）：

ss -ltnp | grep 8888
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8888/

回显：

LISTEN 0      128          0.0.0.0:8888      0.0.0.0:*    users:(("python3",pid=5263,fd=42))
HTTP 200

停止服务（按端口定位进程后优雅终止，再确认端口释放）：

kill $(ss -ltnp | grep ":8888 " | grep -oP "pid=\K[0-9]+" | head -1)
sleep 2
ss -ltn | grep 8888 || echo "8888 closed"

回显：

8888 closed

5.2 登录 WebUI

登录端点为 POST /enter，使用表单格式提交；成功返回 302 并下发 API_SESSION 会话 Cookie（凭该 Cookie 可直接访问受保护 API）：

curl -s -c /tmp/caldera_cookie.txt -X POST http://127.0.0.1:8888/enter -d "username=admin&password=q1w2e3r4" -o /dev/null -w "login HTTP %{http_code}\n"

回显：

login HTTP 302

确认 Cookie 已下发：

grep -c API_SESSION /tmp/caldera_cookie.txt

回显：

⚠️ 注意：登录必须用表单格式（-d "username=admin&password=q1w2e3r4"）；用 JSON 体提交不会下发 Cookie，表现为「302 但未登录」。

5.3 查看插件列表

curl -s http://127.0.0.1:8888/api/plugins -H "KEY: ADMIN123"

回显（节选）：

[{"name": "fieldmanual", "description": "Holds and serves Caldera documentation", "enabled": true, "address": "/plugin/fieldmanual/gui"}, {"name": "manx", "description": "A toolset which supports terminal access", "enabled": true, "address": "/plugin/manx/gui"}, {"name": "stockpile", "description": "A stockpile of abilities, adversaries, payloads and planners", "enabled": true, "address": "/plugin/stockpile/gui"}, …]

统计插件总数与名称：

curl -s http://127.0.0.1:8888/api/plugins -H "KEY: ADMIN123" | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d), [p['name'] for p in d])"

回显：

15 ['fieldmanual', 'manx', 'stockpile', 'sandcat', 'response', 'training', 'ssl', 'debrief', 'compass', 'atomic', 'emu', 'human', 'gameboard', 'access', 'magma']

💡 说明：magma 为 v5 的 VueJS 前端插件，sandcat 为默认 agent 插件，stockpile 为能力库（adversaries/abilities 来源），三者是刚上手最常用的插件。

5.4 模拟 agent/operation 集成调用

查询已注册 agent（新装环境为空数组）：

curl -s http://127.0.0.1:8888/api/agents -H "KEY: ADMIN123"

回显：

[]

查询行动（operation）列表：

curl -s http://127.0.0.1:8888/api/operations -H "KEY: ADMIN123"

回显：

[]

模拟创建 operation（展示 v2 schema 校验，缺必填字段会返回校验错误）：

curl -s -X POST http://127.0.0.1:8888/api/v2/operations -H "KEY: ADMIN123" -H "Content-Type: application/json" -d "{}"

回显：

{"json": {"name": ["Missing data for required field."]}}

说明：创建 action 至少需要 name（及可选的 adversary/agent 等字段）；校验信息即集成时的字段契约，可按提示补全。agent 一般不由 API 直接创建，而是由 sandcat 等 agent payload 在目标主机回连后自动注册。

查询对手模型（adversaries，供 operation 编排使用）：

curl -s http://127.0.0.1:8888/api/v2/adversaries -H "KEY: ADMIN123" | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d), [a['name'] for a in d[:5]])"

回显：

29 ['Advanced Thief', 'Advanced Thief via DropBox', 'Advanced Thief via FTP', 'Advanced Thief via GitHub Gist', 'Advanced Thief via GitHub Repo']

带会话 Cookie 调用受保护 API（legacy 入口）：

curl -s -b /tmp/caldera_cookie.txt -X POST http://127.0.0.1:8888/api/rest -H "Content-Type: application/json" -d "{\"index\":\"agents\"}"

回显：

[]

5.5 健康检查

curl -s http://127.0.0.1:8888/api/v2/health -H "KEY: ADMIN123"

回显（节选）：

{"application": "Caldera", "version": "5.3.0", "access": "RED", "plugins": [{"name": "access", "description": "A toolkit containing initial access throwing modules", "enabled": true, …}]}

💡 说明：access 字段标识当前密钥权限（RED=红队/管理员、BLUE=蓝队），version 可用于集成侧的版本探测与兼容性判断。

5.6 配置热更新

运行中修改参数（以 ability_refresh 为例，60→120 再还原）：

curl -s -X PATCH http://127.0.0.1:8888/api/v2/config/main -H "KEY: ADMIN123" -H "Content-Type: application/json" -d "{\"prop\":\"ability_refresh\",\"value\":\"120\"}"

回显（节选，ability_refresh 已变为 120）：

{"ability_refresh": "120", "app.contact.dns.domain": "mycaldera.caldera", …}

还原：

curl -s -X PATCH http://127.0.0.1:8888/api/v2/config/main -H "KEY: ADMIN123" -H "Content-Type: application/json" -d "{\"prop\":\"ability_refresh\",\"value\":\"60\"}"

回显（节选）：

{"ability_refresh": "60", "app.contact.dns.domain": "mycaldera.caldera", …}

⚠️ 注意：host、port、users、api_key_* 等敏感键不支持热更新，需改 conf/default.yml 后重启（详见《Apache Caldera 配置参数详解》篇）。

六、注意事项

安全基线：正式使用前必须修改默认口令（admin/q1w2e3r4 仅为演示）与 API 密钥 ADMIN123，替换 encryption_key/crypt_salt（方法见《Apache Caldera 配置参数详解》篇）；SSH/FTP 通讯通道的默认弱口令（s4ndc4t! / caldera）暴露公网前务必修改。
认证格式：登录接口只接受表单格式，API 调用接受 KEY 头或 API_SESSION Cookie；混淆二者是集成最常见的失败点。
端口规划：除 8888 外，agent 回连通道默认占用 7010/7011/7012/8022/2222/8853；集成时按需放行，不用的通道可在配置中关闭对应 app.contact.* 键。
agent 注册：agent 通过 payload 回连自动注册（GET /api/agents 查看），无需也不应由 API 手工创建。
前端构建：首次启动必须带 --build（或预先 npm install），否则 WebUI 无法加载；已有构建产物后启动可省略。

七、参考链接

官方文档：https://caldera.apache.org
REST API 文档（在线 Swagger，启动后访问）：http://127.0.0.1:8888/docs
源码仓库：https://github.com/apache/caldera
插件目录：https://github.com/apache/caldera/tree/5.3.0/plugins