Support webtunnel, obfs and snowflake bridges (#170)

Co-authored-by: Franck Nijhof <frenck@frenck.nl> Co-authored-by: Renat Gabdulhakov <akrigator@gmail.com> Co-authored-by: akrigator <akrigator@users.noreply.github.com>
2025-05-03 18:41:32 +00:00 · 2025-02-20 12:58:21 +03:00 · 2025-02-20 12:58:21 +03:00 · 2736d0ec53
commit 2736d0ec53
parent ee43c77a92
6 changed files with 158 additions and 3 deletions
--- a/.github/renovate.json
+++ b/.github/renovate.json
@ -24,6 +24,31 @@
      "versioningTemplate": "loose",
      "datasourceTemplate": "repology",
      "depNameTemplate": "alpine_3_21/{{package}}"
+    },
+    {
+      "fileMatch": ["/Dockerfile$"],
+      "matchStrings": ["ARG OBFS_VERSION=[\"']?(?<currentValue>.+?)[\"']?\\s+"],
+      "versioningTemplate": "loose",
+      "datasourceTemplate": "github-releases",
+      "depNameTemplate": "Yawning/obfs4"
+    },
+    {
+      "fileMatch": ["/Dockerfile$"],
+      "matchStrings": [
+        "ARG SNOWFLAKE_VERSION=[\"']?(?<currentValue>.+?)[\"']?\\s+"
+      ],
+      "versioningTemplate": "loose",
+      "datasourceTemplate": "github-releases",
+      "depNameTemplate": "tpo/anti-censorship/pluggable-transports/snowflake"
+    },
+    {
+      "fileMatch": ["/Dockerfile$"],
+      "matchStrings": [
+        "ARG WEBTUNNEL_VERSION=[\"']?(?<currentValue>.+?)[\"']?\\s+"
+      ],
+      "versioningTemplate": "loose",
+      "datasourceTemplate": "github-releases",
+      "depNameTemplate": "tpo/anti-censorship/pluggable-transports/webtunnel"
    }
  ],
  "packageRules": [
--- a/tor/DOCS.md
+++ b/tor/DOCS.md
@ -44,6 +44,7 @@ Example add-on configuration:
 ```yaml
 log_level: info
 socks: true
+http_tunnel: false
 hidden_services: true
 stealth: true
 client_names:
@ -51,6 +52,7 @@ client_names:
  - haremote2
 ports:
  - 8123
+bridges: []
 ```

 **Note**: _This is just an example, don't copy and past it! Create your own!_
@ -85,6 +87,12 @@ applications on your network to use the Tor network.
 so exposing it in this way could leak your information to anybody watching your
 network, and allow anybody to use your computer as an open proxy._

+### Option: `http_tunnel`
+
+Setting this option to `true` opens port `9080` to listen for connections from
+HTTP-speaking applications. Enabling this feature allows you to use other
+applications on your network to access the Tor network via the HTTP proxy.
+
 ### Option: `hidden_services`

 The `hidden_services` options allows you to enable
@ -150,6 +158,62 @@ The accepted syntaxs of this configuration is:
 If you do not define a published port, the local port will be used.
 If you do not define a hostname or IP adress `homeassistant` will be used.

+### Option: `bridges`
+
+> Ensure the option value is clear to avoid unintended use of transport plugins and bridges.
+
+Bridges are Tor relays that help you circumvent censorship.
+Access to bridges is provided by supported transport plugins:
+
+#### OBFS
+
+Because bridge addresses are not public, you will need to request them yourself. You have a few options:
+
+- Visit [Tor][tor-bridges-obfs4] project and follow the instructions, or
+- Email `bridges@torproject.org` from a Gmail, or Riseup email address
+- Send a message to @GetBridgesBot on Telegram. Tap on 'Start' or write /start or /bridges in the chat.
+
+For example:
+
+```yaml
+bridges:
+  - >-
+    obfs4 123.45.67.89:443 EFC6A00EE6272355C023862378AC77F935F091E4
+    cert=KkdWiWlfetJG9SFrzX8g1teBbgxtsc0zPiN5VLxqNNH+iudVW48CoH/XVXPQntbivXIqZA
+    iat-mode=0
+```
+
+#### Webtunnel
+
+Visit [Tor][tor-bridges-webtunnel] project and follow the instructions
+
+For example:
+
+```yaml
+bridges:
+  - >-
+    webtunnel 192.0.2.3:1
+    DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF
+    url=https://akbwadp9lc5fyyz0cj4d76z643pxgbfh6oyc-167-71-71-157.sslip.io/5m9yq0j4ghkz0fz7qmuw58cvbjon0ebnrsp0
+    ver=0.0.1
+```
+
+#### Snowflake
+
+What is [snowflake][what-is-snowflake], example:
+
+```yaml
+bridges:
+  - >-
+    snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72
+    fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72
+    url=https://snowflake-broker.torproject.net/
+    ampcache=https://cdn.ampproject.org/
+    front=www.google.com
+    ice=stun:stun.l.google.com:19302,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478
+    utls-imitate=hellorandomizedalpn
+```
+
 ## Tor client access setup

 Using this add-on, you can access your Home Assistant instance over Tor from
@ -261,3 +325,6 @@ SOFTWARE.
 [releases]: https://github.com/hassio-addons/addon-tor/releases
 [semver]: http://semver.org/spec/v2.0.0.htm
 [tor-hidden-service]: https://www.torproject.org/docs/hidden-services.html.en
+[tor-bridges-obfs4]: https://bridges.torproject.org/bridges/?transport=obfs4
+[tor-bridges-webtunnel]: https://bridges.torproject.org/bridges/?transport=webtunnel
+[what-is-snowflake]: https://support.torproject.org/censorship/what-is-snowflake/
--- a/tor/Dockerfile
+++ b/tor/Dockerfile
@ -8,15 +8,32 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 # Copy root filesystem
 COPY rootfs /

+ARG OBFS_VERSION=obfs4proxy-0.0.14
+ARG SNOWFLAKE_VERSION=v2.10.1
+ARG WEBTUNNEL_VERSION=v0.0.2
+
 # Setup base
 RUN \
    apk add --no-cache \
        coreutils=9.5-r2 \
-        openssl=3.3.3-r0 \
-        tor=0.4.8.14-r1
+        tor=0.4.8.14-r1 \
+    && apk add --no-cache --virtual .build-dependencies \
+        go=1.23.6-r0 \
+        git=2.47.2-r0 \
+    && git clone -b "${OBFS_VERSION}" --single-branch --depth 1 \
+        https://github.com/Yawning/obfs4.git /tmp/obfs4 \
+    && go build -C /tmp/obfs4 -ldflags '-extldflags "-static" -s -w' -o /usr/local/bin/obfs4proxy ./obfs4proxy \
+    && git clone -b "${SNOWFLAKE_VERSION}" --single-branch --depth 1 \
+        https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git /tmp/snowflake \
+    && go build -C /tmp/snowflake/client -ldflags '-extldflags "-static" -s -w' -o /usr/local/bin/snowflake \
+    && git clone -b "${WEBTUNNEL_VERSION}" --single-branch --depth 1 \
+        https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/webtunnel.git /tmp/webtunnel \
+    && go build -C /tmp/webtunnel/main/client -ldflags='-extldflags "-static" -s -w' -o /usr/local/bin/webtunnel \
+    && apk del --no-cache --purge .build-dependencies \
+    && rm -rf /tmp/*

 HEALTHCHECK \
-    --start-period=5m \
+    --start-period=15m \
    --interval=60s \
    --timeout=30s \
    CMD curl \
--- a/tor/config.yaml
+++ b/tor/config.yaml
@ -13,24 +13,31 @@ arch:
 init: false
 ports:
  9050/tcp: 9050
+  9080/tcp: 9080
 ports_description:
  9050/tcp: Tor SOCKS proxy port
+  9080/tcp: Tor HTTP proxy port
 map:
  - ssl:rw
 options:
  socks: false
+  http_tunnel: false
  hidden_services: true
  stealth: false
  client_names: []
  ports:
    - "8123"
    - "8123:80"
+  bridges: []
 schema:
  log_level: list(trace|debug|info|notice|warning|error|fatal)?
  socks: bool
+  http_tunnel: bool
  hidden_services: bool
  stealth: bool
  client_names:
    - match(^[A-Za-z0-9+-_]{1,16}$)
  ports:
    - match(^(.*:)?(?:[0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])?$)
+  bridges:
+    - str
--- a/tor/rootfs/etc/s6-overlay/s6-rc.d/init-tor/run
+++ b/tor/rootfs/etc/s6-overlay/s6-rc.d/init-tor/run
@ -89,6 +89,11 @@ else
    echo 'SOCKSPort 127.0.0.1:9050' >> "${torrc}"
 fi

+# Configure Http tunnel port
+if bashio::config.true 'http_tunnel'; then
+    echo 'HTTPTunnelPort 0.0.0.0:9080' >> "${torrc}"
+fi
+
 # Configure hidden services
 if bashio::config.true 'hidden_services'; then
    echo "HiddenServiceDir ${hidden_service_dir}" >> "${torrc}"
@ -125,6 +130,29 @@ if bashio::config.true 'hidden_services'; then
    done
 fi

+# Configure bridges
+if bashio::config.exists 'bridges' \
+    && ! bashio::config.is_empty 'bridges';
+then
+    bashio::log.info 'Use bridges:'
+    echo "UseBridges 1" >> "${torrc}"
+
+    # Add client for OBFS transport
+    echo "ClientTransportPlugin obfs2,obfs3,obfs4,scramblesuit exec /usr/local/bin/obfs4proxy managed" >> "${torrc}"
+    
+    # Add client for Snowflake transport
+    echo "ClientTransportPlugin snowflake exec /usr/local/bin/snowflake" >> "${torrc}"
+
+    # Add client for WebTunnel transport
+    echo "ClientTransportPlugin webtunnel exec /usr/local/bin/webtunnel" >> "${torrc}"
+    
+    # Add bridges
+    while read -r bridge; do
+        bashio::log.info "Bridge ${bridge}"
+        echo "Bridge ${bridge}" >> "${torrc}"
+    done <<< "$(bashio::config 'bridges')"
+fi
+
 # Figure out the address
 if bashio::config.true 'hidden_services'; then
    bashio::log.info 'Starting Tor temporarly...'
--- a/tor/translations/en.yaml
+++ b/tor/translations/en.yaml
@ -30,5 +30,16 @@ configuration:
    description: >-
      Configures hosts and ports to publish via a Tor Hidden Service. Check
      the add-on documentation for the exact format to enter here.
+  bridges:
+    name: Bridges
+    description: >-
+      Configures bridges to establish a connection with the Tor network. Check the
+      add-on documentation for the exact format to enter here.
+  http_tunnel:
+    name: HTTP proxy
+    description: >-
+      Open this port to listen for proxy connections using the HTTP protocol
+      instead of SOCKS.
 network:
  9050/tcp: Tor SOCKS proxy port
+  9080/tcp: Tor HTTP proxy port