1. Gitleaks 是什么Gitleaks 是一个用于检测 Git 仓库中敏感信息泄露的工具可以扫描API KeyAccess Token数据库密码JWT Secret私钥云服务密钥GitHub TokenAWS Key其他疑似凭证信息它可以用于手动扫描项目扫描 Git 历史在git commit前自动扫描在 CI/CD 流程中扫描配合自定义规则使用推荐采用 .gitignore .gitleaks.toml .githooks/pre-commit CI/CD 扫描形成多层防护。2. 安装 Gitleaks官方发布地址Releases · gitleaks/gitleaks · GitHubWindows 下可以直接下载官方 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 启动时继承的是旧的环境变量。解决方法完全关闭 VSCode。确保任务管理器中没有残留Code.exe。重新打开 VSCode。新建终端。然后再次执行 gitleaks version可以检查 VSCode 当前 PATH$env:Path确认其中是否存在 D:\Program Files\Gitleaks或者临时添加 PATH$env:Path ;C:\Program Files\Gitleaks然后验证 gitleaks version4. 项目中创建 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-commit9. 配置.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 010. 告诉 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 .githooks12. 推荐项目结构建议项目最终包含project/ ├─ src/ ├─ package.json ├─ .gitignore ├─ .env.example ├─ .gitleaks.toml └─ .githooks/ └─ pre-commit13..gitignore配置Gitleaks 不应该代替.gitignore。敏感文件应该首先通过.gitignore排除。Node / Vue 项目可以加入.env .env.* !.env.example *.pem *.key *.p
Gitleaks基本配置流程（含.githooks配置）
1. Gitleaks 是什么Gitleaks 是一个用于检测 Git 仓库中敏感信息泄露的工具可以扫描API KeyAccess Token数据库密码JWT Secret私钥云服务密钥GitHub TokenAWS Key其他疑似凭证信息它可以用于手动扫描项目扫描 Git 历史在git commit前自动扫描在 CI/CD 流程中扫描配合自定义规则使用推荐采用 .gitignore .gitleaks.toml .githooks/pre-commit CI/CD 扫描形成多层防护。2. 安装 Gitleaks官方发布地址Releases · gitleaks/gitleaks · GitHubWindows 下可以直接下载官方 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 启动时继承的是旧的环境变量。解决方法完全关闭 VSCode。确保任务管理器中没有残留Code.exe。重新打开 VSCode。新建终端。然后再次执行 gitleaks version可以检查 VSCode 当前 PATH$env:Path确认其中是否存在 D:\Program Files\Gitleaks或者临时添加 PATH$env:Path ;C:\Program Files\Gitleaks然后验证 gitleaks version4. 项目中创建 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-commit9. 配置.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 010. 告诉 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 .githooks12. 推荐项目结构建议项目最终包含project/ ├─ src/ ├─ package.json ├─ .gitignore ├─ .env.example ├─ .gitleaks.toml └─ .githooks/ └─ pre-commit13..gitignore配置Gitleaks 不应该代替.gitignore。敏感文件应该首先通过.gitignore排除。Node / Vue 项目可以加入.env .env.* !.env.example *.pem *.key *.p
