efij/pii-leak-hunter

# PII 泄露检测 **PII Leak Hunter** 是一款开源工具，用于检测日志、文件、SaaS 记录和运营数据源中的 **PII 泄露、脱敏失败、云和基础设施机密以及危险暴露模式**。 它帮助安全、AppSec、SecOps、DevSecOps 和平台团队识别那些本不该出现在日志中的内容。 ## 亮点 - 检测 PII、云机密、基础设施机密和复合暴露。 - 关联高风险场景，如凭证组合、脱敏失败、机密+PII 重叠以及控制平面泄露。 - 扫描本地文件、压缩包、数据库、对象存储、日志平台和选定的 SaaS 来源。 - 在精致的 Streamlit Web 控制台中对发现进行分类，支持会话内 Provider 配置、目标构建器、扫描进度、分组发现、基线差异、可视化暴露图谱和资产感知上下文。 - 导出安全的 HTML 审计报告、SARIF 和证据包，用于分类、PR 和安全审查。 - 跟踪最小权限指南、可利用性评分、内置 Hunting 配方以及首次/末次发现范围，以优先关注最重要的泄露。 ## 🔥 功能特性 - 检测 **日志中的 PII**（SSN、税号、IBAN、银行卡等） - 检测 **脱敏失败**（部分或破损的涂改） - 检测 **身份组合**（KYC 级别的暴露） - 检测 **机密 + PII 组合** - 检测 **云和基础设施机密**（AWS 密钥、ARN、Secrets Manager 引用、Kubernetes token、私钥、IaC token） - **PII 检测由 [Microsoft Presidio](https://github.com/microsoft/presidio) + 自定义 NLP 识别器驱动** - **Presidio 驱动的检测 + 自定义识别器** - **默认安全预览**（不暴露原始敏感数据） - **CLI 支持自动化、CI/CD 和脚本编写** - **Streamlit Web 控制台**，用于来源选择、凭证输入、进度跟踪、分类、基线比较和可视化暴露图表 - **可利用性分类**，包含优先级、评分和分类桶 - **Hunting 配方**，内置 20 个模块化、高信噪比的工作流供研究人员使用 - **资产映射 + 时间线上下文**，使发现和活动显示服务/项目/环境提示、范围以及首次/末次发现时间 - **活动聚类**，将跨系统的重复泄露合并为一个调查案例 - **机密验证**，支持离线检查和只读 Provider 验证挂钩（在支持的情况下） - **实时 Hunting 模式**，包含安全的 hunting 制品和基于差异的重新运行 - **50 个差异签名族**，使 Hunting 能够检测活动、哈希、范围、资产漂移、来源漂移、优先级/严重性转变、影响范围、Provider 族和验证状态等方面的有意义变化 - **静态 HTML 审计报告**，包含脱敏证据、可利用性阶梯和适于打印的布局 - 输出格式： - JSON - CSV - SARIF - Markdown 摘要 - HTML 审计报告 - 证据包 (`.zip`) - 内置 **演示/测试数据集**，用于安全测试和截图 ## 🧱 技术栈 - [Microsoft Presidio](https://github.com/microsoft/presidio) – PII 检测和分析 - Python 3.10+ ## 🧩 支持的 Provider ### 当前支持 - **Coralogix** (v1) - **AWS CloudWatch Logs** - **Datadog** - **Dynatrace** - **Splunk** - **New Relic** - **ServiceNow** - **Notion** - **Confluence** - **Jira** - **Azure DevOps** - **GitHub** - **Slack** - **Google Workspace** - **Monday** - **Microsoft Teams** - **Zendesk** - **Snowflake** ### 即将推出 - 额外的 Provider 调优和特定于 Provider 的查询助手 - Intercom ## 🎯 使用场景 - 日志中的敏感数据搜寻 - 验证安全日志记录和脱敏控制 - 支持 **Shift-Left DLP (SLDLP)** 计划 - 检测隐私和合规问题 - 调查涉及数据暴露的事件 - 部署后验证（发布后检测泄露） ## 🧠 定位 PII Leak Hunter 是： - **SLDLP 对齐**（Shift-Left 数据防泄漏） - **DSPM 相邻**（日志是真实的数据面） - **合规支持**（PCI DSS, GDPR, SOC 2, HIPAA, ISO 27001） - **Provider 不可知**（优先 Coralogix，多 Provider 路线图） - **研究者友好**（优先分类、优先图谱、工作流感知） ## 🚫 它不是什么 - 不是 SIEM - 不是 DSPM 平台 - 不是自动修复系统 - 不局限于金融科技 ## ⚡ 快速开始 版本和仓库标识现在在两个操作界面中均可见： ``` pii-leak-hunter --version ``` CLI 会打印当前版本、仓库 URL 和 hunting 差异签名包摘要。Streamlit UI 的标题和侧边栏也会显示当前版本以及直接的仓库链接。 Hunting 差异包现在跟踪 50 个实用的签名族，包括： - 精确的活动标识 - 重复的机密哈希 - 实体类型 + 哈希 - 实体类型 + 来源 - 实体类型 + 资产 - 活动类型 + 资产 - 活动类型 + 来源 - 活动优先级和严重性 - 活动发现次数桶 - 活动资产数量桶 - 活动来源数量桶 - 资产 + 环境 - 资产 + 来源 - 资产 + Provider 族 - 资产 + 验证类别 - 影响范围 - Provider 族 - 验证族 + 分类 - 首次发现日 - 末次发现日 - 来源 + 优先级 - 来源 + 严重性 - 发现类型 + 资产 - 实体类型 + 优先级 - 实体类型 + 严重性 ### 1. 安装 ``` git clone https://github.com/efij/pii-leak-hunter.git cd pii-leak-hunter python -m venv .venv source .venv/bin/activate pip install -e . ``` ### 2. 配置 设置你的 Coralogix 凭证： ``` export CORALOGIX_API_KEY=your_api_key export CORALOGIX_REGION=us1 ``` `CORALOGIX_REGION` 可以是短区域名（如 `us1` 或 `eu1`）、API 主机或完整的 Coralogix 应用 URL。 其他支持的 Provider 使用以下环境变量： ``` # Datadog export DATADOG_API_KEY=your_api_key export DATADOG_APP_KEY=your_application_key export DATADOG_SITE=your_site # Dynatrace export DYNATRACE_API_TOKEN=your_api_token export DYNATRACE_ENV_URL=https://your_environment_url # Splunk export SPLUNK_BASE_URL=https://your_splunk_url export SPLUNK_TOKEN=your_token # New Relic export NEW_RELIC_API_KEY=your_user_key export NEW_RELIC_ACCOUNT_ID=1234567 export NEW_RELIC_REGION=us ``` ### 3. 运行扫描 (Coralogix) ``` pii-leak-hunter scan --out-json findings.json --out-csv findings.csv --fail-on critical ``` 该默认远程流程意味着： - 不需要 Provider 查询 - 扫描窗口默认为过去 24 小时 - 引擎在返回的任何日志中搜寻机密、PII、脱敏失败和风险组合 - Coralogix 默认使用 `source logs` DataPrime 查询，因此“扫描所有内容”不依赖于 Lucene 通配符行为 - 如果该默认 Coralogix 查询返回为空，扫描器现在会使用 Lucene 通配符和归档层回退重试同一窗口，然后才声明窗口为空 - 对于更长的 Coralogix 窗口，当频繁搜索返回为空时，扫描器会自动重试归档搜索 - 当 Coralogix 块达到批量上限时，扫描器会拆分时间范围并继续，而不是在第一个满批次处停止 在不知道查询语言的情况下使用其他 Provider 运行扫描： ``` pii-leak-hunter scan --provider datadog ``` 运行高信噪比配方，而不是手动筛选每个发现： ``` pii-leak-hunter scan --provider cloudwatch --recipe prod-credentials pii-leak-hunter scan github://owner --recipe dev-collaboration pii-leak-hunter scan slack://workspace?channel_query=incident --recipe incident-war-room pii-leak-hunter scan googleworkspace://drive --recipe workspace-doc-leaks pii-leak-hunter recipes pii-leak-hunter hunt prod-credentials --provider datadog --baseline-out hunt.json pii-leak-hunter hunt incident-war-room slack://workspace?channel_query=incident --baseline-in hunt.json --new-only ``` 内置配方是模块化的，位于 `pii_leak_hunter/hunts/recipes.py`，因此添加新 hunt 只需进行小型注册表更改，而无需重写 CLI。 ### 4. Provider 和来源指南 - CloudWatch 被实现为日志 Provider，因为它的行为类似于日志后端，并且适合现有的远程扫描路径。 - Slack、Google Workspace、Confluence、Jira、Azure DevOps、GitHub、Monday、Microsoft Teams、Zendesk、ServiceNow 和 Notion 被实现为来源，因为它们公开的是消息、文档、工单、页面、工作项和协作线程，而不是时间窗口化的日志流。 - Snowflake 被实现为使用 SQL API 的只读来源。它扫描显式语句或表查询，这保持了访问的狭窄性和可预测性。 - GitHub 扫描侧重于 Issues、Pull Request、Issue 评论和 PR 审查评论。将仓库留空以扫描所有者下所有可见的仓库。仓库 Blob 和历史记录扫描仍由 gitleaks 等专用工具处理更好。 - Azure DevOps 扫描涵盖工作项以及项目中匹配仓库的 Pull Request 标题、描述和审查线程。 - Google Workspace 支持有意从 Drive、Docs 和 Sheets 内容开始。这通过将 Workspace 发现带入与其他系统相同的分类、图谱和跨源关联流程来补充 Google DLP。 - Monday 和 Microsoft Teams 支持侧重于研究人员实际发现粘贴机密的协作面：看板、项目更新、频道消息和回复。 如果你确实想缩小范围，Provider 过滤器仍然可用： ``` pii-leak-hunter scan --provider datadog --query 'service:your-service' pii-leak-hunter scan --provider splunk --query 'index=main service="your-service"' --from '-6h' ``` 使用统一目标运行扫描： ``` pii-leak-hunter scan fixtures/demo_logs.ndjson pii-leak-hunter scan file:///absolute/path/to/logs/ pii-leak-hunter scan postgres://user:pass@host:5432/dbname?schema=public&row_limit=1000 pii-leak-hunter scan s3://bucket/path/to/logs/ pii-leak-hunter scan 'servicenow://your-instance-host?table=incident&query=active=true' pii-leak-hunter scan 'notion://workspace?query=prod&page_size=25' pii-leak-hunter scan 'github://your-org' pii-leak-hunter scan 'azuredevops://workspace?organization_url=https://dev.azure.com/your-org&project=security' pii-leak-hunter scan 'monday://workspace?query=incident' pii-leak-hunter scan 'teams://workspace?team_query=security' ``` ### 4. 运行 UI (Streamlit) ``` streamlit run pii_leak_hunter/ui/app.py ``` Web 控制台现在包括： - 远程 Provider 扫描，带有会话内凭证字段 - 本地路径、Postgres、S3、ServiceNow、Notion、Confluence、Jira、Azure DevOps、GitHub、Slack、Google Workspace、Monday、Microsoft Teams、Zendesk 和 Snowflake 的目标/URI 构建器 - 本地文件上传扫描 - 远程 Provider 的默认“扫描所有日志查找泄露”模式，带有可选的自定义 Provider 过滤器 - 可选的基线制品上传，来自先前的安全 JSON 或证据包 - 会话扫描历史和活动扫描摘要 - 可见的扫描进度，而非即发即弃的按钮点击，包括经过时间、ETA 和 Coralogix 窗口扫描的实时单行状态 - `Scan Details` 部分，显示远程扫描的有效 Provider 查询、语法、时间窗口和解析的行数 - 有界的 Coralogix 扫描批次，带有部分结果和对长时间运行窗口的恢复支持 - 严重性和可利用性概览卡片 - 聚类优先的发现下钻，GUI 中默认显示原始值以便于验证 - 增长最快的活动、验证摘要和范围感知的资产视图 - Hunt 制品下载以及上传先前 Hunt 制品时的聚类级差异 - 主要集成的内置最小权限预设 - 一键导出 HTML 审计报告、JSON、CSV、Markdown、SARIF 和证据包 ### 5. 扫描本地日志 ``` pii-leak-hunter scan-file logs.ndjson ``` `scan-file` 也支持目录和压缩输入： ``` pii-leak-hunter scan-file ./logs/ pii-leak-hunter scan-file ./rotated/app.ndjson.gz pii-leak-hunter scan-file ./archives/logs.zip ``` 基线/差异模式： ``` pii-leak-hunter scan-file fixtures/demo_logs.ndjson --baseline-out baseline.json pii-leak-hunter scan-file fixtures/demo_logs.ndjson --baseline-in baseline.json --new-only ``` 证据包导出： ``` pii-leak-hunter scan-file fixtures/demo_logs.ndjson --out-evidence evidence.zip ``` Streamlit Web 控制台还可以生成： - 用于与安全、工程和领导层共享的独立 HTML 审计报告 - 基于当前发现视图的过滤导出 - 基线感知分类，显示 `new`（新增）、`unchanged`（未变）和 `resolved`（已解决）的发现 最小权限预设： ``` pii-leak-hunter least-privilege servicenow pii-leak-hunter least-privilege notion ``` ### 6. 使用 Docker 运行 构建镜像： ``` docker build -t pii-leak-hunter . ``` 运行 CLI： ``` docker run --rm \ -e DATADOG_API_KEY \ -e DATADOG_APP_KEY \ -e DATADOG_SITE \ pii-leak-hunter \ pii-leak-hunter scan --provider datadog ``` 运行 Streamlit UI： ``` docker run --rm -p 8501:8501 \ -e CORALOGIX_API_KEY \ -e CORALOGIX_REGION \ pii-leak-hunter \ streamlit run pii_leak_hunter/ui/app.py --server.address=0.0.0.0 ``` ## 📊 示例发现 - 生产日志中未脱敏的 SSN → **critical**（严重） - 脱敏失败（原始 + 已脱敏同时存在） → **critical**（严重） - 带有受益人上下文的 IBAN → **high**（高） - 身份组合（姓名 + DOB + SSN） → **critical**（严重） - 同一载荷中的机密 + PII → **critical**（严重） - 一条记录中的 AWS 访问密钥 + 私密密钥 → **critical**（严重） - Kubernetes API 端点 + Bearer Token → **critical**（严重） ## 🖥️ Web 控制台 Web 控制台专为快速人工分类而设计，而非原始数据转储。 - `Remote Provider`：选择 Coralogix、Datadog、Dynatrace、Splunk 或 New Relic，然后直接在 UI 中为当前会话输入凭证 - `Target / URI`：扫描主机路径或构建 Postgres、S3、ServiceNow 和 Notion 目标，无需手动组装 URI - `Upload File`：上传本地制品以直接扫描 - `Overview`：查看严重性总计、可利用性阶梯、顶级实体族和源元数据 - `Findings`：按严重性、可利用性和基线状态过滤，然后检查分组事件，GUI 中默认显示原始匹配 - `Reports`：导出自包含的 HTML 审计报告以及现有的机器可读格式，如果你确实希望在下载中包含原始值，有单独的切换开关 - `Coralogix resume`：继续部分宽窗口扫描，而不是零开始 GUI 现在默认显示原始值，以便你可以快速验证发现。除非显式启用了 `Unsafe: include raw values in exports`，否则下载仍受保护。 ## 🧾 HTML 审计报告 HTML 审计报告旨在作为默认的可共享制品。 - 自包含的单文件 - 默认安全，带有脱敏预览和哈希 - 严重性总计和可利用性排序 - 针对重复泄露的分组事件展示 - 修复步骤、影响范围和策略标签 - 适于打印的布局，可通过浏览器“另存为 PDF” ## 🔐 安全性 - 默认不显示原始敏感数据 - 输出中的值已脱敏 - 仅基于哈希的关联 - 只读扫描（不对日志 Provider 进行变更） 显示原始值（不推荐）： ``` --unsafe-show-values ``` ## 🧱 检测方法 PII Leak Hunter 结合了： - 模式匹配 (regex) - 上下文感知检测 - 基于字段的启发式 - 多实体关联 - 自定义金融科技感知识别器 - 云/基础设施机密分类 - 影响范围标记和修复提示 - 可利用性优先排序 - 基线/差异工作流 - 可导出的证据包 这避免了仅限 regex 工具的局限性。 ## 🧪 演示与截图 仓库包含用于以下用途的 **合成数据集**： - 安全演示 - UI 截图 - CI 测试 不包含真实敏感数据。 ## 🛣 路线图 - [x] Coralogix Provider - [x] Datadog Provider - [x] Dynatrace Provider - [x] Splunk Provider - [x] New Relic Provider - [x] CLI + Streamlit UI - [x] ServiceNow 来源 - [x] Notion 来源 - [x] 基线/差异模式 - [x] 证据包 - [x] 最小权限预设 - [ ] CI/CD 集成模板 - [ ] 高级检测调优 ## 🤝 贡献 欢迎贡献。 重点领域： - 新识别器 - Provider 适配器 - 性能改进 - 减少误报 - UI 增强 请确保： - 测试中不包含真实 PII - 所有新逻辑都包含测试 - 更改保持简单 (KISS) ## 📄 许可证 MIT License ## 🧠 最后说明

标签：AMSI绕过, AWS密钥检测, DevSecOps, DLP, Force Graph, HTML审计报告, Kubernetes, PII, PII检测, SaaS安全, SecOps, Streamlit, StruQ, 上游代理, 个人身份信息, 云安全架构, 合规性审计, 威胁检测, 安全合规, 安全运营, 密钥泄露检测, 开源安全工具, 扫描框架, 敏感数据扫描, 数据泄露, 数据脱敏, 数据隐私, 日志安全, 网络代理, 网络安全, 访问控制, 请求拦截, 逆向工具, 逆向工程平台, 错误基检测, 隐私保护, 静态代码分析