Gitleaks基本配置流程（含.githooks配置）

1. Gitleaks 是什么

Gitleaks 是一个用于检测 Git 仓库中敏感信息泄露的工具，可以扫描：

• API Key

• Access Token

• 数据库密码

• JWT Secret

• 私钥

• 云服务密钥

• GitHub Token

• AWS Key

• 其他疑似凭证信息

它可以用于：

• 手动扫描项目

• 扫描 Git 历史

• 在 git commit 前自动扫描

• 在 CI/CD 流程中扫描

• 配合自定义规则使用

推荐采用 .gitignore + .gitleaks.toml + .githooks/pre-commit + CI/CD 扫描，形成多层防护。

---

2. 安装 Gitleaks

官方发布地址：Releases · gitleaks/gitleaks · GitHub

Windows 下可以直接下载官方 Release 中对应架构的压缩包，例如：

gitleaks_x.x.x_windows_x64.zip

解压得到 gitleaks.exe ，建议放置到 D:\Program Files\Gitleaks\

最终路径类似 D:\Program Files\Gitleaks\gitleaks.exe

然后把 D:\Program Files\Gitleaks 加入 Windows 系统或用户环境变量 Path。

因为我不太喜欢放东西到C盘，所以此处用的是D盘，磁盘根据个人喜好选择即可

重新打开 PowerShell 后验证：

gitleaks version

也可以执行：

Get-Command gitleaks

如果能够显示 gitleaks.exe 的路径，则安装成功。

---

3. VSCode（或其他IDE） 中找不到 Gitleaks 的处理方式

如果普通 PowerShell 中

gitleaks version

可以正常运行，但 VSCode 内置 PowerShell 中提示找不到命令，通常是因为：

VSCode 启动时继承的是旧的环境变量。

解决方法：

1. 完全关闭 VSCode。

2. 确保任务管理器中没有残留 Code.exe。

3. 重新打开 VSCode。

4. 新建终端。

然后再次执行 gitleaks version

可以检查 VSCode 当前 PATH：

$env:Path

确认其中是否存在 D:\Program Files\Gitleaks

或者临时添加 PATH：

$env:Path += ";C:\Program Files\Gitleaks"

然后验证 gitleaks version

---

4. 项目中创建 Gitleaks 配置

在项目根目录创建：

.gitleaks.toml

例如：

title = "Project Gitleaks Config"

[extend]
useDefault = true

[allowlist]
description = "Ignore generated and dependency files"

paths = [
  '''node_modules/''',
  '''dist/''',
  '''build/''',
  '''coverage/''',
  '''package-lock\.json$'''
]

其中最重要的是：

[extend]
useDefault = true

表示：

使用 Gitleaks 官方默认规则，同时允许当前项目继续扩展自己的配置。

这样就不需要自己重新定义 GitHub Token、AWS Key、私钥等常见敏感信息规则。

---

5. 手动扫描项目

在项目根目录执行：

gitleaks git .

如果要明确指定配置文件：

gitleaks git . --config .gitleaks.toml

建议第一次接入 Gitleaks 时，先对整个项目扫描一次。

---

6. 最基础的 Git Hook 用法

Git 原生 Hook 位于：

.git/hooks/

可以创建：

.git/hooks/pre-commit

内容例如：

#!/bin/sh

echo "Running Gitleaks..."

gitleaks git --pre-commit --staged --config .gitleaks.toml

RESULT=$?

if [ $RESULT -ne 0 ]; then
    echo ""
    echo "Gitleaks detected secrets."
    echo "Commit aborted."
    exit 1
fi

echo "Gitleaks scan passed."
exit 0

然后提交：

git add .
git commit -m "test"

执行流程为：

git commit
    ↓
执行 pre-commit
    ↓
执行 Gitleaks
    ↓
扫描暂存区
    ↓
发现敏感信息？
    ↓
是 → 阻止提交
否 → 正常提交

---

7. 为什么不推荐直接使用 .git/hooks

.git/hooks 最大的问题是：

.git/

本身不会进入 Git 仓库。

因此：

.git/hooks/pre-commit

也不会被提交。

这样就会导致：

开发者 A
有 Hook

开发者 B clone 项目
没有 Hook

因此团队项目更推荐使用 .githooks。

---

8. 进阶用法：使用 .githooks

在项目根目录创建：

.githooks/

然后创建：

.githooks/pre-commit

项目结构：

project/
├─ src/
├─ package.json
├─ .gitignore
├─ .gitleaks.toml
└─ .githooks/
   └─ pre-commit

---

9. 配置 .githooks/pre-commit

示例：

#!/bin/sh

echo "🔍 Running Gitleaks secret scan..."

gitleaks git --pre-commit --staged --config .gitleaks.toml

RESULT=$?

if [ $RESULT -ne 0 ]; then
    echo ""
    echo "❌ Gitleaks detected sensitive information."
    echo "❌ Commit aborted."
    exit 1
fi

echo "✅ Gitleaks scan passed."
exit 0

---

10. 告诉 Git 使用 .githooks

执行：

git config core.hooksPath .githooks

检查：

git config core.hooksPath

应该返回：

.githooks

从此以后 Git 会从：

.githooks/

读取 Hook，而不是：

.git/hooks/

---

11. .githooks 的优势

.githooks 可以进入 Git 仓库。

因此可以提交：

git add .githooks
git add .gitleaks.toml

git commit -m "chore: add gitleaks pre-commit hook"

团队成员 clone 项目后会自动得到：

.githooks/pre-commit

但是要注意：

core.hooksPath 属于本地 Git 配置，不会随仓库一起 clone。

因此新成员第一次 clone 后仍需要执行：

git config core.hooksPath .githooks

---

12. 推荐项目结构

建议项目最终包含：

project/
├─ src/
├─ package.json
├─ .gitignore
├─ .env.example
├─ .gitleaks.toml
└─ .githooks/
   └─ pre-commit

---

13. .gitignore 配置

Gitleaks 不应该代替 .gitignore。

敏感文件应该首先通过 .gitignore 排除。

Node / Vue 项目可以加入：

.env
.env.*
!.env.example

*.pem
*.key
*.p