Apache Caldera 常用 CLI 命令与工具详解

Apache Caldera 5.3.0 常用 CLI 命令与工具详解：server.py 启动参数速查、服务启停与日志命令、REST API curl 调用、插件工具用法，参数标注真实默认值，回显均实测。

Apache CalderaCaldera2026/10/14

Apache Caldera 常用 CLI 命令与工具详解

目标：详解 Apache Caldera 5.3.0 的命令行启动参数与常用配套工具（REST API、插件工具），整理成速查表并标注真实默认值。所有 --help 输出与命令回显均在 Ubuntu 22.04 + Caldera 5.3.0 服务器实测采集（CentOS 8 回显一致）。

一、环境信息

项目值
操作系统Ubuntu 22.04.5 LTS / CentOS 8.4.2105
Caldera 版本5.3.0
部署目录/opt/caldera
启动脚本/opt/caldera/server.py
Web/API 端口8888
API 密钥ADMIN123（默认 api_key_red）

二、工具概览

Caldera 的命令行/工具面主要由四部分组成：

工具位置/形式用途
server.py 启动脚本/opt/caldera/server.py服务启动参数（-E/-l/--fresh/-P/--insecure/--uidev/--build）
REST API/api/v2/*、/api/rest（curl 调用）服务管理、数据查询、配置热更新
插件工具/plugin/<名>/gui（Web 端）+ 各插件自带脚本sandcat（agent）、manx（终端）、stockpile（能力库）等
运维命令ps/ss/kill/systemctl进程与端口管理

💡 说明：Caldera 无独立 CLI 二进制（不同于 mysqld 类守护进程），「命令行」即 python3 server.py 的启动参数 + 对 REST API 的 curl 调用组合。

三、前置条件

  • 已按安装指南完成部署（源码 /opt/caldera、Python 依赖、Node.js 16+）；
  • 需在 /opt/caldera 目录下执行 server.py（内部依赖相对路径）；
  • Python 解释器：Ubuntu 用 python3，CentOS 8 用 python3.9。

四、server.py 启动命令详解

4.1 帮助输出（--help，实测原样）

cd /opt/caldera
python3 server.py --help

回显（实测原样）：

usage: server.py [-h] [-E ENVIRONMENT]
                 [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--fresh]
                 [-P PLUGINS] [--insecure] [--uidev UIDEVHOST] [--build]


 ██████╗ █████╗ ██╗     ██████╗ ███████╗██████╗  █████╗
██╔════╝██╔══██╗██║     ██╔══██╗██╔════╝██╔══██╗██╔══██╗
██║     ███████║██║     ██║  ██║█████╗  ██████╔╝███████║
██║     ██╔══██║██║     ██║  ██║██╔══╝  ██╔══██╗██╔══██║
╚██████╗██║  ██║███████╗██████╔╝███████╗██║  ██║██║  ██║
 ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝  ╚═╝


optional arguments:
  -h, --help            show this help message and exit
  -E ENVIRONMENT, --environment ENVIRONMENT
                        Select an env. file to use
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level
  --fresh               remove object_store on start
  -P PLUGINS, --plugins PLUGINS
                        Start up with a single plugin
  --insecure            Start caldera with insecure default config values.
                        Equivalent to "-E default".
  --uidev UIDEVHOST     Start VueJS dev server for front-end alongside the
                        caldera server. Provide hostname, i.e. localhost.
  --build               Build the VueJS front-end to serve it from the caldera
                        server.

4.2 参数速查表

参数默认值作用
-h, --help—打印帮助并退出
-E ENVIRONMENT无（默认加载 conf/default.yml）选择要加载的环境配置文件（如 -E staging 读取 conf/staging.yml）
-l, --logINFO日志级别，可选 DEBUG/INFO/WARNING/ERROR/CRITICAL
--fresh关闭启动时清空 object_store（数据对象存储），相当于重置运行时数据
-P PLUGINS加载配置中全部插件仅以单个插件启动（如 -P sandcat），用于隔离调试
--insecure关闭使用默认安全配置启动，等价 -E default
--uidev UIDEVHOST关闭并行启动 VueJS 前端开发服务器（参数为主机名，如 localhost），前端改动热更新
--build关闭构建 VueJS 前端（首次启动必须，构建产物供 WebUI 使用）

💡 说明：--insecure 与 -E default 等价——都会加载 conf/default.yml（含默认弱口令/弱密钥），仅适合初次部署验证；生产配置建议用 -E <自定义环境文件> 或直接改造 default.yml 后不带该参数启动。

4.3 典型启动组合（实测）

常规启动（前端已构建）：

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

首次启动（构建前端）：

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

启动日志（节选，--build 时会打印构建进度）：

INFO     Using main config from                server.py:228
         conf/default.yml
INFO     Building VueJS front-end.             server.py:265
…
INFO     VueJS front-end build complete.       server.py:268
INFO     Enabled plugin: fieldmanual           app_svc.py:131
…
INFO     Enabled plugin: magma                 app_svc.py:131
INFO     serving on 0.0.0.0:2222               server.py:741

调试启动（DEBUG 日志 + 只加载 sandcat 插件 + 清空对象存储）：

cd /opt/caldera
python3 server.py -l DEBUG -P sandcat --fresh

回显（节选，DEBUG 级别日志显著增多，并仅启用 sandcat 插件）：

DEBUG    … (详细初始化/加载日志)
INFO     Enabled plugin: sandcat               app_svc.py:131

⚠️ 注意：--fresh 会删除 data/object_store（运行时对象数据，含历史 operation/agent 记录），仅用于排障/重置，切勿在生产误用。

五、常用运维命令（实测）

查看进程与端口：

ps -ef | grep "[s]erver.py"
ss -ltnp | grep -E "8888|7010|7012"

回显（节选）：

root      5263   …   python3 server.py --insecure
LISTEN 0      128          0.0.0.0:8888      0.0.0.0:*    users:(("python3",pid=5263,fd=42))
LISTEN 0      100          0.0.0.0:7010      0.0.0.0:*    users:(("python3",pid=5263,fd=37))

优雅停止（按 8888 端口定位 PID 后 kill，避免误杀）：

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

确认停止：

ss -ltn | grep 8888 || echo "8888 closed"

回显：

8888 closed

查看启动日志：

tail -50 /tmp/caldera.log

回显（节选，含各插件启用与监听信息）：

INFO     Enabled plugin: stockpile             app_svc.py:131
INFO     Enabled plugin: sandcat               app_svc.py:131
…
INFO     Creating SSH listener on 0.0.0.0, …
INFO     serving on 0.0.0.0:2222               server.py:741

systemd 托管下的启停（需 systemd 真机，每行仅操作一个单元）：

systemctl start caldera.service
systemctl stop caldera.service
systemctl status caldera.service

⚠️ 说明：systemd 单元文件写法见《CentOS 8 安装 Apache Caldera 指南》/《Ubuntu 22.04 安装 Apache Caldera 指南》篇的「systemd 托管」节。

六、REST API 命令速查（curl 实测）

统一约定：-H "KEY: ADMIN123"（API 密钥认证）或登录后 -b /tmp/caldera_cookie.txt（会话认证）。

操作命令实测回显摘要
健康检查curl -s http://127.0.0.1:8888/api/v2/health -H "KEY: ADMIN123"{"application": "Caldera", "version": "5.3.0", …}
WebUI 登录curl -s -c /tmp/cookie.txt -X POST http://127.0.0.1:8888/enter -d "username=admin&password=q1w2e3r4"302，下发 API_SESSION Cookie
插件列表curl -s http://127.0.0.1:8888/api/plugins -H "KEY: ADMIN123"15 个插件 JSON
agent 列表curl -s http://127.0.0.1:8888/api/agents -H "KEY: ADMIN123"[]（无 agent 时）
行动列表curl -s http://127.0.0.1:8888/api/operations -H "KEY: ADMIN123"[]（无行动时）
对手模型curl -s http://127.0.0.1:8888/api/v2/adversaries -H "KEY: ADMIN123"29 个 adversary JSON
创建行动（示例）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."]}}（schema 校验）
配置热更新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\"}"返回完整配置 JSON（ability_refresh 已更新）
legacy 查询curl -s -X POST http://127.0.0.1:8888/api/rest -H "KEY: ADMIN123" -H "Content-Type: application/json" -d "{\"index\":\"agents\"}"[]

💡 说明：KEY 头认证为无状态（每请求携带密钥），适合脚本/自动化集成；Cookie 认证为有状态（模拟浏览器会话），适合交互式工具。两者等价访问同一批资源。

七、插件工具详解（实测）

7.1 sandcat（默认 agent 插件）

sandcat 为 Go 编写的跨平台 agent，部署在目标主机回连 Caldera 服务器。管理入口：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8888/plugin/sandcat/gui -H "KEY: ADMIN123"

回显：

HTTP 302

说明：302 为重定向（未登录/需经 UI 引导），agent 的 payload 下载与部署入口在该插件页面完成；已注册 agent 统一在 GET /api/agents 查看。其 Go 系 agent 的动态编译依赖服务器安装 Go 1.19+（缺失时启动日志仅 WARNING，不影响框架）。

7.2 manx（终端访问插件）

manx 提供经 SSH 隧道（默认 0.0.0.0:8022）对 agent 的终端访问能力，账号 sandcat。启用验证：

ss -ltnp | grep 8022

回显：

LISTEN 0      100          0.0.0.0:8022      0.0.0.0:*    users:(("python3",pid=5263,fd=19))

7.3 stockpile（能力库插件）

stockpile 提供 adversaries/abilities/payloads/planners 数据，是 operation 编排的数据来源。数据量可通过 API 核实：

curl -s http://127.0.0.1:8888/api/v2/adversaries -H "KEY: ADMIN123" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"

回显：

29

💡 说明：29 个内置 adversary 主要来自 stockpile 插件；/plugin/stockpile/gui 直接访问在 v5 下返回 500（旧式 GUI 已由 magma 前端替代），属预期行为，请统一使用 WebUI 主界面（http://127.0.0.1:8888/）浏览能力库。

八、注意事项

  • 目录依赖：server.py 必须在 /opt/caldera 目录下执行，否则相对路径（conf/、data/、plugins/）解析失败。
  • 解释器差异：CentOS 8 需用 python3.9 运行（系统 python3 为 3.6 不满足要求）；Ubuntu 22.04 直接用 python3。
  • 端口冲突：8888/7010/7011/7012/8022/2222 被占用会导致对应服务启动失败，先 ss -ltn 排查。
  • --fresh 慎用：会清空 object_store 运行时数据。
  • 密钥安全：文中 ADMIN123/q1w2e3r4 均为默认演示值，生产务必修改（见《Apache Caldera 配置参数详解》篇）。

九、常见问题（FAQ）

Q1：执行 server.py 报找不到 conf/default.yml？

未在部署目录下执行。先 cd /opt/caldera 再运行；systemd 托管场景在单元文件 WorkingDirectory=/opt/caldera 已保证。

Q2：--build 构建前端很慢或失败？

首次构建需下载 npm 依赖（1–2 分钟属正常）。失败常见原因：npm 未安装（Ubuntu 官方源 nodejs 为 v12 需按 4.2 节装 18）；网络无法访问 npm 源。构建完成后产物在 plugins/magma/dist，后续启动无需再带 --build。

Q3：-P sandcat 启动后 WebUI 打不开？

-P 只加载单个插件（magma 前端不在其中），仅用于隔离调试后端模块；正常使用请去掉 -P 按配置加载全部插件。

Q4：如何查看各参数当前值？

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\"}"

PATCH 返回体即当前完整运行配置（敏感键已过滤）。

十、参考链接