JMartynov/secret-scan

# LLM 敏感信息泄露检测器 [](https://github.com/JMartynov/secret-scan/actions/workflows/self-scan.yml) **LLM 敏感信息泄露检测器**是一款安全工具，旨在防止在与大型语言模型（LLM）交互时意外泄露敏感数据。 现代 AI 开发工作流程经常需要向语言模型发送代码片段、配置文件、日志和调试输出。在很多情况下，开发者在无意中会包含敏感信息，如 API 密钥、数据库凭据、私有令牌或内部基础设施详情。 本项目会在敏感信息**离开开发者环境之前**进行检测。 该系统会扫描提示词、响应、日志和源代码，以识别潜在的敏感信息，并在机密数据可能暴露时向用户发出警告。 # 问题 LLM 辅助开发显著提高了开发者的工作效率。然而，它也引入了一种新的安全风险。 开发者经常将整个代码块、配置文件或日志粘贴到 AI 助手中，提出如下问题： 这些输入通常包含以下敏感信息： * API 密钥 * 数据库凭据 * 私有令牌 * 身份验证密钥 * 内部基础设施 URL * 加密密钥 * JWT 令牌 可能泄露的输入示例： ``` OPENAI_API_KEY=sk-abc123 DATABASE_URL=postgres://user:pass@db JWT_SECRET=super-secret-token ``` 一旦发送到外部 LLM 服务，这些数据可能会： * 出现在提供商日志中 * 被存储用于调试 * 违反合规策略 * 泄露敏感的基础设施详情 软件制品中敏感信息泄露的情况正在迅速增加，近年来在公共仓库中发现了数百万个凭据。（[arXiv][1]） 安全团队现在将**敏感信息检测视为现代开发管道的关键部分**。 # 解决方案 LLM 敏感信息泄露检测器会自动扫描 AI 交互数据，并在传输前识别潜在的敏感信息。 该工具分析： * 发送给 LLM 的提示词 * LLM 的响应 * 应用程序日志 * 代码片段 * 配置文件 当检测到潜在的敏感信息时，该工具会生成警告，描述： * 敏感信息类型 * 位置 * 严重程度 输出示例： ``` ⚠ Secrets detected Type: OpenAI API Key Location: line 3 Risk: HIGH Type: Database credentials Location: line 4 Risk: CRITICAL ``` 这允许开发者在敏感信息到达外部 AI 系统之前**将其删除或脱敏**。 # 核心检测方法 检测引擎使用与现代敏感信息检测系统类似的分层策略。 大多数敏感信息扫描器依赖三种互补技术： 1. **模式匹配（正则表达式）** 识别具有已知格式的敏感信息，如 AWS 密钥或 GitHub 令牌。 2. **熵分析** 检测看起来随机的字符串，这对于加密令牌很典型。 3. **上下文分析** 通过分析周围代码和变量名来减少误报。（[gitguardian.com][2]） 结合这些方法可以显著提高准确性。 # 检测的敏感信息类型 该扫描器可检测超过 **180 类**敏感数据，包括： ### API 密钥 示例： ``` sk-xxxxxxxxxxxxxxxx AIzaSyxxxxxxxxxxxx ``` ### 云凭据 示例： ``` AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AZURE_TOKEN ``` ### 版本控制令牌 示例： ``` ghp_xxxxxxxxxxxxxxxxx glpat_xxxxxxxxxxxxx ``` ### 身份验证密钥 示例： ``` JWT_SECRET SESSION_SECRET PRIVATE_KEY ``` ### 数据库凭据 示例： ``` postgres://user:password@host mysql://root:pass@db ``` ### 加密材料 示例： ``` -----BEGIN PRIVATE KEY----- ``` # 功能矩阵 **LLM 敏感信息泄露检测器**提供了一套全面的功能，专为安全性、性能和开发者体验而设计。 | 类别 | 功能 | 状态 | 实现详情 | | :--- | :--- | :--- | :--- | | **检测引擎** | **正则匹配（RE2）** | ✅ | 主要引擎使用 `google-re2`。
快速、线性时间匹配。 | | | **正则匹配（传统）** | ✅ | 回退到 `regex`（Python）处理复杂模式。
防止 ReDoS 攻击。 | | | **熵分析** | ✅ | 对随机外观的令牌进行香农熵评分（最少 20 个字符）。 | | | **上下文启发式** | ✅ | 根据周围关键词（如 `prod`、`password`、`key`）识别敏感信息。支持多语言对话意图匹配（英语、西班牙语、法语、德语）。 | | | **基于规则的逻辑** | ✅ | 从 `data/` 加载 1750+ 条规则（2026 年扩展）。 | | **输入源** | **文件扫描** | ✅ | 扫描支持 UTF-8 的本地文件。
包含错误处理。 | | | **标准输入/管道输入** | ✅ | 实时处理管道数据（如 `cat log \| ./run.sh`）。 | | | **直接文本** | ✅ | 通过 `--text` 标志快速验证提示词。 | | | **流式处理** | ✅ | 优化的逐行生成器，实现低延迟处理。 | | **脱敏** | **脱敏** | ✅ | 遮盖敏感信息中间部分（如 `AKIA...CDEF`）。 | | | **哈希** | ✅ | 一致的 SHA-256 哈希（前 12 个字符），用于安全调试。 | | | **合成数据** | ✅ | [新功能] 使用 `Faker` 生成逼真的假数据（AWS、GitHub、电子邮件）。 | | **安全与性能** | **关键词过滤** | ✅ | 使用 `ahocorasick-rs` 自动机（带 SIMD）跳过缺少必需关键词的规则。 | | | **并行扫描** | ✅ | [新功能] 使用 `ProcessPoolExecutor` 进行高速历史审计和多文件目录扫描。 | | | **提交缓存** | ✅ | [新功能] 使用 `.secretscan_cache` 进行增量扫描，跳过已验证的 SHA。| | | **零拷贝扫描** | ✅ | 使用带块重叠的 `mmap` 映射，处理 GB 级日志。 | | | **ReDoS 保护** | ✅ | 非 RE2 正则执行使用 `SIGALRM` 超时（1秒）。 | | | **输入截断** | ✅ | 块限制为 1MB 字符，防止内存耗尽。 | | | **去重** | ✅ | 合并重叠发现结果。
优先最长匹配。 | | | **强制全量扫描** | ✅ | `--force-scan-all` 跳过关键词过滤器，对每一行进行评分。 | | **报告与 UI** | **精确高亮** | ✅ | [新功能] 带 ANSI 颜色的上下文行，敏感信息以红色高亮显示。 | | | **修复建议** | ✅ | [新功能] 可操作建议，包含官方提供商文档链接。 | | | **彩色输出** | ✅ | 风险级别的 ANSI 颜色（红色=高，黄色=中，蓝色=低）。 | | | **报告格式** | ✅ | `Summary`（仅计数）。
`Short`（脱敏后）。
`Full`（原始敏感信息+上下文）。
`SARIF`（GitHub 代码扫描）。 | | | **CI/CD 友好** | ✅ | `--nocolors` 标志。
自动化标准退出码。 | | **测试与开发** | **BDD 验收** | ✅ | `acceptance.feature` 中的 25 个场景（包括 Git 工作流），使用 `pytest-bdd`。 | | | **性能基准** | ✅ | [新功能] 自动套件验证缓存和并行化效果。 | | | **单元测试** | ✅ | 核心逻辑综合套件（检测器、脱敏器、CLI）。 | | | **合成语料库** | ✅ | `generate_test_data.py` 从规则创建平衡测试集。 | | | **规则去重** | ✅ | `tools/deduplicate_rules.py` 在发布前保持目录整洁。 | ## Git 与 CI/CD 集成 检测器现在原生支持 Git 生命周期，允许对更改进行精确扫描，而不是扫描整个文件。 ### 🛠 Git 扫描模式 ``` # 扫描暂存的更改（非常适合 pre-commit 钩子） ./run.sh --git-staged --mode fast # 扫描工作目录中未暂存的更改 ./run.sh --git-working # 扫描功能分支与 main 分支之间的差异（PR 审计） ./run.sh --git-branch origin/main --format sarif # 仓库历史深度审计（并行化且缓存） ./run.sh --history --since "1 month ago" --max-commits 100 ``` ### 🏎 性能与可扩展性 - **并行执行**：大规模历史审计和多文件目录扫描自动利用多个 CPU 核心进行正则和熵分析。 - **提交缓存**：引擎维护 `.secretscan_cache` 以跟踪已验证的"干净"提交，在增量审计中将冗余扫描时间减少高达 90%。 - **模式**：在 `fast`（优化用于 <1s 钩子）、`balanced`（标准开发）和 `deep`（彻底 CI 审计）之间选择。 ## 精确高亮与修复建议 当检测到敏感信息时，终端输出会提供即时视觉上下文和可操作的修复指令。 ``` ⚠ Secrets detected: 1 - HIGH: 1 Type: stripe_api_key Location: line 1 Risk: HIGH Suggestion: Rotate this Stripe API key immediately in your dashboard. See: https://stripe.com/docs/keys#api-key-rotation Context: config process result Stripe secret: [SECRET_HIGHLIGHTED_IN_RED] ``` 修复建议现在包含直接链接到 AWS、GitHub、Stripe 和 Google Cloud 的官方安全指南，指导开发者完成撤销和轮换流程。 ### 自然语言上下文匹配 检测引擎使用 字符的上下文窗口来检测自然语言对话意图，如 `Here is my prod api key:`，这些在 LLM 交互中很常见。此功能支持多语言，当在英语、西班牙语、法语或德语中检测到意图时会提高置信度分数。 ## 扩展基础设施模式 最新的功能扩展将基础设施重点分类法置于前沿： * `data/infrastructure` 现在包含信用卡、IBAN/SEPA 引用、国民身份证号码和其他高风险标识符的规则。 * 熵感知评分加上重叠解析，使结构化基础设施匹配优于通用关键词或高熵启发式。 * CLI `--force-scan-all` 选项确保省略关键词的旧日志仍能获得评估（请参阅此模式的新验收场景）。 * 专用测试涵盖去重规则、合成脱敏和扩展数据集，确保库保持精确。 ## 开发工具 使用配套工具保持目录健康： * `tools/migrate_patterns.py` 规范化模式字段，添加熵默认值，并将外部类别映射到树内分类法。 * `tools/generate_test_data.py` 从正则表达式重建 base64 编码的 `data/*/test_data.json` 文件，以便每条规则都附带可重现的样本。 * `tools/deduplicate_rules.py` 在规则发布前合并跨类别的重复模式。 * 使用 `tools/regex_lint.py`、`tools/run_safe_regex.py` 和 `tools/run_redoctor.py` 防止 ReDoS、语法漂移和模式回归。 在发布前运行 `pytest tests/test_acceptance.py::test_force_scan_keywordless` 以测试无关键词模式。 # 模式数据库 检测引擎可以利用包含数千个敏感信息签名的大型开源模式数据库。 例如，开源数据集包含 **超过 1600 个正则表达式**，可检测数百种服务的 API 密钥、令牌、密码和其他凭据。（[GitHub][3]） 这使扫描器能够与新引入的 API 密钥格式保持同步更新。 # 项目目标 项目专注于**保护 AI 工作流**，而非传统的仓库扫描。 关键设计目标： ### AI 优先的安全 检测以下内容中的敏感信息： * LLM 提示词 * 聊天记录 * 代理日志 * 调试会话 ### 开发者优先的体验 该工具直接集成到开发者工作流中，无需复杂配置。 ### 本地处理 所有扫描都在本地进行，确保数据不会离开环境。 ### 快速反馈 敏感信息应在开发过程中立即被检测到。 # 核心组件 系统由多个模块组成。 ### 检测引擎 负责使用以下方式识别潜在的敏感信息： * 正则模式匹配 * 熵评分 * 上下文启发式 ### 模式数据库 敏感信息签名的持续更新集合。 包含以下模式： * API 提供商 * 云平台 * CI/CD 令牌 * 身份验证系统 ### 扫描器接口 扫描器处理不同的输入源： * 文本提示词 * 日志流 * 源文件 * 应用程序输出 ### 报告系统 发现结果以结构化结果形式返回，包括： * 敏感信息类型 * 位置 * 置信度分数 * 风险级别 * 风险分数（0-100） CLI 生成清晰的彩色输出，高亮显示位置、风险级别（高、中、低）和检测到的敏感信息的高级风险分数（0-100）。风险分数由加权启发式确定，包含正则置信度、上下文邻近度奖励和熵调整。`report` 模块管理去重和格式化。使用 `--format sarif` 进行 CI/CD 集成。 您可以通过使用 `--min-score` 标志（例如 `--min-score 70`）来调整灵敏度并过滤低置信度噪音。 # 架构 架构优先考虑简单性和速度。 ``` Input Sources │ │ ▼ Preprocessing Layer │ │ ▼ Detection Engine ├── Regex Matching ├── Entropy Detection └── Context Analysis │ ▼ Secret Classification │ ▼ Security Report ``` # 检测示例 输入文本： ``` Here is my configuration: DATABASE_URL=postgres://admin:password@localhost ``` 输出： ``` Secrets detected: [1] OpenAI API Key location: line 3 risk: HIGH [2] Database Credentials location: line 4 risk: CRITICAL ``` ## 安装 ``` # 从 PyPI 安装（推荐） pip install secret-scan-detector # 运行 secret-scan example_file.txt ``` ### 开发者安装 ``` # 创建虚拟环境 python3 -m venv .venv source .venv/bin/activate # 以可编辑模式安装 pip install -e . ``` 或者直接扫描文本： ``` # 标准扫描 secret-scan --text "My API key is AIzaSy-12345" # 强制扫描所有行（绕过关键词过滤器） secret-scan --force-scan-all . ``` ### 数据脱敏与遮盖 您可以在保留其余文本的同时，从日志或提示词中脱敏敏感数据。这对于在与 LLM 共享之前清理数据或安全调试很有用。 使用 `--obfuscate` 标志启用脱敏： ``` # 默认模式：编辑（编辑敏感信息的中间部分） # 输入："My key is ghp_1234567890abcdefghijklmnopqrstuvwx" # 输出："My key is ghp_...uvwx" cat logs.txt | secret-scan --obfuscate ``` 使用 `--obfuscate-mode` 选择不同的脱敏策略： #### 1. `redact`（默认） 部分遮盖，保留前缀/后缀以保持上下文，但隐藏敏感核心。 * **示例：** `AKIA...CDEF` #### 2. `hash` 用一致的短 SHA-256 哈希替换敏感信息。相同的敏感信息将产生相同的哈希，这对于调试数据流而不查看实际值至关重要。 * **示例：** `[HASHED_d8c7b92f4a19]` #### 3. `synthetic`（推荐用于 LLM 提示词） 用与原始格式匹配的逼真假数据替换敏感信息（使用 `Faker` 库）。这允许 LLM 仍然"理解"您的数据结构（例如，在真实位置看到假 AWS 密钥），而不会暴露真实凭据。 * **示例（AWS ID）：** `AKIAJ7O2N6M4L9K0P8R1` * **示例（GitHub 令牌）：** `ghp_zXyWvUtSrQpOnMlKjIhGfEdCbA9876543210` * **示例（电子邮件）：** `fake_user@example.org` ``` # 使用合成模式生成真实占位符 secret-scan --obfuscate --obfuscate-mode synthetic logs.txt ``` ### 自定义 CLI 辅助工具 仓库附带了一些便捷命令： * `./run.sh ` 已弃用，请直接使用 `secret-scan `。 * `secret-scan --text ""` 对内联字符串运行扫描（在构建发送给 LLM 的提示词时很有用）。 * `python tools/generate_test_data.py` 从 `data/rules.json` 重建 `data/test_data.json`，每当规则集更改时都应重新运行。 ## 使用示例 ``` $ secret-scan test_file.py ⚠ Secrets detected: 1 - CRITICAL: 1 Type: Database Credentials Location: line 10 Risk: CRITICAL Content: post...ocal (redacted) ``` # 测试数据与自定义用例 `data/rules.json` 中的每条规则都映射到 `data/test_data.json` 下的 base64 编码阳性和阴性样本。`tools/generate_test_data.py` 驱动数据生成： * 它加载每个正则，通过 `exrex`（带长度限制）运行以发出匹配，并对其进行编码，以便检测器测试使用与生产数据相同的字符串。 * 阴性是手工制作的近似匹配，类似于真实世界的敏感信息，但不应触发命中。 * `STRICT_RULES` 中列出的规则绕过默认的 `encode_str` 突变，因为即使插入 `DUMMY_IGNORE` 也会破坏所需格式。 * 自定义辅助工具为最复杂的模式（`auth0_domain_url`、`skybiometry_api_key`、`okta_api_domain_url`、`facebook_oauth_id`、`linemessaging_api_key`、`nethunt_api_key`）生成有效载荷，以便检测器仍能看到合法样本，尽管这些正则严格限制字符集或长度。 在任何规则更改后运行 `python tools/generate_test_data.py`；它每 100 条规则打印进度，并覆盖 `data/test_data.json` 与刷新后的语料库，为 pytest 套件提供动力。 # 用例 ### AI 应用开发 构建以下内容的开发者： * 聊天机器人 * RAG 管道 * AI 代理 * 编码助手 可以在发送给 LLM API 之前扫描提示词。 ### 安全审计 安全团队可以分析： * 提示词日志 * 应用程序日志 * LLM 交互历史 以确保没有敏感信息泄露。 ### 合规 组织可以强制执行策略，防止敏感信息发送给外部 AI 提供商。 ### DevSecOps 集成 扫描器可以集成到： * CI/CD 管道 * AI 网关 * API 代理 * 开发者工具 # PII 检测 扫描器现在支持检测个人身份信息（PII），包括电子邮件、电话号码、信用卡和 SSN。 使用 `--pii` 标志启用 PII 检测： ``` # 扫描文件中的敏感信息和 PII secret-scan --pii example_file.txt # 将 PII 扫描限制在特定区域（例如，仅限美国的 SSN 和美国电话号码） secret-scan --pii --pii-region US example_file.txt ``` PII 发现结果集成到多层级报告系统中，其中高度结构化的敏感信息（第 1 层）优先于上下文或通用熵命中。 # 目标用户 ### AI 开发者 构建 LLM 驱动的应用的工程师。 ### 安全工程师 负责应用安全审查的团队。 ### AI 初创公司 从事提示工程和 LLM 管道工作的公司。 # 路线图 项目分几个阶段发展。 ### CLI 扫描器 用于扫描提示词和日志的轻量级命令行工具。 ### API 服务 允许 AI 系统在发送给 LLM 提供商之前验证提示词的服务。 ### 开发者工具 集成： * IDE 插件 Git 钩子 * CI 管道 ### 企业安全平台 未来功能可能包括： * 实时提示过滤 * AI 数据丢失防护（DLP） * 跨 AI 基础设施的敏感信息监控 # 为什么这很重要 AI 辅助开发显著提高了编码和调试速度，但也增加了意外暴露敏感数据的风险。 开发者经常在不检查敏感信息的情况下，将大块代码或日志粘贴到 AI 系统中。 LLM 敏感信息泄露检测器提供了一层安全保护，防止机密数据离开组织。 # 许可证 MIT 许可证

标签：AMSI绕过, API密钥保护, DevSecOps, JWT检测, meg, Secrets检测, StruQ, 上游代理, 信息安全, 凭证扫描, 加密密钥保护, 可视化界面, 威胁检测, 密钥泄露检测, 对抗攻击, 开发安全, 敏感信息检测, 数据库凭证保护, 数据泄露防护, 源代码扫描, 结构化查询, 网络安全, 网络探测, 自动化安全, 逆向工具, 隐私保护