git-security-checks

Git 安全检查

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
提交前运行 gitleaks 扫描机密	一般暂存和提交消息规范请使用 git-commit-workflow
配置 .gitleaks.toml 允许列表和 pre-commit 集成	如需执行 git fsck 完整性检查，而非机密扫描，请使用 git-maintain
验证凭据不会泄露到 PR 中	当 CI 的 gitleaks 扫描失败且需要在分支上修复时，请使用 git-fix-pr
设置用于凭据扫描的 pre-commit 钩子	使用 release-please-protection 检测对由 release 管理的文件进行的手动编辑

使用 gitleaks 和 pre-commit 钩子进行提交前安全验证与机密检测的专家指南。

核心专长

• gitleaks：使用正则表达式和熵分析扫描硬编码机密与凭据
• Pre-commit 钩子：在提交前自动执行安全验证
• 声明式允许列表：通过 .gitleaks.toml 配置管理误报
• 安全优先工作流：防止凭据泄露

快速安全扫描（推荐）

通过一条命令运行全面的安全扫描流程：

# Full scan: check all tracked files
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-security-checks/scripts/security-scan.sh"

# Staged-only: check only files about to be committed
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-security-checks/scripts/security-scan.sh" --staged-only

此脚本会检查：gitleaks 扫描、敏感文件模式、.gitignore 覆盖情况、差异中的高熵字符串，以及 pre-commit 钩子状态。详情请参阅 scripts/security-scan.sh。

Gitleaks 工作流

初始设置

# Install gitleaks (macOS)
brew install gitleaks

# Install gitleaks (Go)
go install github.com/gitleaks/gitleaks/v8@latest

# Install gitleaks (binary download)
# See https://github.com/gitleaks/gitleaks/releases

# Scan repository
gitleaks detect --source .

# Scan with verbose output
gitleaks detect --source . --verbose

配置

创建 .gitleaks.toml，设置项目专属的允许列表：

title = "Gitleaks Configuration"

[extend]
useDefault = true

[allowlist]
description = "Project-wide allowlist for false positives"
paths = [
    '''test/fixtures/.*''',
    '''.*\.test\.(ts|js)$''',
]

regexes = [
    '''example\.com''',
    '''localhost''',
    '''fake-key-for-testing''',
]

Pre-commit 扫描工作流

每次提交前运行 gitleaks：

# Scan for secrets in current state
gitleaks detect --source .

# Scan only staged changes (pre-commit mode)
gitleaks protect --staged

# Scan with specific config
gitleaks detect --source . --config .gitleaks.toml

管理误报

Gitleaks 提供三种声明式方法来处理误报：

1. 行内注释 — 标记特定行：

# This line is safe
API_KEY = "fake-key-for-testing-only"  # gitleaks:allow

# Works in any language
password = "test-fixture"  # gitleaks:allow

2. 基于路径的排除项 — 在 .gitleaks.toml 中配置：

[allowlist]
paths = [
    '''test/fixtures/.*''',
    '''.*\.example$''',
    '''package-lock\.json$''',
]

3. 基于正则表达式的允许列表 — 针对特定模式：

[allowlist]
regexes = [
    '''example\.com''',
    '''localhost''',
    '''PLACEHOLDER''',
]

4. 按规则设置允许列表 — 针对特定检测规则：

[[rules]]
id = "generic-api-key"
description = "Generic API Key"

[rules.allowlist]
regexes = ['''test-api-key-.*''']
paths = ['''test/.*''']

完整的 Pre-commit 安全流程

# 1. Scan for secrets
gitleaks protect --staged

# 2. Run all pre-commit hooks
pre-commit run --all-files --show-diff-on-failure

# 3. Stage your actual changes
git add src/file.ts

# 4. Show what's staged
git status
git diff --cached --stat

# 5. Commit if everything passes
git commit -m "feat(auth): add authentication module"

Pre-commit 钩子集成

.pre-commit-config.yaml

gitleaks 配置示例：

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.22.1
    hooks:
      - id: gitleaks

运行 Pre-commit 钩子

# Run all hooks on all files
pre-commit run --all-files

# Run all hooks on staged files only
pre-commit run

# Run specific hook
pre-commit run gitleaks

# Show diff on failure for debugging
pre-commit run --all-files --show-diff-on-failure

# Install hooks to run automatically on commit
pre-commit install

--files 不会限定 gitleaks 钩子的扫描范围——请先暂存

pre-commit run gitleaks --files <path> 看起来像是限定范围的扫描，但实际上并非如此。上游将此钩子声明为 pass_filenames: false，因此路径不会传递给它，而它的入口会扫描 --staged：

# gitleaks/.pre-commit-hooks.yaml, v8.30.0
- id: gitleaks
  entry: gitleaks git --pre-commit --redact --staged --verbose
  pass_filenames: false

在干净的工作树中，没有任何内容处于暂存状态，因此该命令会扫描 零字节 并打印 Passed。在一个包含真实 JWT 的文件上进行测试，两次都运行相同的命令：

文件状态	结果
仅在工作树中（??）	Detect hardcoded secrets … Passed — 0 commits scanned
已执行 git add	RuleID: jwt … leaks found: 1

值得了解这一点，是因为它可能导致相反的结果：把 --files 调用当作扫描干净的证明，是一种虚假的完全安全信号，而且看起来与真实结果完全一样。务必：

git add <paths>
pre-commit run gitleaks

有两项习惯也适用于 gitleaks 之外的场景：

• 在相信钩子的绿色结果之前，先查看固定 rev 对应的上游 .pre-commit-hooks.yaml 中的 pass_filenames。 忽略文件名的钩子也会忽略你的范围限定标志。
• 对钩子进行对照测试。 在临时文件中放入已知的不良值，将其暂存，并确认钩子会报错后，再相信它的绿色结果。请谨慎选择不良值——gitleaks 不会标记 AWS 自己公布的示例密钥（wJalrXUtnFEMI…EXAMPLEKEY），因此用它构造的探测值会通过，无法证明任何事情。JWT 或其他高熵令牌都适用。

有关检测规则覆盖范围、误报管理、泄露补救、CI/CD 集成、故障排除，以及完整的 gitleaks/pre-commit 命令参考，请参阅 REFERENCE.md。