文章总结： 文章介绍了使用gitleaks、trufflehog和ggshield三种工具检测代码仓库中API密钥泄露的方法。作者首先解释了为什么需要进行密钥仓库硬编码扫描，包括防止公开仓库泄露、内部信息泄露和管理成本等问题。然后详细介绍了三种工具的安装、使用方法和特点，并进行了对比。文章建议企业应遵循永不硬编码、采用动态获取、密钥轮换+最小授权原则等安全措施，并推荐测试环境与生产环境使用不同密钥。
综合评分： 91
文章分类： 代码审计,安全工具,漏洞分析,安全建设,应用安全

三步定位APIKey泄露：gitleaks + trufflehog + ggshield 实战指南

原创

Ice

Ice ThirdSpace

2025年8月9日 09:00
广东

最近在内部自娱自乐，排查仓库一些历史的API-KEY记录，固有此文。

01

—

前言

为什么要进行秘钥仓库硬编码扫描？
1、代码仓库公开：公司的程序员会将秘钥放到Github公开仓库中，如果被黑客扫到则会直接泄露Key直接对企业安全造成严重的破坏。

    2、内部信息泄露：秘钥若没有被上传到公开网站，仅是存放在内部平台也存在一定风险，因为企业员工绝大部分是不可信的，包括企业的外包，离职人员，或可能遭受到钓鱼攻击都可能提高窃取内部仓库秘钥的可能性。

    3、管理成本及生命管理周期：如果企业采用硬编码在代码或者配置文件当中，如果遇到秘钥泄露的安全事件时，首先是难以排查秘钥对项目影响程度；然后是如果秘钥存放在仓库里，就算整改后秘钥也会存放在git history commit里，就算能进行清除，最后是严格来说秘钥是需要定期轮换的，如果采用硬编码方式企业往往会因为成本过高而不采用定期轮换。

4、企业应当遵循的原则

1）永不硬编码在代码或配置文件当中

2）采用动态获取如KMS，可以参考历史文章

https://mp.weixin.qq.com/s/bdxirs2bWMrvSvZxfUM5Xw

3）应当采取密钥轮换+最小授权原则

4）测试环境或者开发环境的秘钥禁止与生产环境的秘钥通用

5）按照企业自身的实际情况，测试环境或开发环境可以一定程度的在内部暴露密钥

API-KEY检测工具

第一梯队：

https://github.com/GitGuardian/ggshield

https://github.com/trufflesecurity/trufflehog/releases/

https://github.com/gitleaks/gitleaks

第二梯队：

Semgrep

CodeQL

Checkmarx, Fortify, Snyk Code, SonarQube等

02

—

ggshield

|
| |

下载安装

#python3 3.7+python3 -m pip install --upgrade pippython3 -m pip install --user pipxecho 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcsource ~/.bashrcsudo apt update
#报错提醒需要使用py3.9mkdir ~/venvscd ~/venvspython3.9 -m venv ggshield-envsudo apt install python3.9-venvsource ~/venvs/ggshield-env/bin/activate(ggshield-env) root@hcss-ecs-b4f9:~/venvs# ggshield

#dockerdocker pull gitguardian/ggshielddocker run --rm gitguardian/ggshield:latest ggshield --help

使用

该工具使用的第一步必须进行登录

ggshield auth login

ggshield auth login –method token

创建API

网上随便找的github项目进行扫描，视觉效果还是相对不错的，并且自动进行了打码处理

ggshield secret scan path –recursive BlueBus/

查看API的使用额度——每个月有1W的使用额度

(ggshield-env) root@hcss-ecs-b4f9:/tmp123# ggshield quota

Quota available: 9994

Quota used in the last 30 days: 6

Total Quota of the workspace: 10000

| | | | |
| — | — | — | — |
| api-status | Show API status and version | 显示API状态和版本 | 检查GitGuardian服务是否可用 |
| auth | Commands to manage authentication | 认证管理命令 | 登录/登出、API密钥管理 |
| config | Commands to manage configuration | 配置管理命令 | 修改扫描规则、忽略路径等 |
| hmsl | Commands for HasMySecretLeaked | 密钥泄露检查命令 | 查询敏感信息是否已暴露 |
| honeytoken | Commands to work with honeytokens | 蜜罐令牌管理命令 | 创建/监控诱饵密钥 |
| install | Installs as git hook | 安装Git钩子 | 提交/推送时自动扫描 |
| quota | Show remaining API quota | 显示API调用剩余额度 | 监控扫描配额使用情况 |
| secret | Commands to work with secrets | 密钥扫描命令 | 检测代码中的敏感信息 |

该工具支持”在您的私有资产中创建和部署蜜标以检测违规行为”

03

—

gitleaks

下载安装

docker pull ghcr.io/gitleaks/gitleaks:latestdocker run --rm -v "$PWD:/pwd"  ghcr.io/gitleaks/gitleaks:latest

常用用法

#扫描指定目录gitleaks detect -s /path/to/code
#例如sudo docker run --rm -v "$PWD:/pwd" ghcr.io/gitleaks/gitleaks:latest detect -s "/pwd/digift-parent"
#扫描远程仓库gitleaks detect -u https://github.com/user/repo.git
#仅检测当前仓库,不会去查看历史git提交记录--no-git
#显示Api-Key 详情-v
#隐藏50%的敏感字符输出--redact=50
# 在CI/CD中使用（发现密钥就退出）--exit-code 1
# 加载自己的规则--config="/pwd/.gitleaks.toml"

.gitleaks自定义规则

[[rules]]id = "custom-db-pwd"description = "检测数据库密码赋值语句（格式：db_pwd = '...'）"regex = '''db_pwd\s*=\s*['"]([0-9a-zA-Z!@#$%^&*_\-+=]{8,64})['"]'''entropy = 3.5  # 熵值阈值，过滤低随机性字符串keywords = ["db_pwd", "password"]  # 触发关键词加速匹配

#全局白名单参数[allowlist]    escription = "全局忽略规则"    paths = [  # 忽略的文件路径      '''.*\.jpg$''',   # 所有图片      '''test/.*'''     # 测试目录    ]    regexes = [  # 忽略的文本模式      '''public_.*'''   # 忽略以"public_"开头的字符串    ]    commits = ["a1b2c3d"]  # 忽略特定历史提交[4,6](@ref)

别的公众号偷的规则

[[rules]]id&nbsp;=&nbsp;"all-apikey"description =&nbsp;"尽可能匹配"regex:&nbsp;'''(?i)((access_key|access_token|admin_pass|admin_user|algolia_admin_key|algolia_api_key|alias_pass|alicloud_access_key|amazon_secret_access_key|amazonaws|ansible_vault_password|aos_key|api_key|api_key_secret|api_key_sid|api_secret|api.googlemaps AIza|apidocs|apikey|apiSecret|app_debug|app_id|app_key|app_log_level|app_secret|appkey|appkeysecret|application_key|appsecret|appspot|auth_token|authorizationToken|authsecret|aws_access|aws_access_key_id|aws_bucket|aws_key|aws_secret|aws_secret_key|aws_token|AWSSecretKey|b2_app_key|bashrc password|bintray_apikey|bintray_gpg_password|bintray_key|bintraykey|bluemix_api_key|bluemix_pass|browserstack_access_key|bucket_password|bucketeer_aws_access_key_id|bucketeer_aws_secret_access_key|built_branch_deploy_key|bx_password|cache_driver|cache_s3_secret_key|cattle_access_key|cattle_secret_key|certificate_password|ci_deploy_password|client_secret|client_zpk_secret_key|clojars_password|cloud_api_key|cloud_watch_aws_access_key|cloudant_password|cloudflare_api_key|cloudflare_auth_key|cloudinary_api_secret|codepushdeploymentkey|cloudinary_name|codecov_token|config|conn.login|connectionstring|consumer_key|consumer_secret|credentials|cypress_record_key|database_password|database_schema_test|datadog_api_key|datadog_app_key|db_password|db_server|db_username|dbpasswd|dbpassword|dbuser|deploy_password|digitalocean_ssh_key_body|digitalocean_ssh_key_ids|docker_hub_password|docker_key|docker_pass|docker_passwd|docker_password|dockerhub_password|dockerhubpassword|dot-files|dotfiles|droplet_travis_password|dynamoaccesskeyid|dynamosecretaccesskey|elastica_host|elastica_port|elasticsearch_password|encryption_key|encryption_password|env.heroku_api_key|env.sonatype_password|eureka.awssecretkey)[a-z0-9_ .\-,]{0,25})(=|>|:=|\|\|:|<=|=>|:).{0,5}[\"]([0-9a-zA-Z\-_=]{8,64})[\"]'''entropy =&nbsp;3.5&nbsp;&nbsp;# 熵值阈值，过滤低随机性字符串

检测历史的commit

扫描后发现显示泄漏的api，但是查看一下扫描的仓库当前并没有代码显示该文件内容存在泄漏的秘钥

Gitleaks报告的是历史提交中的敏感信息

Gitleaks报告的是历史提交中的敏感信息

cd light-webapp/git show 7f5e417fdad1c13bcfd05ce1a7fb4fe1613eecf5:src/stores/modules/user.ts

使用 –no-git 扫描，就只会扫描当前的代码，而不会扫描历史代码

04

—

truffleshog

下载安装

docker pull trufflesecurity/trufflehogdocker run --rm -v "$PWD:/pwd" trufflesecurity/trufflehog

常用用法

#扫描远程仓库trufflehog git https://github.com/user/repo.git
#扫描s3云存储trufflehog s3 --bucket=my-bucket
#扫描google cloud storetrufflehog gcs --project=my-project
#扫描当前目录下的所有文件docker run --rm -v "$PWD:/pwd" trufflesecurity/trufflehog filesystem /pwd
#扫描当前目录下的xxxproject项目docker run --rm -v "$PWD:/pwd" trufflesecurity/trufflehog filesystem /pwd/xxxproject

常用参数

--json  # JSON格式输出 --csv   # CSV格式输出

#设置熵值--filter-entropy=5.0
#寻找到密钥时退出（CI/CD阻断流程）--fail
#自定义配置文件--config=/pwd/config.yaml
#不验证结果（默认会验证，建议关闭）--no-verification

 #排除某些路径和文件 --exclude-paths="**/node_modules/**,**/vendor/**"

扫描结果：

docker run –rm -v “$PWD:/pwd” trufflesecurity/trufflehog filesystem /pwd/xxxproject

05

—

常规状态结果对比

使用非标准化的TOKEN名称检测

gitleaks

echo “SLACK_TOKE=sk-2e765144319c4507a50596f0d3b3fb37” | docker run –rm -i ghcr.io/gitleaks/gitleaks:latest stdin

没有检测出来

trufflehog

echo “SLACK_TOKE=sk-2e765144319c4507a50596f0d3b3fb37” | docker run –rm -i trufflesecurity/trufflehog stdin

没有检测出来

修改为带有token关键词的API-KEY

gitleaks成功检测，truffehog未检测出来，可以看出来默认的规则库之间还是存在比较大的检测差别。

当然如果使用自定义规则肯定100%能够检测出来

gitleaks和truff对比

这三个工具都各有优劣

比如说gitleaks只能扫描仓库，没法扫描镜像，以及多种多样的类型

gitleaks比较轻量级，速度最快

免责声明：

本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。

任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。

本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。

本文转载自：Ice ThirdSpace Ice《三步定位APIKey泄露：gitleaks + trufflehog + ggshield 实战指南》