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 を使用します

gitleaks と pre-commit フックを使用した、コミット前のセキュリティ検証とシークレット検出に関する専門的なガイダンスです。

主な専門知識

• gitleaks：正規表現とエントロピー分析を使用して、ハードコードされたシークレットや認証情報をスキャンします
• Pre-commit フック：コミット前にセキュリティ検証を自動化します
• 宣言的な許可リスト：.gitleaks.toml の設定を通じて誤検知を管理します
• セキュリティ優先のワークフロー：認証情報の漏えいを未然に防ぎます

クイックセキュリティスキャン（推奨）

包括的なセキュリティスキャンのパイプラインを、次の 1 つのコマンドで実行します。

# 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 では、誤検知に対処するための宣言的な方法が 3 つ用意されています。

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

ワークツリーがクリーンな状態では何もステージされていないため、このコマンドは 0 バイト をスキャンし、Passed と表示します。実際の JWT を含む 1 つのファイルで測定したところ、同じコマンドの結果は次のとおりでした。

ファイルの状態	結果
ワークツリーのみ（??）	Detect hardcoded secrets … Passed — 0 commits scanned
git add 済み	RuleID: jwt … leaks found: 1

この点を知っておくべき理由は、失敗の方向にあります。クリーンなスキャンの証拠として --files の実行結果を提示するのは、誤った安全宣言であり、本物の安全なスキャン結果とまったく同じように見えます。必ず次の手順に従ってください。

git add <paths>
pre-commit run gitleaks

gitleaks 以外にも応用できる習慣が 2 つあります。

• フックの成功を信頼する前に、固定された rev における上流の .pre-commit-hooks.yaml で pass_filenames を確認してください。 ファイル名を無視するフックは、対象を限定するフラグも無視します。
• フックの動作をテストしてください。 使い捨てのファイルに既知の不正な値を入れてステージし、フックが失敗することを確認してから、成功を信頼してください。不正な値は慎重に選んでください。gitleaks は AWS が公式に公開している例示用のキー（wJalrXUtnFEMI…EXAMPLEKEY）を検出しないため、これを使ったテストは成功してしまい、何も証明できません。JWT やその他の高エントロピーのトークンを使用してください。

検出ルールの対象範囲、誤検知の管理、漏えいへの対処、CI/CD との統合、トラブルシューティング、gitleaks と pre-commit のコマンドリファレンス全体については、REFERENCE.md を参照してください。