yuzeguitarist/ParallaX

# ParallaX ParallaX 是一个单二进制抗审查代理。当前的产品路线刻意保持精简：本地 SOCKS5 入口，TCP/TLS 伪装传输，ClientHello 嵌入式身份验证，针对未认证流量的回退透传，以及使用 ML-KEM-1024 重新加密的 AEAD 数据平面。 ``` Application ──SOCKS5──► plx client ──TLS 1.3 / Safari-like ClientHello──► plx serve ──► target │ └─ unauthenticated or malformed traffic ──► fallback origin ``` 代码库还包含了源码级别的 GFW 模拟器和审查研究笔记。这些是验证和研究资产，而不是第二个生产级传输协议。 没有 `--quic` CLI 标志，但一个 **实验性** 的 UDP/QUIC 快速平面（TUDP 中的 "U"）*确实* 已经接入到客户端和服务器运行时中：在**两端**设置 `[udp].enabled = true` 即可为单一 Connect 数据中继激活一个伪装的 h3 QUIC 载体，通过一个与 exporter 绑定的探测 token 进行验证（QUIC 部分将其服务器证书视为伪装，而不是信任锚）。它**默认关闭**；禁用时，所有路径在 TCP 上保持字节一致。启用时，其 QUIC 客户端默认就已经会发出一个 Safari-26 H3 形状的 ClientHello，但该快速平面尚未成为可用于生产环境的操作模式，因此启用它是为了进行实验，而不是用于抗审查的生产用途。 ## ParallaX 的优化目标 1. **浏览器形状的服务器入口。** 客户端驱动 ParallaX 单一 Safari 26 TLS 1.3 状态机，并且仅修补身份验证所需的熵字段。可见的握手是围绕 `src/tls/safari26.rs` 中实现的 Safari 26 / macOS Tahoe 配置文件进行的。 2. **探测安全的失败行为。** 如果第一个记录格式错误、未通过身份验证、未获得 SNI 授权，或者只是不完整的探测前缀，服务器会将流量转发到配置好的回退 TLS 源站，而不是暴露出代理形状的拒绝响应。 3. **混合后量子重新加密。** 在伪装 TLS 握手之后，ParallaX 数据平面执行一个绑定的 ML-KEM-1024 + X25519 + PSK “三明治”式重加密，并验证 ML-DSA-87 服务器身份证明。 4. **操作简单。** `plx init`、`plx probe`、`plx check`、`plx speed` 和 `scripts/deploy-vps.sh` 旨在保持部署的可重复性，而无需将源代码复制到 VPS 上。 5. **证据驱动的验证。** CI 和本地验证使用 Rust 测试套件、被忽略的本地回环中继测试、固定参数基准测试，以及 `tests/gfw_simulator.rs` 下的 GFW 模拟器场景。 ## 功能图 | 领域 | 当前行为 | 主要代码 | |---|---|---| | CLI 和配置 | `check`、`keygen`、`crypto-self-test`、`serve`、`client`、`speed`、`netmatrix`、`bench`、`config-template`、`probe`、`init`；带有密钥权限检查的 TOML 配置。 | `src/cli.rs`, `src/config.rs` | | 客户端运行时 | 仅限本地回环的 SOCKS5 监听器、经过身份验证的服务器连接、PQ 重加密、ML-DSA 身份验证、双向中继。 | `src/client/runtime.rs`, `src/client/socks.rs` | | 服务器运行时 | 首记录分类、授权 SNI 检查、回退透传、经过身份验证的数据中继、固定的 `server.data_target` 支持。 | `src/handshake/server.rs` | | TLS 伪装 | 手写的 Safari 26 TLS 1.3 客户端状态机，包含 Safari 的密码套件/加密组/扩展顺序、GREASE、ALPN、ClientHello 身份验证字段、证书验证和 HTTP/2 preface 支持。 | `src/tls/safari26.rs`, `src/tls/client_hello.rs`, `src/fingerprint/http2.rs` | | 握手身份验证 | 将 PSK + X25519 材料嵌入到 `ClientHello.random` 和兼容性 `SessionID` 中；重放缓存用于控制已认证的握手。 | `src/crypto/auth.rs`, `src/crypto/replay.rs` | | PQ 和身份验证 | ML-KEM-1024 重加密、绑定握手记录的服务器密钥交换、基于重加密绑定的 ML-DSA-87 身份证明。 | `src/crypto/pq.rs`, `src/crypto/identity.rs`, `src/protocol/command.rs` | | 数据平面 | AEAD 记录（服务器协商的 AES-256-GCM 或 ChaCha20-Poly1305；96 位单记录计数器 nonce）承载在 TLS `ApplicationData` 帧内，单向 nonce 防回滚机制，可选的填充/时序/掩护流量；批量任务通过共享的多核加密池进行加解密。 | `src/crypto/session.rs`, `src/protocol/data.rs`, `src/crypto/parallel.rs`, `src/traffic.rs` | | TCP 传输 | 默认的 TCP 生产级传输，具有 `TCP_NODELAY`、跨平台的 TCP keepalive (SO_KEEPALIVE)、基于 fd 限制的中继并发，以及 64 KiB 中继缓冲区。 | `src/transport/tcp.rs` | | 进程加固 | 尽力而为的无核心转储设置、不可转储进程标志、`mlock`、`MADV_DONTDUMP`，以及严格的配置文件所有权/权限检查。 | `src/process_hardening.rs`, `src/config.rs` | | 操作运维 | 本地构建、仅向 VPS 上传二进制文件、强化的 systemd unit、可选的 BBR/fq 设置、可选的 Polar Signals / parca-agent 性能分析。 | `scripts/deploy-vps.sh`, `scripts/uninstall-vps.sh` | | 验证 | 单元/集成测试、Safari 一致性测试夹具、被忽略的本地回环测试、GFW 模拟器、固定的 59 例基准测试套件、速度证据报告。 | `tests/`, `src/bench.rs`, `src/speed.rs` | ## 构建 要求： - 最近的稳定版 Rust 工具链（锁定的 `Cargo.lock` 需要 Cargo ≥ 1.85；`Cargo.toml` 中的 `rust-version = 1.80` 只是名义版本） - `cargo` - 无需 `openssl-sys` 或系统 OpenSSL 依赖 ``` cargo build --release ``` 该 crate 构建了两个入口点： - `parallax` — 标准的包二进制文件 - `plx` — 文档中使用的简短操作别名 从仓库根目录安装两者： ``` cargo install --path . ``` ## 快速开始 ### 1. 探测回退源站 ``` plx probe cloudflare.com ``` `probe` 接受 `domain`、`domain:port` 或 `https://domain`。它会检查 TCP 连通性、TLS 握手行为、TLS 1.3、ALPN、握手后记录，并打印评分，以便您决定该源站是否是一个好的伪装回退。 ### 2. 生成成对配置 ``` plx init cloudflare.com --server-addr YOUR_VPS_IP:443 ``` 这将写入： - `parallax.server.toml` - `parallax.client.toml` 在 Unix 上，这两个文件都以 `0600` 权限模式创建。`init` 会拒绝覆盖现有的配置文件。生成的材料包括： - 32 字节的 PSK - X25519 服务器密钥对 - ML-DSA-87 服务器身份密钥对 ### 3. 部署服务器 向导模式： ``` bash scripts/deploy-vps.sh ``` 显式模式： ``` bash scripts/deploy-vps.sh root@YOUR_VPS_IP cloudflare.com ``` 部署脚本会在本地构建一个 Linux `plx` 二进制文件，将文件暂存在 `target/parallax-deploy//` 下，仅上传二进制文件/服务器配置/systemd unit，安装服务，可选择启用 BBR + `fq`，并可选择通过 `parca-agent` 接入 Polar Signals Cloud 性能分析。 ### 4. 运行客户端 ``` plx client -c target/parallax-deploy//parallax.client.toml curl --socks5-hostname 127.0.0.1:1080 https://ifconfig.me ``` 如果您是手动生成的配置，请使用您本地 `parallax.client.toml` 的路径代替。 ## CLI 参考 ``` plx check [-c parallax.toml] Validate config syntax, required sections, key lengths, traffic bounds, loopback-only client listen addresses, server SNI allowlist, and Unix secret-file permissions. plx keygen Print a fresh X25519 key pair. plx crypto-self-test Derive ephemeral AEAD keys, seal and open a local test payload. plx serve [-c parallax.toml] Run the server handshake/fallback listener. plx client [-c parallax.toml] Run the local SOCKS5 client. plx speed [-c parallax.toml] [--json] Run a one-shot network speed evidence test against the configured server. plx netmatrix [-c parallax.toml] [--json] Run a reproducible controlled-network RTT/bandwidth speed matrix against the configured server via an emulated loopback shaper. plx bench [--quick] [--json] Run the fixed-parameter CPU benchmark suite. plx config-template [--server-listen ...] [--client-listen ...] [--server-addr ...] [--fallback-addr ...] [--sni ...] Print paired server/client TOML templates to stdout. plx probe [DEST] [-c parallax.toml] Probe an explicit fallback destination, or infer one from config. plx init [--server-addr ...] [--server-listen ...] [--client-listen ...] [-o DIR] Generate paired config files with fresh key material. ``` 每个命令都支持 `--help`。 ## 配置结构 生成的最小服务器配置结构： ``` mode = "server" [crypto] psk = "base64..." [traffic] min_padding = 0 max_padding = 0 min_delay_ms = 0 max_delay_ms = 0 cover_min_interval_ms = 0 cover_max_interval_ms = 0 max_concurrent_streams = 4 [server] listen = "0.0.0.0:443" fallback_addr = "cloudflare.com:443" private_key = "base64-x25519-secret" identity_secret_key = "base64-mldsa87-secret" replay_cache_path = "/var/lib/parallax/parallax-replay.cache" authorized_sni = ["cloudflare.com"] strict_tls13 = true ``` 生成的最小客户端配置结构： ``` mode = "client" [crypto] psk = "same-base64-psk" [traffic] min_padding = 0 max_padding = 0 min_delay_ms = 0 max_delay_ms = 0 cover_min_interval_ms = 0 cover_max_interval_ms = 0 max_concurrent_streams = 4 [client] listen = "127.0.0.1:1080" server_addr = "YOUR_VPS_IP:443" sni = "cloudflare.com" server_public_key = "base64-x25519-public" server_identity_public_key = "base64-mldsa87-public" ``` 请参阅 [`ParallaX-DeepWiki/Configuration-Reference.md`](./ParallaX-DeepWiki/Configuration-Reference.md) 获取完整的配置参考。 ## 验证 在更改代码或文档后使用这些检查： ``` cargo fmt --all -- --check cargo clippy --all-targets --locked -- -D warnings cargo test --locked --no-fail-fast ``` 被忽略的本地回环中继测试会打开本地 TCP socket。请分开并串行运行它们： ``` cargo test --locked -- --ignored --test-threads=1 ``` 直接运行 GFW 模拟器： ``` cargo test --test gfw_simulator ``` ## 基准测试和速度证据 本地 CPU 基准测试： ``` plx bench plx bench --quick plx bench --json ``` 基准测试套件采用了特意固定的参数。当前的 `main` 分支在六个组中运行 59 个用例：`handshake.crypto`、`handshake.protocol`、`record.aead`、`record.pipeline`、`traffic` 和 `state`。 网络速度证据测试： ``` plx speed -c parallax.client.toml plx speed -c parallax.client.toml --json ``` `plx speed` 不是本地 CPU 基准测试。它会连接到配置的服务器，运行固定的预热以及三个上传/下载采样，并输出一份包含配置指纹、服务器地址、SNI、流量配置、payload 大小、握手时序、预热时序、每次采样吞吐量和汇总统计信息的结构化报告。 `plx client` 和 `plx speed` 使用了运行时保护机制，以防普通客户端进程和速度测试进程意外地针对同一个已配置的服务器产生竞争。 ## 文档导航 维护中的技术知识库位于 [`ParallaX-DeepWiki/`](./ParallaX-DeepWiki/)。它被组织成一个图谱： 操作文档、架构文档、密码学文档、伪装文档、 验证文档，以及一个将页面映射回源文件的元数据/搜索层。 从以下开始： - [知识库索引](./ParallaX-DeepWiki/README.md) - [文档元数据和搜索图](./ParallaX-DeepWiki/Documentation-Metadata-Search-Graph.md) - [ParallaX 概述](./ParallaX-DeepWiki/ParallaX-Overview.md) - [入门与 CLI 参考](./ParallaX-DeepWiki/Getting-Started-&-CLI-Reference.md) - [核心架构](./ParallaX-DeepWiki/Core-Architecture.md) - [部署](./ParallaX-DeepWiki/Deployment.md) - [词汇表](./ParallaX-DeepWiki/Glossary.md) 常用搜索： | 搜索意图 | 查询词 | 从这里开始 | |---|---|---| | 源文件到文档所有者 | `source-to-document ownership`, `doc-id`, 类似 `src/handshake/server.rs` 的路径 | [文档元数据和搜索图](./ParallaX-DeepWiki/Documentation-Metadata-Search-Graph.md) | | 操作员部署上线 | `plx init`, `plx probe`, `deploy-vps`, `systemd`, `BBR` | [入门与 CLI 参考](./ParallaX-DeepWiki/Getting-Started-&-CLI-Reference.md), [部署](./ParallaX-DeepWiki/Deployment.md) | | 当前产品边界 | `product path`, `TCP/TLS`, `experimental [udp].enabled QUIC`, `off by default` | [ParallaX 概述](./ParallaX-DeepWiki/ParallaX-Overview.md), [传输层](./ParallaX-DeepWiki/Transport-Layer.md) | | 验证证据 | `plx speed`, `plx bench`, `gfw_simulator`, `runtime guard` | [探测与基准测试](<./ParallaX-DeepWiki/Probing-&-Benchmarking.md>) | 源码级别的审查研究模型位于 `tests/gfw_sim/` 中，并通过 [GFW 模拟器和 QUIC 研究](<./ParallaX-DeepWiki/GFW-Simulator-&-QUIC-Research.md>) 进行了记录。 ## 仓库布局 ``` src/ cli.rs CLI commands and generated config templates config.rs TOML schema, validation, permission checks client/ SOCKS5 parser and client relay runtime handshake/ Client/server handshake and data-session state crypto/ X25519, AEAD, parallel crypto pool, ML-KEM, ML-DSA, replay cache tls/ Safari-shaped TLS camouflage and TLS records fingerprint/ HTTP/2 Safari preface and header helpers protocol/ Binary commands and encrypted data records transport/ TCP transport helpers traffic.rs Padding, timing, and cover-traffic profiles probe.rs Camouflage target probing speed.rs Network speed evidence report bench.rs Fixed benchmark suite scripts/ deploy-vps.sh Local-build, binary-only VPS deployment uninstall-vps.sh Guided and explicit VPS cleanup tests/ gfw_simulator.rs Source-level adversary scenarios gfw_sim/ Simulator detectors, fixtures, verdicts fixtures/ Safari/TLS/HTTP2 baseline captures ParallaX-DeepWiki/ Interlinked English technical knowledge base ``` ## 许可证 [PolyForm Noncommercial License 1.0.0](LICENSE)。仅限非商业使用 — 可自由阅读、学习、运行、复刻、修改和贡献；**不允许任何形式的商业用途**。复刻和修改后的版本必须保持在此相同的许可证下，并且必须声明它们是基于 ParallaX 的。请参阅 `LICENSE` 了解完整条款，以及 `NOTICE` 了解归属和非商业条件。

标签：Rust, SOCKS5, TLS 1.3, 可视化界面, 安全合规, 抗审查, 流量伪装, 网络代理, 网络流量审计, 通知系统