cfprobe 0.1.0

Cloudflare reverse proxy and CDN detection engine
Documentation

cfprobe

Cloudflare CDN / 反向代理 识别引擎。通过综合 IP 段归属、DNS 解析、TLS 握手、HTTP 指纹 四路证据, 以 基于规则的证据评分引擎 判定一个 IP + Hostname 是否是 Cloudflare 边缘节点上的站点, 并给出置信度、详细证据链和各阶段探测结果。

特性

  • 多路证据融合:Cloudflare 官方 IP 段 + DNS 多解析器共识 + CNAME 链 + TLS 证书 + HTTP 头指纹(CF-Ray、Server: cloudflare 等)
  • 可插拔策略:内置 CloudflareWebProxyV1 策略;也可实现 DetectionPolicy trait 自定义分类规则
  • 安全 SSRF 防护:TargetPolicy 默认拒绝私网 / link-local / 组播 / localhost 等目标,可按需放宽
  • 多级缓存:
    • DNS 内存缓存(TTL + 容量淘汰)
    • Cloudflare 官方 IP 范围:内存 + 磁盘 + 跨进程文件锁 + stale-while-revalidate
  • 高并发:
    • 单目标内 DNS / TLS / HTTP 三路探测并发执行
    • DNS 单解析器内 A/AAAA、MX、TXT、NS 并发;多解析器同时并发
    • 批量扫描:可控并发度 + RPS 限流 + 按目标超时 + CancellationToken 取消
  • 运行模式:
    • Rust 库(cfprobe crate)
    • 命令行(cfprobe probe / scan / serve)
    • HTTP 服务(axum,/probe 单目标 + /scan 批量 + /metrics 统计)
  • 完整观测:每个阶段有独立 ProbeResult,含 duration、错误、最终 DetectionResult(总分、置信度等级、正负证据列表、可读 summary)

架构

                        ┌──────────────────────────────────┐
                        │          CfProbe (facade)        │
                        └──────────────────────────────────┘
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          │                          │                          │
    ┌─────▼─────┐              ┌─────▼─────┐              ┌─────▼─────┐
    │  IP/DNS   │              │    TLS    │              │   HTTP    │
    │ Detector  │              │  Prober   │              │  Prober   │
    └─────┬─────┘              └─────┬─────┘              └─────┬─────┘
          │                          │                          │
          └──────────────────────────┼──────────────────────────┘
                                     ▼
                        ┌──────────────────────────┐
                        │     Evidence Engine      │
                        │  + DetectionPolicy       │
                        └──────────────────────────┘
                                     │
                                     ▼
                      DetectionResult {
                        classification, confidence,
                        score, evidence[], summary
                      }

阶段顺序:

  1. CloudflareRanges — 加载官方 IP/CIDR(内存 cache → 磁盘 cache → HTTP)
  2. Ip — 本地 CIDR 匹配,判断 IP 是否归属 Cloudflare
  3. Dns / Tls / Http — 三路 join 并发
  4. Evidence — 汇总所有信号,按策略打分分类

快速开始

作为库使用

Cargo.toml:

[dependencies]
cfprobe = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

单次探测

use std::net::IpAddr;
use cfprobe::{CfProbe, CfProbeConfig, Target};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 构建长期存活的探测器(内部会初始化 DNS/HTTP/TLS 客户端和缓存)
    let config = CfProbeConfig::cloudflare_web_proxy_v1()?;
    let probe = CfProbe::new(config).await?;

    // 2. 定义目标(IP + SNI/Host 主机名 + 端口 + scheme)
    let target = Target::https("104.16.77.250".parse::<IpAddr>()?, "example.com");

    // 3. 执行探测
    let result = probe.detect(target).await?;

    println!("is_cloudflare   : {}", result.is_cloudflare());
    println!("classification  : {:?}", result.detection.classification);
    println!("confidence      : {:.2}", result.detection.confidence);
    println!("confidence_level: {:?}", result.detection.confidence_level);
    println!("score           : {}",   result.detection.score);
    println!("summary         : {}",   result.detection.summary);

    Ok(())
}

批量扫描(流式)

use std::net::IpAddr;
use std::time::Duration;
use futures::StreamExt;
use cfprobe::{BatchScanConfig, CfProbe, CfProbeConfig, Target};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let probe = CfProbe::new(CfProbeConfig::cloudflare_web_proxy_v1()?).await?;

    let targets = vec![
        Target::https("104.16.77.250".parse::<IpAddr>()?, "example.com"),
        Target::https("104.16.76.250".parse::<IpAddr>()?, "example.org"),
    ];

    let config = BatchScanConfig::default()
        .with_concurrency(32)                   // 最多同时探测 32 个目标
        .with_requests_per_second(Some(50))     // 限流 50 QPS
        .with_target_timeout(Duration::from_secs(30)); // 单目标超时 30s

    // scan_unordered 按完成顺序返回,不是输入顺序
    let mut stream = probe.scan_unordered(targets, config)?;
    while let Some(item) = stream.next().await {
        match item.status {
            BatchItemStatus::Ok(result)  => println!("{:?} → {:?}", item.target.ip, result.detection.classification),
            BatchItemStatus::Timeout     => println!("{:?} timed out",   item.target.ip),
            BatchItemStatus::Cancelled   => println!("{:?} cancelled",   item.target.ip),
            BatchItemStatus::Error(err)  => println!("{:?} err: {}",     item.target.ip, err),
        }
    }
    Ok(())
}

命令行

# 构建
cargo build --release

# 单次探测
./target/release/cfprobe probe --ip 104.16.77.250 --hostname example.com

# 批量扫描(从 targets.jsonl 读取,每行一个 JSON Target)
./target/release/cfprobe scan \
    --input targets.jsonl \
    --output results.jsonl \
    --concurrency 32 \
    --requests-per-second 50 \
    --target-timeout-secs 30

# 启动 HTTP API 服务
./target/release/cfprobe serve --listen 127.0.0.1:8080

# JSON 结构化日志
./target/release/cfprobe --json-logs probe --ip ...

HTTP API

启动服务:cfprobe serve --listen 0.0.0.0:8080

GET /version

{ "name": "cfprobe", "version": "0.1.0" }

POST /probe 单目标

curl -X POST http://127.0.0.1:8080/probe \
  -H 'Content-Type: application/json' \
  -d '{
    "ip": "104.16.77.250",
    "hostname": "example.com",
    "port": 443,
    "scheme": "https"
  }'

返回完整的 ProbeResult(含 IP/DNS/TLS/HTTP/Evidence 各阶段详情、错误列表)。

POST /scan 批量

curl -X POST http://127.0.0.1:8080/scan \
  -H 'Content-Type: application/json' \
  -d '{
    "targets": [
      {"ip": "104.16.77.250", "hostname": "example.com", "port": 443, "scheme": "https"},
      {"ip": "104.16.76.250", "hostname": "example.org", "port": 443, "scheme": "https"}
    ],
    "concurrency": 16,
    "requests_per_second": 20,
    "target_timeout_secs": 30
  }'

按完成顺序 streaming 返回 application/x-ndjson(每行一个 BatchItemResult)。

GET /metrics

纯 JSON 指标(请求总数、成功/失败/超时/取消计数、Cloudflare 三态分类计数、in_flight 等)。

核心概念

Target(探测目标)

pub struct Target {
    pub ip:       IpAddr,    // 直连 IP
    pub hostname: String,    // SNI + Host 头 + DNS 查询名
    pub port:     u16,
    pub scheme:   HttpScheme, // Http / Https
}

便捷构造:

  • Target::https(ip, hostname) → port=443 + Https
  • Target::http(ip, hostname) → port=80 + Http

DetectionClassification(最终分类)

枚举值 含义
Cloudflare 综合证据判定为 Cloudflare 代理
NotCloudflare 综合证据判定不是 Cloudflare
Unknown 证据不足,或 Cloudflare 官方 IP 段加载失败且 require_cloudflare_ranges = true

ConfidenceLevel(置信度等级)

VeryHigh > High > Medium > Low > Insufficient

置信度由 DetectionPolicy::ConfidenceRuleSet 的 (base + score/divisor) 公式计算, 并按阈值映射到等级。

EvidenceItem(证据条目)

每个 EvidenceItem 包含:

  • kind: EvidenceKind 枚举(共 22 种,如 CloudflareIpRange、HttpCfRay、DnsResolverConsensus…)
  • direction: Positive / Negative / Neutral
  • category: Ip / Dns / Tls / Http
  • score: 该条证据的加权分(正值加分、负值减分,最终累加到 DetectionResult.score)
  • detail: serde_json::Value 可读细节

最终 summary 字段会把所有证据按正负数量、强信号拼成人可读的一句话说明。

模块速览

  • cloudflare — 官方 IP 段拉取(CloudflareClient)+ 多级缓存(CloudflareRangeCache:内存 / 磁盘 fs2 文件锁 / stale fallback)+ 命中检测
  • dns — 抽象 DnsBackend + HickoryDnsResolver (hickory-resolver, 支持 DoH) + DnsPool(多解析器并发聚合,可插拔 DNS 内存缓存)+ DnsDetector(CNAME 链遍历、多解析器共识、私网应答过滤、熔断、PTR 反查)
  • tls — rustls 握手,证书 SHA256 / subject / issuer / SAN 解析;支持 verify_certificate 与 observation_fallback(验证失败但仍记录证书信号)
  • http — reqwest 连接池复用(按 (scheme, ip, hostname, port) 缓存 Client),抽取 Cloudflare 头信号(CF-Ray / CF-Cache-Status / Server: cloudflare / CF-Connecting-IP 等)
  • evidence — EvidenceEngine + DetectionPolicy;内置 CloudflareWebProxyV1 是一组针对 Cloudflare Web 反代的调优规则集(IP 段 25 分、DNS 共识、CNAME 指向 Cloudflare、CF-Ray 头 50 分等)
  • probe — 外层 facade:CfProbe、CfProbeConfig、TargetPolicy(SSRF 防护)、批量 scan_unordered
  • server — axum HTTP 服务:/probe /scan /metrics /health /version,JSON metrics

性能要点

本引擎设计用于批量扫描公网目标,核心性能关键路径:

优化点 实现
DNS 多路并发 解析器间并发(semaphore 控制) + 单解析器内 A/AAAA/MX/TXT/NS join! 并发
单目标三阶段并发 DNS / TLS / HTTP tokio::join!,总耗时 ≈ max(三阶段) 而非 sum
TLS ClientConfig 预构建 TlsProber::new 时一次性初始化 RootCertStore(webpki-roots 150+ 根),缓存 Arc<ClientConfig>
HTTP 连接池 按目标 (scheme, ip, hostname, port) 复用 reqwest::Client,避免每次重建 connector
平滑 RPS 限流 StartRateLimiter 预约式槽位:先短暂持锁排期、再解锁 sleep,避免持锁等待阻塞其他任务
Cloudflare 缓存 三级 cache:内存 RwLock → 磁盘 JSON(fs2 文件锁跨进程互斥) → stale-while-revalidate(网络失败时可回退陈旧磁盘缓存)
DNS 内存缓存 容量上限 + TTL 双重淘汰;CNAME 链、IP、MX、TXT、NS、PTR 六类独立缓存
批量取消 CancellationToken 贯穿所有阶段:IP 范围拉取、DNS、TLS、HTTP、PTR、证据引擎全路径可提前退出

SSRF / 目标策略

TargetPolicy::cloudflare_web_proxy_v1() 默认启用以下防护(可调):

  • ❌ 拒绝 loopback / RFC1918 / link-local / 组播 / unspecified / documentation(192.0.2.x 等) / benchmark / IPv4 映射 IPv6 的私网段
  • ❌ 拒绝 hostname 为 localhost / .local. / .internal. / .localhost
  • ❌ 拒绝 DNS 解析结果为私网 IP(可避免 DNS rebinding)
  • ❌ 仅允许 Cloudflare Web Proxy 官方端口:
    • HTTP: 80, 8080, 8880, 2052, 2082, 2086, 2095
    • HTTPS: 443, 2053, 2083, 2087, 2096, 8443

可单独构造 TargetPolicy 并通过 CfProbeConfig::with_target_policy() 覆盖以适配内网扫描场景。

安全说明

  1. cfprobe 是主动出站探测工具,目标 IP/端口完全由调用方提供。请在接入不可信输入前过一层 TargetPolicy::validate_target / validate_dns。
  2. rustls 采用 ring 加密提供者,首次使用前请在 main 入口调用 cfprobe::init_rustls_crypto()(在 CfProbe::new 内部会自动调用;如果直接使用单独模块如 TlsProber::new 请手动调用一次)。
  3. HTTP 探测最大 body 读取量由 HttpProbeConfig.max_body_bytes 控制(默认 1 MiB),避免大响应吞带宽。
  4. 批量扫描的 QPS、并发度、超时请按出口带宽和对端容忍度合理设定;CloudflareWebProxyV1 仅用于授权资产审计。

测试

# 单元/集成测试(排除需要真实公网访问的 slow tests)
cargo test

# 单独跑集成测试(需要真实公网访问)
cargo test --test probe -- test_probe_one_way --include-ignored --nocapture

License

MIT