English | 中文

xw-protocol

A master controller and skills library for designing, reviewing, iterating, and debugging censorship-resistant tunnel protocols.

Overview

xw-protocol is a structured decision-making framework for building anti-censorship proxies and tunnels. It provides:

• Route selection — a decision program that chooses between mimicry routes (become-it / borrow-it / CDN-fronting) and non-mimicry routes based on adversary model and deployment scale
• Layer-by-layer design — specialized skills covering censor modeling, endpoint rendezvous, handshake bytes, probe resistance, traffic shaping, session modeling, transport substrate, crypto core, supply chain operations, and agility rollouts
• 12 iron laws (CONSTITUTION) — enforced rules (C1–C12) that govern every design decision, backed by a corpus of 178 research papers
• Red-team self-test — acceptance testing suite (A/B/C groups) that must pass before any design is considered releasable
• Knowledge base — searchable rule index (kb/rules.yaml) and curated paper abstracts (kb/papers/)

Key Concepts

• Identity-first design — every observable must trace back to a single, real-world entity (C9)
• Necessary exposure — some fingerprints must be present to remain faithful to the identity (C10). Hiding them moves you into a smaller, more detectable bucket.
• Population is bidirectional — identity should be popular (large anonymity set); deployment values should be unique (C11)
• Endpoint rotation > per-flow indistinguishability — aggregate behavior over time is what gets you blocked (C6)

Project Structure

xw-protocol/
├── SKILL.md                   # Master controller (entry point)
├── references/
│   ├── CONSTITUTION.md        # 12 iron laws + exposure ledger
│   ├── conflict-matrix.md     # Hard conflict resolution table
│   ├── route-families.md      # Six route families + selection program
│   ├── design-state-contract.md  # Schema for inter-skill state
│   ├── corpus-map.md          # Paper ID → topic mapping (auto-generated)
│   └── ...
├── kb/
│   ├── rules.yaml             # Machine-readable rule index
│   └── papers/                # Curated paper abstracts
├── scripts/
│   ├── check_library.py       # CI gating (link check, ID validation, lint)
│   ├── kb_query.py            # Knowledge base search tool
│   ├── design_state_init.py   # Initialize per-case design-state.yaml
│   ├── design_state_validate.py  # Validate design-state structure
│   ├── refresh_tool_index.py  # Generate local tool availability index
│   └── paper_watch.py         # Paper corpus freshness & retrieval
├── censor-model/              # Adversary modeling (country/AS/time window)
├── endpoint-rendezvous/       # Endpoint rotation economics & identity
├── handshake-bytes/           # TLS 1.3 / QUIC / DTLS fingerprints
├── probe-resistance/          # Differential probing defenses
├── traffic-shape/             # Traffic shaping specs & overhead
├── session-model/             # Connection patterns & browser profiles
├── transport-substrate/       # Underlying transport layer
├── crypto-core/               # Cryptographic primitives
├── supply-chain-ops/          # Distribution, panel hardening, disclosure
├── agility-rollout/           # Freshness CI, evasion lifecycle
└── redteam-selftest/          # Acceptance testing harness

Getting Started

Prerequisites

• Python 3.8+
• PyYAML (pip install pyyaml)

Usage

This library is designed to be used with an LLM-based agent. Load SKILL.md as the entry point and follow the routing contract:

1. Stage determination — route selection, design, review, troubleshooting, or iteration
2. Adversary modeling — always start with censor-model/
3. Route selection — run the decision program to choose between mimic/generate
4. Layer sequence — pull each specialized skill in order
5. Red-team self-test — final acceptance before release

Scripts

# CI gate — check links, paper IDs, number lint, frontmatter
python3 scripts/check_library.py

# Knowledge base search
python3 scripts/kb_query.py rule K2
python3 scripts/kb_query.py paper 2024-012
python3 scripts/kb_query.py search "复用"

# Initialize a design case
python3 scripts/design_state_init.py work/my-case

# Validate design-state
python3 scripts/design_state_validate.py work/my-case/design-state.yaml

# Paper corpus freshness check
python3 scripts/paper_watch.py staleness

Paper Corpus

The skills library references a corpus of 178 research papers (2024–2026) covering censorship measurement, TLS fingerprinting, traffic analysis, website fingerprinting, and circumvention techniques. Set XW_DOCS_DIR environment variable or place a docs/ directory as a sibling to this repository containing papers.json and paper abstracts.