cfprobe 0.1.0

Cloudflare reverse proxy and CDN detection engine
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
use std::net::{IpAddr, SocketAddr};
use std::sync::Arc;
use std::time::Duration;

use sha2::{Digest, Sha256};

use tokio::{net::TcpStream, time::timeout};

use tokio_rustls::{
    client::{TlsConnector, TlsStream},
    rustls::{self, ClientConfig, RootCertStore},
};

use rustls::pki_types::ServerName;

use webpki_roots::TLS_SERVER_ROOTS;

use x509_parser::{extensions::GeneralName, prelude::*};

use crate::{error::CfProbeError, probe::Target};

use super::{
    model::{CertificateInfo, CertificateVerificationStatus, TlsDetection, TlsDetectionStatus},
    verifier::ObservationVerifier,
};

/// TLS 探测配置。
#[derive(Debug, Clone)]
pub struct TlsProbeConfig {
    /// 单次握手超时。
    pub timeout: Duration,

    /// 默认端口。
    ///
    /// 当调用 `probe` 时使用。
    pub port: u16,

    /// 是否先进行正常的证书链校验握手。
    pub verify_certificate: bool,

    /// 严格模式失败时,是否回退到放宽校验(仅记录证书)。
    pub observation_fallback: bool,

    /// 客户端提供的 ALPN 协议列表。
    pub alpn_protocols: Vec<Vec<u8>>,
}

impl Default for TlsProbeConfig {
    fn default() -> Self {
        Self {
            timeout: Duration::from_secs(8),

            port: 443,

            verify_certificate: true,

            observation_fallback: true,

            alpn_protocols: vec![b"h2".to_vec(), b"http/1.1".to_vec()],
        }
    }
}

/// TLS 握手探测器(可 Clone,内部为 Arc)。
///
/// 在内部预构建了 verified / observation 两种 rustls `ClientConfig`,
/// 避免每次探测重新解析根证书。建议长期存活复用。
#[derive(Clone)]
pub struct TlsProber {
    config: TlsProbeConfig,
    /// 预构建好的 Verified 模式配置,
    /// 避免每次探测重新解析 ~150 个根证书。
    verified_config: Option<Arc<ClientConfig>>,
    /// 预构建好的 Observation 模式配置。
    observation_config: Option<Arc<ClientConfig>>,
}

impl TlsProber {
    /// 根据配置创建 TlsProber;会自动调用 [`crate::init_rustls_crypto`]。
    pub fn new(config: TlsProbeConfig) -> Self {
        crate::init_rustls_crypto();

        let verified_config = if config.verify_certificate {
            match build_client_config(ProbeMode::Verified, &config.alpn_protocols) {
                Ok(cfg) => Some(Arc::new(cfg)),
                Err(e) => {
                    tracing::warn!(
                        error = %e,
                        "failed to pre-build TLS verified config, will fall back at probe time"
                    );
                    None
                }
            }
        } else {
            None
        };

        let observation_config = if config.observation_fallback {
            match build_client_config(ProbeMode::Observation, &config.alpn_protocols) {
                Ok(cfg) => Some(Arc::new(cfg)),
                Err(e) => {
                    tracing::warn!(
                        error = %e,
                        "failed to pre-build TLS observation config, will fall back at probe time"
                    );
                    None
                }
            }
        } else {
            None
        };

        Self {
            config,
            verified_config,
            observation_config,
        }
    }

    /// 获取当前使用的配置引用。
    pub fn config(&self) -> &TlsProbeConfig {
        &self.config
    }

    /// 使用 `TlsProbeConfig::port` 作为默认端口进行 TLS 探测。
    pub async fn probe(&self, ip: IpAddr, hostname: &str) -> Result<TlsDetection, CfProbeError> {
        self.probe_with_port(ip, hostname, self.config.port).await
    }

    /// 对指定 IP + SNI + Port 执行 TLS 探测。
    ///
    /// 行为:
    /// 1. 若 `verify_certificate` 打开,先执行严格校验握手。
    /// 2. 严格失败且 `observation_fallback` 打开,再用忽略校验模式重连,只为提取证书。
    /// 3. 两种模式都失败则返回 `TlsDetectionStatus::HandshakeFailed`。
    pub async fn probe_with_port(
        &self,
        ip: IpAddr,
        hostname: &str,
        port: u16,
    ) -> Result<TlsDetection, CfProbeError> {
        if port == 0 {
            return Err(CfProbeError::InvalidResponse(
                "TLS port cannot be 0".to_string(),
            ));
        }

        let hostname = normalize_hostname(hostname)?;

        /*
         * 第一阶段:
         *
         * 正常验证服务器证书。
         */
        let strict_result = if self.config.verify_certificate {
            self.probe_once(ip, &hostname, port, ProbeMode::Verified)
                .await
        } else {
            None
        };

        /*
         * 如果正常验证模式已经成功,
         * 直接返回,不再做第二次握手。
         */
        if let Some(result) = strict_result {
            if result.handshake_succeeded {
                return Ok(result);
            }

            /*
             * 如果禁止 observation fallback,
             * 那么直接返回 strict 模式结果。
             */
            if !self.config.observation_fallback {
                return Ok(result);
            }
        }

        /*
         * 第二阶段:
         *
         * 如果证书验证失败,但用户允许 observation fallback,
         * 使用 observation verifier 再进行一次 TLS 握手。
         *
         * 这个模式仍然验证 TLS cryptographic handshake,
         * 只是跳过 CA / hostname / expiration 等证书信任判断。
         */
        if self.config.observation_fallback {
            if let Some(result) = self
                .probe_once(ip, &hostname, port, ProbeMode::Observation)
                .await
            {
                return Ok(result);
            }
        }

        /*
         * 理论上 probe_once() 已经会返回失败结果,
         * 这里作为最终保护。
         */
        Ok(TlsDetection::failed(
            ip,
            hostname,
            port,
            "TLS handshake failed".to_string(),
        ))
    }

    /// Phase 8 Facade 使用的 API。
    ///
    /// Target 是整个 cfprobe 的统一目标定义,
    /// 因此这里直接使用 Target 中的 IP / Host / Port。
    pub async fn probe_target(&self, target: &Target) -> Result<TlsDetection, CfProbeError> {
        self.probe_with_port(target.ip, &target.hostname, target.port)
            .await
    }

    async fn probe_once(
        &self,
        ip: IpAddr,
        hostname: &str,
        port: u16,
        mode: ProbeMode,
    ) -> Option<TlsDetection> {
        let addr = SocketAddr::new(ip, port);

        /*
         * -----------------------------------------
         * TCP connect
         * -----------------------------------------
         */
        let stream = match timeout(self.config.timeout, TcpStream::connect(addr)).await {
            Ok(Ok(stream)) => stream,

            Ok(Err(error)) => {
                return Some(TlsDetection::failed(
                    ip,
                    hostname.to_string(),
                    port,
                    format!("TCP connect failed: {error}"),
                ));
            }

            Err(_) => {
                return Some(TlsDetection::failed(
                    ip,
                    hostname.to_string(),
                    port,
                    "TCP connect timeout".to_string(),
                ));
            }
        };

        /*
         * -----------------------------------------
         * SNI
         * -----------------------------------------
         */
        let server_name = match ServerName::try_from(hostname.to_string()) {
            Ok(name) => name,

            Err(error) => {
                return Some(TlsDetection::failed(
                    ip,
                    hostname.to_string(),
                    port,
                    format!("invalid TLS server name: {error}"),
                ));
            }
        };

        /*
         * -----------------------------------------
         * Rustls ClientConfig
         * -----------------------------------------
         *
         * 99% 场景直接使用预构建的 ClientConfig(一次性根证书解析)。
         * 如果初始化时构建失败,才退回到 probe 时现做。
         */
        let config_clone: Arc<ClientConfig> = match mode {
            ProbeMode::Verified => match self.verified_config.as_ref() {
                Some(cfg) => cfg.clone(),
                None => match build_client_config(mode, &self.config.alpn_protocols) {
                    Ok(cfg) => Arc::new(cfg),
                    Err(error) => {
                        return Some(TlsDetection::failed(
                            ip,
                            hostname.to_string(),
                            port,
                            format!("TLS config failed: {error}"),
                        ));
                    }
                },
            },
            ProbeMode::Observation => match self.observation_config.as_ref() {
                Some(cfg) => cfg.clone(),
                None => match build_client_config(mode, &self.config.alpn_protocols) {
                    Ok(cfg) => Arc::new(cfg),
                    Err(error) => {
                        return Some(TlsDetection::failed(
                            ip,
                            hostname.to_string(),
                            port,
                            format!("TLS config failed: {error}"),
                        ));
                    }
                },
            },
        };

        let connector = TlsConnector::from(config_clone);

        /*
         * -----------------------------------------
         * TLS handshake
         * -----------------------------------------
         */
        let tls_stream =
            match timeout(self.config.timeout, connector.connect(server_name, stream)).await {
                Ok(Ok(stream)) => stream,

                Ok(Err(error)) => {
                    return Some(TlsDetection::failed(
                        ip,
                        hostname.to_string(),
                        port,
                        format!("TLS handshake failed: {error}"),
                    ));
                }

                Err(_) => {
                    return Some(TlsDetection::failed(
                        ip,
                        hostname.to_string(),
                        port,
                        "TLS handshake timeout".to_string(),
                    ));
                }
            };

        /*
         * -----------------------------------------
         * Extract TLS information
         * -----------------------------------------
         */
        Some(build_detection(ip, hostname, port, mode, tls_stream))
    }
}

#[derive(Debug, Clone, Copy)]
enum ProbeMode {
    Verified,

    Observation,
}

fn build_client_config(
    mode: ProbeMode,
    alpn_protocols: &[Vec<u8>],
) -> Result<ClientConfig, rustls::Error> {
    crate::init_rustls_crypto();

    let builder = ClientConfig::builder();

    match mode {
        ProbeMode::Verified => {
            let mut roots = RootCertStore::empty();

            roots.extend(TLS_SERVER_ROOTS.iter().cloned());

            let mut config = builder.with_root_certificates(roots).with_no_client_auth();

            config.alpn_protocols = alpn_protocols.to_vec();

            Ok(config)
        }

        ProbeMode::Observation => {
            let provider = rustls::crypto::CryptoProvider::get_default()
                .ok_or_else(|| rustls::Error::General("no rustls CryptoProvider".to_string()))?;

            let verifier = ObservationVerifier::new(provider.signature_verification_algorithms);

            let mut config = builder
                .dangerous()
                .with_custom_certificate_verifier(verifier.into_arc())
                .with_no_client_auth();

            config.alpn_protocols = alpn_protocols.to_vec();

            Ok(config)
        }
    }
}

fn build_detection(
    ip: IpAddr,
    hostname: &str,
    port: u16,
    mode: ProbeMode,
    stream: TlsStream<TcpStream>,
) -> TlsDetection {
    let (_, connection) = stream.get_ref();

    let tls_version = connection
        .protocol_version()
        .map(|version| format!("{version:?}"));

    let cipher_suite = connection
        .negotiated_cipher_suite()
        .map(|suite| format!("{:?}", suite.suite()));

    let alpn = connection
        .alpn_protocol()
        .map(|protocol| String::from_utf8_lossy(protocol).to_string());

    let certificates = connection
        .peer_certificates()
        .map(parse_certificates)
        .unwrap_or_default();

    let verification = match mode {
        ProbeMode::Verified => CertificateVerificationStatus::Valid,

        ProbeMode::Observation => CertificateVerificationStatus::Unknown,
    };

    let status = match mode {
        ProbeMode::Verified => TlsDetectionStatus::HandshakeSucceeded,

        ProbeMode::Observation => TlsDetectionStatus::CertificateVerificationFailed,
    };

    TlsDetection {
        ip,

        hostname: hostname.to_string(),

        port,

        sni: Some(hostname.to_string()),

        handshake_succeeded: true,

        status,

        certificate_verification: verification,

        tls_version,

        cipher_suite,

        alpn,

        certificates,

        error: None,
    }
}

fn parse_certificates(
    certificates: &[rustls::pki_types::CertificateDer<'static>],
) -> Vec<CertificateInfo> {
    certificates
        .iter()
        .filter_map(|certificate| parse_certificate(certificate.as_ref()))
        .collect()
}

fn parse_certificate(der: &[u8]) -> Option<CertificateInfo> {
    let (_, certificate) = X509Certificate::from_der(der).ok()?;

    let mut dns_names = Vec::new();

    let mut ip_addresses = Vec::new();

    if let Ok(Some(san)) = certificate.subject_alternative_name() {
        for name in &san.value.general_names {
            match name {
                GeneralName::DNSName(name) => {
                    dns_names.push(name.to_string());
                }

                GeneralName::IPAddress(bytes) => {
                    if bytes.len() == 4 {
                        let octets: [u8; 4] = match <[u8; 4]>::try_from(bytes.as_ref()) {
                            Ok(value) => value,

                            Err(_) => {
                                continue;
                            }
                        };

                        ip_addresses.push(std::net::Ipv4Addr::from(octets).to_string());
                    } else if bytes.len() == 16 {
                        let octets: [u8; 16] = match <[u8; 16]>::try_from(bytes.as_ref()) {
                            Ok(value) => value,

                            Err(_) => {
                                continue;
                            }
                        };

                        ip_addresses.push(std::net::Ipv6Addr::from(octets).to_string());
                    }
                }

                _ => {}
            }
        }
    }

    let sha256 = Sha256::digest(der);

    Some(CertificateInfo {
        sha256: hex::encode(sha256),

        subject: certificate.subject().to_string(),

        issuer: certificate.issuer().to_string(),

        serial: certificate.raw_serial_as_string(),

        not_before: certificate.validity().not_before.to_string(),

        not_after: certificate.validity().not_after.to_string(),

        dns_names,

        ip_addresses,

        is_ca: certificate.is_ca(),
    })
}

fn normalize_hostname(hostname: &str) -> Result<String, CfProbeError> {
    let hostname = hostname.trim();

    if hostname.is_empty() {
        return Err(CfProbeError::Dns {
            message: "hostname is empty".to_string(),
        });
    }

    let hostname = hostname.trim_end_matches('.');

    if hostname.is_empty() {
        return Err(CfProbeError::Dns {
            message: "hostname is empty".to_string(),
        });
    }

    hickory_resolver::proto::rr::Name::from_utf8(&format!("{hostname}.")).map_err(|error| {
        CfProbeError::Dns {
            message: format!("invalid hostname `{hostname}`: {error}"),
        }
    })?;

    Ok(hostname.to_ascii_lowercase())
}