onlyqzq/dsh-riskproof

RiskProof

让你看见 AI 读了什么来源、拦下了什么风险、操作最终是否执行。

DSH 原生安全账单与数据溯源。敏感数据外发前拦截，给每次工具调用留下可解释的执行证据。

English · 简体中文

从这里开始

| 你的目标 | 入口 |
| --- | --- |
| 安装并开始使用 | 快速开始 · 安装与首次使用 |
| 调整防护模式、规则和任务范围 | 配置参考 |
| 理解项目结构或参与开发 | 架构与模块职责 · 开发指南 |
| 查找验收记录、版本设计和安全边界 | 文档导航 |

在对话旁，看见防护正在工作

安装后，DSH 右下方常驻 RiskProof 安全浮标。正常聊天无需输入任何命令：
工具调用发生后，浮标自动更新检查与拦截状态；点击浮标才展开安全概览。

DSH 中的常驻安全浮标

- 空闲时待命：等待真实工具调用，不播放持续扫描动画。
- 调用时反馈：等待执行回执时显示工作状态，新检查完成后短暂反馈。
- 风险可追溯：点击查看调用分布圆环、最近 24 次活动及最多 3 条风险来源链。
- 会话独立：切换对话立即切换记录；连接中断时隐藏旧图表并提示等待同步。
- 状态明确：首次同步、断线重连分别提示；概览显示任务范围和统计边界，断线时可手动重连。

当前对话的调用分布与风险来源链

真实 DSH Web 界面；截图数据由本地测试模型驱动真实工具管线产生。插件日常使用无需模拟演练。

图表展示“未触发风险 / RiskProof 拦截 / 需要关注”，不生成安全评分。
观察模式明确显示“不主动拦截”；记录关闭或部分检测停用时也会提示。
统计仅覆盖本次运行仍保留的当前会话记录，未触发规则不等于绝对安全。

以下命令保留为辅助入口；完整文字默认折叠，日常使用直接点击浮标即可。

| 需要做什么 | DSH 命令 |
| --- | --- |
| 打开安全概览 | /riskproof |
| 查看文字来源记录 | /riskproof trace |
| 限制为只读任务 | /riskproof task read-only |
| 限制为本地任务 | /riskproof task local-only |
| 恢复常规任务范围 | /riskproof task standard |
| 可选的四项模拟演练 | /riskproof demo |

也可让模型调用 riskproof_report 查看原生工具结果卡。浮标通过 DSH 自带的认证连接读取
脱敏统计，页面可见时约每秒更新，不调用模型、不增加工具记录、不消耗模型 token。

RiskProof 回答的问题

大多数工具权限插件只回答一个问题：这个工具允许调用吗？

RiskProof 回答另一个问题：

这次工具调用里的数据从哪里来、经过了哪些工具、现在准备流向哪里？

单次工具调用通常安全，但组合起来就不一定了。

web_fetch          ← UNTRUSTED_WEB
│
database_query     ← CUSTOMER_DATA
│
send_email         ← 外部目的地
│
RiskProof → DENY   （有证据、在副作用发生之前）

为什么是 RiskProof

| 权限规则                  | RiskProof                        |
| ------------------------- | -------------------------------- |
| 这个工具允许吗？          | 这些数据从哪里来？               |
| 单次调用                  | 跨工具数据流                     |
| 工具名                    | 来源（Provenance）+ 污点（Taint）|
| 静态规则                  | 有状态的攻击链                   |
| 权限决策                  | 有证据支撑的执行决策             |

RiskProof 是 DSH Tool Runtime 之上的一层安全策略，而不是另一套 Agent Runtime。它从不重复实现工具分发、审批或生命周期——它只观察并裁决。

快速开始

需要 Node.js 22.19+，并已安装 DSH 和 pnpm。安装或更新：

dsh plugin --profile web add dsh-riskproof@0.4.1

也可在本仓库根目录构建本地安装包：

在本仓库中构建并安装
npm ci
mkdir -p artifacts
npm pack --pack-destination artifacts
dsh plugin --profile web add ./artifacts/dsh-riskproof-0.4.1.tgz

确认包内 patch 已被组合
dsh --profile web --dump-config

该包声明了 DSH bundle，plugin add 自动组合 riskproof 行。重启该 profile 后，即可看到常驻安全浮标；点击查看当前对话概览。支持原生命令的界面也可通过 / 搜索 RiskProof。

当前版本为 0.4.1。完整步骤见 安装与更新。
已验证 DSH 0.1.0-rc.7 与 0.1.2-rc.1 的安装、SDK 宿主启动、命令和工具管线；DSH 0.1.2-rc.1 的 Chrome 桌面与窄屏 Web 验收已通过，含真实 Agent 工具管线的来源拦截和只读拦截（本地模拟模型驱动）。详见 验收记录 和 Web 操作步骤。

如需调整，可在随后加载的 profile cordis.patch.yml 中覆盖 bundle 行：

- id: riskproof
config:
mode: enforce            # enforce | observe
policy:
preset: balanced         # permissive | balanced | strict
internalDomains: [acme.internal]
blockedDomains: [collector.evil.example]
allowedExternalDomains: [api.approved.example]
classification:
overrides:
gmail_send: [EXTERNAL_ACTION]
company_db: [PRIVATE_ACCESS]
output:
blockedTaints: [SECRET, API_KEY]
trustedDeclassifiers: { approved_redactor: [PII] }

完整配置参考见 docs/configuration.md。

效果演示

sequenceDiagram
participant A as Agent
participant T as DSH ToolRuntime
participant R as RiskProof

A->>T: web_fetch(url)
T->>R: tools/pre-execute
R-->>T: allow（记录 EXTERNAL_INGESTION）
T-->>A: 不可信内容

A->>T: database_query(sql)
T->>R: tools/pre-execute
R-->>T: ask（操作者批准私密数据访问）
T-->>A: CUST-8842 balance 125000

A->>T: send_email(to=external, body=CUST-8842…)
T->>R: tools/pre-execute
R-->>T: DENY —— 摄入 + 私密访问 + 敏感数据 + 外部动作
T-->>A: Error:

同样的流程被做成确定性的回归测试，见 tests/security/attack-chain.test.ts。

无需配置模型或 DSH profile，也可以在安装依赖后运行本地演示：

npm run demo

演示通过真实 DSH 工具管线运行三个模拟工具，见 演示说明。

功能

追踪数据来源

知道工具输入从哪里来。RiskProof 会把参数映射回产生它们的工具结果。

跟随敏感数据

让安全标签——UNTRUSTED_WEB、CUSTOMER_DATA、PII、SECRET 等——以加法方式跨工具传播。

控制敏感输出

在 tools/post-execute 检查模型可见的工具结果；默认在结果进入模型上下文前拦截 SECRET 与 API_KEY。

通过固定工具可信降密

只有操作者按精确名称批准的工具才能移除指定继承标签。结果正文若仍命中敏感特征，标签会被重新加回，因此降密工具必须真正移除敏感数据。

发现攻击链

识别 EXTERNAL_INGESTION → PRIVATE_ACCESS → EXTERNAL_ACTION 这一单工具检查发现不了的模式。

在副作用前拦截

通过原生 tools/pre-execute 门，在副作用执行前拦截或询问。

保护敏感操作面

在执行前检查凭据文件路径、高置信破坏性命令、下载后直接执行的管道、被阻止的目的地，以及网络命令中携带的凭据。

按场景调整策略

默认使用 balanced，初次上线可选 permissive，高安全环境可选 strict；每个可配置裁决仍可单独覆盖。

解释每一次决策

为每一次裁决生成结构化、保护隐私的安全证据和可执行处置建议；proof 既可保留在内存中，也可追加到操作者管理的 JSONL 文件。

工作原理

RiskProof 接入原生 DSH 工具管线：

tools/pre-execute
│  能力分类
│  参数来源映射
│  污点分析
│  工具链状态（EIT → PAT → NAT）
│  确定性策略评估
▼
allow / ask / deny   （与其他插件单调合并）
│
工具执行
│
tools/post-execute
│  输出污点评估
│  可信降密
▼
accept / block
│
tools/result
│  更新 ContextTracker
│  更新工具链状态
▼  记录执行证据

- 分类是确定性的（工具名 + 描述 + schema）、可配置的，且从不使用 LLM。
- 来源追踪使用精确和带边界的子串匹配，基于每个会话的上下文索引。
- 污点是加法的；只有操作者精确批准的降密工具可移除指定继承标签。
- 决策是确定性、可解释、可测试的。

详见 docs/architecture.md。

安全边界

RiskProof 保护的是 DSH 中可观测的工具调用流：

- 经过 tools/pre-execute / tools/post-execute / tools/result 支持路径的 DSH 工具调用
- 可观测的来源追踪（精确 / 带边界子串匹配）
- 配置的敏感数据流与跨工具攻击模式

RiskProof 不能替代：

- OS 沙箱 / 进程隔离
- 网络防火墙 / SSRF 防护
- 端点安全 / 恶意软件扫描
- 凭据保险库
- 完整语义 DLP

完整威胁模型与已知局限见 docs/security-model.md。

文档

完整目录见 文档导航，按使用、开发、安全设计和版本记录分组。

- 使用：安装 · 配置 · Web 验收步骤
- 开发：架构 · 开发指南
- 安全：安全模型 · 来源与污点 · 工具链

路线图

v0.2（已完成）

- DSH 原生运行时（tools/pre-execute、tools/result）
- 来源 + 污点追踪
- 跨工具 EIT → PAT → NAT 检测
- 保护隐私、可选 JSONL 持久化的 proof
- 策略预设、敏感路径门控、确定性危险命令检测和出口域名策略
- 处置建议与按规则聚合的 proof 统计

v0.3（已完成）

- 原生安全账单、来源时间线、无副作用演练与中英文报告
- 工具元数据身份连续性：描述、输入／输出 schema 变化时拒绝
- 操作者设定的任务约束：standard / read-only / local-only
- 按执行 token 关联门控与最终结果的回执
- 中间工具结果继承敏感标签；会话隔离与有界状态

v0.4（当前版本）

- 在结果进入模型上下文前执行输出侧信息流控制
- 默认拦截凭据输出，并允许配置需拦截的标签
- 按精确工具名配置可信降密，结果仍敏感时确定性重新加标
- 在回执中记录脱敏后的输出控制与降密信息

后续

- 更丰富的结构化／语义 DLP 适配
- 带显式信任边界的跨进程来源追踪

贡献

欢迎提交 Issue、规则、工具能力映射和误报报告。见 CONTRIBUTING.md。

安全报告

请私下报告漏洞。见 SECURITY.md。

License

Apache-2.0