ChatGPT-API-Scanner：从密钥泄露扫描工具看代码安全与自动化检测

1. 项目概述与核心思路拆解

最近在安全研究领域，一个名为 ChatGPT-API-Scanner 的工具引起了我的注意。简单来说，这是一个专门用于在 GitHub 上扫描泄露的 OpenAI API 密钥的自动化脚本。它的存在，与其说是一个“攻击工具”，不如说是一面“警示镜”，清晰地映照出开发者在代码安全实践上的疏忽。我自己在管理团队项目和审查开源代码时，也时常为这类无意的密钥泄露感到头疼。这个项目正好提供了一个绝佳的研究样本，让我们能深入理解密钥泄露的常见模式、自动化检测的原理，以及最重要的——如何从根本上避免这类问题。

这个工具的核心价值在于其“主动发现”能力。它模拟了潜在攻击者的行为，通过自动化爬虫技术，在公开的代码仓库中搜寻那些本不该出现的敏感凭证。对于安全研究人员、企业安全团队乃至个人开发者而言，理解其工作原理，能帮助我们更好地构建防御策略，检查自身项目是否存在类似风险。它不适合，也绝不能用于非法获取他人资源，但其技术实现本身，对于提升我们的安全意识和防护水平，具有很高的学习和参考价值。

接下来，我将从工具的设计思路、技术实现细节、实操部署过程，以及围绕API密钥安全的最佳实践，进行一次全面的拆解。无论你是对Python自动化感兴趣，还是关心代码安全，相信都能从中获得启发。

2. 核心组件与技术选型解析

2.1 为什么选择 Selenium 而非官方 API？

项目文档的FAQ里第一个问题就直指核心：为什么用Selenium这种浏览器自动化工具，而不是更“正统”的GitHub Search API？这背后有两个关键的技术原因。

首先，是搜索能力的限制。GitHub的官方搜索API功能相对基础，它支持的是关键词匹配，但不支持正则表达式（Regex）搜索。而寻找API密钥这类具有特定模式（例如以sk-开头的一长串字符）的字符串，正则表达式是最精准、最高效的武器。通过编写如sk-[a-zA-Z0-9]{48}这样的正则模式，我们可以几乎无遗漏地匹配OpenAI API密钥的格式。Web端搜索虽然对普通用户隐藏了正则功能，但其底层引擎是支持的，通过Selenium操控浏览器，我们就能间接利用这个强大的搜索能力。

其次，是绕过反爬策略与模拟真人行为。直接调用API虽然速度快，但容易触发频率限制（Rate Limit），且请求头等信息更容易被服务器识别为机器人。Selenium驱动一个真实的Chrome浏览器，所有的网络请求、Cookie管理、页面渲染都与真人操作无异，这极大地降低了被GitHub风控系统拦截的概率。当然，代价就是速度会慢一些，资源消耗也更大，但这在“获取最佳搜索结果”这个首要目标面前，是可以接受的折中。

注意：使用Selenium进行自动化爬取必须遵守目标网站（此处是GitHub）的robots.txt协议和服务条款。高频率、大规模的爬取行为不仅不道德，也可能导致你的IP甚至GitHub账户被封禁。此工具的设计应仅限于小范围、低频次的安全研究用途。

2.2 数据库设计：为什么用 SQLite？

工具将扫描结果存储在github.db这个SQLite数据库中。这是一个非常务实的选择。SQLite是一个无服务器、零配置的进程内数据库，整个数据库就是一个.db文件，无需安装任何额外的数据库服务（如MySQL或PostgreSQL）。这对于一个轻量级的、单机运行的Python脚本来说，简直是绝配。它简化了部署，用户克隆项目后就能直接运行，没有外部依赖。

从数据表设计来看，它至少会包含以下关键字段：api_key（密钥本身）、source_repo（发现该密钥的仓库URL）、found_time（发现时间）、status（密钥状态，如有效、无效、已吊销）。status字段尤为重要，因为扫描到的密钥可能已经过期或被所有者主动撤销，工具后续可以调用OpenAI的验证接口来更新这个状态，避免研究者使用无效密钥。

2.3 依赖管理：uv 的现代 Python 工作流

项目没有使用传统的pip+requirements.txt，而是采用了新兴的uv包管理器和pyproject.toml配置。这是一个值得称赞的现代实践。uv由 Astral 公司（也是 Ruff 的创造者）开发，用 Rust 编写，速度极快，并且能自动处理 Python 版本（通过.python-version文件）。uv sync命令相当于pip install，但它更智能、更快速，并且能创建可复现的依赖环境。

pyproject.toml是 Python 社区推崇的新一代项目配置标准，它统一了打包、依赖管理和工具配置。在这个文件里，不仅定义了项目依赖，还可以配置代码格式化（如black）、代码检查（如ruff、pylint）等开发工具。通过uv sync --all-groups可以一键安装所有开发依赖，这对于保障代码质量和团队协作一致性非常有帮助。采用这套工具链，体现了项目维护者对开发体验和工程规范的前沿关注。

3. 详细实操部署与运行指南

3.1 环境准备与依赖安装

在开始运行扫描器之前，我们需要一个干净、可复现的环境。以下步骤在 macOS、Windows（含WSL2）和主流Linux发行版上均测试通过。

第一步：安装系统级依赖

1. Google Chrome：确保系统已安装 Chrome 浏览器。Selenium 需要它作为驱动。你可以从官网下载安装。
2. uv：这是项目的Python包管理器。打开终端，执行以下命令一键安装（以类Unix系统为例）：

   curl -LsSf https://astral.sh/uv/install.sh | sh

   安装完成后，重启终端或执行source ~/.bashrc（或对应shell的配置文件）使uv命令生效。在Windows上，如果使用PowerShell，也有对应的安装脚本。

第二步：获取项目代码在终端中，选择一个合适的工作目录，克隆仓库并进入：

git clone https://github.com/Junyi-99/ChatGPT-API-Scanner.git cd ChatGPT-API-Scanner

此时，你会看到项目目录结构，核心是main.py，以及pyproject.toml、uv.lock等配置文件。

第三步：同步项目依赖这是最关键的一步，uv会根据配置文件自动创建虚拟环境并安装所有依赖：

uv sync

这个命令会：

• 读取.python-version文件，自动下载并配置指定版本的Python（如果本地没有）。
• 根据pyproject.toml和uv.lock，解析所有生产依赖（如selenium, requests, regex等），并安装到项目独立的虚拟环境中。
• 所有依赖都被隔离在这个项目内，不会污染你的系统Python环境。

如果你计划阅读或修改代码，建议安装开发工具组，以便进行代码检查和格式化：

uv sync --all-groups

3.2 首次运行与身份认证

完成安装后，直接运行主脚本：

uv run main.py

uv run命令会自动激活项目对应的虚拟环境，并在其中执行main.py。

首次运行的认证流程：

1. 脚本启动后，Selenium 会自动打开一个新的 Chrome 浏览器窗口。
2. 浏览器会导航到 GitHub 的登录页面。这里需要你手动输入你的 GitHub 账号和密码进行登录。
3. 登录成功后，浏览器窗口可能会保持打开状态，脚本将在后台控制它进行搜索操作。

重要提示：这里需要使用你自己的 GitHub 账号。我强烈建议不要使用你的主账号或关联了重要资源的账号。可以专门注册一个用于安全测试的“小号”。因为自动化脚本的行为可能被 GitHub 视为异常，存在一定的风险。登录后，请务必注意不要进行任何手动操作，以免干扰脚本运行。

3.3 高级参数与定制化扫描

工具提供了一些命令行参数，让你可以更灵活地控制扫描行为。理解这些参数能帮你进行更有针对性的研究。

从指定迭代开始 (--from-iter)扫描过程是分“轮次”或“迭代”进行的，每一轮可能对应一组特定的搜索关键词和语言组合。如果脚本意外中断，你可以使用这个参数从断点恢复，避免重复劳动。

uv run main.py --from-iter 100

仅检查数据库中已有密钥的状态 (-ceko)这个模式不会进行新的 GitHub 搜索，而是读取github.db中已存储的 API 密钥，逐个调用 OpenAI 的验证接口，更新它们的status字段（例如从unknown更新为valid或invalid）。这对于定期清理数据库、确认密钥有效性非常有用。

uv run main.py --check-existed-keys-only

自定义搜索关键词与编程语言 (-k,-l)这是最强大的定制功能。默认的搜索列表可能比较宽泛。你可以根据研究重点，缩小或调整搜索范围。

• -k或--keywords: 指定搜索关键词列表。例如，你怀疑某些密钥可能藏在特定的配置变量名里。
• -l或--languages: 指定在哪种编程语言的代码中进行搜索。这利用了GitHub的高级搜索语法language:XXX。

示例：假设你想专注于在 Python 和 JavaScript 项目中，寻找与“openai”和“api key”相关的泄露。

uv run main.py -k “openai” “api key” “OPENAI_API_KEY” -l python javascript

执行后，工具会组合这些参数，生成如openai language:python、“api key” language:javascript等搜索查询，进行更有针对性的扫描。

调试模式 (--debug)当脚本运行出现异常或结果不符合预期时，可以开启调试模式。这会输出更详细的日志信息，包括Selenium执行的每一步、网络请求和响应等，便于定位问题。

uv run main.py --debug

4. 结果分析与数据管理

4.1 解读扫描结果数据库

脚本运行后，会在项目根目录生成或更新github.db文件。你可以使用任何 SQLite 浏览器（如 DB Browser for SQLite ）或命令行工具来查看它。

通过命令行查看的基本步骤：

# 进入 sqlite3 交互环境 sqlite3 github.db # 查看所有表 .tables # 假设主表名为 ‘found_keys’，查看其结构 .schema found_keys # 查看前10条记录 SELECT * FROM found_keys LIMIT 10; # 退出 .quit

典型的表结构可能包含以下字段：

4.2 密钥有效性验证与状态更新

扫描到的密钥只是“字符串”，不代表它有效。status字段为unknown的记录需要进一步验证。工具可能内置或你可以自行编写一个验证脚本。

验证原理是调用 OpenAI API 的一个简单、低消耗的端点，例如列出模型（GET https://api.openai.com/v1/models）或进行一个极小的补全请求。关键是要设置一个很低的max_tokens和超时时间，避免消耗他人额度（尽管密钥已泄露，但伦理上仍应最小化影响）。

一个简单的验证思路（伪代码）：

import requests import sqlite3 def check_key_status(api_key): headers = {“Authorization”: f“Bearer {api_key}”} try: # 使用一个轻量级请求，例如获取模型列表 resp = requests.get(“https://api.openai.com/v1/models”, headers=headers, timeout=5) if resp.status_code == 200: return “valid” elif resp.status_code == 401: # 认证失败 return “invalid” else: return “error” except requests.exceptions.RequestException: return “error” # 连接数据库，更新状态 conn = sqlite3.connect(‘github.db’) cursor = conn.cursor() cursor.execute(“SELECT id, api_key FROM found_keys WHERE status = ‘unknown’“) for key_id, api_key in cursor.fetchall(): new_status = check_key_status(api_key) cursor.execute(“UPDATE found_keys SET status = ?, last_checked = datetime(‘now’) WHERE id = ?”, (new_status, key_id)) conn.commit() conn.close()

运行--check-existed-keys-only模式时，工具内部就是在执行类似的过程。

4.3 数据伦理与后续处理

当你手中有了一份包含潜在有效API密钥的列表时，必须严肃对待数据伦理。

1. 绝不使用：这些密钥属于他人财产，使用它们等同于盗窃服务和资源，是明确违反OpenAI服务条款和可能涉及法律的行为。
2. 负责任披露：更恰当的做法是进行“负责任披露”。你可以尝试联系该仓库的所有者（通过GitHub Issue或邮箱），礼貌地告知其代码中可能存在API密钥泄露，建议其立即撤销旧密钥并生成新密钥。注意沟通方式，避免被误认为是威胁或钓鱼。
3. 清理数据：用于研究后，应及时、安全地删除本地数据库文件。切勿公开分享或传播这些敏感数据。

5. 深度防御：如何避免成为被扫描的目标

研究这个工具的最大意义，在于反向思考：我们如何确保自己的项目不会出现在这样的扫描结果里？以下是我总结的、经过实践检验的密钥管理最佳实践。

5.1 绝对禁止将密钥硬编码在代码中

这是最原始也是最危险的错误。无论你的仓库是公开还是私有，都不要这样做。

• 错误示例：在config.py或app.js中直接写API_KEY = “sk-...”。
• 风险：一旦代码被提交到版本控制系统（如Git），即使后来删除，历史记录中仍然存在。如果仓库被意外设为公开，或内部成员泄露，密钥即刻暴露。

5.2 使用环境变量管理密钥

这是最基本、最通用的安全实践。将密钥存储在操作系统的环境变量中，代码运行时从环境变量读取。

# Python 示例 import os api_key = os.environ.get(“OPENAI_API_KEY”) if not api_key: raise ValueError(“请设置 OPENAI_API_KEY 环境变量”)

如何设置环境变量？

• 本地开发：在项目根目录创建.env文件，写入OPENAI_API_KEY=sk-...，并使用python-dotenv库在程序启动时加载。切记将.env加入.gitignore文件！
• 生产环境：在服务器或云平台（如AWS, GCP, Vercel, Railway）的控制面板中配置环境变量。
• CI/CD管道：在GitHub Actions、GitLab CI等工具的“Secrets”设置中配置。

5.3 利用密钥管理服务

对于企业级应用或拥有大量敏感信息的项目，应使用专业的密钥管理服务：

• 云服务商提供：AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager。
• 第三方服务：HashiCorp Vault, Doppler, 1Password Secrets Automation。 这些服务提供加密存储、细粒度访问控制、自动轮换、审计日志等功能，安全性远高于环境变量。

5.4 启用并善用 Git 的防护机制

GitHub 等平台提供的安全功能是你的第一道防线。

• GitHub Push Protection：正如项目文档警告的，GitHub 已为所有新公开仓库默认启用推送保护。它会实时扫描推送内容中的已知秘密模式（包括OpenAI API密钥），并在检测到时阻止推送。你应在所有仓库中强制启用此功能。
• GitHub Secret Scanning：GitHub 会主动扫描仓库中的所有内容（包括历史提交），与合作伙伴（如OpenAI）的秘密模式数据库匹配。如果发现泄露，GitHub 会通知对应的服务提供商（如OpenAI），由他们通知并协助开发者撤销密钥。作为仓库所有者，你可以在设置中启用此功能。
• .gitignore文件：这是本地防护。确保将包含敏感信息的文件（如.env,config.ini,*.pem,*.key）加入.gitignore。
• Pre-commit Hooks：在本地提交前自动检查。可以使用pre-commit框架集成像detect-secrets、truffleHog这样的工具，在代码进入暂存区前就发现潜在泄露。

5.5 密钥使用的最小权限与定期轮换

• 最小权限原则：不要使用权限过大的密钥。OpenAI 允许你创建仅具有特定权限（如只读、仅限某些模型）的API密钥。为不同的应用场景创建不同的密钥。
• 定期轮换：像更换密码一样，定期（如每季度）撤销旧密钥并生成新密钥。即使密钥不慎泄露，其有效窗口也很有限。
• 监控与告警：关注OpenAI账户的使用情况仪表板。设置用量告警，如果发现异常调用峰值，立即检查是否泄露。

6. 常见问题排查与进阶技巧

6.1 运行时报错与解决方案

在实际运行中，你可能会遇到一些问题。这里记录几个我踩过的坑和解决方法。

问题1：ChromeDriver版本不匹配错误

selenium.common.exceptions.SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version ...

原因与解决：Selenium 需要与已安装的 Chrome 浏览器版本精确匹配的ChromeDriver。项目可能通过webdriver-manager等库自动管理，但有时会失败。

• 方案A（推荐）：确保uv sync已安装所有依赖。项目应该配置了自动下载正确驱动。
• 方案B（手动）：查看你的Chrome版本（浏览器地址栏输入chrome://version/），然后到 ChromeDriver官网 下载对应版本的驱动，放在系统PATH或项目目录下。

问题2：GitHub 登录后脚本卡住或报错原因：登录流程可能触发了二次验证（2FA），或者登录后的页面跳转与脚本预期不符。

• 解决：确保用于测试的GitHub账号关闭了双重认证，以简化自动化流程。如果必须使用2FA账号，可能需要修改脚本，处理TOTP验证码，这大大增加了复杂度。

问题3：扫描速度非常慢，且很快被限制原因：GitHub 对Web搜索有严格的频率限制和反爬机制。即使使用Selenium模拟真人，过快、过多的请求也会被识别。

• 解决：这是设计使然。工具内部应该已经设置了合理的延迟（如time.sleep(random.uniform(2, 5))在请求之间）。不要试图通过减少延迟或增加线程来提速，这几乎必然导致IP被临时封禁。将工具视为一个低速、长期的监控工具，而非高速抓取器。

6.2 扩展工具功能的想法

基于这个项目的基础框架，你可以将其扩展为更通用的内部安全审计工具。

1. 多平台扫描：除了GitHub，是否可以适配 GitLab、Bitbucket 等其它代码托管平台？它们的搜索接口和页面结构不同，需要单独编写适配模块。
2. 更多秘密类型：除了OpenAI API密钥，还可以定义正则模式来扫描 AWS Access Key、Google API Key、数据库连接字符串、各种服务的令牌等。可以参考 GitHub 的 secret patterns database 或 TruffleHog 的规则 。
3. 集成到CI/CD：将扫描逻辑封装成一个脚本或Docker镜像，集成到你的CI/CD管道中。在每次代码推送或合并请求时，自动扫描变更内容，防止新的秘密被提交。这比事后扫描更有预防性。
4. 结果通知：扫描到潜在泄露后，除了存入数据库，是否可以自动发送邮件或Slack通知给指定的安全负责人？

6.3 关于“免费GPT”和密钥安全的思考

项目关键词中提到了“freegpt”。这恰恰点出了一个核心矛盾：很多人寻找泄露的API密钥，是希望“免费”使用GPT服务。但这种行为：

• 不合法也不道德：侵犯了密钥所有者和OpenAI的权益。
• 不可靠：泄露的密钥可能随时被撤销，导致你的应用中断。
• 高风险：你使用的密钥可能被原所有者监控，你的所有请求内容和结果都可能被他人窥视，毫无隐私和安全可言。

真正可持续的“免费”或低成本使用方式，是合理利用官方提供的免费额度（如新用户赠送）、参与研究项目获取资助，或者使用按量付费的API，其成本在合理使用下并不高。依赖泄露的密钥，无异于在沙滩上建城堡。

回过头来看，ChatGPT-API-Scanner 这个项目，其技术实现简洁而有效，清晰地展示了自动化信息收集的能力。而它最大的价值，是给所有开发者上了一堂生动的安全教育课：在数字世界里，任何写入代码的明文秘密，都如同写在公共场所的日记。保护它们，不是可选项，而是开发生命周期中必须贯穿始终的底线思维。