Betterleaks

 + ○
   ▾

Betterleaks 是一个可配置、快速且全面的密钥扫描器。它由打造 Gitleaks 的团队（包括原作者）维护。 查看这一系列博客文章，了解检测引擎的工作原理：1. Regex is all you need，2. Rare Not Random，3. Express YourCELf，4. Better generic secrets detection。

开发工作由以下方支持

主要特性

特性	描述
简单优先级排序	按置信度、验证状态和分析后的严重性评分进行排序，让分类处理变得像 123 一样简单。
密钥验证	通过在规则定义中直接使用 Expr 发起异步 HTTP 请求，验证检测到的密钥是否处于活跃状态。
密钥分析	用与提供商无关的身份、账户、能力和严重性信息来丰富有效凭据。
密钥吊销	可选地吊销密钥。
基于 Expr 的过滤	编写上下文规则过滤器，评估片段（数据块）属性（如 git 作者、提交信息和文件路径）以及发现数据，以减少误报。
BPE 过滤	通过使用 BPE 分词来衡量字符串有多“罕见”或非人类，从而过滤掉自然语言误报。
快速扫描	通过合理的默认并行化设置、ahocorasick 关键字过滤器和 re2 实现快速性能。
新来源	支持 GitHub、GitLab、Hugging Face、S3 等来源。添加新来源也很容易！
容器镜像	扫描所有平台、历史层、配置和嵌入式证明，并带有摘要溯源和已删除/被覆盖路径报告。参见容器指南。
可移植性	可在任何现代操作系统/架构上运行。这个小巧的二进制文件可以集成到任何系统中。

安装

main 分支用于 v2 开发。V1 的维护和文档位于 v1.x 分支。

从 v1 升级？请参阅 v2 迁移指南，了解 CLI、配置、报告和 SDK 的变更。

在首个稳定的 v2 版本发布之前，包管理器和 Docker 的 latest 标签 可能仍会提供 v1。在此之前，请使用迁移指南中的候选发布版本说明 来试用 v2。

# Package managers
brew install betterleaks
brew install --cask betterleaks/tap/betterleaks

# Fedora Linux
sudo dnf install betterleaks

# Containers (stable v2)
docker pull ghcr.io/betterleaks/betterleaks:v2

# Go
go install github.com/betterleaks/betterleaks/v2@latest

# Source
git clone https://github.com/betterleaks/betterleaks
cd betterleaks
make build

稳定版 v2 发布时会更新 tap 中的 betterleaks cask 以及 Docker 的 :v2 和 :latest 标签。Homebrew core 会单独更新。若要在保留 v2 的同时安装 v1， 请使用 brew install --cask betterleaks/tap/betterleaks@1（命令： betterleaks-v1）或 Docker 的 :v1 标签。

用法

默认情况下，扫描会在不向凭据提供方发起请求的前提下检测密钥。使用 -v / --validate 校验凭据，或使用 -a / --analyze 同时解析 身份与权限。分析隐含校验。设置 BETTERLEAKS_VALIDATE=true 或 BETTERLEAKS_ANALYZE=true 可通过环境变量启用这些阶段。显式标志会覆盖对应的变量。

# Scan the filesystem
betterleaks /path/to/target
# Equivalent explicit command
betterleaks filesystem /path/to/target
# Short command alias
betterleaks fs /path/to/target
# Flags may also precede the command
betterleaks --no-banner fs /path/to/target

# Validate detected credentials
betterleaks fs /path/to/target -v
# Validate and analyze identity and permissions
betterleaks fs /path/to/target -a

# Scan a git repo
betterleaks git /path/to/repo

# Also scan merge commit patches (against the first parent)
betterleaks git /path/to/repo --include=merges

# Scan a remote PR's commits relative to its base branch
betterleaks git https://github.com/owner/repo \
  --clone-ref=refs/pull/123/head --revision=main..refs/pull/123/head

# Automatically detect a remote repository and scan its history
betterleaks https://github.com/betterleaks/betterleaks
# The default command can also be named explicitly
betterleaks auto https://github.com/betterleaks/betterleaks
# Explicitly download and scan a web response (without crawling)
betterleaks url https://example.com/config.txt

# Scan GitHub org
betterleaks github https://github.com/betterleaks
# Scan GitHub user
betterleaks github https://github.com/cooluser123456789 --include issues,prs,actions,releases,gists
# Scan a PR's title, description, and comments
betterleaks github https://github.com/betterleaks/betterleaks/pull/113

# Scan GitLab group or project
betterleaks gitlab https://gitlab.com/mygroup
betterleaks gitlab https://gitlab.com/mygroup/myproject --include issues,mrs,releases,ci-jobs
# Scan a specific GitLab merge request
betterleaks gitlab https://gitlab.com/mygroup/myproject/-/merge_requests/42

# Scan Hugging Face models, datasets, Spaces, and buckets
betterleaks huggingface https://huggingface.co/myorg
betterleaks hf https://huggingface.co/datasets/myorg/mydataset
betterleaks hf --include=discussions,prs https://huggingface.co/myorg/model
betterleaks hf hf://buckets/myorg/mybucket/path

# Scan a public s3 dataset (Common Crawl).
betterleaks s3 https://commoncrawl.s3.us-east-1.amazonaws.com/crawl-data/CC-MAIN-2018-17/segments/1524125937193.1/warc/
# Enumerate and scan every bucket in a Cloudflare R2 account
betterleaks s3 'https://<account-id>.r2.cloudflarestorage.com/*'

# Scan stdin
cat some_file.txt | betterleaks stdin

# Revalidate a known credential without running detection
printf '%s\n' "$GITHUB_TOKEN" | betterleaks validate --rule github-pat

# Find rule IDs that support credential analysis
betterleaks config show ids --analysis

# Validate it and resolve identity and permissions
printf '%s\n' "$GITHUB_TOKEN" | betterleaks analyze --rule github-pat

# Print only its status (for example, VALID)
printf '%s\n' "$GITHUB_TOKEN" | betterleaks validate --rule github-pat --simple

Git URL 扫描会将完整的分支和标签历史以及 notes 获取到临时裸仓库中。使用 --clone-ref 添加特定的审查引用或模式，或使用 --clone-all-refs 获取所有已通告的引用。有关资源选择、提交过滤和暂存更改扫描，请参阅 Git 扫描指南。

使用 --hmac-key 或 BETTERLEAKS_FINGERPRINT_HMAC_KEY 进行带密钥的匹配指纹；请参阅 指纹隐私与密钥设置。

-j / --jobs 仅控制检测并发度，默认为 4 * GOMAXPROCS。各来源自行管理其有界读取和下载。

规则还可以定义可选的 revoke Expr 用于显式凭据吊销。使用 betterleaks config show ids --revocation 查找已配置的支持，并使用 betterleaks revoke --rule <id> 执行吊销。扫描永远不会执行吊销。请参阅 吊销指南。

Go SDK

Betterleaks 也可以作为 Go 库嵌入使用。扫描器和分析器默认静默，并且可以安全地在多次扫描之间复用。

go get github.com/betterleaks/betterleaks/v2

package main

import (
	"fmt"

	"github.com/betterleaks/betterleaks/v2/config"
	"github.com/betterleaks/betterleaks/v2/scan"
)

func main() {
	cfg, err := config.Default()
	if err != nil {
		panic(err)
	}
	scanner, err := scan.New(cfg)
	if err != nil {
		panic(err)
	}

	const token = "ghp_aB3dE5fG7hI9jK1mN3pQ5rS7tU9vW1xY3zA5" // betterleaks:allow
	for _, finding := range scanner.ScanString("GITHUB_TOKEN=" + token) {
		fmt.Println(finding.RuleID)
	}
}

有关可运行的 SDK 示例（涵盖自定义配置、分析、正则引擎和并发扫描），请参阅示例目录。

有关完整的默认配置和自定义配置示例，请参阅 scan 包文档。

配置

Betterleaks 的强大之处在于其富有表现力的配置。过滤、验证和分析逻辑均以 Expr 定义。prefilter 在任何正则匹配发生之前运行，并且只能访问 attributes 映射。attributes 描述诸如 git 补丁之类的资源。使用 prefilter 可以在执行更昂贵的扫描之前快速退出。另一方面，filter 在正则匹配之后进行评估，并且可以访问 attributes 映射以及候选 finding 数据，例如 finding["secret"] 或 finding["match"]。

# Global prefilter, it runs before expensive regex calls
prefilter = '''
matchesAny(attributes["path"], [
  `(?i)\.(?:bmp|gif|jpe?g|png|svg|tiff|pdf|exe)$`,
  `(?:^|/)node_modules(?:/.*)?$`,
  `(?:^|/)vendor(?:/.*)?$`
])
|| attributes["git.author_name"] == "renovate[bot]"
'''

# Global filter, it runs for _every_ candidate secret.
filter = '''
containsAny(finding["secret"], [
  "EXAMPLE",
  "CHANGEME",
  "YOUR_API_KEY_HERE",
  "0000000000000000"
])
'''

# An array of tables that contain data on how to detect secrets
[[rules]]
id = "github-pat"
description = "GitHub Personal Access Token, risking unauthorized repository access."
regex = '''ghp_[0-9a-zA-Z]{36}'''
keywords = ["ghp_"]