dejisec/papertrail

# PaperTrail PaperTrail 用于发现目标 域名的公开文档， 下载这些文档，提取嵌入的元数据，并将 结果转换为结构化的 JSON/CSV 报告。它还包含一个可选的 [CrewAI](https://www.crewai.com/) 编排路径，以便每个流水线阶段都可以 委托给自主代理。 ## 功能 - **确定性 Google dorks** – 根据文件类型和可选关键字构建 Serper.dev 查询，并由 SQLite 提供缓存/恢复支持。 - **丰富的元数据提取** – 合并 pypdf、OOXML、旧版 Office 和 ExifTool 信号，然后提取用户名、电子邮件域名和文件系统路径。 - **可操作的报告** – 生成 `results.json`、`downloads.json`、 `metadata.json`、`metadata.csv`、`findings.json` 以及一份 汇总所有文档趋势的 Markdown 格式 `report.md`。 - **代理模式** – 启用后，会捕获每个步骤的产物以及 CrewAI 会话 输出，以便分析师可以审计或复用每个代理生成的内容。 ## 入门指南 ### 前置条件 - Python 3.12+ - [uv](https://docs.astral.sh/uv/) - 一个 [Serper.dev](https://serper.dev) API 密钥（用于访问 Google 搜索结果） ### 安装说明 ``` git clone https://github.com/dejisec/papertrail.git cd papertrail uv sync ``` CrewAI 代理流水线是可选的。要启用它，请运行 `uv sync --extra agents` 并设置 `PAPERTRAIL_USE_CREW=1`。 ### 环境配置 创建一个 `.env` 文件（或复制 `example.env`）并提供所需的密钥： ``` SERPER_API_KEY=sk-serper-your-key-here # 可选：启用 CrewAI 模式 OPENAI_API_KEY=sk-openai-... PAPERTRAIL_USE_CREW=0 # set to 1 to run the CrewAI pipeline ``` ## 用法 通过 `uv run papertrail` 运行 CLI： ``` papertrail \ --domain example.com \ --types pdf,docx,xlsx \ --keywords finance,"internal audit" \ --max-results 10 \ --max-size-mb 75 \ --out ./output ``` 主要选项： - `--domain/-d`（必填）– 用于限定 `site:` 搜索范围的主机。 - `--types/-t`（必填）– 允许的扩展名逗号分隔列表（pdf， docx, xlsx, doc, xls, ppt, pptx）。 - `--keywords/-k` – 可选的逗号分隔关键字，如果 包含空格则会自动加上引号。 - `--max-results` – 所有查询规范化结果的总上限（1–1000）。 - `--max-size-mb` – 拒绝大于此阈值的下载。 - `--out/-o` – 存储所有下载、缓存和报告的用例目录。 - `--db-path` – 自定义 SQLite 路径（默认为 `/papertrail.db`）。 - `--resume` – 复用先前运行的缓存查询和下载。 - `--json` – 将解析后的配置输出为 JSON（用于自动化）并 将其作为 `papertrail-config.json` 存储在输出文件夹中。 - `--verbose` – 启用结构化 DEBUG 日志以进行故障排除。 ### 输出结构 每次运行会产生： - `results.json` – 规范化的 Serper 搜索命中结果以及运行上下文。 - `downloads.json` – 每个 URL 的结果（状态、MIME、SHA-256、大小、最终 URL）。 - `files/` – 按文件类型组织的下载文档。 - `metadata.json` / `metadata.csv` – 结构化元数据记录。 - `findings.json` – 汇总统计（作者、编辑、电子邮件域名等）。 - `report.md` – 可直接用于简报的 Markdown 摘要。 - `papertrail.db` – 为 `--resume` 提供支持的 SQLite 缓存。 当设置了 `PAPERTRAIL_USE_CREW=1` 时，PaperTrail 还会在 `output/agents/*.json` 下写入代理产物（搜索载荷、抓取日志、元数据列表、CrewAI 会话记录等）。`report.md` 会在“Agent Outputs”（代理输出）部分引用这些路径。 ## 代理工作流（可选） 如果同时设置了 `PAPERTRAIL_USE_CREW=1` 和 `OPENAI_API_KEY`，CLI 会路由到 `PapertrailCrewRunner`，该运行器会： 1. 运行相同的确定性搜索/下载/元数据流水线。 2. 保存每个阶段的 JSON 产物以供审计。 3. 调用 CrewAI 的顺序模板（代理/任务定义在 `papertrail/config/agents.yaml` 和 `config/tasks.yaml` 中）。 4. 记录 CrewAI 会话输出，以便调查结果包含 LLM 推理。 此模式完全是可选的；当环境变量不存在时， CLI 会回退到直接流水线。

标签：CrewAI, CSV, ESC4, ExifTool, Google Dorks, JSON, Markdown, OOXML, OSINT, pdf, pentest, pentest-recon, pypdf, Python, Serper.dev, 元数据提取, 公共文档发现, 实时处理, 工具, 搜索引擎Dorking, 数据泄露, 无后门, 目标侦察, 网络安全, 网络调试, 自动化, 进程保护, 逆向工具, 隐私保护