How does the Great Firewall of China work: Technical Architecture and Circumvention Code

The Great Firewall of China operates through a multi-layered system of DNS tampering, IP blocking, deep packet inspection, and active probing, which the bannedbook/fanqiang repository circumvents using STUN-based NAT discovery and dynamic routing protocols.

The Great Firewall of China (GFW) represents one of the most sophisticated internet censorship systems globally, employing stateful packet inspection and real-time traffic analysis to control outbound connections. Understanding how the Great Firewall of China works is essential for developers building circumvention tools, such as those found in the open-source bannedbook/fanqiang repository. This article examines the GFW's technical architecture and demonstrates how specific components in the fanqiang codebase counteract these restrictions.

The Four Pillars of GFW Architecture

IP and Port Filtering

The GFW maintains dynamic blacklists of IP ranges and port numbers associated with proxy services and circumvention tools. When traffic matches these entries, the firewall injects TCP RST packets or employs null-routing to drop connections silently. This stateful filtering operates at the network layer, allowing the GFW to block specific endpoints regardless of protocol encryption.

DNS Poisoning and Domain Hijacking

For censored domain names, the GFW intercepts DNS queries and returns forged A or AAAA records pointing to invalid or domestic IP addresses. This occurs at the recursive resolver level, preventing users from resolving blocked domains regardless of their chosen DNS server. The poisoning happens in real-time, making it appear as if the blocked site simply does not exist.

Deep Packet Inspection and Keyword Filtering

Next-generation firewall (NGFW) engines perform payload analysis to detect forbidden strings within TCP streams. Upon detection of sensitive keywords, the system terminates connections immediately through TCP reset injection. This deep packet inspection (DPI) can identify protocols by their handshake signatures, even when the payload itself is encrypted.

Active Probing and Dynamic Blocking

The GFW actively probes suspicious endpoints using SYN/FIN packets and HTTP GET requests to verify service availability. If a probe confirms a circumvention service is reachable, the firewall automatically adds the target to real-time block lists. This creates a dynamic, adaptive filtering system that responds to new proxy deployments within minutes.

How the fanqiang Repository Circumvents GFW Restrictions

NAT Discovery via STUN Protocol

To bypass inbound UDP blocking, the fanqiang repository implements a STUN client in fqnews2/libcore/stun/client.go that discovers the public NAT mapping assigned by the firewall. The STUN (Session Traversal Utilities for NAT) protocol enables clients to determine their externally visible IP address and port, facilitating UDP hole-punching essential for modern proxy protocols like V2Ray and Shadowsocks.

GeoIP and GeoSite Routing Rules

The repository loads MaxMind databases through fqnews2/libcore/geoip.go and domain lists via fqnews2/libcore/geosite.go to route traffic based on geographic rules. This intelligence allows clients to avoid known GFW-blocked IP ranges while selectively proxying only traffic destined for censored destinations, reducing the overall fingerprint exposed to DPI engines.

Transport Layer Abstractions

Wrapper implementations in fqnews2/libcore/http.go and fqnews2/libcore/dns_box.go provide flexible transport options including plain TCP, TLS, WebSocket, and QUIC. These abstractions make traffic signatures less distinct to DPI engines, reducing the probability of detection and blocking by mimicking standard HTTPS traffic patterns.

Code Implementation: NAT Discovery and Routing

The following Go snippets from the fanqiang repository demonstrate practical implementation of NAT discovery and rule-based routing.

First, the STUN client discovers the NAT type and public endpoint:

// Example 1: Simple NAT type discovery
import (
    "fmt"
    "github.com/bannedbook/fanqiang/fqnews2/libcore/stun"
)

func main() {
    // Create a STUN client (uses the default public STUN server)
    c := stun.NewClient()
    // Enable verbose logging to see the exchange with the STUN server
    c.SetVVerbose(true)

    nat, host, err, _ := c.Discover()
    if err != nil {
        fmt.Println("Discovery error:", err)
        return
    }
    fmt.Printf("NAT type: %s, public IP: %s, public port: %d\n",
        nat, host.IP, host.Port)
}

Source: fqnews2/libcore/stun/client.go

Second, the discovered public address integrates with GeoIP-based routing rules:

// Example 2: Using the discovered public address to build a proxy rule
import (
    "github.com/bannedbook/fanqiang/fqnews2/libcore/geoip"
    "github.com/sagernet/sing-box/option"
)

func buildRule(publicIP string) option.PlainRuleSetCompat {
    var rule option.PlainRuleSetCompat
    rule.Version = option.RuleSetVersion1
    rule.Options.Rules = []option.HeadlessRule{
        {
            Type: option.RuleTypeDefault,
            DefaultOptions: option.DefaultHeadlessRule{
                IPCIDR: []string{publicIP + "/32"},
            },
        },
    }
    return rule
}

Source: fqnews2/libcore/geoip.go

Summary

• The Great Firewall of China employs four primary mechanisms: IP/port filtering, DNS poisoning, deep packet inspection with keyword filtering, and active probing to maintain dynamic block lists.
• The bannedbook/fanqiang repository counters these restrictions through STUN-based NAT discovery implemented in fqnews2/libcore/stun/client.go, enabling clients to identify usable network paths.
• GeoIP and GeoSite modules (geoip.go and geosite.go) provide intelligent routing that avoids known blocked ranges while minimizing suspicious traffic patterns.
• Transport abstraction layers in http.go and dns_box.go support protocol obfuscation through TLS, WebSocket, and QUIC to evade signature-based detection.

Frequently Asked Questions

What is the difference between DNS poisoning and IP blocking in the GFW?

DNS poisoning targets the domain resolution layer by returning forged IP addresses for censored domains, while IP blocking operates at the network layer by dropping packets destined for specific address ranges. The fanqiang repository addresses both through its DNS resolver wrapper in dns_box.go and GeoIP-based routing rules that bypass poisoned responses.

How does STUN help circumvent the Great Firewall?

STUN (Session Traversal Utilities for NAT) reveals the public IP and port mapping assigned by the firewall, allowing clients to perform UDP hole-punching and establish direct connections even when the GFW blocks inbound UDP traffic. The stun/client.go module automates this discovery process, which is essential for maintaining connectivity when the firewall dynamically assigns NAT mappings.

Can the GFW detect encrypted traffic like TLS or Shadowsocks?

While the GFW cannot decrypt modern protocols like TLS 1.3 or properly implemented Shadowsocks, it can use traffic analysis and active probing to identify suspicious patterns. The fanqiang repository mitigates this through transport randomization and WebSocket/QUIC layering implemented in http.go, making circumvention traffic resemble standard HTTPS sessions.

What role does active probing play in GFW enforcement?

Active probing allows the GFW to verify whether a suspected proxy server is actually reachable by sending test packets; if the server responds, it confirms the service is operational and adds it to block lists. Circumvention tools must therefore implement anti-probing measures or rapid IP rotation to avoid detection, as the GFW updates its blacklists in real-time based on probe results.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}