dsh-ramen-guard

dsh-ramen-guard

English | 中文

[!IMPORTANT] 非官方社区集成。 本项目由 ramen-ai 社区独立开发和维护，未经 DeepSeek 审核、推荐或支持。使用任何第三方插件前，请自行评估其安全性。详见 DeepSeek Harness 插件专区规则。

在意图变成行动之前，保护 DeepSeek Harness 工具执行。

dsh-ramen-guard 是一个故障关闭（fail-closed）的 Cordis 插件。它会在 DeepSeek Harness 工具执行之前，通过 ramen-ai 语义防火墙评估工具调用。 插件拦截官方 tools/pre-execute waterfall，将已解析的工具名称和参数交给 @ramen-ai/node-core，并且只有在 verdict 允许且 Ed25519 收据已在本地验证后， 才会继续执行。

DeepSeek Harness 可以赋予自主代理真实的 shell、代码、数据和 API 操作能力。 本插件在模型自身推理之外增加一道独立的语义策略门禁。在默认的强制执行模式中， 违反策略的调用会在产生副作用前被阻止；允许的调用只有携带与已评估工具意图绑定、 并经过本地验证的收据，才会继续进入后续 Cordis guard 链。审计模式明确为非阻止模式。

需要 Node.js 24 或更高版本。已针对 DeepSeek Harness @deepseek-ai/cordis@4.0.1 和 @deepseek-ai/dsh-tools@0.1.1-rc.2 测试。

---

               

---

为什么值得使用？

具备真实操作能力的代理，可能把一条被操纵的指令变成 shell 命令、数据库变更、 云资源操作或支付请求。工具一旦执行，仅记录日志已经太晚。dsh-ramen-guard 把策略判断放在最后一个仍可安全阻止动作的时刻：DeepSeek Harness 已解析工具调用， 但工具函数尚未产生副作用。

• 在执行前阻止。 对已解析的 { tool, arguments } 意图执行策略，而不是事后补救。
• 使用语义策略，而不只是字符串匹配。 当所选 policy 或 bundle scope 覆盖相关风险时， 配置的 ramen-ai 策略可以识别编码 payload、委婉表达或间接措辞。
• 边界不可用时故障关闭。 在强制执行模式中，超时、格式错误的响应、取消或无法验证的 收据都不能静默授权动作。
• 要求执行具备加密证据。 allow 响应只有包含与已评估意图绑定、并经过本地验证的 Ed25519 收据，才能到达工具；边界故障则使用固定的 unavailable 原因拒绝调用。
• 保留纵深防御。 允许的调用通过 next() 继续，因此本 guard 会补充而不是绕过 后续 Cordis 策略。

---

你能绕过它吗？

标准安全过滤器可以识别基础语法，却难以识别编码后的 payload 和企业话术。 欢迎使用官方 Red Team Guide 中的零日规避向量， 测试我们的语义防火墙。

下图模拟 Grok/Bankr 攻击：对抗性 prompt 以“视觉障碍”为社会工程包装， 把一条 3,000,000,000 DRB 转账指令编码为摩尔斯电码。防火墙理解其真实语义， 在执行前拦截未授权转账，并生成经过验证的 Ed25519 收据。

---

API 密钥

使用本集成前，请在以下页面获取 ramen-ai API 密钥： https://ramenai.dev/pricing

Starter 和 Professional BYOK 套餐还需要 provider API 密钥。Enterprise 账户使用托管推理， 无需配置 providerKey。

请把 ramen-ai 和 provider 密钥存放在环境变量中，并通过 Cordis 配置解析。不要把真实密钥 直接写入 cordis.patch.yml 或提交到源代码仓库。

export RAMEN_API_KEY=ramen_ak_...
export OPENAI_API_KEY=sk-...

插件不会隐式读取环境变量。下方配置使用 Cordis 官方的 !!js loader 表达式， 在加载时把环境变量传给 apiKey 和可选的 providerKey。

---

安装

npm 发布后安装

DeepSeek Harness 会把 dsh plugin 的包管理操作转发到所选 profile：

dsh plugin --profile web add @ramen-ai/dsh-ramen-guard@0.1.0

从本仓库安装

npm install
npm run build
npm pack

dsh plugin --profile web add /absolute/path/to/ramen-ai-dsh-ramen-guard-0.1.0.tgz

如果你运行的不是 web profile，请替换为实际 profile 名称。

---

配置

在所选 profile 的 cordis.patch.yml 中添加插件。该文件通常位于 ${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/cordis.patch.yml：

- insert:
    - id: dsh-ramen-guard
      name: '@ramen-ai/dsh-ramen-guard'
      config:
        apiKey: !!js process.env.RAMEN_API_KEY
        providerKey: !!js process.env.OPENAI_API_KEY
        bundleIds: ['ramen__shield_core_it']
        mode: enforce

必须提供至少一个非空的 bundleIds 或 policyIds 数组，也可以同时提供两者。 配置无效或缺失时，插件会加载失败，而不是启动一个未受保护的边界。

强制执行模式

mode: enforce 是默认值，也是生产安全边界。出现以下任一情况时，工具调用会被拒绝：

• ramen-ai 返回阻止 verdict；
• 评估请求失败、超时或被取消；
• 响应格式无效；
• 加密收据缺失或无法在本地验证。

基础设施或收据失败会确定性返回：

ramen ai execution boundary unavailable

本插件不存在 fail-open 配置。

审计模式

只有在明确需要观察策略结果、但不把 ramen-ai 作为强制门禁时，才使用 mode: audit：

- insert:
    - id: dsh-ramen-guard-audit
      name: '@ramen-ai/dsh-ramen-guard'
      config:
        apiKey: !!js process.env.RAMEN_API_KEY
        providerKey: !!js process.env.OPENAI_API_KEY
        policyIds: ['<POLICY_UUID>']
        mode: audit

审计模式会记录允许、拒绝、不可用和未验证结果，然后继续执行 Cordis 策略链。 Harness 中的其他 guard 仍然可以拒绝调用。

BYOK 账户兼容性

Starter 和 Professional 账户可通过 providerKey 配置其 provider API 密钥。核心 SDK 会将其 作为 X-Provider-Key 请求头发送；本插件不会把该密钥放入被评估的工具 intent。Enterprise 账户省略 providerKey 并使用托管推理。不要把 provider 凭据放入工具参数或受版本控制的配置。

---

快速开始

1. 导出 RAMEN_API_KEY。
2. 把 package 安装到 DeepSeek Harness profile。
3. 添加上方 dsh-ramen-guard insert。
4. 重启 profile；如需检查组合后的配置，可运行：

dsh --profile web --dump-config
dsh web

插件激活后，所有进入官方 tools/pre-execute waterfall 的工具调用， 都会在工具函数运行前完成评估。

---

使用场景示例

保护编码与运维代理

在 shell、文件系统、数据库、Kubernetes、云平台或部署工具前增加策略边界。 例如，可在底层工具运行前拒绝破坏性命令、不安全的生产环境变更或权限提升。

防止密钥和数据外泄

评估已经解析到工具调用中的目标地址和 payload。策略可以拒绝把 API key、凭据、 源代码、客户记录或其他敏感数据发送到未批准端点的尝试。

保护财务与管理工作流

在转账、支付、账户管理或访问控制工具执行前，要求 ramen-ai 返回允许 verdict。 当代理能够执行具有真实资金或权限后果的动作时，这道边界尤其重要。

为高风险工作流增加可验证控制

对每个特权工具调用应用标准 ramen-ai bundle 或显式 policy ID。allow 响应只有在其收据 已在本地针对所评估的工具意图完成验证后，才能到达工具。

首日不阻断，逐步上线策略

先使用 mode: audit 观察 verdict 并调优策略，同时让所有调用继续进入 Cordis 链。 准备好启用真实边界后，再显式切换到 mode: enforce。审计模式本身永远不会阻止调用。

[!NOTE] 本插件只评估进入 tools/pre-execute 的已解析工具名称和参数。它不会直接扫描源文档 或 prompt，也无法治理 Harness 工具 pipeline 之外执行的动作。

---

工作原理

DeepSeek 模型提出工具调用
             |
             v
   tools/pre-execute waterfall
             |
             v
 JSON { tool, arguments } intent payload
             |
             v
 @ramen-ai/node-core evaluateCompliance()
             |
             v
 ramen-ai verdict + 本地 Ed25519 验证
        |                         |
 已验证且允许              阻止 / 不可用 /
        |                   收据缺失
        v                         |
     next()                       v
 后续 Cordis 策略          { kind: 'deny', reason }
        |
        v
 工具函数可以执行

对于已验证且允许的调用，listener 会调用 next()，因此不会绕过任何后续 Harness 策略。 已验证的阻止 verdict 会返回 evaluator 的 steering 原因。在强制执行模式中， 评估或收据失败永远不会进入工具函数。

---

API 参考

Cordis exports

配置字段

发送给 SDK 的 intent：

{
  "tool": "shell",
  "arguments": { "command": "rm -rf /" }
}

SDK 还会收到 context.tool_name，用于策略和审计上下文。

---

运行测试

npm install
npm run typecheck
npm test
npm run build

隔离的 Vitest 测试使用 mock Cordis context 和 mock RamenClient， 不发送网络请求，也不需要凭据。覆盖配置验证、已验证的 allow/deny、steering、 transport 失败、取消、收据缺失或无效、payload 结构以及审计模式 delegation。

---

可用 bundles

自定义策略请使用显式 policyIds。Bundle 和 policy 详情见 ramenai.dev/pricing。

---

限制

• DeepSeek Harness 仍处于 developer preview，plugin API 可能发生破坏性变更。 已测试的 peer 版本固定在 package.json 中。
• 每次工具执行前都会增加一次网络往返。
• 审计模式仅用于可观测性，不构成执行边界。
• BYOK 账户必须提供 providerKey；托管推理账户省略该字段。
• 本插件只治理进入 Harness 工具 pipeline 的调用，不治理 pipeline 之外或其他进程中的动作。
• 这是非官方社区集成。DeepSeek 不审核或推荐其策略行为、安全保证或发布流程。