chintanshah35/secretguard

# secretguard 在源代码进入生产环境之前，扫描其中的机密信息、凭证和 PII（个人身份信息）。 ``` npx secretguard . ``` 如果检测到任何 CRITICAL（严重）级别的发现，程序将以代码 `1` 退出——将其放入您的 CI pipeline 中即可直接运行。 ## 检测内容 涵盖凭证和 PII 的 46 种模式，按严重程度分组。 **凭证 — CRITICAL（严重）** - AWS 访问密钥（`AKIA...`）和秘密密钥 - OpenAI API 密钥（`sk-...`） - Anthropic API 密钥（`sk-ant-...`） - GitHub token（`ghp_`、`ghs_`、`gho_`、`github_pat_`） - GitLab 个人访问令牌（`glpat-`） - Slack 机器人和用户 token（`xoxb-`、`xoxp-`） - SendGrid API 密钥（`SG.`） - npm 访问令牌（`npm_`） - Stripe 线上秘密密钥（`sk_live_`） - Twilio auth token - HuggingFace 访问令牌（`hf_...`） - Vercel 访问令牌 - Supabase 服务角色密钥（长 JWT） - Cloudflare API token 和全局 API 密钥 - Azure 存储连接字符串和客户端密钥 - Firebase 服务账号密钥标记 - PyPI API token（`pypi-...`） - Doppler 服务和个人令牌（`dp.st.`、`dp.pt.`） - 数据库 URL（PostgreSQL、MySQL、MongoDB — 包含在 URL 中的凭证） - RSA、EC、OpenSSH 和 PGP 私钥 **凭证 — HIGH（高）** - JWT token - Stripe 线上可发布密钥（`pk_live_`） - Google API 密钥（`AIzaSy...`） - Firebase Web API 密钥 - Twilio 账户 SID - 通用 API 密钥（分配给 `api_key`、`API_KEY` 等的高熵字符串） **PII — CRITICAL（严重）** - 社会保障号码（SSN） - 信用卡号码（Visa、Mastercard、Amex、Discover） **PII — MEDIUM（中）** - 电子邮件地址 - 美国和国际电话号码 **PII — LOW（低）** - 公共 IPv4 地址（排除私有范围） 所有发现的结果在输出中都会进行**掩码处理**——绝不打印原始机密信息。 ## PII 与误报 PII 扫描针对生产源代码进行了优化，不适用于测试夹具。 **在类似测试的路径中跳过** — 电子邮件、电话、SSN、信用卡和公共 IP 模式不会在以下路径中运行： - `*.test.*`, `*.spec.*` - `__tests__/`, `__mocks__/` - `fixtures/`, `mocks/`, `stubs/` **过滤虚假值** — 在其他文件中，明显的占位符会被忽略（例如 `user@example.com`、`test@test.com`，美国 `555-` 号码，所有数字相同的电话）。 **凭证始终会被扫描** — 测试文件中的 API 密钥和 token 仍会被报告。测试文件中真实的 `ghp_` 或 `sk_live_` 依然存在泄露风险。 ## 安装说明 ``` npm install -g secretguard ``` 或者无需安装直接使用： ``` npx secretguard . ``` ## 用法 ``` # 扫描当前目录 secretguard . # 扫描特定路径 secretguard ./src # 忽略额外路径（-i 简写也可用） secretguard . --ignore tests --ignore fixtures # 输出为 JSON secretguard . --json # 保存 HTML 报告（-o 简写也可用） secretguard . --output report.html # 扫描完整 git 历史 secretguard . --history secretguard . --history --json # 仅扫描暂存的更改（在 pre-commit hooks 中很有用） secretguard . --staged # 安装 git pre-commit hook secretguard install-hook # 保存 SARIF 报告（用于 GitHub Code Scanning 上传） secretguard . --sarif results.sarif # 使用 baseline 忽略已知发现 secretguard . --baseline .secretguard-baseline.json # 将 baseline 更新为当前发现 secretguard . --baseline .secretguard-baseline.json --update-baseline ``` ## 默认设置 以下路径会被自动忽略——无需额外配置： ``` node_modules .git dist build coverage .next .nuxt .turbo .cache vendor __pycache__ .venv ``` 二进制文件（图像、PDF、压缩包、已编译的二进制文件）会自动跳过。 在您的项目根目录下添加 `.secretguardignore` 文件即可忽略更多路径： ``` # .secretguardignore tests/ fixtures/ src/mocks/ ``` ## CI/CD ``` # GitHub Actions - name: Scan for secrets run: npx secretguard . --ignore tests # 将 SARIF 上传到 GitHub Security 标签页 - name: Scan and upload SARIF run: npx secretguard . --sarif results.sarif - name: Upload SARIF uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ``` # 安装为 git pre-commit hook secretguard install-hook ``` 该 hook 会在每次提交前运行 `secretguard --staged`，并在检测到 CRITICAL 级别的发现时阻止提交。可以使用 `git commit --no-verify` 来绕过。 当未检测到 CRITICAL 级别的发现时，退出代码为 `0`，否则为 `1`。 ## Git 历史记录扫描 ``` # 扫描 repo 中所有 commits 以查找泄露的 secrets secretguard . --history # 获取 JSON 输出（适用于 piping） secretguard . --history --json ``` 扫描所有提交中新增的每一行，对相同的发现进行去重（跨多个提交的相同文件 + 模式 + 值），并附带提交哈希值、作者、日期和提交信息进行报告。 ## 基线 使用基线可以隐藏您已经审查并确认无问题的发现结果： ``` # 从当前发现生成初始 baseline secretguard . --baseline .secretguard-baseline.json --update-baseline # 在未来的运行中，仅显示新发现 secretguard . --baseline .secretguard-baseline.json ``` 将 `.secretguard-baseline.json` 提交到您的代码库中，以便整个团队共享相同的隐藏列表。 ## 输出格式 **终端（默认）** — 彩色输出，按严重程度分组（优先显示 CRITICAL），并进行值掩码处理 **JSON (`--json`)** — 包含汇总计数的结构化输出，适合通过管道传递给其他工具 **HTML (`--output report.html`)** — 可共享的独立报告，包含严重程度摘要和完整的发现结果表 **SARIF (`--sarif results.sarif`)** — 兼容 GitHub Code Scanning、VS Code SARIF Viewer 和其他 SAST 工具的标准格式 ## 编程 API ``` import { scan, piiPatterns, credentialPatterns } from 'secretguard' import type { ScanResult, Finding } from 'secretguard' // Scan with defaults const result = await scan('./src') // Scan with options const result = await scan('./src', { ignore: ['tests', 'fixtures'], patterns: [...credentialPatterns], // credentials only, skip PII }) console.log(result.findings) // Finding[] console.log(result.scanned) // number of files scanned console.log(result.duration) // ms ``` ## 环境要求 Node.js 18 或更高版本。 ## 相关文章 - **[如何在 Node.js 项目中扫描硬编码机密（GitHub Actions 指南）](https://dev.to/chintanshah35/how-to-scan-for-hardcoded-secrets-in-a-nodejs-project-github-actions-guide)** - Dev.to ## 许可证 MIT

标签：DevSecOps, GNU通用公共许可证, LNA, MITM代理, Node.js, StruQ, 上游代理, 对抗攻击, 敏感信息检测, 文档结构分析, 自动化攻击