README % Klzgrad <kizdiv@gmail.com> Synopsis ======== West-chamber is a research project for the detection and circumvention against hostile intrusion detection and disruption, especially the Great Firewall of China. West-chamber provides kernel modules that modify the behaviors of the user's TCP/IP stack so that hostile intrusion detection can be bypassed without specialized userspace tools and daemons. West-chamber also provides kernel modules that matches patterns of specific packets sent by hostile IDS/IPS for ease of research, or does low-level protocol obfuscation. West-chamber is built upon the development framework of xtables-addons[^1] by Jan Engelhardt. The version of xtables-addons built upon is 1.37. [^1]: http://xtables-addons.sf.net The name of west-chamber comes from the ancient Chinese story "Romance of the West Chamber" about lovers barricaded by walls. Features ======== * TCP connection obfuscation: the ZHANG and CUI target extensions inject carefully crafted packets in a TCP connection so that NIDS fails to do further detection on upper layer. * IDS packets fingerprint matching: the gfw match extension detects packets sent by NIDS to interrupt connection or poison DNS query with pre-recorded fingerprints. * UDP encapsulation & decapsulation: the UDPENCAP target extension does unconditional UDP encapsulation and decapsulation above the internet layer. With this feature, users can set up static tunnels that work with packets that looks like UDP packets for NIDS. Previous work ============= T. Ptacek, et al. proposed methodology of elusion of network intrusion detection in their 1998 paper.[^2] By inserting special packets in a TCP connection that are ignored by the other endpoint of the connection, the NIDS doing detection in the middle will wrongly analyze protocol and tear down connection prematurely. We adopted this idea and built the ZHANG/CUI TCP connection obfuscation modules based on a weakness of the Great Firewall that can be exploited in the most RFC conformant way. [^2]: T. Ptacek, T.N. Newsham. Insertion, Evasion, and Denial of Service: Eluding Network Intrusion Detection. 1998. Implementation design ===================== We surveyed[^3] several possible designs of implementation: * Userspace daemon based on libpcap. This is actually the proof of concept implementation at the first. However, libpcap uses PF_PACKET sockets which argubly introduces performance impact by copying data from kernel to user and works on link layer which is probably too low. ntop improves packet capture performance with PF_RING zero-copy socket, which is not widely avaiable. * Userspace daemon based on netfilter queue and log. libnetfilter_queue and libnetfilter_log bring packets from IP stack of the OS to userspace. This is the appropriate layer but we still don't like the copying data forth and back with file descriptor. * Kprobes. Kprobes dynamically implants breakpoints in kernel to executes ad-hoc code. This can be used to directly modify the behavior of the TCP stack, but it's very intrusive, error-prone and probably unstable. It's also not configurable from userspace. * Netfilter modules. Netfilter has several hooks across system IP stack that can be used for modifying TCP behavior at IP layer, which is close enough. The iptables tool also provides high configurability for netfilter in the userspace. Thanks to the excellent work by Jan Engelhardt, it's even easier to build these modules based on the highly friendly netfilter module development framework -- xtables-addons. [^3]: [Tools for research and diagnosis of the GFW](http://gfwrev.blogspot.com/2009/11/gfw_10.html) (Chinese). There are also some considerations with the UDPENCAP target. It's possible to encapsulate packets in UDP for IPsec ESP and L2TPv3 (UDP_ENCAP_ESPINUDP, UDP_ENCAP_L2TPINUDP). However, the kernel's implementation is limited. The IPsec ESP in UDP requires a syscall on specific socket and is not available for IPv6, and the L2TPv3 creates sockets and binds them to ports in kernel space itself, so that user can't bind the used ports in user space, which is undesired for the purpose of obfuscation. Limitations =========== The TCP connection obfuscation works on TCP protocol, so it does not have any effect on IP blocking. The ZHANG/CUI module assume that the GFW does stateful TCP detection and connection endpoints are RFC conformant, which is somehow not always the case. To prevent misbehavior when the assumptions are not met, ipset can be used to limit the working range of these modules. These modules are built on volatile characteristics and fingerprints of the GFW so they are also inherently volatile and subject to changes. When it changes, more experiments have to be done. Netfilter modules are linux-specific and run in kernel. This could bring in some difficulty in development and porting. Distributions ============= * Debian (wheezy/sid): west-chamber-source * Gentoo Portage Overlay: net-firewall/west-chamber * RPM Fusion: west-chamber, west-chamber-kmod Known bugs ========== * The algorthims in ZHANG/CUI modules and fingerprints in gfw module need constant update or they will likely do not work. * The Windows port version is less stable and needs more testing. See also ======== * [Report bugs](http://code.google.com/p/scholarzhang/issues). * [Our project on Google Code](http://code.google.com/p/scholarzhang). * [Mailing list](http://groups.google.com/group/scholarzhang-dev). * [Our previous research articles (Chinese)](http://gfwrev.blogspot.com/). * [liujinyuan](https://github.com/tewilove/liujinyuan): a fork and port of west-chamber on Android, by tewilove. * [west-chamber-season-2](http://code.google.com/p/west-chamber-season-2/): * [west-chamber-season-3](http://code.google.com/p/west-chamber-season-3/): further work on west-chamber, by liruqi.
from https://github.com/enthus/scholarzhang0/tree/master/trunk/west-chamber
