已合并
feat(pre-commit): 集成 Gitleaks 本地离线密钥扫描功能 #409
yuliangbin创建于 7月11日
feat(pre-commit): 集成 Gitleaks 本地离线密钥扫描功能 #409
已合并
共 2 个文件变更+99-0
| @@ -85,3 +85,19 @@ repos: | |||||||||||||||||
| 85 | - "--verbose" | 85 | - "--verbose" | ||||||||||||||
| 86 | - "-i" | 86 | - "-i" | ||||||||||||||
| 87 | exclude: ^build/|tests/third_party/ | 87 | exclude: ^build/|tests/third_party/ | ||||||||||||||
| 88 | + | ||||||||||||||||
| 89 | + # -------------------------- Gitleaks 本地离线二进制扫描 -------------------------- | ||||||||||||||||
| 90 | + - repo: local | ||||||||||||||||
| 91 | + hooks: | ||||||||||||||||
| 92 | + - id: gitleaks-offline-scan | ||||||||||||||||
| 93 | + name: Gitleaks Secret Scan(Local Binary) | ||||||||||||||||
| 94 | + entry: ./gitleaks | ||||||||||||||||
| 95 | + language: system | ||||||||||||||||
| 96 | + pass_filenames: true | ||||||||||||||||
 | |||||||||||||||||
| 97 | + exclude: ^\.pre-commit-config\.yaml$ | ||||||||||||||||
| 98 | + args: | ||||||||||||||||
| 99 | + - protect | ||||||||||||||||
| 100 | + - --verbose | ||||||||||||||||
| 101 | + - --redact | ||||||||||||||||
| 102 | + - --config=pre-commit/.gitleaks.toml | ||||||||||||||||
🟡 Medium Priority 变更行：
触发条件：开发者在暂存文件的同时存在未暂存的变更（这是日常开发中的常见场景）。 修复：在 args 中增加 建议：在 args 中增加 改动建议
  | |||||||||||||||||
| 103 | + stages: [pre-commit] | ||||||||||||||||
| @@ -0,0 +1,83 @@ | |||
| 1 | +# ============================================== | ||
| 2 | +# Gitleaks 自定义配置文件 | ||
| 3 | +# 路径：pre-commit/.gitleaks.toml | ||
| 4 | +# 当前状态：仅继承二进制内置官方全套默认规则，无新增/无屏蔽任何规则 | ||
| 5 | +# 标准继承语法：[extend] useDefault = true（官方推荐，通用离线二进制兼容） | ||
| 6 | +# ============================================== | ||
| 7 | +title = "torch_npu pre-commit secret scan config" | ||
| 8 | + | ||
| 9 | +# 【标准继承内置默认规则】 | ||
| 10 | +# useDefault=true：加载工具内置全部密钥检测规则（AWS/Git/SSH/OBS等） | ||
| 11 | +# 注意：useDefault 和 path 只能二选一，不可同时使用 | ||
| 12 | +[extend] | ||
| 13 | +useDefault = true | ||
| 14 | +# disabledRules = ["generic-api-key","generic-password"] | ||
| 15 | +# ↑ 取消注释可批量全局禁用指定内置规则，填写规则ID数组 | ||
| 16 | + | ||
| 17 | +# ============================================================================== | ||
| 18 | +# 1、全局屏蔽内置规则两种写法（注释示例，当前未启用） | ||
| 19 | +# ============================================================================== | ||
| 20 | +# 写法A（新版推荐，数组批量禁用，写在[extend]内） | ||
| 21 | +# [extend] | ||
| 22 | +# useDefault = true | ||
| 23 | +# disabledRules = ["generic-api-key","generic-password"] | ||
| 24 | + | ||
| 25 | +# 写法B（旧版兼容，单条逐条禁用） | ||
| 26 | +# [[rules.disabled]] | ||
| 27 | +# id = "generic-api-key" | ||
| 28 | +# [[rules.disabled]] | ||
| 29 | +# id = "generic-password" | ||
| 30 | +# 查询所有内置规则ID命令：./gitleaks detect --list-rules --config=pre-commit/.gitleaks.toml | ||
| 31 | + | ||
| 32 | +# ============================================================================== | ||
| 33 | +# 2、新增自定义业务检测规则（注释示例，当前未启用） | ||
| 34 | +# 格式固定 [[rules]]，用于检测项目特有凭证 | ||
| 35 | +# ============================================================================== | ||
| 36 | +# [[rules]] | ||
| 37 | +# id = "huawei-obs-plain-ak-sk" | ||
| 38 | +# description = "硬编码华为云OBS AK/SK明文密钥" | ||
| 39 | +# regex = '''(access_key|secret_key|AK|SK)\s*[:=]\s*["']?[A-Z0-9]{20,}["']?''' | ||
| 40 | +# secretGroup = 1 | ||
| 41 | +# entropy = 3.5 | ||
| 42 | +# keywords = ["ak", "sk", "obs"] | ||
| 43 | +# # 单条规则局部白名单：ut测试目录跳过本条检测 | ||
| 44 | +# [[rules.allowlist]] | ||
| 45 | +# paths = ["^ut/", "^test/"] | ||
| 46 | + | ||
| 47 | +# ============================================================================== | ||
| 48 | +# 3、全局白名单配置（新版必须 [[allowlists]]，不能 [allowlist]） | ||
| 49 | +# 语法要求：内部至少存在一个未注释数组，否则配置加载失败 | ||
| 50 | +# ============================================================================== | ||
| 51 | +[[allowlists]] | ||
| 52 | +# 占位空正则，仅用于通过语法校验，不会放行任何文件 | ||
| 53 | +paths = ["^$"] | ||
| 54 | +# 如需放行目录取消注释示例 | ||
| 55 | +# paths = [ | ||
| 56 | +# "^dist/", | ||
| 57 | +# "^build/", | ||
| 58 | +# "\\.md$" | ||
| 59 | +# ] | ||
| 60 | +# 放行固定测试假密钥字符串 | ||
| 61 | +stopwords = [ | ||
| 62 | + # "dummy-test-ak-123456", | ||
| 63 | + # "fake-secret-000000" | ||
| 64 | +] | ||
| 65 | +commits = [] | ||
| 66 | + | ||
| 67 | +# ============================================================================== | ||
| 68 | +# 4、代码单行/文件内局部屏蔽告警（无需修改本配置文件） | ||
| 69 | +# 两种行内注释方式，提交代码时写在代码末尾，gitleaks自动识别放行 | ||
| 70 | +# ============================================================================== | ||
| 71 | +# 方式1：仅屏蔽当前单行密钥告警（推荐） | ||
| 72 | +# access_key = "AKXXXXXXXXXXXXXXXXXXXX" # gitleaks:allow | ||
| 73 | +# | ||
 【openlibing.ci】识别到代码检查告警抑制注释，匹配工具：gitleaks，请Committer检视其合理性。 【openlibing.ci】识别到代码检查告警抑制注释，匹配工具：gitleaks，请Committer检视其合理性。 【openlibing.ci】识别到代码检查告警抑制注释，匹配工具：gitleaks，请Committer检视其合理性。 | |||
| 74 | +# 方式2：屏蔽整个文件全部告警，写在文件最顶部 | ||
| 75 | +# # gitleaks:skip-file | ||
| 76 | + | ||
| 77 | +# ============================================================================== | ||
| 78 | +# 全局扫描基础参数 | ||
| 79 | +# ============================================================================== | ||
| 80 | +minEntropy = 3.0 | ||
| 81 | +redact = true | ||
| 82 | +maxMatchLength = 2048 | ||
| 83 | +scanGitHistory = false | ||
🟡 Medium Priority 变更行：第 80–83 行的 问题链：
失效模式：开发者可能误以为已通过配置文件设置了全局熵阈值、脱敏输出、匹配长度限制和历史扫描禁用，但实际上这些配置均未生效，造成安全配置的虚假安全感。例如，若将来有人将 建议：删除第 80–83 行的无效全局配置键，或将其改为注释说明正确的 CLI 使用方式。例如 | |||
🟠 High Priority
变更行：
.pre-commit-config.yaml第 96 行pass_filenames: true，搭配第 99 行protect子命令。gitleaks protect命令直接扫描 git 暂存区，不接受文件路径作为位置参数。pre-commit 在pass_filenames: true时会将每个暂存文件作为独立参数追加到 entry 命令末尾，实际执行命令变为：gitleaks（v8+）的
protect子命令使用 cobra 框架且不接受额外位置参数，这些文件参数会导致 gitleaks 报错退出（"unknown command/argument"），pre-commit hook 始终失败，密钥扫描功能完全失效。触发条件：任何有暂存文件的 commit 尝试都会触发此失败。
标准修复：将
pass_filenames设为false，并添加--staged标志以精确扫描暂存区内容。这是 gitleaks 官方推荐的 pre-commit 配置模式。建议：将
pass_filenames改为false，同时在 args 中添加--staged标志以确保只扫描暂存区内容。这是 gitleaks 官方 pre-commit hook 的标准配置模式。true