GitHub Secret Scanner

检测和修复 GitHub 仓库中的 API key 泄露。支持 CLI 命令行和 GitHub Action 两种使用方式。

功能特性

• 当前代码扫描 — 检测代码中硬编码的 API key、secret、token
• Git 历史扫描 — 检测 git 历史中曾经出现过的密钥
• .gitignore 检查 — 检查 .gitignore 是否正确配置
• 自动修复 — 自动修复 .gitignore 配置，移除敏感文件跟踪
• 内置规则库 — 支持 AWS、GitHub、OpenAI、Stripe 等 20+ 种密钥格式
• 熵值检测 — 通过香农熵检测高随机性的可疑字符串
• 自定义规则 — 支持通过 YAML 文件定义自定义检测规则
• 多格式输出 — 终端彩色输出、JSON 报告、HTML 报告

安装

# 全局安装
npm install -g github-secret-scanner

# 或直接使用 npx
npx github-secret-scanner scan

使用方法

扫描命令

# 扫描当前仓库
npx github-secret-scanner scan

# 扫描指定仓库
npx github-secret-scanner scan --repo owner/repo

# 扫描所有公开仓库
npx github-secret-scanner scan --all-public

# 指定扫描模式
npx github-secret-scanner scan --mode full|current|history|gitignore

# 使用自定义规则
npx github-secret-scanner scan --rules ./my-rules.yml

# 生成 JSON 报告
npx github-secret-scanner scan --output json --file report.json

# 生成 HTML 报告
npx github-secret-scanner scan --output html --file report.html

# 指定 GitHub token
npx github-secret-scanner scan --token ghp_xxxxx

修复命令

# 交互式修复
npx github-secret-scanner fix

# 自动修复（只修复安全部分）
npx github-secret-scanner fix --auto

# 只修复 .gitignore
npx github-secret-scanner fix --only gitignore

# 干跑模式（预览修复操作）
npx github-secret-scanner fix --dry-run

GitHub Action

在 .github/workflows/ 下创建 secret-scan.yml：

name: Secret Scan

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  schedule:
    - cron: "0 9 * * 1" # 每周一早上9点

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Secret Scanner
        uses: Han-cy830/github-secret-scanner@v1
        with:
          mode: "full"
          fail-on-found: "true"
          auto-fix: "false"
          create-issue: "true"

Action 输入参数

参数	说明	默认值
mode	扫描模式	full
rules	自定义规则文件路径	-
fail-on-found	发现泄露时是否失败	true
auto-fix	是否自动修复并提交	false
create-issue	是否自动创建 Issue	true
github-token	GitHub token	${{ github.token }}

Action 输出

输出	说明
issues-found	发现的问题数量
critical	Critical 级别问题数量
report-path	报告文件路径

检测规则

内置规则

类别	规则	严重程度
云服务	AWS Access Key, Secret Key	Critical
代码平台	GitHub Token, GitLab Token	Critical
AI 服务	OpenAI Key, Anthropic Key	Critical
支付	Stripe Key	Critical
通信	Slack Token, Discord Token	High
数据库	MongoDB/PostgreSQL/MySQL/Redis URI	Critical
通用	私钥, JWT Token, Bearer Token	High/Critical

熵值检测

自动检测长度 ≥ 20 且熵值 ≥ 4.5 的高随机性字符串，排除 UUID、hash、base64 等常见误报。

自定义规则

创建 rules.yml 文件：

rules:
  - name: "Internal API Key"
    pattern: "internal_[a-zA-Z0-9]{32}"
    severity: high
    description: "公司内部 API 密钥"

使用：npx github-secret-scanner scan --rules ./rules.yml

认证方式

按优先级自动检测：

1. --token 参数
2. GITHUB_TOKEN 环境变量
3. gh CLI 已登录状态

安全原则

• 永远不自动删除代码 — 只标记，让用户决定
• 永远不自动 force push — 历史清理需要用户手动执行
• 优先保护本地文件 — git rm --cached 不删除工作区文件
• 每次修复前创建备份分支

开发

# 克隆仓库
git clone https://github.com/Han-cy830/github-secret-scanner.git
cd github-secret-scanner

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

License

MIT