ben7am1n/dsh-security-scan

dsh-security-scan

DeepSeek Harness 的密钥与危险模式扫描器 —— 一个 security_scan 工具，遍历你的文件并报告泄露的 API 密钥、令牌、私钥以及携带凭据的连接字符串。零运行时依赖（纯 Node 内置模块）。

概述

dsh-security-scan 为 harness 提供了一个面向模型的安全卫生工具。将它指向一个代码检出目录（或你的整个工作区），它就能找出那些本不该被提交的密钥——然后以脱敏方式报告它们，因此原始密钥材料永远不会进入模型上下文或日志。

它适合谁？

- 任何曾经推送过 .env 或将令牌粘贴进配置文件的人。
- 希望在提交前、或在将仓库交给 agent 之前，拥有一个廉价、内置的密钥闸门的团队。
- 想要一份可读的参考来编写面向模型的工具插件的开发者（裸 ToolDefinition，无框架）。

它能检测什么

| 类型 | 模式（示例） |
|---|---|
| AWS 访问密钥 | AKIA + 16 个 base62 字符 |
| GitHub 令牌 | ghp_ + 36 个字符 |
| OpenAI 风格密钥 | sk- + 20+ 个字符 |
| Bearer 令牌 | 通用的 Bearer 内联凭据 |
| 私钥 | -----BEGIN ... PRIVATE KEY----- 块 |
| 数据库连接字符串 | 内嵌密码的 mysql:// / postgres:// / mongodb:// |
| 危险文件 | 含可疑值的 .env；.pem / .key / .p12 产物 |

它（目前）不做什么

- 不扫描 git 历史，不做修复，不做网络检查。这是一个文件系统扫描器，不是完整的安全审计套件。
- 没有 tools/pre-execute 强制闸门（计划中：阻止会重新引入已知密钥的写入）。参见开发。

兼容性

- 需要 Node.js ≥ 22.19（仅使用 node:fs/promises 和不依赖全局 fetch 的内置模块）。
- 基于 @deepseek-ai/dsh@0.1.0-rc.6 / @deepseek-ai/cordis@^4.0.1 构建并验证。
- 最后验证： 2026-08-14。
- dsh 处于开发者预览阶段；harness 更新后请重新验证。该插件仅依赖 ctx.tools.register（一个稳定的扩展点）和 @deepseek-ai/dsh-tools 类型。

安装 / 卸载

安装到 dsh profile（本地检出）：

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-security-scan

从 GitHub 安装（源码安装——pnpm 会运行 prepare 脚本，因此需允许一次）：

pnpm dsh plugin --profile web add github:/dsh-security-scan
pnpm ≥10 会在首次安装时阻止构建脚本；将打印出的包键
复制到 /pnpm-workspace.yaml 的 allowBuilds 下，然后重新运行。

卸载：

pnpm dsh plugin --profile web remove dsh-security-scan

快速开始

安装该 bundle，然后让 agent：

Run security_scan on this repository and summarize the high-severity findings.

或直接通过 harness 工具触发它。默认行为：扫描 .（相对于 harness 的 cwd），跳过 node_modules/.git/dist/build，跳过超过 1 MB 的文件，每个文件最多报告 10 条发现。
示例输出形态（机密已脱敏）：

[HIGH] github-token        config/keys.ts:12  ghp_ab12yz
[HIGH] private-key         deploy/keys.pem (file artifact)
[LOW]  db-connection-string src/db.ts:88      postgres://user:*@host/db
Scan complete: 412 files scanned, 3 findings (HIGH: 2, LOW: 1)

配置

所有键都位于 dsh-security-scan 行的 config 下：

| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
| paths | string[] | ['.'] | 要扫描的目录（相对于 harness cwd）。 |
| ignored | string[] | ['node_modules','.git','dist','build'] | 遍历期间跳过的目录基名。 |
| maxFileSizeBytes | number | 1048576 | 大于此大小的文件将被跳过。 |
| maxMatchesPerFile | number | 10 | 每个文件报告的最大发现数。 |

权限与数据

- 只读： 扫描器只读取文件；它从不写入、编辑或删除。
- 脱敏： 每个匹配到的机密在离开扫描器之前都会被掩码处理（显示前 4 个 / 后 2 个字符）。原始密钥材料不会进入模型上下文或日志。
- 范围： 扫描被限制在配置的 paths 内，并遵守忽略列表；它不会跟随符号链接离开目录树。
- 无网络： 检测完全是本地正则扫描；不会上传或发送到任何地方。

故障排查

| 症状 | 原因 | 修复 |
|---|---|---|
| 工具报告扫描到零个文件 | paths 指向相对于 harness cwd 不存在的目录 | 使用绝对路径或从预期目录运行 |
| 对示例密钥产生误报 | 测试夹具通常包含占位密钥（AKIAIOSFODNN7EXAMPLE 是 AWS 文档中的示例） | 手动审查发现；该工具只报告，不判断意图 |
| 在超大仓库上扫描缓慢 | 对大量文件执行正则 | 扩大 ignored 覆盖范围（例如添加 vendor、third_party）或减少 paths |
| 模型看不到 security_scan | 插件加载时未包含 tools 服务 | 验证已安装的 lib/index.js 中存在 inject: ['tools']（编辑后重新构建） |

开发

pnpm install
pnpm run typecheck     # tsc --noEmit
pnpm run build         # tsc → lib/
pnpm run test          # vitest (19 tests)

结构：

- src/index.ts — 插件入口、扫描器以及 security_scan 工具；检测正则和脱敏辅助函数被导出以供单元测试使用。
- tests/ — 脱敏、忽略目录和检测词汇覆盖。
- cordis.patch.yml — 挂载插件行的 bundle 补丁层。

设计说明：

- 检测有意基于正则且保守——宁可标记误报，也不愿漏掉真正的机密。将新模式添加为新的 SecretKind，并在测试中固定它们。
- 路线图：一个 tools/pre-execute 强制执行门（拒绝重新引入已知机密的写入）以及 git 历史扫描。

许可证与安全
麻省理工学院。请通过仓库的安全公告私下报告安全问题（或在不包含机密信息的情况下提交 issue）。扫描器完全在操作员的机器上运行，具有只读访问权限；它不会向任何地方发送任何内容。