lyrebird

Lyrebird - Pluggable Transport Proxy Applications

This crates contains multiple binary exceutables designed specifically to work with and pluggable transport library implementing the ['ptrs'] interface.

⚠️ 🚧 WARNING This crate is still under construction 🚧 ⚠️

• interface subject to change at any time
• Not production ready
  • do not rely on this for any security critical applications

Lyrebird Pluggable Transport Bridge

['lyrebird'] provides an executable program designed to manage the calling interface used by the Tor libraries when launching pluggable transports (see pt-spec.txt).

... [tor_client] <---> [pt_client] <====> [pt_bridge] <---> [tor_orport] ...

Usage info:

Tunnel Tor SOCKS5 traffic through pluggable transport connections

Usage: lyrebird [OPTIONS]

Options:
      --enable-logging         Log to {TOR_PT_STATE_LOCATION}/obfs4proxy.log
      --log-level <LOG_LEVEL>  Log Level (ERROR/WARN/INFO/DEBUG/TRACE) [default: ERROR]
      --unsafe-logging         Disable the address scrubber on logging
  -h, --help                   Print help
  -V, --version                Print version

Installation

To install:

`cargo install lyrebird`

This installs in the configured Rust location (i.e. $HOME/.cargo/bin). You may wish to copy ./lyrebird to a permanent location (e.g. /usr/local/bin).

Client side torrc configuration:

ClientTransportPlugin obfs4 exec /usr/local/bin/lyrebird

Bridge side torrc configuration:

# Act as a bridge relay.
BridgeRelay 1

# Enable the Extended ORPort
ExtORPort auto

# Use lyrebird to provide the obfs4 protocol.
ServerTransportPlugin obfs4 exec /usr/local/bin/lyrebird

# (Optional) Listen on the specified address/port for obfs4 connections as
# opposed to picking a port automatically.
#ServerTransportListenAddr obfs4 0.0.0.0:443

Tips and tricks

• On modern Linux systems it is possible to have lyrebird bind to reserved ports (<=1024) even when not running as root by granting the CAP_NET_BIND_SERVICE capability with setcap:

  # setcap 'cap_net_bind_service=+ep' /usr/local/bin/lyrebird

• The autogenerated obfs4 bridge parameters are placed in DataDir/pt_state/obfs4_state.json. To ease deployment, the client side bridge line is written to DataDir/pt_state/obfs4_bridgeline.txt.

Forward proxy

[client] <---> [fwd\_client] <====> [fwd\_server] <---> [target]

Usage info:

Generalized forward proxy client and server for transparently proxying traffic over PTs.

Usage: fwd [OPTIONS] [LADDR] <COMMAND>

Commands:
  client  Run as client forward proxy, initiating pluggable transport connection
  server  Run as server, terminating the pluggable transport protocol
  help    Print this message or the help of the given subcommand(s)

Arguments:
  [LADDR]  Listen address, defaults to "[::]:9000" for client, "[::]:9001" for server

Options:
  -a, --args <ARGS>            Transport argument string
  -s, --state-dir <DIR>        Path to a directory where launch state is located.
  -l, --log-level <LOG_LEVEL>  Log Level (ERROR/WARN/INFO/DEBUG/TRACE) [default: INFO]
  -x, --unsafe-logging         Disable the address scrubber on logging
  -h, --help                   Print help
  -V, --version                Print version

Examples

fwd -s ./state/ server fwd "127.0.0.1:5201"

fwd -a "cert=AAAAAAAAAAAAAAAAAAAAAAAAAADTSFvsGKxNFPBcGdOCBSgpEtJInG9zCYZezBPVBuBWag;iat-mode=0" -l DEBUG 127.0.0.1:9000 client 127.0.0.1:9001

Potential Features

• geoip for obvious signs of censorship
• tracking resets / injections / replays
• tunnel metrics - throughput / bytes-per-tunnel / etc.
• socks proxy handler in fwd