ProxyProbe

ProxyProbe 是一个用 Go 编写的高性能、高隐蔽性的网络代理（HTTP/SOCKS5）发现与验证工具。

很多网络扫描工具专注于广度，但 ProxyProbe 专注于深度与隐蔽。它结合了“网络端口扫描”与“应用层协议验证”，并且内置了全局目标洗牌（Global Shuffle）和抖动限速机制，专门设计用于在严苛的网络环境（如 IDS/IPS 防火墙）下进行慢速、隐蔽的可用代理探测。

同时，它还具备自动化发现能力，可以从你指定的公开代理网站上自动抓取、去重并验证代理的可用性。

---

为什么要使用它？

如果你面临以下情况，ProxyProbe 就是为你准备的：

1. 你需要验证海量的代理 IP：传统的 curl 测试太慢，你需要利用 Go 的高并发压榨网络性能。
2. 你需要绕过安全设备的检测：连续扫描同一个 IP 的不同端口，或不同 IP 的同一个端口，都会立即被防火墙拉黑。ProxyProbe 能够将百万级的探测任务打散成网络中的“背景噪声”。
3. 你想搭建自己的高匿代理池：它能自动从 Github 或其他网站的纯文本列表中抓取潜在代理，经过严格的双阶段验证（TCP 握手 -> 协议连通性测试）后，输出真正可用的高质量代理。

---

快速上手 (The Black Triangle)

让我们用最快的方式验证一下它。我们将从一个公开列表抓取一些代理，并测试它们能否访问 Google。

1. 编译安装

确保你安装了 Go (1.20+) 环境：

git clone https://github.com/honghaier/proxyprobe.git
cd proxyprobe
go build -o proxyprobe ./cmd/proxyprobe

2. 使用默认配置运行

项目内提供了一个示例配置文件 config.example.yaml，它已经配置好了从公开 GitHub 仓库抓取代理。

# 复制示例配置
cp config.example.yaml config.yaml

# 运行扫描（启用快速模式看效果）
./proxyprobe --config config.yaml --fast

你会看到终端立刻开始输出发现的可用代理：

[http] 1.2.3.4:8080
[socks5] 5.6.7.8:1080

(注意：如果没有加 --verbose 或 JSON 输出，控制台只会打印经过验证可用的代理。)

---

核心教程 (The Hairball)

当你成功跑起上面的命令后，你可能会好奇：它是怎么工作的？我该如何定制它？让我们循序渐进地了解 ProxyProbe 的核心概念。

这是 ProxyProbe 的完整数据流转架构：

                               ┌─────────────────┐
                 ┌────────────▶│ RangeProvider   │ (从命令行/配置解析网段和端口)
                 │             └────────┬────────┘
                 │                      │
┌────────────┐   │             ┌────────▼────────┐
│ config.yml │───┤             │ ScraperProvider │ (并发从指定的 URL 抓取代理列表)
└────────────┘   │             └────────┬────────┘
                 │                      │
                 │             ┌────────▼────────┐
                 └────────────▶│ FileProvider    │ (从 results.txt 加载历史结果并优先验证)
                               └────────┬────────┘
                                        │
                                        ▼ 
                            ┌──────────────────────┐
                            │    Target Manager    │ (将收集到的所有 IP:Port 去重)
                            └───────────┬──────────┘
                                        │
                                        ▼ 
                            ┌──────────────────────┐
                            │     FilterAlive      │ (默认行为：并发 TCP Ping 过滤离线 IP)
                            └───────────┬──────────┘
                                        │
                                        ▼ (仅存活的目标列表)
                            ┌──────────────────────┐
                            │      Scheduler       │ (全局打乱顺序、执行严格限速与抖动)
                            └───────────┬──────────┘
                                        │
                                        ▼ (节流后的目标流)
                            ┌──────────────────────┐
                            │      Scanner         │ (快速 TCP Connect 端口存活测试)
                            └───────────┬──────────┘
                                        │
                                        ▼ (仅存活的开放端口)
                            ┌──────────────────────┐
                            │       Prober         │ (真实 HTTP/SOCKS 协议验证与内容匹配)
                            └───────────┬──────────┘
                                        │
                                        ▼
                                     [Output]

概念一：目标 (Targets) 从哪里来？

ProxyProbe 的目标生成器被称为 Provider。目前支持三种主要方式，它们可以同时工作并自动去重：

1. 历史结果文件 (FileProvider)：优先加载。它会读取 results.txt（或其他指定的输出文件），保留已知的协议信息进行定向复测。
2. CLI / 配置文件指定网段 (RangeProvider)：直接指定待扫网段和端口。
3. 自动发现 (ScraperProvider)：从配置的 URL 中正则提取代理列表。

概念二：存活探测与两阶段扫描

为了追求极致效率，ProxyProbe 采用了并发的存活探测与验证管线：

1. 前置存活过滤 (FilterAlive)：这是一个默认且并发的行为。在正式开始大规模扫描前，系统会并发地对所有唯一目标进行“TCP Ping”（建立 TCP 连接）。
   • 相比传统的顺序探测，这种并发探测速度极快，能瞬间过滤掉数千个死 IP。
   • 这种机制避免了离线 IP 阻塞后续的打乱与调度队列。
2. 协议验证 (Prober)：对存活的端口，尝试构建 HTTP 或 SOCKS5 客户端进行真实的协议验证。如果是 HTTPS 目标，则会执行严格的 CONNECT 隧道与 TLS 握手测试。

概念三：隐蔽模式 (Slow Mode) vs 快速模式 (Fast Mode)

这是 ProxyProbe 的杀手锏。

• 快速模式 (--fast)：火力全开，只受 --concurrency 限制。适合扫内网或不怕被封的场景。
• 慢速模式 (--slow)：
  1. 全局洗牌 (Global Shuffle)：将所有目标（例如 [IP1:80, IP1:8080, IP2:80...]）完全打乱顺序。
  2. 全局限速 (--rate)：利用令牌桶算法，严格限制每秒发出的最大连接数 (PPS)。
  3. 随机抖动 (--jitter)：在每次请求前加入毫秒级的随机延迟。

概念四：严格的 HTTPS 验证

很多公开代理会伪造 200 OK 响应或劫持流量。ProxyProbe 为 HTTPS 目标实现了严格的验证：

• 隧道验证：手动发起 CONNECT 请求并验证代理服务器是否成功建立隧道。
• 强制握手：在隧道之上强制执行 TLS Handshake。只有真实透传加密流量、未被中间人劫持的代理才能通过验证。

概念五：守护进程与健康监控 (Daemon Mode)

开启守护进程模式 (--daemon) 后，ProxyProbe 演进为一个常驻的代理池管理器：

• 持续监控：按照设定的 monitor_interval（如 1 分钟）对已保存的代理进行轮回复测。
• 自动清洗：一旦发现代理失效，立即从内存和 results.txt 中剔除。
• 数据保护：采用原子写入策略，并确保在扫描被中断（如 Ctrl+C）时保护历史数据不被清空。

---

参考资料 (The Reference)

命令行参数

你可以通过 ./proxyprobe --help 查看所有参数。大部分参数都可以在 config.yaml 中配置。命令行参数的优先级高于配置文件。

参数	配置文件字段	描述
--config	N/A	YAML 配置文件路径
-p, --ports	ports	扫描的端口，例如 80,443,8080-8090，使用 - 表示全端口
-e, --exclude	exclude_targets	排除的 IP 或 CIDR 列表
--fast	fast_mode	启用快速模式（高并发，无延迟）
--slow	slow_mode	启用慢速隐蔽模式
--rate	rate_limit	全局速率限制（每秒数据包数 PPS），默认 1000
--jitter	jitter	慢速模式下的最大随机抖动延迟（毫秒）
-c, --concurrency	concurrency	并发工作线程数，默认 100
--daemon	daemon_mode	启用守护进程模式，持续监控已发现代理的健康状态
--monitor-interval	monitor_interval	守护模式下的健康检查间隔（例如 1m, 5m）
-o, --output	output_file	结果保存路径
--json	json_output	是否以 JSON 格式输出结果

输出格式

默认文本输出（方便 grep/awk）：

[http] 192.168.1.1:8080
[socks5] 10.0.0.1:1080

JSON 输出 (--json)，适合与其他流水线工具（如 jq）集成：

{"IP":"192.168.1.1","Port":8080,"Protocol":"http"}

已知限制 (Trade-offs)

1. 文件描述符 (ulimit)：如果 --concurrency 设置过高（如大于 1000），在 Linux/macOS 上可能会遇到 too many open files 错误。请使用 ulimit -n 65535 提高系统限制。
2. 内存占用：由于采用“全局洗牌”，所有目标对（IP:Port）在启动时都会被加载到内存中。扫描单个 /16 网段的全部端口可能会消耗百兆级别的内存。对于 /8 以上的超大网段全端口扫描，建议分批进行。

贡献指南 (Contributing)

我们欢迎任何形式的贡献！无论你是发现了 Bug、有新功能的想法，还是想改进文档，都非常欢迎。

如何参与开发：

1. Fork 仓库 并克隆到本地。
2. 理解架构：请务必先阅读本文档中的“核心教程”以及源码中的 TargetProvider 接口，理解 Two-Phase Pipeline 的数据流转。
3. 新建分支：git checkout -b feature/your-awesome-feature
4. 编写代码和测试：确保你的代码符合 Go 的习惯用法，并为新功能补充单元测试（特别是 internal/provider 和 internal/engine 下的改动）。运行 go test ./... 确保所有测试通过。
5. 提交 PR (Pull Request)：在 PR 描述中清晰地说明你解决了什么问题，以及你的实现思路。

寻求帮助：如果你在阅读代码或开发过程中遇到阻碍，请随时在 Issues 中提出，我们会尽力协助你（Teach, Don't Tell 是我们的原则）。

---

Teach, Don't Tell. 祝你探测愉快！