aleff-github/wayparam

# wayparam  **wayparam** 是一款现代的跨平台命令行（CLI）工具，用于**从 Internet Archive Wayback CDX API 获取历史 URL**，过滤掉“无聊”的 URL（静态资源），并**规范化查询参数**，以便您将精力集中在真正重要的端点上。 本项目**受 ParamSpider 启发**（目标一致，但采用了更健壮的架构、现代异步 I/O、更好的过滤机制以及适用于生产环境的输出行为进行了完全重写）。 将这个 `example.com` 转换成类似这样的结果： ``` ... http://www.example.com/_next/image?q=FUZZ&url=FUZZ&w=FUZZ https://www.example.com/_Incapsula_Resource?SWJIYLWA=FUZZ http://www.example.com/?format=FUZZ&retailerId=FUZZ ... ``` ## 主要特性 - **Wayback CDX API** URL 收集（支持单个域名或列表） - **异步 + 并发** 提速，高效处理多域名 - **速率限制**（`--rps`）以友善对待 Wayback/CDX - **重试 + 退避**机制以及更清晰的错误提示 - 支持 **CDX 分页**（resumeKey，可用时） - 通过以下方式过滤“无聊”的 URL： - 扩展名黑名单/白名单 - 可选的路径正则表达式排除 - **规范化与标准化** - 去除片段（fragment） - 规范化主机/端口 - 参数排序 - 屏蔽参数值（默认占位符：`FUZZ`） - 可选的跟踪参数移除（utm_*、gclid、fbclid 等） - 输出： - 按域名分类的独立文件（默认） - 用于管道操作的 **stdout 流式传输**（`--stdout`） - `txt` 或 `jsonl` 格式输出（`--format`） ## 安装 ### 通过 PyPI 安装（推荐） ``` pip install wayparam ``` ### 从源码安装 ``` python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate python -m pip install -U pip pip install -e . ``` ### 开发环境安装（包含测试 + lint） ``` pip install -e ".[dev]" ``` ## 快速开始 ### 1) 单个域名（写入 `results/` 目录） ``` wayparam -d example.com ``` ### 2) 域名列表 ``` wayparam -l domains.txt ``` ### 3) 流式输出到标准输出（用于管道传输），不生成文件 ``` wayparam -d example.com --stdout --no-files ``` ### 4) JSONL 格式输出（适合工具链处理） ``` wayparam -d example.com --stdout --no-files --format jsonl ``` ### 5) 包含子域名 + 优化对 Wayback 的请求 ``` wayparam -d example.com --include-subdomains --rps 1 --concurrency 2 ``` ### 6) 自定义过滤（扩展名 + 路径正则） ``` wayparam -d example.com --ext-blacklist ".png,.jpg,.css,.js" --exclude-path-regex "^/static/" ``` ## 工作原理（底层机制） 1. **输入解析** * `-d/--domain` 用于指定单个主机 * `-l/--list` 用于指定多个主机（每行一个，支持注释和基本规范化） 2. **查询 Wayback CDX API** * 向 CDX 端点发送请求 * 默认使用 `matchType=host`，当启用 `--include-subdomains` 时使用 `matchType=domain` * 在 API 提供时使用分页 3. **过滤“无聊”的 URL** * 丢弃类似于静态资源的 URL（按扩展名），支持可选的白名单模式 * 可选的正则表达式过滤器，用于排除特定路径（例如 `/static/`、`/assets/` 等） 4. **规范化与标准化** * 去除 URL 片段（`#...`） - 规范化默认端口（`:80`、`:443`） - 解析查询字符串并： - 用占位符（默认为 `FUZZ`）替换参数值 - 可选丢弃跟踪参数 - 对参数进行排序以保证输出稳定 - 对结果进行去重处理 5. **输出** * 默认将每个域名的结果写入 `results/` 目录 * `--stdout` 以机器可读的格式流式输出 * 诊断信息（提示、日志、统计）发送到 **stderr**（对管道安全） ## 输出行为（对管道操作很重要） * **stdout**：仅在启用 `--stdout` 时输出结果（URLs 或 JSONL 格式） * **stderr**：日志、错误、提示（VPN/代理）以及可选的统计信息 这意味着您可以安全地执行： ``` wayparam -d example.com --stdout --no-files | sort -u > urls.txt ``` ## 常用选项 ### Wayback/CDX * `--include-subdomains` * `--from 2019` / `--to 2021`（或完整时间戳如 `20190101000000`） * `--filter statuscode:200`（可重复使用） * `--no-collapse`（更多重复项，更多数据） ### 规范化 * `--placeholder X` * `--keep-values`（如果您要分享日志，则不推荐使用） * `--drop-tracking` / `--no-drop-tracking` * `--all-urls`（包含没有查询参数的 URL） ### 过滤 * `--ext-blacklist ".png,.jpg,.css,.js"` * `--ext-whitelist ".php,.asp,.aspx"` * `--exclude-path-regex "regex"`（可重复使用） ### 性能 / 网络 * `--concurrency 8` * `--rps 1`（使用 VPN 或不稳定网络时推荐） * `--timeout 30` * `--retries 4` * `--proxy http://127.0.0.1:8080` ## 故障排除：VPN / 代理问题 如果您在请求 CDX 端点时遇到诸如“failed after retries”之类的错误，通常意味着： * 该 VPN/代理的出口节点被 Wayback **屏蔽**或**限速**了 * 您的 VPN 进行了 TLS 过滤，或其网络策略破坏了自动化请求 请尝试： * 断开 VPN/代理并重新运行 * 切换到其他 VPN 服务器 * 降低 `--concurrency` 并设置 `--rps 1` 当 wayparam 检测到此类情况时，会在 stderr 打印**人类可读的英文提示**。 ## 手册页 本项目包含一份手册页： ``` man ./man/wayparam.1 ``` ## 测试 安装开发依赖项并运行： ``` pip install -e ".[dev]" pytest -q ``` 测试套件包含使用 `httpx.MockTransport` 进行的 **httpx 级别集成测试**（无需网络）。 ## 许可证 wayparam 是根据 **GNU 通用公共许可证 v3 (GPLv3)** 发布的**自由软件**。 详情请参阅 `LICENSE` 文件。 ## 致谢 - 灵感来源于 **ParamSpider**（相同的目标：获取 Wayback URL，过滤干扰，专注于带参数的端点）。 - 感谢 OSINT / 安全社区在 URL 收集和参数发现方面提供的模式与工作流。 ## 免责声明 请合法、负责任地使用。本工具仅查询 Internet Archive，并不主动扫描目标，但您对收集到的 URL 的后续使用可能会根据具体情境产生法律和伦理方面的影响。

标签：BeEF, Bug Bounty, CDX API, ESC4, OSINT, ParamSpider, Python, URL发现, URL规范化, Wayback Machine, Web安全, 参数抓取, 反汇编, 可自定义解析器, 安全检测, 密码管理, 异步IO, 文档结构分析, 无后门, 模糊测试准备, 爬虫, 网络安全, 蓝队分析, 路径扫描, 运行时操纵, 逆向工具, 隐私保护