配置文件
了解如何通过配置文件进行自定义设置
SIREN 客户端与服务端启动时都会读取 YAML 配置文件。找不到配置文件时会直接退出,因此建议把客户端配置保存为 config.yaml,服务端配置保存为 server_config.yaml。
查找顺序
启动时,SIREN 会按以下顺序查找配置文件(找到即停止):
-c/--config指定的路径- 当前工作目录下的
config.yaml(客户端)或server_config.yaml(服务端) - 当前工作目录的
config/子目录
部分命令行参数会覆盖对应配置项。客户端远程模式可用 siren client -s/-p 指定服务端地址和端口;服务端可用 siren_server -l/-p --cert --key --webui-dossier-dir --webui-projects-base-dir 覆盖常用启动项。
敏感信息
不要把 AccessKey、API Key 等敏感凭证写入配置文件。OSS 与 SOAR 凭证均通过环境变量读取,详见凭证设置。
客户端配置
server: 127.0.0.1 # 服务端地址
port: 443 # 服务端端口
recon:
commandTimeout: 30 # Recon 单个 source 命令执行超时时间
collectionTimeout: 270 # 整个 Profile 的客户端采集预算
defaultProfile: default # 省略 --profile 时使用
profiles:
default: [user, ssh, process, network, cron, service, env, file, rootkit, application]
quick: [user, ssh, process, network, cron, service, env, rootkit, application]
hunt: [user, ssh, process, network, cron, service, env, application, topology, supplychain, config, activity, credential]
oss:
region: cn-hongkong # OSS Bucket Region
bucketName: ir-transfer-station # OSS Bucket 名称
objectPath: tmp/siren_upload # 本地 upload 文件上传路径
docObjectPath: tmp/siren_upload/docs/latest # 本地 Recon artifacts 上传路径前缀
plugins:
marketplace: https://example.com/plugins # 插件市场地址
collector: true # 所有类型插件统一开关配置项说明
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
server | string | 127.0.0.1 | 远程模式下连接的服务端地址 |
port | int | 443 | 远程模式下连接的服务端端口 |
recon.commandTimeout | int | 30 | Recon 单个 source 命令和客户端远程命令执行的基础超时时间(秒);MCP / AIR 慢命令建议服务端也设置相同值 |
recon.collectionTimeout | int | 270 | 客户端完成整个 Recon Profile 的总预算(秒);远程 v2 请求会取该值与服务端下发预算中的较小值 |
recon.defaultProfile | string | default | 本地命令未传 --profile 或远程入口未指定 Profile 时使用的名称 |
recon.profiles.<name> | list | 见示例 | 命名的模块集合;只选择采集模块,不覆盖超时、资源上限或分析逻辑。default 为标准完整采集,quick 只移除 file,hunt 额外采集应用拓扑、运行载荷供应链、配置、近期应用活动和凭据证据 |
oss.region | string | - | OSS Bucket 所在地域 |
oss.bucketName | string | - | OSS Bucket 名称 |
oss.objectPath | string | tmp/siren_upload | 本地 siren upload 的 OSS 路径前缀 |
oss.docObjectPath | string | tmp/siren_upload/docs/latest | 本地 siren recon 的 JSONL 与 Markdown 上传路径前缀 |
plugins.marketplace | string | - | 插件市场 URL,用于下载和更新插件 |
plugins.<name> | bool | - | 启用或禁用插件,command 与 recon 类型统一使用该开关 |
Profile 名必须匹配 ^[a-z][a-z0-9_-]{0,63}$。每个 Profile 包含 1 到 64 个不重复模块;未知模块会使配置加载失败。Basic 始终执行,不写入列表。recon 插件以 plugin:<name> 引用,例如 custom: [user, process, plugin:collector];插件缺失或被 plugins.<name> 禁用时,采集开始前会失败。 |
没有 recon.profiles 的旧配置会把已启用的传统 recon.<module> 与旧式 recon 插件合成为唯一的 default,并记录迁移提示。topology、supplychain、config、activity 和 credential 属于 opt-in 采集,不会被旧配置或无配置 fallback 自动启用;Linux 与 Windows 的内置 hunt 会显式包含这些模块。Linux 的 rootkit 仍保留在 default、quick 和用户自定义 Profile 中,但不进入 hunt。新旧结构同时存在时,以 Profile 为准,旧键被忽略。旧配置中残留的 rules 不影响启动,但会记录一次已忽略提示;这些规则不再参与 Recon。无效的远程 reload 会保留当前配置与上一个有效 Profile 快照。客户端配置正在被 Recon 或其他操作使用时,重载会提示稍后重试。
服务端配置
listen: 0.0.0.0 # 客户端、WebUI 与 MCP 的 TLS 监听地址
port: 443 # 共享 TLS 监听端口
cert: certs/cert.pem # TLS 证书路径
key: certs/key.pem # TLS 密钥路径
logging:
level: info # debug / info / warning / error
format: text # text / json
output: stderr # stderr / stdout / none
bufferSize: 5000 # Logs 页面保留的日志条数,0 表示关闭
webui: # Web 控制台
enabled: true # 是否启用 WebUI
publicURL: https://siren.example.com # AIR 注入 MCP 时使用的 HTTPS Origin
userDBPath: data/users.db # 可选:WebUI 用户数据库路径
dossierDir: /opt/siren/dossier # 可选:Dossier 编辑器文件目录
projectsBaseDir: "" # 可选:Project 目录创建基准路径
recon:
responseTimeout: 300 # 所有远程 Recon 入口等待客户端的秒数
mcp:
enabled: true # 是否启用 MCP 服务
runOutputMode: auto # run 长结果默认返回 auto 预览;full 返回完整有界结果
cmdBlacklist: # MCP run 命令黑名单(正则表达式)
- '(?:^|[;|&\n]\s*)(?:sudo\s+)?rm(?:\s|$)'
- '(?:^|[;|&\n]\s*)(?:sudo\s+)?find(?:\s|$)[^;|&\n]*\s-delete(?:\s|$)'
- '(?:^|[;|&\n]\s*)(?:sudo\s+)?dd(?:\s|$)[^;|&\n]*\bof=/dev/(?:sd|hd|vd|xvd|nvme|mapper|dm-|loop|md|ram)'
- '(?:^|[;|&\n]\s*)(?:sudo\s+)?systemctl\s+(stop|disable|mask|restart|reload)(?:\s|$)'
- '(?:^|[;|&\n]\s*)(?:sudo\s+)?(?:useradd|usermod|userdel|groupadd|groupmod|groupdel)(?:\s|$)'
# ...more destructive-action patterns
air:
# WebUI AIR 的默认 Provider;也可逐会话在页面上选择
provider: codex # codex / claude / qoder / pi
maxSessions: 20 # GUI 与 Terminal 合计最大并发数;<=0 表示不限制
replayBufferBytes: 4194304 # 每个会话的断线回放上限(字节)
prompt: 启动安全应急响应,UID:%s,... # 告警事件模式的 prompt 模板
customPromptPrefix: 在 SIREN Client %d 上... # 自定义 prompt 模式的前缀
# providers.<name> 用于 WebUI AIR 和 Manual 裸终端;服务端 REPL air 固定使用 Claude
providers:
claude:
cliPath: claude # Claude Code CLI 路径
args: [] # 额外 Claude CLI 参数
codex:
cliPath: codex # Codex CLI 路径
args: [--no-alt-screen] # 保留浏览器终端滚动历史
qoder:
cliPath: qodercli # QoderCLI 路径
args: [] # 额外 QoderCLI 参数
pi:
cliPath: pi # 全局 Pi CLI 路径
args: [] # 额外 Pi CLI 参数
agentDir: /root/.pi/agent # 全局 Pi 配置与插件目录
contextModeDir: /root/.pi/context-mode # 长上下文存储目录
memoryDir: /root/.pi/agent/memory # 长期记忆目录配置项说明
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
listen | string | 0.0.0.0 | 客户端、WebUI、WebSocket 与 MCP 共用的 TLS 监听地址 |
port | int | 443 | 共享 TLS 监听端口 |
cert | string | certs/cert.pem | TLS 证书文件路径;浏览器访问的域名必须包含在证书中 |
key | string | certs/key.pem | TLS 私钥文件路径 |
logging.level | string | info | 最低日志级别,可选 debug、info、warning 或 error;success 与 info 使用同一级别 |
logging.format | string | text | 日志格式,可选适合终端阅读的 text 或每行一个对象的 json |
logging.output | string | stderr | 服务端运行日志输出流,可选 stderr、stdout 或 none(不输出到终端,仅保留 Logs 页面缓冲) |
logging.bufferSize | int | 5000 | Web 控制台 Logs 页面在内存中保留的最近日志条数;服务重启后清空,设为 0 或负数则关闭该页面 |
webui.enabled | bool | true | 是否启用 Web 控制台。关闭后若 mcp.enabled 仍为 true,/mcp 会继续在共享端口上提供服务 |
webui.publicURL | string | "" | WebUI AIR 注入 MCP 时使用的绝对 HTTPS Origin,不得包含路径、query 或凭证;使用 AIR 时必须设置。服务端本机应将该域名解析到本机的非 loopback 内网地址,不能指向 127.0.0.1 或 ::1 |
webui.userDBPath | string | data/users.db | WebUI 用户 SQLite 数据库路径(相对路径基于启动 CWD) |
webui.dossierDir | string | -(示例配置为 /opt/siren/dossier) | Dossier 编辑器文件目录,可位于服务端工作目录外;左侧 Dossier 入口以只读模板方式打开该目录下的 report.md,实际报告需从 Artifacts 进入后保存。目录留空、不可用或默认报告不可访问时,WebUI 会提示错误。详见 Dossier 配置 |
webui.projectsBaseDir | string | ""(服务端当前工作目录) | WebUI Project 目录创建基准路径。创建 Project 时只允许在该目录下创建一个 basename 子目录;Project 重命名不会移动目录,删除 Project 只删除元数据并保留目录文件 |
recon.responseTimeout | int | 300 | REPL、WebUI 和 MCP 等远程 Recon 入口等待客户端结果的最长时间(秒);旧 mcp.reconTimeout 仍作为兼容回退 |
mcp.enabled | bool | true | 是否启用 MCP 服务,独立于 webui.enabled |
mcp.runOutputMode | string | auto | MCP run 默认输出模式:auto 对超过 8 KiB 的结果返回可恢复首尾预览,full 返回客户端 50 KiB 上限内的完整结果;单次调用可用 output_mode 覆盖 |
mcp.cmdBlacklist | list | 见 MCP 集成 | MCP run 工具的命令黑名单,值为正则表达式列表 |
air.provider | string | codex | WebUI AIR 默认 Provider,可选 codex、claude、qoder 或 pi;页面中也可在每次启动会话时选择。服务端 REPL 的 air 命令固定使用 Claude Provider 配置 |
air.maxSessions | int | 20 | WebUI GUI 与 Terminal 合计最大并发会话数;适用于 Manual、Custom、Event 和 Resume,设为 0 或负数表示不限制 |
air.replayBufferBytes | int | 4194304 | 每个会话用于断线重连的回放预算;Terminal 按原始输出字节、GUI 按序列化事件字节计算,设为 0 或负数时使用默认的 4 MiB |
air.prompt | string | 见示例配置 | 告警事件模式下的 prompt 模板,依次填入 %s UID、%s 安全中心告警 ID、%d Client ID(告警 ID 即 air 命令的 Security Center Alert ID,详见 Agentic 应急响应) |
air.customPromptPrefix | string | 见示例配置 | 自定义 prompt 模式下的前缀(支持 %d Client ID) |
air.providers.claude.cliPath | string | claude | WebUI Claude Provider 和服务端 REPL air 命令使用的 Claude Code CLI 路径 |
air.providers.claude.args | list | [] | 传递给 Claude CLI 的额外参数 |
air.providers.codex.cliPath | string | codex | WebUI Codex Provider 使用的 Codex CLI 路径 |
air.providers.codex.args | list | [--no-alt-screen] | 传递给 Codex CLI 的额外参数;默认使用 inline TUI 保留浏览器终端滚动历史,自定义时可移除该参数恢复 Codex 的 alternate screen 行为 |
air.providers.qoder.cliPath | string | qodercli | WebUI Qoder Provider 使用的 QoderCLI 路径 |
air.providers.qoder.args | list | [] | 传递给 QoderCLI 的额外参数 |
air.providers.pi.cliPath | string | pi | WebUI Pi Provider 使用的全局 Pi CLI 路径 |
air.providers.pi.args | list | [] | 传递给 Pi CLI 的额外参数;SIREN 会覆盖冲突的 model、thinking、mode 和 session 参数 |
air.providers.pi.agentDir | string | /root/.pi/agent | Pi 的全局配置、插件、认证与 Skills 目录 |
air.providers.pi.contextModeDir | string | /root/.pi/context-mode | Pi 长上下文卸载与恢复目录 |
air.providers.pi.memoryDir | string | /root/.pi/agent/memory | Pi 跨会话长期记忆目录 |
日志输出
服务端日志默认写入标准错误流,普通命令输出仍可保留在标准输出流。text 格式包含完整日期和时间;json 格式每行输出一个独立对象,固定包含 time、level 和 message,有上下文时还会包含 fields:
{"time":"2026-07-21T14:30:00.123456+08:00","level":"info","message":"client connected","fields":{"client_id":7,"component":"client","event":"client.connected","project":"global"}}结构化运行事件使用稳定的 event 字段,常见关联字段包括 request_id、client_id、session_id 和 duration_ms。成功的常规 MCP 列表调用及工具启动过程属于 debug 诊断信息,默认 info 级别不会输出;工具完成、失败、超时和其他运行状态仍按相应级别记录。
日志不会记录 HTTP query、请求正文、Cookie、token、prompt、命令正文或凭证。Artifacts、Reports 和远程文件错误也不会写入用户提交的路径或文件名;需要关联 WebUI 故障时,可使用响应头 X-Request-ID 对应日志中的 request_id。
SIREN 不直接创建日志文件或执行轮转。需要持久化时,应由 systemd、容器运行时或其他进程管理器采集所选输出流并负责保留与轮转。
logging.bufferSize 额外在内存中保留最近若干条日志,供 Web 控制台 Logs 页面查看。保留的内容同样受 logging.level 约束,logging.output 设为 none 时也照常保留;缓冲区仅存在于内存中,服务重启后清空,不能替代上述持久化方案。
WebUI GUI 与 Terminal 都复用
air.providers.<name>。所有入口都会注入当前范围的 SIREN MCP:Project 使用/mcp/project/<id>,Global 使用/mcp。Manual 只启动空白 Provider 会话;Custom、Event、Resume 再按需加入种子 prompt 或恢复会话 ID。两种界面都受 WebUI 全局鉴权保护。
AIR 配置边界
AIR 的 Provider 配置只保留 Provider、prompt、CLI 路径和额外参数;会话并发与重连回放容量分别由 air.maxSessions 和 air.replayBufferBytes 控制。Claude Code、Codex 和 Qoder 的模型、权限、沙箱、普通 Shell 审批等行为由各自配置决定;GUI 仅展示 Provider 主动返回的审批,不写入用户级永久规则。Pi 复用全局 Pi 配置并固定使用 Qwen Aegis,文件、Shell、MCP 和子 agent 操作不产生权限审批。旧版 AIR 细分字段和独立的 agentTerminal.* 配置块已移除,残留时不会生效。
v1.x 升级提示
v2.0.0 合并了 MCP 与 WebUI 端口,顶层 mcpPort 字段与 --mcp-port 参数已移除。升级后的配置示例如上,mcpPort 如有残留不会报错但会被忽略。
MCP 认证环境变量
启用 mcp.enabled 前,必须通过受保护的服务环境配置 SIREN_MCP_ADMIN_TOKEN 和 SIREN_MCP_RAVEN_TOKEN,两者须非空且不同,不能写入 YAML 或项目文件。前者供运维客户端使用,后者仅用于 Raven 申请群项目凭证。未配置时服务端拒绝启动,不降级为匿名访问。AIR 自动注入当前会话凭证;外部客户端的 Header 和迁移步骤见 MCP 集成。