dortort/betterleaks-action
GitHub: dortort/betterleaks-action
一个封装 Betterleaks 的 GitHub Action，用于在 CI/CD 流水线中自动检测代码仓库泄露的凭证和机密信息，支持 SARIF 报告输出与 GitHub Code Scanning 集成。
Stars: 0 | Forks: 0
# Betterleaks Action
[](https://github.com/dortort/betterleaks-action/actions/workflows/ci.yml)
[](https://github.com/dortort/betterleaks-action/actions/workflows/integration.yml)
[](https://opensource.org/licenses/MIT)
一个使用 [Betterleaks](https://github.com/betterleaks/betterleaks) 扫描仓库和目录中的机密信息与凭证的 GitHub Action。
Betterleaks 是一个现代的、开源的机密检测工具，作为 Gitleaks 的继任者而构建。此 Action 封装了 Betterleaks CLI，可与您的 GitHub CI/CD 流水线无缝集成。
## 功能特性
- **智能扫描模式**：在 push 事件时自动选择 `git` 扫描，在 pull request 时选择 `dir` 扫描
- **跨平台**：支持 Linux、macOS 和 Windows 运行器（x64 和 ARM64）
- **快速**：带有二进制缓存的 JavaScript Action —— 没有 Docker 拉取的开销
- **SARIF 输出**：原生支持 SARIF，可集成 GitHub Code Scanning
- **Job 摘要**：在您的工作流运行中生成扫描结果的 Markdown 摘要
## 快速开始
```
- uses: dortort/betterleaks-action@v0.1.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
这使用了智能默认值：根据事件类型自动检测扫描模式，输出 SARIF，并在发现泄露时报错退出。
## 配合 SARIF 上传使用
若要集成 GitHub Code Scanning，建议配合 [`github/codeql-action/upload-sarif`](https://github.com/github/codeql-action) 使用推荐的两步方法：
```
name: Secrets Scan
on: [push, pull_request]
permissions:
contents: read
security-events: write
jobs:
betterleaks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for git scan mode
- uses: dortort/betterleaks-action@v0.1.0
id: betterleaks
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on-leak: 'false' # Don't fail here; let code scanning handle it
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: ${{ steps.betterleaks.outputs.sarif-path }}
```
## 无 GitHub Advanced Security
如果您的仓库没有 GitHub Advanced Security（Code Scanning / SARIF 上传所需），您仍然可以使用此 Action。扫描在本地运行，所有输出均正常工作 —— 只需将报告保存为 workflow artifact：
```
name: Secrets Scan
on: [push, pull_request]
jobs:
betterleaks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: dortort/betterleaks-action@v0.1.0
id: betterleaks
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
- uses: actions/upload-artifact@v4
if: always()
with:
name: betterleaks-report
path: ${{ steps.betterleaks.outputs.report-path }}
```
Job 摘要、`leaks-found`、`leak-count` 和 `exit-code` 输出在没有任何安全计划的情况下也能正常工作。
## 完整用法
```
- uses: dortort/betterleaks-action@v0.1.0
with:
# Betterleaks version (e.g., v1.1.1 or latest)
version: 'latest'
# Scan mode: git, dir, stdin, or auto
# auto: pull_request -> dir, push -> git
scan-mode: 'auto'
# Path to scan (positional argument)
scan-path: '.'
# Path to Betterleaks config file
config: ''
# Path to baseline file for incremental adoption
baseline-path: ''
# Report format (single value): json, csv, junit, sarif, or template
report-format: 'sarif'
# Path to write the report file
report-path: 'betterleaks-report.sarif'
# Redact secrets from output
redact: 'true'
# Custom exit code when leaks are found
exit-code: ''
# Enable verbose output
verbose: 'false'
# Disable colored output
no-color: 'true'
# Suppress ASCII banner
no-banner: 'true'
# Enable live secret validation
validation: 'true'
# Additional CLI arguments
extra-args: ''
# Fail the action if leaks are found
fail-on-leak: 'true'
# GitHub token for API calls
github-token: ${{ secrets.GITHUB_TOKEN }}
# Scan timeout in seconds
timeout: '300'
```
## 输入参数
| Input | Description | Default |
|-------|-------------|---------|
| `version` | Betterleaks 版本 | `latest` |
| `scan-mode` | 扫描模式：`git`, `dir`, `stdin`, `auto` | `auto` |
| `scan-path` | 扫描路径 | `.` |
| `config` | 配置文件路径 | |
| `baseline-path` | 基线文件路径 | |
| `report-format` | 报告格式（单值）：`json`, `csv`, `junit`, `sarif`, `template` | `sarif` |
| `report-path` | 报告写入路径 | `betterleaks-report.sarif` |
| `redact` | 从输出中编修（隐藏）机密信息 | `true` |
| `exit-code` | 发现泄露时的自定义退出码 | |
| `verbose` | 启用详细输出 | `false` |
| `no-color` | 禁用彩色输出 | `true` |
| `no-banner` | 隐藏 ASCII 标语 | `true` |
| `validation` | 启用机密验证 | `true` |
| `extra-args` | 额外的 CLI 参数 | |
| `fail-on-leak` | 发现泄露时失败 | `true` |
| `github-token` | 用于 API 调用的 GitHub token | `${{ github.token }}` |
| `timeout` | 扫描超时时间（秒） | `300` |
## 输出
| Output | Description |
|--------|-------------|
| `exit-code` | Betterleaks 进程退出码 |
| `report-path` | 生成报告的路径 |
| `sarif-path` | SARIF 文件路径（用于 `codeql-action/upload-sarif`） |
| `leaks-found` | 是否发现泄露（`true`/`false`） |
| `leak-count` | 发现的泄露数量（仅限 SARIF 格式） |
## 扫描模式
| Mode | Description |
|------|-------------|
| `auto` | 根据事件类型选择模式（推荐） |
| `git` | 使用 `git log -p` 扫描 git 历史 |
| `dir` | 扫描工作目录中的文件 |
| `stdin` | 从标准输入读取 |
**Auto 模式映射：**
- `push` -> `git` 扫描
- `pull_request` / `pull_request_target` -> `dir` 扫描
- `schedule` / `workflow_dispatch` -> `dir` 扫描
## 配置
Betterleaks 使用以下配置文件优先级顺序：
1. `--config` 标志（通过 `config` 输入参数）
2. `BETTERLEAKS_CONFIG` 环境变量
3. 目标目录中的 `.betterleaks.toml`
4. 目标目录中的 `.gitleaks.toml`（向后兼容）
5. 内置默认规则
## 退出码
| Code | Meaning |
|------|---------|
| `0` | 未检测到泄露 |
| `1` | 检测到泄露 |
| `126` | 未知标志错误 |
## 许可证
MIT
## 致谢
此 Action 封装了 [Betterleaks](https://github.com/betterleaks/betterleaks)，这是一个用于检测 git 仓库和文件中密码、API 密钥和令牌等机密信息的工具。Betterleaks 的开发由 [Aikido Security](https://www.aikido.dev) 支持。
标签：Betterleaks, CI/CD 安全, DevSecOps, GitHub Action, meg, Python安全, SARIF, StruQ, USENIX Security 2025, 上游代理, 云安全监控, 信息安全, 凭证扫描, 开源安全工具, 数据可视化, 数据投毒防御, 自动化攻击, 逆向工程平台, 防泄密, 静态分析