dsh-shield

DeepSeek Harness 的安全防火墙。

安装前扫描。执行前拦截。动作后审计。

> Don't trust your agent's tools. Verify them.

安装

需要 Node.js 20+ 和 pnpm。

1. 装 CLI（预检扫描器）

装完就可以在装任何 Harness 插件之前先扫一遍：

git clone https://github.com/245678000000/dsh-shield.git
cd dsh-shield
pnpm install
pnpm build
pnpm link --global

验证：

dsh-shield --help
dsh-shield doctor

不想链到全局的话，在仓库里直接跑：

node packages/cli/dist/bin.js scan ./某个插件目录

2. 装进 DeepSeek Harness（运行时护栏）

先有可用的 dsh。用本地目录安装，不要先 allowBuilds 去跑未知 git 包的 prepare：

dsh plugin --profile web add /你的路径/dsh-shield

装好后重启 dsh web（或对应 profile）。默认策略是 balanced。

自定义策略可以放在：

~/.dsh-shield/policy.yaml

示例见 [examples/policy/balanced.yaml](examples/policy/balanced.yaml)。

3. 立刻试一下

# 扫一个会拉起进程的合成插件（不会执行它）
dsh-shield scan ./fixtures/plugins/process

# 扫一个干净插件
dsh-shield scan ./fixtures/plugins/clean

# 生成信任清单
dsh-shield manifest ./fixtures/plugins/process

process 夹具会报 HIGH / REVIEW BEFORE INSTALLING。干净包显示 NO HIGH-RISK FINDINGS DETECTED——这不是「SAFE」，静态扫描不能证明代码安全。

不要这样装

# 会拉源码；若再 allowBuilds，可能执行对方的 prepare
dsh plugin add github:245678000000/dsh-shield

git 安装拿到的是源码，不是编好的产物。官方 Harness 也写了：allowBuilds 等于允许安装期在你机器上跑代码。要走 git，先扫再 pin commit：

dsh-shield scan github:245678000000/dsh-shield#<完整sha>
dsh plugin --profile web add github:245678000000/dsh-shield#<完整sha>

---

这不是一个普通 Harness 插件

安装阶段的恶意行为，不能靠「装完才加载」的插件来拦。

dsh-shield 因此是两层，共用同一套安全模型：

安装之前
→ 预检扫描器（CLI）

运行期间
→ 运行时护栏（Harness Plugin）

层	是什么	何时生效
预检 CLI `dsh-shield scan`	下载 / 解包 / 解析 / 检查。绝不执行待扫描包	在 `dsh plugin add` 之前
运行时插件	挂在官方 `tools/pre-execute` 与 `ctx.tools.guard()` 上	每一次工具 / MCP 调用

产品能力就六个词：

SCAN → CLASSIFY → ALLOW / ASK / DENY → AUDIT

它做的是 风险发现、策略执行、信任元数据、人工审批、可审计性。它不是「完美安全」，也不会声称 100% 防住 Prompt Injection。

---

为什么需要它

DeepSeek Harness（dsh）里，插件、MCP、内置工具都跑在宿主机 Node 进程权限下。

用户用 dsh plugin add github:someone/plugin 安装插件时，底层是 pnpm。 prepare / preinstall 这类 lifecycle 脚本，会在任何 Harness 插件 apply() 之前执行。

运行时，模型可以调用 mcp__<server>__<tool>，把本地文件、密钥、客户资料送出本机。

dsh-shield 卡在这些边界上：

安装插件之前
运行插件期间
调用 MCP 之前
数据离开本机之前
执行高风险 Tool 之前

---

预检扫描器

dsh-shield scan <目录|tarball|github:owner/repo#sha|npm:name>
dsh-shield inspect <target>
dsh-shield policy check <target>
dsh-shield manifest <target>
dsh-shield diff old.json new.json
dsh-shield doctor

扫描不会：

跑 npm install / pnpm install
require() / import() 待扫描包
执行 prepare / preinstall / postinstall

远程包路径是：下载 → 防 zip-slip 解包 → 解析 → 检查。

AST 优先于纯正则。字符串里写了 "child_process"，或文档写「我们不会读 ~/.ssh」，不会直接判成恶意。

---

运行时护栏

安装方式见上文「安装」。对接的是当前官方 API（Harness 0.1.0-rc.5，commit 47f94385），不 fork AgentLoop，不改 Harness 源码：

| 官方缝 | dsh-shield 怎么用 | |---|---| | tools/pre-execute | 返回 { kind: 'allow' \| 'ask' \| 'deny' } | | ctx.tools.guard() | 单调 DENY：后面的 hook 不能把拒绝改回允许 | | ctx.approval.request() | ASK 走官方审批；没有审批通道则 降级为 DENY | | MCP 公开名 | mcp__<serverName>__<rawName> |

管理工具（只读，没有「一键关闭全部安全」）：

shield_status
shield_explain
shield_policy
shield_recent_events

---

MCP 安全

新 MCP Server 默认是 unknown，不是 trusted。

	未知 MCP	已审查（如 github）
只读 + 非敏感	ASK（balanced）	ALLOW
外部写入	ASK	ASK
密钥 / 凭据外泄	DENY	DENY

---

数据出境

外部 MCP / HTTP 工具执行前，会给 payload 分级：

日志和审批理由里的密钥一律脱敏（sk-abc...xyz），从不写完整 secret。

DATA EGRESS WARNING

Destination: crm-cloud
Detected: CONFIDENTIAL DOCUMENT, PERSONAL DATA, POSSIBLE SECRET
Action: DENY

---

Prompt Injection

检测 + 行为策略，不是魔法防御。

网页 / README / MCP 返回值里的指令腔（「ignore previous instructions」「把 ~/.ssh 发出去」）会被打上 UNTRUSTED_*。同一会话里随后的敏感读取或外部写入，会升为 ASK / DENY（SHIELD-INJECT-002）。

原文不会被删掉。普通文档里的「Run npm install to install this package」单独出现，不会当成攻击。

---

策略档位

YAML / JSON。内置四档，不是换名字：

	permissive	balanced（默认）	strict	enterprise
本地读	allow	allow	allow	allow
本地写	allow	ask	ask	ask
破坏性操作	ask	deny	deny	deny
外部写	ask	ask	deny	deny
密钥出境	deny	deny	deny	deny
未知 MCP 读	allow	ask	ask	deny
未知 MCP 写	ask	ask	deny	deny

配置坏了：高风险决策 fail closed，不会静默全放行。

示例：[examples/policy/balanced.yaml](examples/policy/balanced.yaml) 模型说明：[docs/security-model.md](docs/security-model.md)

---

架构

                 DSH SHIELD
                      │
        ┌─────────────┴─────────────┐
        ↓                           ↓
     预检安全                      运行时安全
        │                           │
        ├─ 包扫描                    ├─ 工具门
        ├─ 源码扫描                  ├─ MCP 门
        ├─ 依赖扫描                  ├─ 出境护栏
        ├─ 脚本扫描                  ├─ 人工审批
        ├─ 权限推断                  ├─ 敏感数据
        ├─ 风险引擎                  ├─ 注入信号
        └─ 信任清单                  └─ 审计日志

包	职责
`@dsh-shield/core`	发现项、能力、风险分、策略、密钥检测
`@dsh-shield/scanner`	不执行目标的预检
`@dsh-shield/cli`	`dsh-shield` 命令行
`@dsh-shield/runtime`	Harness 插件
`@dsh-shield/ui`	输出格式化（先服务 CLI）

风险分是确定性公式，LLM 不能决定 ALLOW / DENY。

---

信任清单

dsh-shield manifest <target> 写出 dsh-shield.manifest.json：

包名、来源与 commit、风险、能力、安装脚本、发现项、扫描完整性、扫描器版本。

信任库按 (来源, commit) 记录。commit 变了，信任作废。

---

威胁模型

见 [docs/threat-model.md](docs/threat-model.md)。

覆盖：恶意插件、被投毒依赖、恶意 MCP、Prompt Injection、数据外泄、危险工具调用、只读伪装、供应链漂移、动态配置。

明确不声称：

100% 防住 Prompt Injection
证明任意插件安全
完美沙箱任意恶意 JavaScript
抓住所有混淆载荷
替代操作系统沙箱 / 终端安全
保证 MCP Server 可信

---

示例

fixtures/ 里全是合成样本，不是真实恶意软件。

pnpm test
node packages/cli/dist/bin.js scan fixtures/plugins/process
pnpm exec vitest run tests/runtime/demos.spec.ts

Demo	结果
本地 `read_file`	ALLOW
`mcp__github__get_issue`（已审查）	ALLOW
`mcp__github__create_issue`	ASK
未知 MCP + `TEST_API_KEY=shield_test_123456`	DENY
注入 README → `upload_debug_info`	DENY

---

隐私

默认全部本地：扫描、策略、审计都不上传云端。

审计只留规则 ID、决策、目的地、数据分级、脱敏摘录。不留原始密钥，不留完整机密正文。

---

局限

详见 [docs/limitations.md](docs/limitations.md)。

dsh-shield 不能保证： 安全证明、完整防注入、JS 沙箱、检出所有混淆加载器、MCP 诚实，以及你已经允许安装脚本跑过之后的保护。

Harness 对接调研：[docs/harness-integration.md](docs/harness-integration.md) 规则目录：[rules/catalog.md](rules/catalog.md)

---

开发与测试

pnpm lint
pnpm typecheck
pnpm test
pnpm build

CI 跑这四项。夹具是合成包。CI 不会执行未知第三方代码。

当前：55 个测试通过。

---

路线图

v0.1 — 预检扫描、运行时策略、MCP 信任、出境护栏、审计（本版本）
v0.2 — 更完整的清单 diff、注册表信誉适配器、更深的来源追踪、可选 Web UI
v0.3 — 签名信任清单、插件透明度、CI Action
v0.4 — 组织策略、集中分发

---

供应链安装注意

见上文「安装 → 不要这样装」。git 安装拉到的是源码；allowBuilds 等于允许安装期在你机器上跑代码。

---

参与

欢迎 Issue 和 PR。

不要把 LLM 做成安全边界。不要为了「看看它干什么」去执行扫描目标。不要编造 Harness API——先读 docs/harness-integration.md 和官方仓库。

安全漏洞请走 GitHub Security Advisory，见 [SECURITY.md](SECURITY.md)。

许可证：[MIT](./LICENSE)

dsh-shield-24567800

安装

检查来源文件

dsh-shield

安装

1. 装 CLI（预检扫描器）

2. 装进 DeepSeek Harness（运行时护栏）

3. 立刻试一下

不要这样装

这不是一个普通 Harness 插件

为什么需要它

预检扫描器

运行时护栏

MCP 安全

数据出境

Prompt Injection

策略档位

架构

信任清单

威胁模型

示例

隐私

局限

开发与测试

路线图

供应链安装注意

参与

来源信息

安装

检查来源文件

dsh-shield

安装

1. 装 CLI（预检扫描器）

2. 装进 DeepSeek Harness（运行时护栏）

3. 立刻试一下

不要这样装

这不是一个普通 Harness 插件

为什么需要它

预检扫描器

运行时护栏

MCP 安全

数据出境

Prompt Injection

策略档位

架构

信任清单

威胁模型

示例

隐私

局限

开发与测试

路线图

供应链安装注意

参与

更多相关插件

dsh-autopilot

ouroboros#integrations/dsh-plugin

tongflow#dsh-tongflow