EnvGuard — 预提交密钥检测工具

EnvGuard 在代码提交至 git 之前，扫描源码中泄露的密钥、凭证、API 密钥以及 .env 文件内容。它基于正则表达式匹配 20+ 个服务的 50+ 种密钥格式，通过 lefthook 实现 Git 钩子集成，并生成符合 SARIF 标准的报告，以支持合规性工作流。

命令

免费版（无需许可证）

envguard scan [file|directory]

对指定文件或目录执行一次性密钥扫描。

执行方式：

bash "/scripts/envguard.sh" scan [target]

功能说明：

1. 接受文件路径或目录路径（默认为当前目录）
2. 查找所有文本文件（排除 .git/、node_modules/、dist/、build/、vendor/ 和 pycache）
3. 对每个文件运行 50+ 种密钥检测模式
4. 尊重 .envguardignore 中定义的排除规则（语法同 .gitignore）
5. 输出结果包含：文件路径、行号、匹配模式、严重等级、脱敏后的匹配内容
6. 若未发现风险项，退出码为 0；若发现 Critical 或 High 级别问题，退出码为 1

典型使用场景：

• “扫描本仓库是否存在泄露的密钥” → 执行 envguard scan .
• “检查该文件是否包含 API 密钥” → 执行 envguard scan src/config.ts
• “我的源码中是否存在任何密钥？” → 执行 envguard scan src/

专业版（$19/用户/月 —— 需设置 ENVGUARD_LICENSE_KEY）

envguard hooks install

安装 Git 预提交钩子，在每次提交前扫描暂存区文件中的密钥。

执行方式：

bash "/scripts/envguard.sh" hooks install

功能说明：

1. 校验专业版及以上许可证有效性
2. 将 lefthook 配置复制到项目根目录
3. 安装 lefthook 预提交钩子
4. 每次提交时：扫描所有暂存文件中的密钥；若发现密钥则阻止提交，并提供修复建议

envguard hooks uninstall

移除 EnvGuard 的 Git 钩子。

bash "/scripts/envguard.sh" hooks uninstall

envguard allowlist [add|remove|list] [pattern]

管理误报模式。加入白名单的模式在扫描过程中将被跳过。

bash "/scripts/envguard.sh" allowlist add "EXAMPLE_API_KEY_FOR_TESTS"
bash "/scripts/envguard.sh" allowlist remove "EXAMPLE_API_KEY_FOR_TESTS"
bash "/scripts/envguard.sh" allowlist list

功能说明：

1. 校验专业版及以上许可证有效性
2. 读写白名单配置于 ~/.openclaw/openclaw.json（字段路径：envguard.config.allowlist）
3. 白名单中的模式被视为已知安全项，在扫描中自动跳过

envguard diff

仅扫描暂存区变更（即 git diff --cached 输出的内容）中的密钥。

bash "/scripts/envguard.sh" diff

功能说明：

1. 校验专业版及以上许可证有效性
2. 通过 git diff --cached 获取暂存变更
3. 仅扫描新增或修改的代码行中的密钥
4. 适用于大型仓库的预提交检查

团队版（$39/用户/月 —— 需使用团队版 ENVGUARD_LICENSE_KEY）

envguard history [directory]

完整 Git 历史扫描 —— 查找所有历史提交中可能存在的密钥。

bash "/scripts/envguard.sh" history [directory]

功能说明：

1. 校验团队版及以上许可证有效性
2. 使用 git log -p 遍历全部 Git 提交历史
3. 对每个提交的差异内容执行密钥扫描
4. 报告内容包括：提交哈希、作者、日期、文件路径、行号、匹配模式
5. 对存在历史密钥泄露风险的仓库接入尤为关键

envguard report [directory]

生成符合 SARIF 标准或 Markdown 格式的合规性报告。

bash "/scripts/envguard.sh" report [directory]

功能说明：

1. 校验团队版及以上许可证有效性
2. 对指定目录执行完整扫描
3. 生成结构化 Markdown 报告，含各严重等级问题统计
4. 为每类问题提供对应的修复步骤建议
5. 输出内容适用于合规审计与安全评审

envguard policy [directory]

自定义密钥模式与强制执行规则。

bash "/scripts/envguard.sh" policy [directory]

功能说明：

1. 校验团队版及以上许可证有效性
2. 从 ~/.openclaw/openclaw.json（字段路径：envguard.config.customPatterns）加载自定义模式
3. 强制执行组织级密钥规范（例如内部令牌格式）
4. 将自定义模式与内置模式合并，实现全面覆盖式扫描

支持检测的密钥类型

EnvGuard 支持检测来自 20+ 个服务的 50+ 种密钥模式：

配置

用户可在 ~/.openclaw/openclaw.json 中配置 EnvGuard：

{
  "skills": {
    "entries": {
      "envguard": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "high",
          "allowlist": [],
          "customPatterns": [],
          "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
          "reportFormat": "markdown"
        }
      }
    }
  }
}

重要说明

• 免费版 开箱即用，无需任何配置
• 所有扫描均在本地执行 —— 不会将代码或密钥发送至任何外部服务器
• 许可证校验离线完成 —— 不进行“回拨”（phone-home）或网络请求
• 支持 .envguardignore 文件（语法同 .gitignore），用于排除扫描路径
• 输出中的匹配内容始终为脱敏显示（仅保留首尾各 4 个字符）
• Git 钩子依赖 lefthook，需提前安装（参见上方安装说明）
• 退出码含义：0 = 无风险项；1 = 发现风险项（便于 CI/CD 集成）

错误处理

• 若未安装 lefthook 却尝试执行 hooks install，提示用户安装
• 若许可证密钥无效或已过期，显示清晰提示并附上链接：https://envguard.pages.dev/renew
• 若待扫描文件为二进制文件，则自动跳过，不发出警告
• 若 .envguardignore 文件格式错误，给出警告后继续使用默认排除规则
• 若目标路径下未找到任何文件，报告“扫描干净”，并附带信息提示

何时使用 EnvGuard

用户可能会提出如下请求：

• “扫描是否存在泄露的密钥”
• “检查我的代码中是否包含任何 API 密钥”
• “为我的提交设置密钥扫描”
• “这个仓库中是否存在任何凭证？”
• “生成一份用于合规审查的安全报告”
• “扫描 Git 历史中泄露的密码”
• “阻止密钥被提交到仓库”
• “检查我暂存的文件中是否存在密钥”
• “将一个误报添加至白名单”