@deepwhale-cn/dsh-env-audit
在你把密钥提交进 git 之前，先看一眼 .env 本身。
关键词：配置文件审计 · .env 检查 · 密钥进 git · 文件权限 · 明文密码 · gitignore · 环境变量 · .env.example · 配置与代码分离
先说清楚它是什么、不是什么
是：只盯环境配置文件本身的四件事 —— 会不会被提交、权限宽不宽、里面是不是明文、有没有模板。
不是：
- ❌ 不是密钥扫描器 —— 扫代码里的密钥字面量（
sk-...、AKIA...）是 dsh-secret-scan 的活
- ❌ 不是密钥管理工具 —— 它不存密钥、不轮换、不加密
- ❌ 不是运行时防护 —— 不拦读取，只做静态审计
- ❌ 不下「安全 / 不安全」的结论 —— 只描述事实，判断留给你
一句话分界：
secret-scan = 代码里有没有写死密钥
env-audit = 配置文件本身有没有把密钥暴露出去
它查什么（5 条）
| 规则 | 查什么 | 级别 |
|---|
ENV-NOT-IGNORED | .gitignore / .git/info/exclude 里没有忽略 .env，而项目里有凭据型环境配置 | 🔴 |
ENV-PLAINTEXT | .env 里 PASSWORD= / SECRET= / TOKEN= / API_KEY= 跟的是明文而非占位符 | 🔴 |
ENV-FILE-PERM | .env 权限宽于 600（同机器其他用户可读） | 🟡 |
ENV-NO-EXAMPLE | 有环境配置内容，却找不到 .env.example / .env.sample 模板 | 🔵 |
ENV-HARDCODED-CONFIG | 源码里硬编码内网/私有网段地址或 .internal 主机名 | 🔵 |
每条都会给出：哪个文件、第几行、证据、依据（可查证的标准/文档）、以及怎么办。
安装
dsh plugin --profile web add @deepwhale-cn/dsh-env-audit
用法
# 审计当前目录
dsh-env-audit
# 审计指定目录
dsh-env-audit --root /path/to/project
# 看内置演示（一个「.env 没忽略 + 644 + 明文密码 + 没有模板」的项目）
dsh-env-audit --demo
# 列出规则与依据
dsh-env-audit --list-rules
# 出 HTML 报告（可截图归档）
dsh-env-audit --root . --html env-audit.html
# 挂 CI：有 high 命中时退出码 1
dsh-env-audit --quiet --json
一个真实的例子
--demo 那个样本项目的一切看起来都很正常：有 package.json、有 src/、有 .gitignore。
dsh-env-audit 看见的：
🔴 .gitignore 没忽略 .env，且有凭据型环境配置 .gitignore
🔴 .env 明文：DB_PASSWORD= （报告只到等号为止） .env:10
🔴 .env 明文：STRIPE_SECRET_KEY= .env:14
🔴 .env 明文：JWT_SECRET= .env:15
🔴 .env 明文：SMTP_PASSWORD= .env:16
🟡 .env 权限 644 超过上限 600 .env
🔵 有凭据型环境配置，却找不到 .env.example 模板 .env.example
🔵 源码硬编码内网地址 10.0.3.12 src/db.js:4
这 8 条，git add . 之前就能看见。
关于「明文」这条规则的两个设计取舍
- 报告里不会出现你的密钥值。 正则只吃到
KEY= 为止，值是用零宽断言「验证存在」的 —— 所以证据栏永远是 DB_PASSWORD= 这个样子。工具自己不能变成泄露源。
- 占位符不算。
空值、${DB_PASSWORD}、<generate-with-openssl-rand>、your_xxx、changeme、xxx、test、example 这类写法会被跳过。
边界（说清楚做不到什么）
- 不知道
.env 是不是「已经」提交过 —— 核心引擎是离线文件扫描，不读 git 索引。规则报的是「当前 .gitignore 没忽略它」，以及「忽略它不等于已提交的历史被清掉」。已提交过的情况请用 git log --all -- .env 自查。
- 权限规则只在 POSIX（Linux/macOS）上有意义 —— Windows 没有这套权限位；若在 Windows 上跑，
600 的比较结果不可用。
ENV-NOT-IGNORED 和 ENV-NO-EXAMPLE 有「适用门槛」 —— 引擎的 when 门槛是「某处存在形如 ...PASSWORD= / SECRET= / TOKEN= / API_KEY= / CREDENTIAL= 的赋值行」。带来两个后果：
- 只写小写键名、或只含
NODE_ENV / PORT 这类无凭据项的环境文件，不会触发这两条（报告里会标为「因不适用未运行」）
- 非
.env 的配置文件（.ini、.properties 等）里出现同形状的凭据赋值时，也会触发 —— 因为 when 门槛看不到文件名。此时标题只陈述「没有忽略 .env」和「有凭据型环境配置」两个事实，不宣称 .env 一定存在
- 明文规则只认常见的高危键名（PASSWORD / PASSWD / SECRET / TOKEN / API_KEY / ACCESS_KEY / PRIVATE_KEY / CREDENTIAL）—— 自定义键名（如
FOO=真实密钥）不报。
ENV-NOT-IGNORED 是「整仓库任一 .gitignore 忽略了 .env 就算过」 —— 语义是「仓库里有没有忽略 .env 的地方」。这符合 gitignore 可叠加的实际行为；代价是：多包仓库里如果只有某一个子目录的 .gitignore 写了 .env，就不会报（单一根 .gitignore 的项目不受影响）。- 只看
.env 系列文件 —— config.json、settings.yaml 里的明文凭据不归它管。
- 硬编码地址规则是低优先提示 —— 内网地址写在代码里不一定有问题，它只是违反「配置与代码分离」，报出来让你确认。
依据
每条规则的 source 都能查到原文：
License
MIT © 深鲸 DeepWhale
