NeiveZ/BreachLens

# BreachLens     ## 概述 BreachLens 帮助分析人员检查凭据暴露信号，而无需抓取暗网来源或收集明文泄露数据。 它专为防御性使用、授权评估和实验室工作而设计。它**不会**绕过付费 API、下载原始泄露数据库、抓取非法市场或打印明文密码。 该工具分层工作： | 层级 | 成本 | API key | 功能描述 | |---|---:|---:|---| | Pwned Passwords | 免费 | 否 | 通过 k-anonymity 检查密码；仅发送 5 个 SHA-1 字符 | | 本地组合扫描 | 免费 | 否 | 解析授权的本地 `email:password` 文件并对密码进行掩码处理 | | GitHub 公开元数据 | 免费层 | 可选 | 搜索公开代码元数据，无需下载原始文件内容 | | DNS / crt.sh | 免费 | 否 | 检查域名的安全态势以及公开的证书透明度主机名 | | HIBP 账户/域名元数据 | 付费/可选 | 是 | 配置 `HIBP_API_KEY` 后提供的官方账户/域名泄露元数据 | ## 功能特性 - 组织良好的 Rich CLI 输出，包含风险摘要、覆盖范围表、已跳过的模块以及发现结果表 - `doctor` 命令用于验证可选的 API key 和免费模块 - 使用 Pwned Passwords k-anonymity 的 `password` 命令 - 用于本地授权组合文件的 `combo-scan`，并对密码进行掩码处理 - 针对本地组合文件的可选 `--check-passwords` 功能，仅使用 k-anonymity - 结合可选的 HIBP、GitHub 元数据和本地文件的 `email` 命令 - 用于 DNS、crt.sh、GitHub 元数据和可选 HIBP 域名检查的 `domain` 命令 - 用于按域名或电子邮件搜索公开元数据的 `github` 命令 - 用于在本地授权文件中扫描电子邮件和类似机密信息的 `local-scan` - JSON、HTML 和可选的 TXT 报告 - 包含 `.env.example` 文件 - 不涉及原始泄露数据库、不抓取暗网、不报告明文密码 ## 安装说明 ``` git clone https://github.com/NeiveZ/BreachLens.git cd BreachLens chmod +x breachlens.sh ./breachlens.sh --install source .venv/bin/activate breachlens doctor ``` 手动安装： ``` python3 -m venv .venv source .venv/bin/activate pip install -U pip pip install -e . cp .env.example .env breachlens doctor ``` ## 配置说明 复制示例环境文件： ``` cp .env.example .env nano .env ``` 可选值： ``` HIBP_API_KEY= GITHUB_TOKEN= BREACHLENS_TIMEOUT=20 BREACHLENS_REPORT_DIR=reports ``` `HIBP_API_KEY` 是可选的。如果没有配置，将跳过官方的 HIBP 账户/域名泄露元数据，但免费/本地模块仍能正常工作。 `GITHUB_TOKEN` 是可选的。它可以提升 GitHub API 的速率限制。 ## 使用说明 ``` breachlens [command] [options] ``` 命令： ``` doctor Check configuration and module readiness password Check one password via Pwned Passwords k-anonymity combo-scan Scan authorized local email:password-style files email Check an e-mail using optional HIBP, GitHub and local files domain Assess a domain using DNS, crt.sh, GitHub and optional HIBP github Search public GitHub metadata for a domain or e-mail local-scan Scan a local text file for e-mails and secret-like assignments dns DNS posture check crtsh Certificate Transparency hostname collection demo Run bundled safe demo data ``` ## 示例 ### 检查配置 ``` breachlens doctor ``` ### 安全地检查密码 ``` breachlens password ``` 或者仅限实验室/演示环境使用的非交互式操作： ``` breachlens password -p 'Password123!' ``` BreachLens 仅将 SHA-1 哈希值的前 5 个字符发送至 Pwned Passwords。它不会发送明文密码或完整的哈希值。 ### 扫描本地授权的组合文件 ``` breachlens combo-scan examples/sample_combos.txt ``` 按电子邮件过滤： ``` breachlens combo-scan combos.txt --email user@example.com ``` 按域名过滤： ``` breachlens combo-scan combos.txt --domain example.com ``` 使用 k-anonymity 根据本地匹配到的密码与 Pwned Passwords 进行比对检查： ``` breachlens combo-scan combos.txt --domain example.com --check-passwords --max-password-checks 25 ``` 在输出和报告中，密码始终会被掩码处理。 ### 在不支付 HIBP 费用的情况下检查电子邮件 ``` breachlens email user@example.com --no-hibp ``` 添加授权的本地文件： ``` breachlens email user@example.com --no-hibp --local-file combos.txt ``` 如果未配置 `HIBP_API_KEY`，将跳过 HIBP 模块，并明确将覆盖范围标记为受限。 ### 在 HIBP 可用时检查电子邮件 ``` breachlens email user@example.com ``` 如果 `.env` 中包含 `HIBP_API_KEY`，将查询官方的 HIBP 账户/paste 元数据。否则，免费/本地模块仍会运行。 ### 评估域名 ``` breachlens domain example.com ``` 结合本地组合证据： ``` breachlens domain example.com --local-file combos.txt ``` 结合可选的 HIBP 域名元数据： ``` breachlens domain example.com --hibp ``` ### 仅限 GitHub 公开元数据 ``` breachlens github example.com breachlens github user@example.com ``` BreachLens 仅收集由 GitHub Code Search 返回的元数据。它不会下载原始文件内容。 ### 在终端中显示证据样本 ``` breachlens combo-scan combos.txt --domain example.com --show-evidence ``` ### 同时保存 TXT 报告 ``` breachlens domain example.com --txt ``` 对于大多数命令，默认会保存 JSON 和 HTML 报告。 ## 输出样式 BreachLens 在各模块中使用统一的、组织良好的输出格式： ``` BreachLens Target: example.com Scan type: domain Risk score: 35/100 — MEDIUM Findings: 5 HIGH+: 1 MEDIUM: 2 LOW: 1 INFO: 1 Coverage Module Status Notes DNS posture EXECUTED MX/SPF/DMARC/CAA inventory GitHub public metadata EXECUTED Metadata only; raw contents not downloaded HIBP domain SKIPPED HIBP_API_KEY is not configured Findings Severity Source Category Title HIGH Local scan credential_exposure Matching credential-like entries found locally LOW Coverage coverage_limit Limited coverage mode ``` ## 隐私与安全保证 - 不抓取暗网 - 不绕过付费 API - 不下载原始泄露数据库 - 报告中不包含明文密码 - Pwned Passwords 使用 k-anonymity - HIBP 账户/域名查询是可选的 - 本地组合扫描仅适用于授权文件 ## 局限性 如果没有 `HIBP_API_KEY`，BreachLens 无法确切证实电子邮件是否出现在官方的 HIBP 泄露元数据中。它依然可以检查本地授权文件、被攻陷的密码（pwned passwords）以及公开来源的元数据。 类似 `No matching local entries found` 的结果仅表示所提供的本地文件中未包含匹配项。这并不能证明某个账户从未被泄露过。 ## 法律声明 仅可用于您拥有或已获得明确书面授权进行评估的账户、域名和文件。未经授权收集、持有或使用泄露的凭据可能是违法行为。 ## 开源许可 MIT License。

标签：Python, TLS, 凭据泄露检测, 安全防护, 情报分析, 无后门, 网络诊断, 逆向工具, 防御工具