SIREN

配置文件

了解如何通过配置文件进行自定义设置

SIREN 客户端与服务端启动时都会读取 YAML 配置文件。找不到配置文件时会直接退出,因此建议把客户端配置保存为 config.yaml,服务端配置保存为 server_config.yaml

查找顺序

启动时,SIREN 会按以下顺序查找配置文件(找到即停止):

  1. -c / --config 指定的路径
  2. 当前工作目录下的 config.yaml(客户端)或 server_config.yaml(服务端)
  3. 当前工作目录的 config/ 子目录

部分命令行参数会覆盖对应配置项。客户端远程模式可用 siren client -s/-p 指定服务端地址和端口;服务端可用 siren_server -l/-p --cert --key --webui-dossier-dir --webui-projects-base-dir 覆盖常用启动项。

敏感信息

不要把 AccessKey、API Key 等敏感凭证写入配置文件。OSS 与 SOAR 凭证均通过环境变量读取,详见凭证设置

客户端配置

config.yaml
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                           # 所有类型插件统一开关

配置项说明

配置项类型默认值说明
serverstring127.0.0.1远程模式下连接的服务端地址
portint443远程模式下连接的服务端端口
recon.commandTimeoutint30Recon 单个 source 命令和客户端远程命令执行的基础超时时间(秒);MCP / AIR 慢命令建议服务端也设置相同值
recon.collectionTimeoutint270客户端完成整个 Recon Profile 的总预算(秒);远程 v2 请求会取该值与服务端下发预算中的较小值
recon.defaultProfilestringdefault本地命令未传 --profile 或远程入口未指定 Profile 时使用的名称
recon.profiles.<name>list见示例命名的模块集合;只选择采集模块,不覆盖超时、资源上限或分析逻辑。default 为标准完整采集,quick 只移除 filehunt 额外采集应用拓扑、运行载荷供应链、配置、近期应用活动和凭据证据
oss.regionstring-OSS Bucket 所在地域
oss.bucketNamestring-OSS Bucket 名称
oss.objectPathstringtmp/siren_upload本地 siren upload 的 OSS 路径前缀
oss.docObjectPathstringtmp/siren_upload/docs/latest本地 siren recon 的 JSONL 与 Markdown 上传路径前缀
plugins.marketplacestring-插件市场 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,并记录迁移提示。topologysupplychainconfigactivitycredential 属于 opt-in 采集,不会被旧配置或无配置 fallback 自动启用;Linux 与 Windows 的内置 hunt 会显式包含这些模块。Linux 的 rootkit 仍保留在 defaultquick 和用户自定义 Profile 中,但不进入 hunt。新旧结构同时存在时,以 Profile 为准,旧键被忽略。旧配置中残留的 rules 不影响启动,但会记录一次已忽略提示;这些规则不再参与 Recon。无效的远程 reload 会保留当前配置与上一个有效 Profile 快照。客户端配置正在被 Recon 或其他操作使用时,重载会提示稍后重试。

服务端配置

server_config.yaml
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        # 长期记忆目录

配置项说明

配置项类型默认值说明
listenstring0.0.0.0客户端、WebUI、WebSocket 与 MCP 共用的 TLS 监听地址
portint443共享 TLS 监听端口
certstringcerts/cert.pemTLS 证书文件路径;浏览器访问的域名必须包含在证书中
keystringcerts/key.pemTLS 私钥文件路径
logging.levelstringinfo最低日志级别,可选 debuginfowarningerrorsuccessinfo 使用同一级别
logging.formatstringtext日志格式,可选适合终端阅读的 text 或每行一个对象的 json
logging.outputstringstderr服务端运行日志输出流,可选 stderrstdoutnone(不输出到终端,仅保留 Logs 页面缓冲)
logging.bufferSizeint5000Web 控制台 Logs 页面在内存中保留的最近日志条数;服务重启后清空,设为 0 或负数则关闭该页面
webui.enabledbooltrue是否启用 Web 控制台。关闭后若 mcp.enabled 仍为 true/mcp 会继续在共享端口上提供服务
webui.publicURLstring""WebUI AIR 注入 MCP 时使用的绝对 HTTPS Origin,不得包含路径、query 或凭证;使用 AIR 时必须设置。服务端本机应将该域名解析到本机的非 loopback 内网地址,不能指向 127.0.0.1::1
webui.userDBPathstringdata/users.dbWebUI 用户 SQLite 数据库路径(相对路径基于启动 CWD)
webui.dossierDirstring-(示例配置为 /opt/siren/dossierDossier 编辑器文件目录,可位于服务端工作目录外;左侧 Dossier 入口以只读模板方式打开该目录下的 report.md,实际报告需从 Artifacts 进入后保存。目录留空、不可用或默认报告不可访问时,WebUI 会提示错误。详见 Dossier 配置
webui.projectsBaseDirstring""(服务端当前工作目录)WebUI Project 目录创建基准路径。创建 Project 时只允许在该目录下创建一个 basename 子目录;Project 重命名不会移动目录,删除 Project 只删除元数据并保留目录文件
recon.responseTimeoutint300REPL、WebUI 和 MCP 等远程 Recon 入口等待客户端结果的最长时间(秒);旧 mcp.reconTimeout 仍作为兼容回退
mcp.enabledbooltrue是否启用 MCP 服务,独立于 webui.enabled
mcp.runOutputModestringautoMCP run 默认输出模式:auto 对超过 8 KiB 的结果返回可恢复首尾预览,full 返回客户端 50 KiB 上限内的完整结果;单次调用可用 output_mode 覆盖
mcp.cmdBlacklistlistMCP 集成MCP run 工具的命令黑名单,值为正则表达式列表
air.providerstringcodexWebUI AIR 默认 Provider,可选 codexclaudeqoderpi;页面中也可在每次启动会话时选择。服务端 REPL 的 air 命令固定使用 Claude Provider 配置
air.maxSessionsint20WebUI GUI 与 Terminal 合计最大并发会话数;适用于 Manual、Custom、Event 和 Resume,设为 0 或负数表示不限制
air.replayBufferBytesint4194304每个会话用于断线重连的回放预算;Terminal 按原始输出字节、GUI 按序列化事件字节计算,设为 0 或负数时使用默认的 4 MiB
air.promptstring见示例配置告警事件模式下的 prompt 模板,依次填入 %s UID、%s 安全中心告警 ID、%d Client ID(告警 ID 即 air 命令的 Security Center Alert ID,详见 Agentic 应急响应
air.customPromptPrefixstring见示例配置自定义 prompt 模式下的前缀(支持 %d Client ID)
air.providers.claude.cliPathstringclaudeWebUI Claude Provider 和服务端 REPL air 命令使用的 Claude Code CLI 路径
air.providers.claude.argslist[]传递给 Claude CLI 的额外参数
air.providers.codex.cliPathstringcodexWebUI Codex Provider 使用的 Codex CLI 路径
air.providers.codex.argslist[--no-alt-screen]传递给 Codex CLI 的额外参数;默认使用 inline TUI 保留浏览器终端滚动历史,自定义时可移除该参数恢复 Codex 的 alternate screen 行为
air.providers.qoder.cliPathstringqodercliWebUI Qoder Provider 使用的 QoderCLI 路径
air.providers.qoder.argslist[]传递给 QoderCLI 的额外参数
air.providers.pi.cliPathstringpiWebUI Pi Provider 使用的全局 Pi CLI 路径
air.providers.pi.argslist[]传递给 Pi CLI 的额外参数;SIREN 会覆盖冲突的 model、thinking、mode 和 session 参数
air.providers.pi.agentDirstring/root/.pi/agentPi 的全局配置、插件、认证与 Skills 目录
air.providers.pi.contextModeDirstring/root/.pi/context-modePi 长上下文卸载与恢复目录
air.providers.pi.memoryDirstring/root/.pi/agent/memoryPi 跨会话长期记忆目录

日志输出

服务端日志默认写入标准错误流,普通命令输出仍可保留在标准输出流。text 格式包含完整日期和时间;json 格式每行输出一个独立对象,固定包含 timelevelmessage,有上下文时还会包含 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_idclient_idsession_idduration_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.maxSessionsair.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_TOKENSIREN_MCP_RAVEN_TOKEN,两者须非空且不同,不能写入 YAML 或项目文件。前者供运维客户端使用,后者仅用于 Raven 申请群项目凭证。未配置时服务端拒绝启动,不降级为匿名访问。AIR 自动注入当前会话凭证;外部客户端的 Header 和迁移步骤见 MCP 集成

On this page