omoji-personal/torque

# 扭矩 **让 AI 代理操作真实的 Salesforce org —— 且无法让其自行向生产环境写入数据。** 前沿的编程代理现在可以直接运行 Salesforce 操作：查询、部署、运行 Apex、移动 数据。这确实非常有用，但也确实非常危险 —— 同一个修复流程的会话，可能 会因为一个错误的别名，向客户的生产 org 写入数据。仅仅告诉代理要小心是 约束不了它的。Torque 就是那个能起到约束作用的层。 ## 3秒内见效 —— 无需 org、无需凭证、零风险 ``` git clone && cd torque python3 bin/torque-demo ``` 通过真实的 hook 运行的真实攻击： ``` Shell indirection The gate never sees the literal word `sf` — it is assembled at runtime. DENIED x=sf; $x data delete bulk --sobject Account --target-org acme-prod variable-assembled command → Salesforce operation hidden in a shell assignment value DENIED s$'\x66' data delete bulk --sobject Account --target-org acme-prod ANSI-C hex escape spells 'sf' → indirect command invocation cannot be authorized — call `sf` literal Path expansion A glob or variable that only becomes the secret's path when bash expands it. DENIED cat /Users/you/.tor*/secret glob reaches the signing secret → reference to the trust anchor (~/.torque) — secret and tokens are operator-only DENIED p=$HOME/.torque;cat $p/secret path assembled through a shell variable → reference to the trust anchor (~/.torque) Overwriting the gate itself Disable the hook and everything downstream is ungated. DENIED : >hooks/lib.py >/tmp/z two redirects; bash truncates BOTH → write to a protected path: hooks/lib.py DENIED git checkout HEAD~5 -- hooks/ restore an older, weaker gate from git → git checkout targeting protected paths Normal work is untouched A gate that blocks real work gets turned off. These all run. allowed sf data query --query "SELECT Id FROM Account" --target-org any-org allowed grep -rn 'sf data delete --target-org' . allowed sf project deploy start --dry-run --manifest p.xml --target-org acme-prod all 24 behaved correctly ``` 这里的每一次攻击都是通过对该代码早期版本的对抗性审计发现的，并且 现在已成为永久的回归测试固定数据。最后一部分与其余部分同样重要：**一个阻碍 正常工作的 gate 会被关掉。** ## 它是如何起效的 —— 五个层级 1. **凭证。** 以只读方式连接生产环境。Torque 不存储任何 org 凭证；`sf` CLI 是 唯一的凭证路径。（它确实会创建一个本地签名密钥，`~/.torque/secret`， 这正是使批准 token 不可伪造的原因。） 2. **基于身份而非推断的授权。** 只有当非生产环境的写入目标在明确的 allowlist 中 **并且** 在写入的瞬间通过*实时* org 查询将其归类为非生产环境时（绝不依赖别名或 URL 猜测），该写入才会被允许。 3. **确定性 gate。** 两个 PreToolUse hook 共享一个支持扩展的解析器。它们通过*解析 argv* 进行授权并默认拒绝 —— 因此间接调用、分组、包装器、解释器、粘合 重定向、旧版 `force:data:*` 动词以及 glob/`$var` 路径技巧都会被拒绝，而不会 靠猜测。破坏性操作和匿名 Apex 需要操作员在场、HMAC 签名的 一次性 token。**代理可以请求批准；通过其工具层面，它可证明无法伪造 token。** 崩溃的 gate 会拒绝而不是放行。 4. **生产环境覆盖 —— 是刻意为之，而非不可能。** 实际工作包括部署到客户的 生产环境。`torque approve --prod` 会生成一个一次性 token（你需要在真实的终端中输入 `WRITE PRODUCTION`）；`torque approve --session ` 会打开一个有限的、可撤销的窗口。 每一次生产环境写入都会被审计。 5. **经过验证的强制执行。** 每一条规则都被标记为 hook 强制执行、harness 强制执行或 由模型遵守 —— 并且这些标签是经过*检查*的，而不是装饰性的。 ## 在你自己的 org 上运行它 前置条件：[Claude Code](https://claude.com/claude-code)（hook 是它的 PreToolUse 层面）， `git`，`python3` ≥ 3.11，[Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli) ≥ 2.60， 以及任何非生产环境的 org —— [免费的 Developer Edition](https://developer.salesforce.com/signup) 即可。 （`node` 是可选的；它仅影响实时浏览器检查。） ``` sf org login web --alias my-dev-org python3 bin/torque init my-dev-org # verifies the org is NOT production, then configures npm install # optional: only the live browser check needs this python3 harness/validate.py --profile release --target-org my-dev-org ``` 跳过 `npm install`，一切依然会运行 —— 浏览器检查会报告 `BLOCKED` 并附带注明日期的 原因，结论将是 `DEGRADED` 而不是 `PASS`。这是刻意为之的：一个无法运行的检查 永远不会被报告为绿色（通过）。 `torque init` 拒绝将生产环境的 org 加入 allowlist，在 repo 之外创建信任锚点， 并在告诉你它已生效之前证明 gate 是起约束作用的。allowlist 是刻意不随包发布的： 你可以向哪个 org 写入数据，是一个只有坐在键盘前的人才能做出的决定。 然后在 Claude Code 中打开该文件夹并开始工作。这些 hook 会在每次工具调用时触发。 ## 为什么你可以相信它 Torque 验证自己的方式与它验证 Salesforce 工作的方式相同。`--profile release` 运行： - **128 个对抗性测试固定数据** —— 审计中发现的每一类攻击，每一个都是一个命名的、 可运行的测试。 - **11 个突变测试** —— 每个测试会暂时削弱一个防护，并*要求*相应的 攻击必须成功（或者，对于静态扫描器，要求检查必须 FAIL）。一个不可能失败的检查证明不了什么；这些测试证明了每个防护都是承重部件。其中七个在任何克隆版本上都能运行； 另外三个测试干净 IP 扫描并需要私有模式列表，因此它们会报告为 仅限操作员运行，而不是假装通过；第十一个需要 `--target-org`，因为 它削弱的检查会查询某个 org。被跳过的突变器永远不会被报告为已捕获。 - **针对你的 org 的实时能力循环** —— 部署一个字段，通过 SOQL 验证它，验证 字段级安全性，将其硬删除，确认零残留；一次带有有效撤销机制的批量更新； 一次真实的无头 Lightning 渲染。 - **发布 gate** —— 代理层面的 token 生成必须失败，并且七种绕过形态必须被拒绝。 这套安全设计在代码存在*之前*，就通过九轮多模型审计推动到了收敛状态，随后构建好的 gate 又经历了四轮独立的对抗性测试 —— 一位 shell 语义审查者，一位*执行*了针对真实 `sf` CLI 的每种漏洞利用的审查者，以及一位架构怀疑论者 —— 外加两次确认测试。大约发现了 55 个真实漏洞并已修复；每一个都是 一个测试固定数据。整个轨迹记录在 [`harness/VALIDATION.md`](harness/VALIDATION.md) 中。 ## 指南 [`guide/Torque-Guide.pdf`](guide/Torque-Guide.pdf) —— 14 页：它的功能、为什么它不是 MCP 服务器、设置说明、梳理过的操作、安全模型、故障排除 以及 harness 如何证明自身。 ## Torque *不*主张什么 这些 gate 约束的是代理的**工具层面**（Bash / Edit / Write / Read / MCP）。它们能确切地阻止意外发生，并击败可枚举的规避手段。它们**不**主张能够阻止同一用户的执行者跳出该层面去执行任意代码 —— 例如使用定制程序伪造登录会话，通过操作系统读取签名密钥，或者让代理编写并运行脚本， 从而使得 `sf` 作为子进程执行，而 hook 根本看不见。 对于这些情况，承重防线是第 1 层：以只读方式连接生产环境，并且绝不在 自主会话中让生产环境的 org 保持已验证状态。正确关闭子进程通道需要 一个在 `exec` 之前进行分类的 PATH 级别 shim —— 这是 v2 的路线图，目前尚未 构建。说明这一点才是关键：你无法复现的安全主张只是营销，而不是安全。 **找到了突破的方法？** 这正是重点所在 —— 套件中的每一个固定数据的存在，都是因为某次审查击败了这段代码的早期版本。请参阅 [`SECURITY.md`](SECURITY.md) 了解发送途径。 ## 它不是什么 不是 CI/CD pipeline（Gearset、Copado）。不是 org 内的代码生成 IDE（Agentforce Vibes）。不是命令 库（sfdx-hardis —— 很好的现有技术；Torque 可以建立在它之上）。它是这些类别 未曾提供的操作员级安全和验证层。 **完整指南、安全模型和威胁模型：** [`guide/TORQUE-GUIDE.md`](guide/TORQUE-GUIDE.md) **验证日志和审计轨迹：** [`harness/VALIDATION.md`](harness/VALIDATION.md) MIT 许可证。

标签：AI代理, DNS 反向解析, Salesforce, Streamlit, 命令行安全防护, 应用安全, 开发运维, 沙箱, 访问控制, 逆向工具