https://docs.rs/psi_detector

PSI-Detector 🧙‍♂️

PSI-Detector (Protocol Stream Identifier Detector) 是一个高性能的协议检测和升级框架，专为现代网络应用设计。通过智能的协议识别、魔法包特征检测和严格的过滤机制，为您的网络服务提供企业级的性能和安全保障。

✨ 核心特性

🚀 超高性能

• 2.3倍性能提升 - 严格协议过滤机制
• 魔法包检测 - 前几个字节的启发式快速判断
• SIMD加速 - 利用现代CPU指令集优化
• 零拷贝设计 - 最小化内存分配和拷贝

🛡️ 企业级安全

• 攻击面缩小 - 只响应配置的协议，其他流量被静默丢弃
• 扫描器欺骗 - 让端口扫描器误认为端口关闭
• 严格模式 - 强制配置验证，防止意外暴露
• 协议隔离 - 不同服务类型完全隔离

🎯 智能检测

• 15+ 预置协议 - HTTP/1.1, HTTP/2, HTTP/3, TLS, QUIC, SSH, WebSocket等
• 自定义协议 - 轻松添加游戏、IoT或专有协议
• 双向框架 - 支持服务器和客户端模式
• 协议升级 - 智能协议协商和升级

🔧 开发者友好

• 链式API - 直观的构建器模式
• 预设配置 - 针对不同场景的优化配置
• 详细错误 - 清晰的配置指导和错误信息
• 丰富示例 - 涵盖各种使用场景

---

🚀 快速开始

安装

[dependencies]
psi_detector = "0.1.1"

基础用法

use psi_detector::{DetectorBuilder, ProtocolType};

// 创建HTTP服务器检测器
let detector = DetectorBuilder::new()
    .enable_http()
    .enable_websocket()
    .enable_tls()
    .high_performance()
    .build()?;

// 检测协议
let data = b"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n";
let result = detector.detect(data)?;

println!("检测到协议: {} (置信度: {:.1}%)", 
         result.protocol_type(), 
         result.confidence() * 100.0);

---

📋 应用场景配置

🌐 HTTP/Web服务器

适用于：Web应用、API服务、微服务网关

let detector = DetectorBuilder::new()
    .enable_http()       // HTTP/1.1 支持
    .enable_http2()      // HTTP/2 支持  
    .enable_websocket()  // WebSocket 支持
    .enable_tls()        // HTTPS 支持
    .high_performance()  // 性能优化
    .build()?;

效果：

• ✅ 检测 HTTP/HTTPS/WebSocket 流量
• ❌ 过滤 SSH、数据库、游戏协议
• 🛡️ 对扫描器隐藏真实服务类型

🎮 游戏服务器

适用于：游戏后端、实时应用、IoT设备

// 定义自定义游戏协议
let game_probe = create_game_protocol_probe(); // 您的实现

let detector = DetectorBuilder::new()
    .enable_custom()                    // 启用自定义协议
    .add_custom_probe(Box::new(game_probe))
    .high_performance()
    .build()?;

效果：

• ✅ 只检测游戏协议数据包
• ❌ 100%过滤HTTP、SSH等协议
• 🚀 最高2.3倍性能提升
• 🔒 对网络扫描完全隐身

🔐 SSH/远程访问服务器

适用于：堡垒机、远程管理、安全隧道

let detector = DetectorBuilder::new()
    .enable_ssh()        // SSH协议支持
    .enable_tls()        // 安全隧道支持
    .high_accuracy()     // 高精度模式
    .build()?;

效果：

• ✅ 检测SSH和安全连接
• ❌ 忽略Web攻击和扫描
• 🔍 高精度识别避免误判

🌍 多协议网关

适用于：API网关、代理服务、协议转换

let detector = DetectorBuilder::new()
    .enable_http()
    .enable_http2() 
    .enable_grpc()      // gRPC支持
    .enable_quic()      // QUIC/HTTP3支持
    .enable_tls()
    .balanced()         // 平衡性能和精度
    .build()?;

效果：

• ✅ 支持现代Web协议栈
• ❌ 过滤传统和专有协议
• ⚖️ 性能与功能平衡

---

🎯 Agent模式（双向框架）

PSI-Detector支持服务器和客户端双向检测：

服务器Agent（被动检测）

use psi_detector::core::detector::{Role, Agent};

let server_agent = DetectorBuilder::new()
    .enable_http()
    .enable_tls()
    .with_role(Role::Server)           // 服务器角色
    .with_instance_id("web-server-01") // 实例标识
    .build_agent()?;

// 被动检测传入连接
let result = server_agent.detect(incoming_data)?;

客户端Agent（主动探测）

let client_agent = DetectorBuilder::new()
    .enable_http2()
    .enable_quic()
    .with_role(Role::Client)           // 客户端角色
    .build_agent()?;

// 主动探测服务器能力
let supported_protocols = client_agent.probe_capabilities(&mut transport)?;

负载均衡配置

let lb_agent = DetectorBuilder::new()
    .enable_http()
    .with_role(Role::Server)
    .with_load_balancer(
        LoadBalanceStrategy::RoundRobin,
        vec!["backend-1".to_string(), "backend-2".to_string()]
    )
    .build_agent()?;

---

🔮 魔法包特征检测

PSI-Detector内置超高速魔法包检测，可在前几个字节内识别协议：

预置协议特征

协议	魔法字节	置信度	检测速度
HTTP/1.1	GET , POST , HTTP/	95%-98%	~1800 ns
HTTP/2	PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n	100%	~1700 ns
TLS	0x16, 0x03	90%	~3400 ns
SSH	SSH-	99%	~1500 ns
QUIC	0x80 (长头部)	70%	~1600 ns

自定义协议特征

use psi_detector::core::magic::{MagicDetector, CustomSignatureBuilder};

let mut detector = MagicDetector::new();

// 添加自定义协议特征
let custom_sig = CustomSignatureBuilder::new(ProtocolType::Custom, "My Game Protocol")
    .with_magic_string("GAME")     // 魔法字符串
    .with_confidence(0.95)         // 置信度
    .with_offset(0)                // 偏移位置
    .case_insensitive()            // 不区分大小写
    .build();

detector.add_signature(custom_sig);

// 快速检测
let result = detector.quick_detect(b"GAME v1.0 login request");

---

⚡ 性能配置

高性能模式

适用于：高并发场景、实时应用

let detector = DetectorBuilder::new()
    .enable_http()
    .high_performance()    // 性能优先配置
    .build()?;

特点：

• ✅ 启用SIMD加速
• ✅ 被动探测策略（50ms超时）
• ✅ 大缓冲区（8KB）
• ✅ CPU保护机制

高精度模式

适用于：安全要求高、误判成本大的场景

let detector = DetectorBuilder::new()
    .enable_all()
    .high_accuracy()       // 精度优先配置
    .build()?;

特点：

• ✅ 启用启发式探测
• ✅ 较长超时时间（200ms）
• ✅ 高置信度阈值（90%）
• ✅ 深度特征分析

平衡模式

适用于：一般应用场景

let detector = DetectorBuilder::new()
    .enable_http()
    .enable_tls()
    .balanced()           // 平衡配置
    .build()?;

特点：

• ⚖️ SIMD + 启发式
• ⚖️ 中等超时（100ms）
• ⚖️ 平衡置信度（80%）

自定义配置

let detector = DetectorBuilder::new()
    .enable_http()
    .with_strategy(ProbeStrategy::Passive)
    .with_timeout(Duration::from_millis(50))
    .with_min_confidence(0.85)
    .enable_simd()
    .enable_heuristic()
    .with_buffer_size(4096)
    .build()?;

---

🧙‍♂️ 尤里主题（特殊模式）

致敬经典，PSI-Detector提供特殊的"心灵"检测模式：

心灵探测模式

let detector = DetectorBuilder::new()
    .enable_http()
    .psychic_detection()   // 高精度被动探测
    .build()?;

心灵控制模式

let detector = DetectorBuilder::new()
    .enable_all()
    .mind_control()        // 高性能被动探测
    .build()?;

心灵风暴模式

let detector = DetectorBuilder::new()
    .psychic_storm()       // 全面被动探测
    .build()?;

---

📊 性能基准测试

运行性能测试：

# 基础性能测试
cargo run --example magic_bytes_performance

# 协议过滤性能对比
cargo run --example protocol_filtering_performance

# 实际场景模拟
cargo run --example real_world_scenarios

基准数据

测试场景	检测时间	吞吐量	性能提升
魔法包检测	1,108 ns	902K/秒	2.08x
游戏服务器	4,420 ns	226K/秒	2.30x
HTTP服务器	7,880 ns	127K/秒	1.29x
标准检测	2,303 ns	434K/秒	1.00x

---

🛠️ 进阶功能

异步支持

#[cfg(feature = "runtime-tokio")]
use psi_detector::core::detector::AsyncProtocolDetector;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let detector = DetectorBuilder::new()
        .enable_http()
        .build()?;
    
    let result = detector.detect_async(data).await?;
    Ok(())
}

批量检测

let data_chunks = vec![
    http_request.as_slice(),
    tls_handshake.as_slice(),
    ssh_banner.as_slice(),
];

let results = detector.detect_batch(&data_chunks)?;
for result in results {
    println!("协议: {}", result.protocol_type());
}

统计信息

use psi_detector::core::detector::DetectionStats;

let mut stats = DetectionStats::new();

// 检测并记录统计
let result = detector.detect(data)?;
stats.record_success(result.protocol_type(), result.detection_time);

// 查看统计
println!("成功率: {:.1}%", stats.success_rate() * 100.0);
println!("最常见协议: {:?}", stats.most_common_protocol());
println!("平均检测时间: {:?}", stats.avg_detection_time);

---

🔧 集成示例

与 Tokio 集成

use tokio::net::TcpListener;
use psi_detector::{DetectorBuilder, ProtocolType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let detector = DetectorBuilder::new()
        .enable_http()
        .enable_tls()
        .high_performance()
        .build()?;
    
    let listener = TcpListener::bind("127.0.0.1:8080").await?;
    
    loop {
        let (mut socket, _) = listener.accept().await?;
        let detector = detector.clone(); // 需要实现Clone
        
        tokio::spawn(async move {
            let mut buf = [0; 1024];
            if let Ok(n) = socket.read(&mut buf).await {
                if let Ok(result) = detector.detect(&buf[..n]) {
                    match result.protocol_type() {
                        ProtocolType::HTTP1_1 => {
                            // 处理HTTP请求
                        }
                        ProtocolType::TLS => {
                            // 处理HTTPS请求
                        }
                        _ => {
                            // 其他协议或拒绝连接
                        }
                    }
                }
            }
        });
    }
}

与 mammoth_transport 集成

use mammoth_transport::{TransportBuilder, ProtocolRouter};
use psi_detector::DetectorBuilder;

let detector = DetectorBuilder::new()
    .enable_http()
    .enable_quic()
    .enable_tls()
    .build()?;

let transport = TransportBuilder::new()
    .with_protocol_detector(detector)
    .with_auto_routing()
    .build()?;

---

🚨 安全最佳实践

1. 最小权限原则

// ❌ 错误：启用所有协议
let detector = DetectorBuilder::new().enable_all().build()?;

// ✅ 正确：只启用需要的协议
let detector = DetectorBuilder::new()
    .enable_http()
    .enable_tls()
    .build()?;

2. 严格配置验证

// PSI-Detector 强制配置验证
let result = DetectorBuilder::new().build(); // 将失败

match result {
    Err(e) => {
        // 会收到详细的配置指导
        println!("配置错误: {}", e);
    }
    Ok(_) => unreachable!(),
}

3. 监控和日志

use psi_detector::utils::logger;

// 启用详细日志
logger::init_logger(log::LevelFilter::Debug);

let result = detector.detect(data)?;
// 自动记录检测过程和结果

4. 错误处理

match detector.detect(suspicious_data) {
    Ok(result) => {
        if result.confidence() < 0.5 {
            // 低置信度，可能是攻击
            log::warn!("检测到可疑流量: {:?}", result);
        }
    }
    Err(e) => {
        // 检测失败，记录并拒绝连接
        log::error!("协议检测失败: {}", e);
        // 静默拒绝连接
    }
}

---

🐛 故障排除

常见问题

Q: 编译错误："至少需要启用一个协议"

// ❌ 问题代码
let detector = DetectorBuilder::new().build()?;

// ✅ 解决方案
let detector = DetectorBuilder::new()
    .enable_http()  // 至少启用一个协议
    .build()?;

Q: 性能不如预期

// ✅ 使用高性能配置
let detector = DetectorBuilder::new()
    .enable_http()
    .high_performance()    // 关键！
    .build()?;

// ✅ 避免启用过多协议
// ❌ 不要: .enable_all()
// ✅ 推荐: 只启用需要的协议

Q: 误检率高

// ✅ 使用高精度模式
let detector = DetectorBuilder::new()
    .enable_http()
    .enable_tls()
    .high_accuracy()       // 提高精度
    .build()?;

Q: 自定义协议无法检测

// ✅ 确保启用自定义协议
let detector = DetectorBuilder::new()
    .enable_custom()       // 必须启用！
    .add_custom_probe(your_probe)
    .build()?;

调试技巧

启用详细日志

// 在main函数开始添加
env_logger::init();
std::env::set_var("RUST_LOG", "psi_detector=debug");

性能分析

use std::time::Instant;

let start = Instant::now();
let result = detector.detect(data)?;
let duration = start.elapsed();

if duration.as_millis() > 10 {
    println!("检测耗时过长: {:?}", duration);
}

---

📚 API 参考

核心类型

DetectorBuilder

构建器模式配置探测器

• enable_*() - 启用特定协议
• with_*() - 设置配置参数
• high_performance() - 性能优化预设
• build() - 构建探测器实例

ProtocolDetector

协议检测核心接口

• detect(&self, data: &[u8]) -> Result<DetectionResult> - 检测协议
• confidence(&self, data: &[u8]) -> Result<f32> - 获取置信度
• supported_protocols(&self) -> Vec<ProtocolType> - 支持的协议

DetectionResult

检测结果

• protocol_type(&self) -> ProtocolType - 协议类型
• confidence(&self) -> f32 - 置信度(0.0-1.0)
• detection_time(&self) -> Duration - 检测耗时
• is_high_confidence(&self) -> bool - 是否高置信度

ProtocolType

支持的协议类型

• HTTP1_1, HTTP2, HTTP3 - HTTP协议族
• TLS, QUIC - 安全协议
• SSH, FTP, SMTP - 传统协议
• WebSocket, GRPC - 现代协议
• Custom - 自定义协议

---

🤝 贡献指南

我们欢迎各种形式的贡献！

报告Bug

1. 使用 GitHub Issues
2. 提供详细的重现步骤
3. 包含系统信息和错误日志

功能请求

1. 先检查是否有类似的Issue
2. 详细描述用例和预期行为
3. 考虑向后兼容性

代码贡献

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

开发环境设置

# 克隆项目
git clone https://github.com/your-org/psi-detector.git
cd psi-detector

# 运行测试
cargo test

# 运行示例
cargo run --example magic_bytes_performance

# 代码格式化
cargo fmt

# 代码检查  
cargo clippy

---

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

---

🙏 致谢

• 感谢 Rust 社区的优秀生态
• 灵感来源于经典游戏《红色警戒2》中的尤里
• 参考了现代网络协议检测的最佳实践

---

📞 联系我们

• 📧 Email: your-email@example.com
• 💬 讨论: GitHub Discussions
• 🐛 问题: GitHub Issues
• 📖 文档: docs.rs

---

让我们一起构建更快、更安全的网络应用！ 🚀

---