3.7 Flocks 安全管控设计说明

本文用于说明 Flocks 在产品设计、运行执行、外部交互与部署运维层面的安全管控能力，便于面向客户解释“Flocks 自身如何降低暴露面、如何约束 Agent 行为、如何审计和隔离数据”。本文基于当前产品代码与默认配置梳理，企业版能力以实际授权版本为准。

3.7.1 安全设计目标

Flocks 是一个 AI-Native SecOps 多 Agent 平台，本身具备连接大模型、调用工具、执行命令、接入安全设备/API、运行工作流和对接 IM 渠道的能力。因此安全设计重点不是只做单点登录，而是围绕以下目标进行分层控制：

• 减少暴露面：默认本机监听，远程访问需显式开启，并建议通过防火墙、Nginx/反向代理控制访问来源。
• 身份可信：浏览器端走账号登录和安全 Cookie，非浏览器客户端必须携带 API Token，不把 localhost 当作可信边界。
• 能力最小化：Agent 通过工具白名单获得能力，工具本身可注册、启用、禁用、卸载，API/设备工具还受服务开关约束。
• 执行可审批：命令执行、文件写入、外部目录访问等敏感操作进入权限审批流，可单次、会话级或永久授权/拒绝。
• 运行可隔离：支持 Docker 部署，也支持 Agent/工作流执行放入 Docker sandbox，限制网络、文件系统、进程与资源使用。
• 数据可隔离：多账号下会话按 owner 隔离，私有会话默认只对所有者可见。
• 过程可审计：企业版可注册审计 sink，对登录、会话、工作流等关键事件进行审计查询。

3.7.2 Flocks 与外界的交互

HTTP 与 WebUI 访问

Flocks WebUI 与 API 共用同一个服务地址和端口，默认绑定 127.0.0.1:5173，避免安装后直接暴露到全网。需要远程访问时，必须通过启动参数显式配置：

flocks start --host <ip>

推荐部署方式是：

• 单机/个人使用：保持默认 127.0.0.1，只允许本机浏览器访问。
• 局域网或服务器部署：仅绑定指定内网 IP，结合主机防火墙限制来源 IP。
• 企业生产部署：通过 Nginx/网关暴露统一服务入口，WebUI 与同源 /api 一起转发。

浏览器默认使用同源 /api 路径，避免绕过反向代理直接访问其他后端源站。CORS 配置也不会因为服务绑定 0.0.0.0 自动放开所有来源，远程部署需要显式配置允许的 origin。

认证路径与公开入口

启用本地账号体系后，Flocks 默认保护所有 HTTP API，仅放行必要的公开路径，例如：

• WebUI 引导页、登录页、初始化管理员页；
• 静态资源；
• 健康检查；
• 明确设计给外部平台调用的 webhook 路径。

这类 webhook 需要进行独立的签名、Token、来源或重放校验。

非浏览器客户端访问

TUI、SDK、脚本、自动化调用等非浏览器客户端必须携带 API Token。Token 支持两种请求头：

Authorization: Bearer <token>
X-Flocks-API-Token: <token>

API Token 存放在本机 secret store 中，secret id 为 server_api_token。该设计避免“只要请求来自 127.0.0.1 就默认可信”的风险，尤其适合反向代理、桌面端、脚本和本机多进程场景。

网络管控策略

Flocks 对外网络访问主要包括以下类型：

• 大模型服务：访问配置的大模型网关或企业指定 LLM 域名。
• 依赖安装：安装或升级过程中可能访问 uv/PyPI、npm registry、GitHub/GHCR、Chrome for Testing 等依赖源；国内安装脚本支持镜像源。
• 企业授权与升级：企业版授权、升级和组件下载需要访问企业授权/门户服务，例如 passport.threatbook.cn、portalflocks.threatbook.cn 等，具体以交付版本配置为准。
• 安全能力集成：按客户启用的情报服务、安全设备、IM 平台、MCP 服务等访问对应 API。

生产环境可按实际启用能力做出口白名单。若客户希望最小化网络访问，可采用“仅放行 LLM 网关、企业授权/升级域名、已启用的安全 API/设备域名”的策略。

IM、Webhook 与工作流触发

Flocks 支持通过 IM、邮件网关、webhook、syslog、Kafka、定时任务等方式触发会话或工作流。相关安全控制包括：

• 入站 IM 消息有去重机制，避免重复投递导致重复执行。
• IM 渠道支持 allowlist，限制允许发起请求的用户、群或房间。
• 邮件网关应配置发件人 allowlist，并使用专用邮箱和应用专用密码，避免任意邮件触发 Agent。
• 飞书群可配置 groupPolicy、群 ID allowlist、群内用户 allowlist、是否必须 @bot。
• Slack 通道应配置用户 ID / 频道 ID allowlist，并优先使用 app_mention、私聊或回复触发，避免频道普通消息全部触发 Agent。
• Telegram webhook 校验 X-Telegram-Bot-Api-Secret-Token。
• 飞书 webhook 支持签名校验、verification token、时间戳校验和 replay key 去重。
• 工作流 webhook trigger 支持 api_key 与 hmac 鉴权，HMAC 使用请求体与密钥计算 SHA256 并进行常量时间比较。

外部媒体与 SSRF 控制

部分 IM 渠道涉及外部媒体下载。以微信相关能力为例，代码中对媒体 URL 做了 CDN host allowlist，只允许访问已知微信 CDN 域名，并限制 URL scheme 为 http/https，用于降低 SSRF 风险。

3.7.3 Flocks 自身的执行管控

Agent 能力模型

Flocks 的 Agent 不是天然拥有全部系统能力，而是通过工具获得外部能力。Agent 配置中支持显式 tools 白名单：

• 主 Agent Rex 负责整体编排和任务拆解。
• 子 Agent 可被设计为只拥有特定工具集合。
• 未显式声明工具的 Agent 默认不会继承全部工具。
• delegate_task 创建子 Agent 会话时，会叠加 session permission 规则。
• 子 Agent 默认禁止继续嵌套委派，避免权限扩散和不可控任务链。

因此，面向不同业务场景可以设计不同 Agent：例如只读分析 Agent、只允许查询设备 API 的 Agent、允许执行主机应急命令但必须审批的 Agent 等。

工具注册与启停控制

Flocks 的外部能力主要通过工具系统承载。工具具备以下元数据和控制点：

• 工具来源：内置工具、插件工具、MCP 工具、API 工具、设备工具等。
• 工具状态：启用、禁用、默认启用状态、用户自定义状态。
• 工具归属：API/设备工具关联具体 provider/service。
• 工具管理：支持注册、刷新、启用、禁用、重置、更新、删除。

API/设备工具还受服务级开关控制：

• 服务禁用时，关联工具即使有工具级启用配置，也不能被实际打开。
• 工具可以全局禁用，也可以按设备实例禁用。
• 接入安全设备时，可选择只接入查询类 API，不接入具有执行、封禁、隔离、删除等能力的 API。

工具管理接口属于管理操作，需要管理员权限。

工具调用上下文校验

Flocks 对“直接通过 HTTP 调用工具”做了额外约束。对于内置本地工具或权限敏感工具，直接 HTTP 调用必须绑定真实的 sessionID 与 messageID，确保工具执行仍然落在一个会话上下文中，并进入权限审批流。

如果没有会话上下文，HTTP 工具上下文不能自动批准权限。该设计用于防止调用者绕过 Agent 会话和审批机制直接触发本地工具。

敏感操作审批

Flocks 内置权限审批机制，适用于命令执行、文件写入、外部目录访问等敏感行为。审批回复支持：

• allow：本次允许；
• deny：本次拒绝；
• allow_session：当前会话允许；
• always：永久允许；
• never：永久拒绝。

审批请求会持久化 pending/reply 状态，前端或客户端可以响应审批。审批规则可来自会话权限、Agent 权限或用户操作。

需要注意：系统存在 FLOCKS_AUTO_APPROVE=true 自动审批开关，适合本地开发或受控自动化场景，生产环境或客户交付环境不建议开启。

Bash/命令执行控制

Bash 工具是高风险能力，Flocks 对其做了多层控制：

• 执行前请求 bash 权限审批。
• 工作目录超出当前项目时，额外请求 external_directory 权限。
• 支持超时控制，默认命令不会无限运行。
• 支持 abort 和进程树清理。
• 输出有行数和字节数限制，避免超大输出拖垮系统或污染上下文。
• 沙箱模式下，bash 默认在 Docker 容器中执行。
• 若要从沙箱提升到宿主机执行，需要显式开启 sandbox.elevated.enabled 并把 bash 加入允许提升的工具列表。

对于主机应急 Agent，可将执行命令类工具设为必须审批，使每条主机命令都需要用户确认后才执行。

文件与路径安全

Flocks 在路径处理和插件脚本执行上有基础防护：

• sandbox 路径解析会阻止 .. 等路径逃逸。
• 会检查 symlink，避免通过符号链接跳出沙箱根目录。
• 文件读写类工具可进入权限审批。
• YAML script 工具只能加载用户或项目 .flocks/plugins 目录下的脚本，不能任意指向系统路径执行。
• 用户自定义页面导入 zip 时，会限制隐藏路径、文件数量、单文件大小和总大小。

工作流执行控制

工作流可以通过手动、定时、webhook、syslog、Kafka 等方式触发。相关控制包括：

• Trigger 可启用/禁用。
• Webhook trigger 支持 API Key/HMAC。
• Trigger 支持并发策略，例如允许并发、禁止重叠、排队、丢弃旧任务或丢弃新任务。
• 工作流执行记录会保存状态、输入、输出、日志、耗时、触发来源等信息，可用于追踪和审计。
• 工作流 Python 执行可走 sandbox runtime，降低对宿主机的影响。

3.7.4 产品部署上的管控

默认本地部署

默认部署适合 PC 或单台服务器本地使用：

• Flocks 统一服务默认 127.0.0.1:5173；
• WebUI 使用 /，API 使用同源 /api；
• 浏览器通过本机访问；
• 不对外暴露服务端口。

这是最小暴露面的默认模式。

远程访问部署

如需远程访问，应结合网络层控制：

• 仅绑定内网 IP 或指定 IP，避免无必要的 0.0.0.0。
• 使用主机防火墙限制访问来源。
• 使用 Nginx/网关做 TLS 终止、访问控制、日志记录和限流。
• 反向代理应转发 X-Forwarded-Proto: https，使服务端正确设置 secure cookie。
• 浏览器端优先通过同源 /api 访问后端，避免跨域和直连后端。

Docker 部署

Flocks 支持 Docker 部署，适合客户担心影响 PC 或服务器主机环境的场景：

• 服务运行在容器内，依赖与运行环境相对隔离。
• 容器使用非 root 用户运行。
• 用户数据目录可通过 volume 挂载到宿主机。
• 端口需要显式 -p 映射后才能从宿主机访问。

需要说明的是，Docker 部署是产品整体运行环境隔离；Flocks 还支持更细粒度的 Agent/工作流 sandbox，用于隔离具体执行任务。

Agent/工作流 Sandbox

Sandbox 可用于控制 Agent 或工作流执行对宿主机的影响。默认安全项包括：

• Docker 容器运行；
• network=none，默认无网络；
• 只读根文件系统；
• /tmp、/var/tmp、/run 等 tmpfs；
• cap-drop=ALL；
• no-new-privileges；
• 可配置进程数、内存、CPU、ulimit；
• 可配置 seccomp/AppArmor；
• workspace 访问级别支持 none、ro、rw；
• 支持按 session、agent、shared 维度隔离容器。

这类控制适用于执行不可信脚本、运行工作流节点、让子 Agent 做探索性任务等场景。

网络出口控制建议

客户可以按“最小必要”原则收敛出口：

• 运行期仅放行配置的大模型网关或企业 LLM 域名。
• 仅放行已启用安全设备/API、IM 平台、MCP 服务等业务集成域名。
• 企业授权和升级放行企业门户、passport、升级包下载域名。
• 安装/升级窗口临时放行 GitHub/GHCR、PyPI/uv、npm registry 等依赖源；生产运行期可关闭这些出口。
• 对不需要公网访问的 sandbox，保持 network=none。

3.7.5 身份、账号与数据隔离

本地账号体系

Flocks 支持本地账号体系：

• 初次部署创建唯一 admin。
• 支持 admin/member 角色。
• 管理员可查看用户列表、重置密码、强制用户改密。
• 密码最小长度 8 位，使用 scrypt 加盐哈希。
• 临时密码有有效期。
• 改密或重置密码会撤销已有 session。

会话所有权

会话数据按 owner 隔离：

• owner 可读写自己的会话。
• member 默认不能读取其他用户私有会话。
• admin 默认也不能读取或删除其他用户私有会话。
• 显式共享会话可被共享用户只读访问。
• ownerless 历史会话或后台/IM 产生的无主会话，admin 可管理并支持回填归属。

Agent、Skill 与共享资源

Agent、Skill、插件和工具属于平台能力资源，通常是共享的；会话内容和执行记录按用户隔离。企业交付时可根据客户组织管理要求进一步定义哪些资源由管理员统一维护，哪些资源允许用户自定义。

3.7.6 密钥与凭据管理

Flocks 使用 SecretManager 管理本地密钥，包括：

• 大模型 API Key；
• 外部 API service key；
• MCP server key；
• server API token；
• workflow trigger secret；
• 设备凭据等。

默认存储位置为 ~/.flocks/config/.secret.json，文件权限会被设置为 600，仅当前系统用户可读写。工具 YAML 支持 {secret:secret_id} 占位符，运行时从 secret store 解析，避免把密钥直接写入工具定义。

注意：当前默认实现是本地文件最小权限保护和展示脱敏，并非默认加密存储。若客户有更高等级要求，可在企业版或交付集成中接入操作系统密钥库、KMS、Vault 或其他企业密钥管理系统。

3.7.7 审计与可追溯

Flocks 代码中提供审计 facade，企业版可注册真实 audit sink，将关键事件落库并提供查询。可审计事件包括但不限于：

• 登录成功/失败；
• 用户和密码管理操作；
• session 创建、删除、归属等；
• 工具权限请求和响应；
• 工作流执行记录、触发来源、执行状态、输出摘要；
• 企业授权、升级请求和许可证同步。

OSS 默认 audit sink 是 no-op；企业版授权后可启用完整审计能力。

3.7.8 插件、工具与外部能力接入管控

Flocks 支持插件、MCP、API YAML 工具、设备工具等扩展方式。安全控制建议如下：

• 仅安装可信来源插件。
• 对 API/设备工具按 provider/service 统一启停。
• 对具备执行能力的设备 API 默认禁用或不接入。
• 对需要写入、删除、隔离、封禁等影响生产环境的工具，配置审批或只允许特定 Agent 使用。
• 对 YAML script 工具保留脚本路径约束，脚本应位于 .flocks/plugins 目录下。
• 对插件导入和自定义页面导入保留 admin 权限。

3.7.9 客户侧推荐管控策略

面向安全要求较高的客户，建议采用以下组合：

1. 部署层

   • 默认不暴露公网；
   • 通过 Nginx/TLS/防火墙暴露统一服务入口；
   • 不额外开放旧的后端端口；
   • 配置明确 CORS origin。

2. 账号层

   • 启用本地账号；
   • 管理员单独保管；
   • 定期轮换 API Token；
   • 离职或角色变化时重置密码并撤销 session。

3. 执行层

   • 生产环境关闭自动审批；
   • bash、写文件、外部目录、主机命令默认审批；
   • 高危 Agent 放入 sandbox；
   • 对主机应急类 Agent 强制逐条命令审批。

4. 工具层

   • 只启用必要工具；
   • 情报查询类工具与处置执行类工具分开管理；
   • 安全设备 API 优先接入只读查询能力；
   • 高风险 API 按设备实例禁用或只授权给专用 Agent。

5. 网络层

   • 运行期仅放行 LLM、授权、升级和已启用集成所需域名；
   • sandbox 默认不联网；
   • 安装/升级依赖访问使用临时窗口或内网镜像。

6. 审计层

   • 企业版开启审计 sink；
   • 定期导出和检查登录、工具执行、工作流执行记录；
   • 对高风险工具审批记录保留追溯。

3.7.10 小结

Flocks 的安全管控不是单一开关，而是由部署暴露面、账号认证、会话隔离、Agent 工具白名单、工具启停、权限审批、sandbox 隔离、密钥管理和审计追踪共同组成。客户可以根据使用场景选择不同强度的组合：本机默认安全使用、服务器反代部署、Docker 隔离部署，或企业版多账号审计与严格网络出口控制。