HarnessRouter 安全机制完全指南每会话独立用户、SQL 只读解析器与凭据脱敏如何保护你的数据【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouterHarnessRouter 是一个自托管的 Agent 统一网关社区版Apache-2.0 许可让你用同一个 API 运行 Codex、Claude Code、Hermes、PI、DSH 等多种 Agent Harness并实现 Unified Harness ProtocolUHP 开放标准。当你要把会执行命令、读写文件、持有模型密钥的 Agent 跑在自己的服务器上时安全问题绕不开。本文带你拆解 HarnessRouter 社区版里三套最值得学习的安全设计每会话独立用户、SQL 只读解析器和凭据脱敏看看它们是如何把你的数据、密钥和数据库保护起来的。为什么 Agent 网关比普通 API 更危险传统模型 API 最坏的情况是算错答案而 UHP 网关背后跑的是真正会执行工具、写文件、持有模型提供商凭据的 Agent 进程。UHP 规范在 protocol/versions/2026-09-28/security.md 里说得很直白Agent 的沙箱是整个系统里最不可信的地方——它可能诱导 Agent 读取自己的环境变量并打印出来。因此规范明确要求凭据不能放在 Agent 工具可读到的位置任何对象会话、文件、响应必须归属创建它的主体越权访问一律返回404而不是403403会暴露这个 ID 存在凭据严禁出现在任何响应体、错误信息、日志行中HarnessRouter 社区版把这几条从纸面要求落成了三套可验证的工程机制。安全机制一每会话独立用户Per-Session UID核心思路不是告知不许写而是做不到自托管的 HarnessRouter 容器以 root 启动但 root 只用来干一件事为每个会话创建一个独立的操作系统用户。每个 Agent 进程以自己的会话用户身份运行只拥有该会话工作区的文件其余一概无权。相关实现可见 docker/entrypoint.sh其中HR_SESSION_UIDS1启动 Runner与 Dockerfile 第 179 行附近的注释。官方自托管指南 docs/self-hosting-guide.md 对这套机制文中称为write-wall的总结很精彩保护点普通做法HarnessRouter 做法隔离其他会话的文件靠约定/提示词约束操作系统级属主隔离写不进去误写到工作区外静默丢失写入当场失败模型还有机会自我纠正进程环境变量可能携带平台密钥Agent 进程不携带任何产品级机密这意味着同一个容器里服务多个会话时一个被注入的 Agent 也无法偷看或篡改另一个会话的工作区、数据库或密钥存储——不是被告知不可以而是物理上做不到。而且这一切没有使用--privileged、没有额外 capability只用了 Docker 默认权限。环境Environments也复用同样的隔离思路每个环境有自己的用户/组构建产物只读会话进程只能读取被分配到的那一个环境连枚举其他环境都做不到详见 runner/environments.py。安全机制二SQL 只读解析器让 Agent 查数据库但永远改不了HarnessRouter 内置了databaseMCP 工具和数据看板刷新接口Agent 可以探索数据库结构、试跑查询来设计仪表盘。这要求一个硬约束——任何从网关发出的 SQL 只能是只读查询。核心实现在 gateway/sql_plane.py它做了四道闸门只认 SELECT语句清洗后必须以select或with开头否则直接拒绝SqlRefused全语句禁用词扫描insert、update、delete、drop、truncate、grant、set、copy……等 30 余个危险词在任何位置出现都会被拦截——因为 PostgreSQL 允许WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x这种以 WITH 开头实则删数据的花式写法只看开头关键字是防不住的防注释/字面量欺骗扫描前先剥掉行注释、块注释和字符串字面量这样叫update_time的列名或字符串please delete me不会误伤藏在注释里的恶意指令也无处遁形单语句 行数上限一次只允许一条语句SELECT 1; DROP TABLE users里的分号会触发拒绝并自动补LIMIT 5000已有更小 LIMIT 则保留防止拖库式查询打爆内存。代码注释里还有一句值得新手记住的清醒话只读闸门不是唯一的防线——解析器是人写的人写的可能有错。因此 Postgres 查询还会再套一层数据库原生的只读事务conn.transaction(readonlyTrue)gateway/sql_plane.py 里两条防线互相独立。官方甚至建议把工具指向一个只有 SELECT 权限的数据库账号让解析器和数据库权限成为两道彼此不依赖的锁。安全机制三凭据脱敏Redaction数据库连接串永远不离开网关进程SQL 查询的第二层保障是凭据的最小化流转数据库连接串DSN只在网关内部从密钥存储中解析RunnerAgent 进程拿不到浏览器也拿不到。配置里存的是vault:ref引用真正值在使用那一刻才取——这正是每轮只发一个短期能力永不发 DSN的设计。错误消息把驱动吐回来的密码抹掉数据库驱动报错时经常把整个 DSN 复述出来例如postgres://user:passwordhost/db: ...。这类消息会展示给人、交给 Agent——两处都不该出现密码。所以 _clean_db_error() 用正则://[^/\s]*把 userinfo 段替换成://***后才放行。模型提供商的原话先脱敏再落地更隐蔽的泄露点是提供商返回的错误信息本身。比如 OpenAI 的 401 响应就是Incorrect API key provided: sk-…——错误句子里直接带密钥。HarnessRouter 在 gateway/media_plane.py 采用入口处统一清洗策略精确匹配优先本网关实际发出的每把密钥在解析时就登记remember_secret出现即整体替换为[redacted]这是保证级别的形状匹配兜底对sk-、ghp_、xoxb-、AIza…、AKIA…AWS、Bearer …、URL 内嵌凭据、?api_key…等常见形态做正则网兜这是网而不是保证——注释里坦率说明了边界不能误伤长得像密钥的提供商任务 ID只洗一次所有字段读取路径统一经过_clean()将来新增字段不用记住去脱敏。会话环境里的密钥Runner 侧回传全部打码当你在 Harness 的env配置里写vault:xxx引用时网关解析出真实值交给 Runner同时把变量名标记为机密Runner 会把该值从所有回传内容事件流、结果、错误中替换掉任何记录、流或响应都不携带它逻辑在 gateway/app.py。而字面量如us-east-1不会被脱敏——因为它本来就存在 Harness 配置里打码只会毁掉日志。其他值得新手知道的安全细节错误卫生error.message必须是可以直接给用户看的——不含凭据、内部主机名、文件路径或堆栈需要排查的细节进日志并用error.detail里的关联 ID 对应protocol/versions/2026-09-28/errors.md插件当第三方代码对待插件声明的 stdio MCP 服务器必须在 Agent 沙箱内运行、不能过 shell 启动占位符只允许展开${PLUGIN_ROOT}和${PLUGIN_DATA}防止插件进程偷读沙箱里的凭据protocol/versions/2026-09-28/plugins.md产物即敌意内容Agent 写的文件会被X-Content-Type-Options: nosniff服务防存储型 XSS路径穿越有专门的合规探针 X-08会话删除即销毁删除后产物与转录必须不可达会话分享只读且可撤销。如何验证UHP 合规测试套件这套设计是否真的落实了不必只听文档说——UHP 附带了一个合规测试套件 protocol/conformance/它对实现做路径穿越、保留字段、流式帧格式等自动化探针并在 protocol/conformance/reports/ 中归档了历史版本0.3.0 → 0.9.0-rc的完整报告安全回归一目了然。规范还建议实现者用两个主体手工验证对象隔离A 建对象B 尝试对它做所有操作应全部得到404。总结HarnessRouter 社区版给普通自托管用户的启示很清晰机制防什么关键位置每会话独立用户Agent 横向越权、互看会话docker/entrypoint.sh、docs/self-hosting-guide.mdSQL 只读解析器 只读事务 单语句 LIMIT误删库、拖库gateway/sql_plane.py凭据脱敏精确 形状双重密钥经错误消息/日志泄露gateway/media_plane.pyDSN 不出网关、vault:引用Agent 偷环境变量gateway/app.py对象一律 404 越权、错误卫生ID 枚举、信息泄露protocol/versions/2026-09-28/security.md想亲自体验的话可以先阅读 docs/self-hosting-guide.md 按指南拉取镜像自托管再对照本文三个机制逐一验证。你的密钥、你的基础设施——这正是这个社区版想守住的东西。【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考