tomkidron/DigitalFootprintInvestigator

# 数字足迹调查器 一款基于 [LangGraph](https://langchain-ai.github.io/langgraph/) 构建的多代理 OSINT 工具，可并行搜索 Google、社交媒体平台和 enrichment API，随后通过由 Claude (Anthropic) 驱动的分析与报告生成阶段对结果进行链式处理。 ## 功能特性 - **并行 LangGraph 工作流**：Google 搜索和社交媒体搜索同时运行；结果汇入单一的分析 → 报告流水线 - **平台覆盖**：Google (Tavily → SerpAPI → 免费后备), GitHub, Reddit, Twitter/X (含 dork 后备), YouTube, LinkedIn, Instagram (dork 后备), Facebook (dork 后备), SoundCloud (dork 后备) - **API enrichment**：HIBP 违规检测，Hunter.io 邮箱发现 - **弹性执行**：带指数退避的自动重试，基于磁盘的缓存以规避速率限制 - **输入验证**：对所有用户输入进行清洗和验证 - **Streamlit Web UI**：交互式界面，包含双标签页 (调查 / 报告)，支持实时日志流和内联查看已保存的报告 - **CLI 模式**：可通过 `python main.py` 脚本化运行 - **高级分析** (可选)：时间线关联，网络分析，深度内容分析 - **Docker 优先**：单一镜像即可运行应用、单元测试和 UI 测试 ## 前置条件 - Python 3.11+ (或 Docker) - **必需**：Anthropic API key - **可选**：用于获取更丰富结果的额外 API keys (参见 [环境配置](#environment)) ## 快速开始 ### 选项 1: Docker (推荐) ``` # 复制并填写您的 API keys cp .env.example .env # then edit .env and set ANTHROPIC_API_KEY # 构建并启动 web UI docker compose up --build ``` 在浏览器中打开 `http://localhost:8501`。 **通过 Docker 使用 CLI：** ``` docker compose run --rm osint-tool python main.py "John Doe" ``` ### 选项 2: 本地 Python ``` # 安装 dependencies pip install -r requirements.txt # 复制并配置 environment cp .env.example .env # then edit .env # 启动 web UI streamlit run app.py # 或者使用 CLI python main.py "John Doe" ``` ## 环境配置 将 `.env.example` 复制到 `.env` 并配置： ``` # 必需 ANTHROPIC_API_KEY=sk-ant-... LLM_MODEL=claude-sonnet-4-6 # default; change to use a different Claude model # 可选 — 工具在没有这些的情况下也能工作，但结果会显著改善 TAVILY_API_KEY=... # Best Google results (free tier available) SERPAPI_KEY=... # Google results fallback ($50/mo, 5000 searches) GITHUB_TOKEN=... # Higher rate limits (free personal access token) TWITTER_BEARER_TOKEN=... # Twitter timeline access (free tier available) YOUTUBE_API_KEY=... # YouTube channel data (free, 10 000 units/day) HUNTER_API_KEY=... # Email discovery (free tier: 25 searches/month) HIBP_API_KEY=... # Breach detection ($3.50/month) # Logging LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR ``` **获取 API keys：** | Key | 获取位置 | 费用 | |-----|----------------|------| | `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com) | 按量付费 | | `GITHUB_TOKEN` | GitHub → Settings → Developer settings → Personal access tokens | 免费 | | `YOUTUBE_API_KEY` | [console.developers.google.com](https://console.developers.google.com) → YouTube Data API v3 | 免费 (配额制) | | `TWITTER_BEARER_TOKEN` | [developer.twitter.com](https://developer.twitter.com) | 免费套餐 | | `HUNTER_API_KEY` | [hunter.io/api](https://hunter.io/api) | 免费套餐 (25次/月) | | `HIBP_API_KEY` | [haveibeenpwned.com/API/Key](https://haveibeenpwned.com/API/Key) | $3.50/月 | | `TAVILY_API_KEY` | [tavily.com](https://tavily.com) | 提供免费套餐 | | `SERPAPI_KEY` | [serpapi.com](https://serpapi.com) | $50/月 | ## 项目结构 ``` DigitalFootprintInvestigator/ ├── graph/ │ ├── nodes/ │ │ ├── _timing.py # Shared log_start / log_done helpers │ │ ├── search.py # Google and social search nodes (run in parallel) │ │ ├── analysis.py # Data correlation and pattern extraction │ │ ├── advanced.py # Optional timeline / network / content analysis │ │ └── report.py # Claude-powered report generation │ ├── state.py # LangGraph state TypedDict │ └── workflow.py # Graph construction and MemorySaver checkpointing ├── tools/ │ ├── search_tools.py # Google search and platform scrapers │ └── api_tools.py # HIBP, Hunter.io, YouTube, Twitter wrappers ├── utils/ │ ├── llm.py # Shared ChatAnthropic factory │ ├── logger.py # Logging setup │ ├── cache.py # Disk-based caching for API calls │ ├── retry.py # Exponential backoff retry logic │ ├── validation.py # Input validation and sanitization │ └── models.py # Pydantic data models ├── tests/ │ ├── conftest.py # Playwright session/page fixtures │ ├── healer.py # Self-healing Playwright page wrapper │ ├── unit/ # 215 unit tests (no browser or live API required) │ └── ui/ # 25 Playwright browser tests ├── app.py # Streamlit web UI ├── main.py # CLI entry point ├── config.yaml # Platform and analysis settings ├── pytest.ini # Test markers and paths ├── .env.example # Environment variable template ├── requirements.txt # Python dependencies ├── Dockerfile # Single image used by all three services ├── docker-compose.yml # Services: osint-tool, unit-tests, tests ├── pyproject.toml # Bandit security scan config ├── .pre-commit-config.yaml # Pre-commit hooks └── .dockerignore # Docker build exclusions ``` ## 运行测试 ### 本地 ``` # Unit tests (无浏览器，无需 API key) python -m pytest tests/unit/ -v # UI tests (自动启动 Streamlit；需要 Playwright 浏览器) playwright install chromium # first time only python -m pytest tests/ui/ -m "not integration" -v # Integration tests (需要 ANTHROPIC_API_KEY 和完整的 workflow 运行) python -m pytest tests/ui/ -m integration -v ``` ### 在 Docker 中 ``` # Unit tests — 无需运行 app docker compose run --rm unit-tests # UI tests — 自动启动 app 并等待其状态变为 healthy docker compose run --rm tests ``` ## 配置 `config.yaml` 控制平台和高级分析的默认设置。Streamlit 侧边栏和 CLI 参数可在每次运行时覆盖这些值。 **高级分析** (每个选项会增加一次额外的 LLM 调用；默认全部关闭)： ``` advanced_analysis: timeline_correlation: false # Build a chronological activity timeline network_analysis: false # Map relationships between accounts deep_content_analysis: false # Sentiment, topics, behavioral patterns ``` **CLI 参数：** ``` python main.py "Jane Smith" --timeline --network --deep ``` ## 使用示例 ``` # Name python main.py "Jane Smith" # Email python main.py "jane.smith@example.com" # Username python main.py "@janesmith" # With advanced analysis python main.py "Jane Smith" --timeline --network --deep ``` 报告将保存到 `reports/` 目录，文件名包含时间戳，例如 `reports/Jane_Smith_20260227_143022.md`。 ## 代码质量 Pre-commit 钩子会在 `git commit` 时自动运行： ``` pip install pre-commit pre-commit install ``` 包含的钩子：`detect-secrets`, `ruff` (lint + format), 合并冲突检测, 大文件 guard, YAML/JSON/TOML 验证, debug 语句拦截, 以及 `bandit` 安全扫描。Bandit 配置位于 `pyproject.toml`。 手动运行所有钩子：`pre-commit run --all-files` ## 自定义 ### 添加平台 1. 在 `tools/search_tools.py` 中添加搜索函数，遵循 `_search_github` / `_search_reddit` 模式。 2. 在同一文件的 `_search_platform` 分发表中注册它。 3. 可选：在 `config.yaml` 中添加平台配置。 ### 添加图节点 1. 创建 `graph/nodes/my_node.py`： ``` from graph.state import OSINTState from graph.nodes._timing import log_start, log_done def my_node(state: OSINTState) -> dict: start = log_start("My Node") # ... process state ... log_done("My Node", start) return {"my_key": result} ``` 2. 在 `graph/workflow.py` 中注册： ``` from .nodes.my_node import my_node workflow.add_node("my_node", my_node) workflow.add_edge("analysis", "my_node") ``` ## 故障排除 **“No Anthropic API key found”** — 从 `.env.example` 创建 `.env` 并设置 `ANTHROPIC_API_KEY`。 **Google 搜索无结果** — 免费的 `googlesearch-python` 库存在速率限制且不可靠。在 `.env` 中添加 `TAVILY_API_KEY` 或 `SERPAPI_KEY` 以获得稳定结果 (优先尝试 Tavily，然后是 SerpAPI，最后是免费后备)。 **Docker 下 Windows 页面刷新卡死** — Streamlit 的文件监视器与 Docker 卷挂载冲突。`.streamlit/config.toml` 中已设置 `fileWatcherType = "none"`；如果被移除请恢复。 **`Module not found`** — 运行 `pip install -r requirements.txt` 并确认 Python 3.11+。 **控制台警告：`missing ScriptRunContext`** — 无害的启动警告，已在 `app.py` 中处理。 **控制台警告：`file_cache is only supported with oauth2client<4.0.0`** — 来自 Google API 客户端库的无害警告。 **Docker Desktop 无法启动 (WSL 错误)** — Ubuntu WSL 发行版可能已自动关闭。先在终端运行 `wsl -d Ubuntu`，等待几秒，然后重试 Docker Desktop。 ## 隐私与道德 **仅供教育和合法用途** 适用场景：安全研究，尽职调查，调查性新闻，个人隐私审计，OSINT 方法论研究，经同意的身份核实。 禁止用途：跟踪或骚扰，未经授权的监控，身份盗窃，人肉搜索，任何非法活动。 所有搜索仅使用公开可用信息。用户需遵守： - 当地隐私法律 (GDPR, CCPA 等) - 平台服务条款 (包括 Twitter/X, Reddit, YouTube 及其他) - 计算机欺诈与滥用法 (CFAA) 及当地同等法律 UI 中的同意复选框并非法律挡箭牌 —— 您需对使用本工具的方式负全责。 **使用本工具即表示您同意以负责任和道德的方式使用它。** ## 性能与可靠性 该工具包含内置优化： - **缓存**：API 响应缓存 1-24 小时，以减少配额消耗并提升速度。重复搜索明显更快。 - **重试逻辑**：失败的 API 调用自动重试最多 3 次，采用指数退避策略，以应对网络问题。 - **输入验证**：所有输入在处理前都经过清洗和验证，以防止错误并提高安全性。 缓存文件存储在 `.cache/`，并根据 TTL 自动过期。清除缓存：`rm -rf .cache/` (Unix) 或 `rmdir /s .cache` (Windows)。 ## 许可证 本项目仅供教育目的。请根据适用法律负责任地使用。

标签：Anthropic, Atomic Red Team, CIS基准, Claude, CVE检测, Docker, Docker Compose, ESC4, ESC8, HIBP, Hunter.io, Kali工具, Kubernetes, LangChain, LangGraph, LinkedIn, OSINT, Python, reconnaissance, Reddit, SerpAPI, Streamlit, Tavily, Twitter/X, Unix, 人员调查, 加密文件系统, 多智能体, 威胁情报, 安全防御评估, 实时处理, 密码管理, 开发者工具, 开源网络情报, 数字足迹, 数据泄露检测, 无后门, 暗网搜索, 特征检测, 社交媒体监控, 社会工程学, 网络安全, 自动化报告, 访问控制, 请求拦截, 轻量级, 逆向工具, 邮箱挖掘, 隐私保护