Apache Caldera 配置参数详解

目标：详解 Apache Caldera 5.3.0 配置文件 conf/default.yml 的全部参数，覆盖服务监听、安全认证、插件、Agent 通讯通道、运行行为与依赖要求六大类，给出真实默认值、改法与 REST API 热更新实测回显。本文在 Ubuntu 22.04 + Caldera 5.3.0 环境实测，参数文件结构在 CentOS 8 上完全一致。

一、环境信息

二、前置条件

• 已按《CentOS 8 安装 Apache Caldera 指南》或《Ubuntu 22.04 安装 Apache Caldera 指南》完成 0→1 部署（Python 3.9+/3.10、Node.js 16+/18、源码在 /opt/caldera）；
• 服务已启动（python3 server.py --insecure），8888 端口可访问；
• 具备 red 组账号或 API 密钥（默认 KEY: ADMIN123）以调用配置 API。

三、参数查看与修改方式

Caldera 提供三种配置读写途径，本环节全部实测。

3.1 直接编辑 conf/default.yml

配置为 YAML 格式，服务启动时加载。修改后需重启服务生效：

grep -cE "^[a-z_]" /opt/caldera/conf/default.yml
sed -i "s|^port: 8888$|port: 8888|" /opt/caldera/conf/default.yml

说明：grep 计数可快速确认文件可读；sed 为编辑示范（保持默认值不变）。实际改值示例（把 Web 端口改为 9999）：

sed -i "s|^port: 8888$|port: 9999|" /opt/caldera/conf/default.yml
grep "^port:" /opt/caldera/conf/default.yml

回显：

port: 9999

改回 8888 并重启：

sed -i "s|^port: 9999$|port: 8888|" /opt/caldera/conf/default.yml

💡 说明：-E <文件名> 启动参数可加载其他环境文件（如 -E staging 读取 conf/staging.yml），--insecure 等价 -E default。多环境（开发/预发/生产）可用不同文件管理差异配置。

3.2 REST API 热更新（运行中生效）

Caldera 提供 v2 配置 API，无需重启即可修改部分运行参数。实测将 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\"}"

回显（节选，返回完整配置，可见已生效为 120）：

{"ability_refresh": "120", "app.contact.dns.domain": "mycaldera.caldera", "app.contact.dns.socket": "0.0.0.0:8853", "app.contact.gist": "API_KEY", "app.contact.html": "/weather", …}

还原：

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", …}

⚠️ 注意：以下敏感键被 API 侧白名单过滤，不允许通过 PATCH 修改，只能在配置文件中改：api_key_blue、api_key_red、auth.login.handler.module、crypt_salt、encryption_key、host、port、requirements、users。实测 GET 单个敏感键返回错误：

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

回显：

{"error": "Config not found: port"}

非敏感键可 GET 读取（如 agents 相关配置段）：

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

回显（节选）：

{"sleep_min": 30, "sleep_max": 60, "watchdog": 0, "deadman_abort": 0, "proxy_chain": [], "originator": false, "c2": {"HTTP": {"c2_key": "ADMIN123", "proxy": "", "user_agent": "Mozilla/5.0 …", "interval": 30}}, …}

四、参数总览

conf/default.yml 全文参数与默认值一览（实测 5.3.0 原样）：

解读：上表为全部顶层/二层参数。其中 app.contact.* 一组是 Caldera 的特色——同一 agent 可支持多种回连通道，参数即各通道的监听端点与凭据。

五、核心参数分类详解

5.1 服务监听（host、port）

• host：HTTP 服务监听地址，默认 0.0.0.0（全接口）。改 127.0.0.1 仅本机可访问 WebUI/API。
• port：HTTP 服务端口，默认 8888。

改法（改后需重启）：

sed -i "s|^port: 8888$|port: 8888|" /opt/caldera/conf/default.yml

⚠️ 注意：host/port 属 API 敏感键，无法热更新；修改后 systemctl restart caldera.service 或重启进程生效。改端口后 app.contact.http 中的地址也需同步调整（agent 通过该地址回连）。

5.2 安全与认证（api_key、users、encryption、crypt_salt）

• api_key_red / api_key_blue：红队/蓝队 API 密钥，调用 REST API 时通过 HTTP 头 KEY: <值> 认证。默认 ADMIN123 / BLUEADMIN123，生产必须修改。
• encryption_key：数据加密密钥，默认 ADMIN123，生产必须修改。
• crypt_salt：加密盐，默认占位符 REPLACE_WITH_RANDOM_VALUE，生产必须替换为随机字符串（可用 openssl rand -base64 32 生成）。
• users：本地账号表，按组（red 红队 / blue 蓝队）组织：

users:
  blue:
    blue: admin
  red:
    admin: q1w2e3r4
    red: admin

上面为实测修改后的形态（red 组 admin 口令已改为 q1w2e3r4）。新增用户直接在对应组下加一行 用户名: 口令 即可，重启后生效。

• auth.login.handler.module：登录处理器模块，默认 default（本地账号校验）。可替换为自定义/LDAP 处理器（配合 ldap 配置段），属敏感键、仅文件可改。

5.3 插件管理（plugins）

plugins 列表控制启动时加载的插件，默认（实测 15 个启用）：

plugins:
- access
- atomic
- compass
- debrief
- fieldmanual
- manx
- response
- sandcat
- stockpile
- training

💡 技术拓展：Caldera 插件是独立子仓库（git submodule），按用途分类——

插件	用途
sandcat	Go 版跨平台 agent（默认回连器）
stockpile	能力库（abilities/adversaries/payloads/planners）
manx	终端访问（SSH 隧道）
access	初始访问模块集
atomic	原子测试（对标 MITRE ATT&CK）
compass	攻击图可视化
debrief	行动报告导出
fieldmanual	内置文档站点
training	训练/学习材料
magma	v5 VueJS 前端（UI 本体）

本文默认启用官方预置的 15 个插件（上表外还有 emu、gameboard、human、ssl）；取消某插件只需从列表移除对应行。

新增插件时需先拉取子模块并加入列表：

cd /opt/caldera
git submodule update --init --recursive
sed -i "s|^  - magma$|  - magma\n  - emu|" /opt/caldera/conf/default.yml

💡 说明：-P <插件名> 启动参数可临时只加载单个插件（见《Apache Caldera 常用 CLI 命令与工具详解》篇）。

5.4 Agent 通讯通道（app.contact.*）

Caldera 的 agent 通过多种 C2（命令与控制）通道回连，各通道独立监听：

⚠️ 注意：ssh/ftp 的用户口令为默认弱口令，暴露公网前务必修改；Gist/Slack 中转需先配置有效第三方凭据，否则对应通道不启动（启动日志会打印 Invalid Github Gist personal API token provided. Gist C2 contact will not be started.）。

5.5 运行行为（ability_refresh、exfil_dir、reports_dir、planners）

• ability_refresh：能力（abilities）刷新周期，单位秒，默认 60。调大减少磁盘/内存扫描开销，调小加快新能力可见。
• exfil_dir：外传数据（exfiltrated data）落盘目录，默认 /tmp/caldera。生产建议改为持久化目录，如 /opt/caldera/data/exfil：

sed -i "s|^exfil_dir: /tmp/caldera$|exfil_dir: /opt/caldera/data/exfil|" /opt/caldera/conf/default.yml
mkdir -p /opt/caldera/data/exfil

• reports_dir：行动报告输出目录，默认 /tmp。
• objects.planners.default：默认 planner（行动编排器），默认 atomic。
• reachable_host_traits：判定 agent 可达的主机特征字段列表，默认 remote.host.fqdn、remote.host.ip。

5.6 依赖要求（requirements）

启动时校验运行环境的程序/模块最低版本：

requirements:
  go:
    command: go version
    type: installed_program
    version: 1.19
  python:
    attr: version
    module: sys
    type: python_module
    version: 3.9.0

• go：要求已安装 Go 1.19+（go version 校验），用于动态编译 Go 系 agent。缺失时仅打印 WARNING，框架仍可运行。
• python：要求 Python 3.9.0+（通过 sys.version 校验），不满足时拒绝启动。

六、生产配置模板

适用场景：16GB 内存、2+ CPU、面向受控红队演练的长期运行服务器。在 default.yml 基础上做如下收敛（改后重启）：

cd /opt/caldera
sed -i "s|^api_key_red: ADMIN123$|api_key_red: $(openssl rand -hex 16)|" conf/default.yml
sed -i "s|^api_key_blue: BLUEADMIN123$|api_key_blue: $(openssl rand -hex 16)|" conf/default.yml
sed -i "s|^encryption_key: ADMIN123$|encryption_key: $(openssl rand -hex 16)|" conf/default.yml
sed -i "s|^crypt_salt: REPLACE_WITH_RANDOM_VALUE$|crypt_salt: $(openssl rand -base64 32)|" conf/default.yml
sed -i "s|^exfil_dir: /tmp/caldera$|exfil_dir: /opt/caldera/data/exfil|" conf/default.yml

配置说明：

• API 密钥与加密密钥、加密盐均替换为随机值（openssl rand 生成），杜绝默认口令；
• exfil 数据落到持久化目录，避免 /tmp 清理丢失演练成果；
• 其余保持默认：8888 端口、15 个插件、app.contact 通讯通道（如需公网暴露，按 5.4 节改弱口令）；
• 用户账号按 5.2 节在 users 段维护，首次登录后修改为强口令。

⚠️ 注意：$(openssl rand …) 为命令替换，每次执行生成不同随机值；执行后请用 grep -E "^(api_key|encryption_key|crypt_salt)" conf/default.yml 核对替换结果，并妥善备份新密钥。

七、常见问题（FAQ）

Q1：改配置后不生效？

default.yml 在启动时加载，文件修改需重启服务：systemctl restart caldera.service（或重启进程）。部分参数可用 PATCH /api/v2/config/main 热更新（见 3.2 节），但 host/port/users/api_key 等敏感键必须改文件重启。

Q2：PATCH 配置报「Missing data for required field」？

请求体需包含 prop 与 value 两个字段（如 {"prop":"ability_refresh","value":"60"}）；同时目标键不能是 API 敏感键（见 3.2 节白名单）。

Q3：启动日志提示 Gist C2 未启动？

INFO     Invalid Github Gist personal API token provided. Gist C2 contact will not be started.

属预期行为：未配置有效的 GitHub 个人 API token（app.contact.gist），Gist 中转通道停用，不影响其他通道与核心功能。

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 返回体即当前完整运行配置（敏感键已过滤），可核对各键当前值。

八、参考链接

• 官方配置文档：https://caldera.apache.org
• 源码默认配置：https://github.com/apache/caldera/blob/5.3.0/conf/default.yml
• 配置 API 源码（敏感键白名单）：https://github.com/apache/caldera/blob/5.3.0/app/api/v2/managers/config_api_manager.py