dsh-secret-scrub

English | 中文 | 更新日志

不可逆的密钥脱敏守护插件，源自 kaya-ai-terminal 项目的用户敏感信息保护策略，现独立开源（大陆官网：https://www.yunhouai.com；非大陆地区官网：https://www.yunhou.ai）。它在文本流向会话日志和模型请求的路上进行改写：当配置的规则命中形似密钥的片段——访问密钥、Bearer 令牌、私钥块——该片段会被不可逆地替换为 [REDACTED:<category>] 占位符，使持久日志和模型请求在被覆盖的位置只携带占位符。

安装

npm install dsh-secret-scrub

运行时依赖为 @deepseek-ai/cordis(peer）和 @deepseek-ai/schemastery。@deepseek-ai/dsh-* 系列 peer 包仅为类型依赖且可选。

在 dsh profile 中使用

本包声明了 dsh.bundle.patch，一条命令装完即用（默认 balanced 级别脱敏，无需任何凭据）：

# 1. 安装 dsh CLI
npm i -g @deepseek-ai/dsh

# 2. 把插件装到目标 profile 里（以 headless 为例）
dsh plugin --profile headless add dsh-secret-scrub
#    发布前想测试本地改动，可用 npm pack 生成的 tarball：
#    dsh plugin --profile headless add /path/to/dsh-secret-scrub-0.1.2.tgz

# 3. 重启该 profile 后，运行包含敏感信息的任务——密钥会在进入模型/会话日志前被脱敏
dsh --profile headless "echo AWS AKIAIOSFODNN7EXAMPLE"

dsh plugin add 会自动应用包内的 cordis.patch.yml（以 balanced 级别挂载插件）。想调整级别或追加自定义规则，可在 profile 补丁层 ~/.dsh/profiles/headless/cordis.patch.yml 中覆盖同 id 的配置：

- id: secret-scrub
  config:
    level: aggressive
    extra:
      - category: internal-token
        pattern: 'internal-[0-9]{4}'

作为独立 Cordis 插件使用

如果你不使用 dsh，也可以直接挂载到 Cordis Context 上：

import { Context } from '@deepseek-ai/cordis'
import * as SecretScrub from 'dsh-secret-scrub'

const ctx = new Context()
await ctx.plugin(SecretScrub, {
  level: 'aggressive',               // 脱敏深度:minimal | balanced(默认)| aggressive
  disabled: ['env-var-secret'],      // 仅限 tier 1/2 内置类目——tier 0 不可禁用
  extra: [
    { category: 'internal-token', pattern: 'internal-[0-9]{4}' },
  ],
})

插件挂载三个前置的 waterfall 监听器，先委托下游，再对链路最终采纳的内容脱敏：

• agent/pre-step 改写每个 step 采纳的用户消息，然后才进入会话日志和模型请求。用户消息按 inputLevel 脱敏——默认 aggressive，与 level 无关——即使工具输出保持较低级别，粘贴进来的 PII 和密钥也会按全量规则表处理。
• tools/post-execute 改写被接受的工具结果的纯文本内容。
• tools/ptc-dispatch-log 改写 run_code 子调用的 tool/code-dispatch 持久化副本。

| 字段 | 默认值 | 含义 | |---|---|---| | level | balanced | 工具输出的脱敏深度：minimal 只跑 tier 0,balanced 加 tier 1,aggressive 加 tier 2——PII 与高熵兜底 | | inputLevel | aggressive | agent/pre-step 采纳的用户消息的脱敏深度，独立于 level | | disabled | [] | 关闭指定的 tier 1/2 内置类目；tier-0 核心规则不可禁用，禁用会在加载时报错 | | extra | [] | 部署方追加的规则，在所有级别下生效：全局唯一的小写连字符 category 加上以 new RegExp(pattern, 'g') 编译的 pattern |

无效配置在启动时即以明确的错误失败——未知或 tier-0 的 disabled 类目、无法编译的 extra 正则、不能出现在占位符中的类目 id、重复类目——绝不静默回退。

内置规则分级

level 选择生效的最高 tier。tier 0–1 为前缀锚定，tier 2 按形状匹配（规则见 src/rules.ts):

| Tier | 生效级别 | 类目 | |---|---|---| | 0 — 核心密钥 | 所有级别；不可禁用 | private-key、private-key-truncated（截断 PEM 护甲）、api-key（通用 apikey 赋值）、aws-access-key、github-token、google-api-key、deepseek-key、openai-key、anthropic-key、gitlab-pat、rollbar-token、stripe-key、slack-token、slack-signing-secret、slack-webhook-url、npm-token、pypi-token、sendgrid-key、twilio-key、digitalocean-token、shopify-token、telegram-bot-token、tavily-key、age-secret-key、docker-pat、notion-token、supabase-token、linear-api-key、generic-sk-key(sk-/sk_ 兜底)、url-credentials（连接串 authority)、url-access-token(OAuth 回调令牌)、generic-bearer(Bearer 令牌与 JWT) | | 1 — 赋值与云厂商密钥 | balanced 及以上 | env-var-secret（名称以 _ 分段整体包含 KEY/SECRET/TOKEN/PASSWORD 的大写赋值）、azure-storage-key、alibaba-access-key、key-assignment（任意大小写的同类赋值形状，带取值过滤） | | 2 — PII 与高熵兜底 | 仅 aggressive | email、phone-cn、phone-intl、id-cn、credit-card(Luhn 校验)、ssn-us、high-entropy |

直接使用引擎

纯脱敏引擎从 dsh-secret-scrub/rules 导出，不依赖 Cordis:

import { BUILTIN_RULES, scrubText } from 'dsh-secret-scrub/rules'

const { text, redactions } = scrubText('key: AKIAIOSFODNN7EXAMPLE', BUILTIN_RULES)
// text       → 'key: [REDACTED:aws-access-key]'
// redactions → { 'aws-access-key': 1 }

已知限制

脱敏是单向的、基于正则的。无前缀密钥、跨文本块拆分的密钥、编码形式（base64 包裹、URL 转义）按设计会绕过保守的规则形状。tier-2 规则匹配的是形状而非确凿的密钥，因此以误报换覆盖——任务说明中的邮箱会被当作密钥脱敏，哈希状文本（git SHA、SHA-256 摘要）在 aggressive 级别会命中 high-entropy 兜底。不要把本守护当作防止凭证泄漏的唯一手段。

开发

npm install
npm run typecheck
npm test
npm run build

许可证

MIT — Copyright (c) 2026 jkt-check