SpoofDPI Documentation

SpoofDPI is a simple proxy tool designed to neutralize Deep Packet Inspection (DPI) techniques used by internet censorship systems.

Security Warning: SpoofDPI is NOT available on iOS or Android. Official binaries are ONLY provided through GitHub and official package managers. Avoid downloading from unofficial sources to prevent malware.

spoofdpi provides the following capabilities:

• High Performance: Low latency via the Go runtime and caching mechanisms.
• Built-in DNS Resolver: Includes built-in DNS resolvers, allowing use without modifying system-wide DNS settings.
• Flexible Policies: Supports robust policy rules based on domains (e.g., allow or ignore specific domains).
• Easy Configuration: Configurable via a TOML file.
• Cross-Platform Support: Compatible with macOS, Linux, and FreeBSD.

To get started with minimal configuration, enable DNS over HTTPS (DoH) by setting the dns.mode to "https" and providing an https-url.

[dns]
mode = "https"
https-url = "https://dns.google/dns-query"

For testing multiple scenarios of the same logic, use table-driven tests. This pattern involves defining a slice of structs containing inputs and expected outputs, then iterating over them using t.Run to execute subtests.

func TestCalculation(t *testing.T) {
    tcs := []struct {
        name     string
        input    int
        expected int
    }{
        {
            name:     "positive number",
            input:    5,
            expected: 10,
        },
        {
            name:     "zero",
            input:    0,
            expected: 0,
        },
    }

    for _, tc := range tcs {
        t.Run(tc.name, func(t *testing.T) {
            result := calculate(tc.input)
            assert.Equal(t, tc.expected, result)
        })
    }
}

If default settings fail to bypass DPI, use aggressive settings to disorder the Client Hello and inject multiple fake packets. You can specify fake-count, a fake-packet byte array, enable disorder, and set split-mode to "chunk" with a specific chunk-size.

[https]
fake-count = 5
fake-packet = [0x16, 0x03, 0x01] # Simple fake Client Hello prefix
disorder = true
split-mode = "chunk"
chunk-size = 1

To prevent spoofdpi from processing traffic for local networks, create a rule matching specific cidrs and set https.skip = true.

[[rules]]
name = "local bypass"
match = { cidrs = ["192.168.0.0/16"] }
https = { skip = true }

You can install spoofdpi automatically using the provided shell script. The binary will be installed to /usr/local/bin.

$ curl -fsSL https://raw.githubusercontent.com/xvzc/spoofdpi/main/install.sh | bash

The project uses the standard testing package along with github.com/stretchr/testify for assertions.

• Use testify/assert for general assertions where a failure should record an error but allow the test to continue.
• Use testify/require for critical checks (like error handling or setup) where the test must stop immediately if the condition is not met.

import (
    "testing"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func TestExample(t *testing.T) {
    result, err := SomeFunction()
    
    // Stop immediately if there's an error
    require.NoError(t, err)
    
    // Assert the result, but continue even if it fails
    assert.Equal(t, "expected", result)
}

To unblock a specific site, use a rule that matches its domain and applies custom https configuration settings, such as fake-count and disorder.

[[rules]]
name = "unblock site"
match = { domains = ["blocked-site.com"] }
https = { fake-count = 2, disorder = true }

If you do not specify a path using the --config flag, spoofdpi searches for spoofdpi.toml in the following locations in order. It will apply only the first file it finds:

1. The path specified in the $SPOOFDPI_CONFIG environment variable.
2. /etc/spoofdpi.toml
3. $XDG_CONFIG_HOME/spoofdpi/spoofdpi.toml
4. $HOME/.config/spoofdpi/spoofdpi.toml