Secure Socket Funneling

Secure Socket Funneling (SSF) is a network tool and toolkit.

It provides simple and efficient ways to forward data from multiple sockets (TCP or UDP) through a single secure TLS tunnel to a remote computer.

SSF is cross platform (Windows, Linux, OSX) and comes as standalone executables.

Features:

• Local and remote TCP port forwarding
• Local and remote UDP port forwarding
• Local and remote SOCKS server
• Local and remote shell through sockets
• File copy
• Native relay protocol
• TLS connection with the strongest cipher-suites

Download prebuilt binaries

Documentation

Build on Windows

Build on Unix/Linux

Cross compiling SSF (e.g. Raspberry Pi)

How to use

Command line

Client

Usage: ssf[.exe] [options] server_address

Options:

• -v verbose_level: Verbosity: critical|error|warning|info|debug|trace (default: info)

• -q: Quiet mode. Do not print logs

• -p port: Remote port (default: 8011)

• -c config_file_path: Specify configuration file. If not set, 'config.json' is loaded from the current working directory

• -m attempts: Max unsuccessful connection attempts before stopping (default: 1)

• -t delay: Time to wait before attempting to reconnect in seconds (default: 60)

• -n: Do not try to reconnect client if connection is interrupted

• -g: Allow gateway ports. Allow client to bind local sockets for a service to a specific address rather than "localhost"

• -S: Display microservices status (on/off)

Services options:

• -D [[bind_address]:]port: Run a SOCKS proxy on the server accessible on [[bind_address]:]port on the local side

• -F [[bind_address]:]port: Run a SOCKS proxy on the local host accessible from the server on [[bind_address]:]port

• -X [[bind_address]:]port: Forward server shell I/O to the specified port on the local side. Each connection creates a new shell process

• -Y [[bind_address]:]port: Forward local shell I/O to the specified port on the server

• -L [[bind_address]:]port:host:hostport: Forward TCP connections to [[bind_address]:]port on the local host to host:hostport on the server

• -R [[bind_address]:]port:host:hostport: Forward TCP connections to [[bind_address]:]port on the server to host:hostport on the local side

• -U [[bind_address]:]port:host:hostport: Forward local UDP traffic on [[bind_address]:]port to host:hostport on the server

• -V [[bind_address]:]port:host:hostport: Forward UDP traffic on [[bind_address]:]port on the server to host:hostport on the local side

Server

Usage: ssfd[.exe] [options]

Options:

• -v verbose_level: Verbosity: critical|error|warning|info|debug|trace (default: info)

• -q: Quiet mode. Do not print logs

• -c config_file_path: Specify configuration file. If not set, 'config.json' is loaded from the current working directory

• -p port: Local port (default: 8011)

• -R: The server will only relay connections

• -l host: Set server bind address

• -g: Allow gateway ports. Allow client to bind local sockets for a service to a specific address rather than "localhost"

• -S: Display microservices status (on/off)

Copy

The copy feature must be enabled on both client and server configuration file:

{
  "ssf": {
    "services": {
      "copy": { "enable": true }
    }
  }
}

Usage: ssfcp[.exe] [options] [host@]/absolute/path/file [[host@]/absolute/path/file]

Options:

• -v verbose_level: Verbosity: critical|error|warning|info|debug|trace (default: info)

• -q: Quiet mode. Do not print logs

• -c config_file_path: Specify configuration file. If not set, 'config.json' is loaded from the current working directory

• -p port: Remote port (default: 8011)

• -t: Use stdin as input

• --resume: Attempt to resume file transfer if the destination file exists

• --check-integrity: Check file integrity at the end of the transfer

• -r: Copy files recursively

• --max-transfers arg: Max transfers in parallel (default: 1)

Examples

Client

The client will run a SOCKS proxy on port 9000 and transfer connection requests to the server 192.168.0.1:8000

ssf -D 9000 -c config.json -p 8000 192.168.0.1

Server

The server will be bound to port 8011 on all the network interfaces

ssfd

The server will be bound to 192.168.0.1:9000

ssfd -p 9000 -l 192.168.0.1

Copy local file to remote filesystem

ssfcp [-c config_file] [-p port] path/to/file host@absolute/path/directory_destination

ssfcp [-c config_file] [-p port] path/to/file* host@absolute/path/directory_destination

ssfcp [-c config_file] [-p port] -r path/to/dir host@absolute/path/directory_destination

Pipe file from standard input to remote filesystem

data_in_stdin | ssfcp [-c config_file] [-p port] -t host@path/to/destination/file_destination

Copy remote files to local filesystem :

ssfcp [-c config_file] [-p port] remote_host@path/to/file absolute/path/directory_destination

ssfcp [-c config_file] [-p port] remote_host@path/to/file* absolute/path/directory_destination

ssfcp [-c config_file] [-p port] -r remote_host@path/to/dir absolute/path/directory_destination

Configuration file

{
  "ssf": {
    "arguments": "",
    "circuit": [],
    "http_proxy": {
      "host": "",
      "port": "",
      "user_agent": "",
      "credentials": {
        "username": "",
        "password": "",
        "domain": "",
        "reuse_ntlm": true,
        "reuse_nego": true
      }
    },
    "socks_proxy": {
      "version": 5,
      "host": "",
      "port": "1080"
    },
    "tls" : {
      "ca_cert_path": "./certs/trusted/ca.crt",
      "cert_path": "./certs/certificate.crt",
      "key_path": "./certs/private.key",
      "key_password": "",
      "dh_path": "./certs/dh4096.pem",
      "cipher_alg": "DHE-RSA-AES256-GCM-SHA384"
    },
    "services": {
      "datagram_forwarder": { "enable": true },
      "datagram_listener": {
        "enable": true,
        "gateway_ports": false
      },
      "stream_forwarder": { "enable": true },
      "stream_listener": {
        "enable": true,
        "gateway_ports": false
      },
      "copy": { "enable": false },
      "shell": {
        "enable": false,
        "path": "/bin/bash|C:\\windows\\system32\\cmd.exe",
        "args": ""
      },
      "socks": { "enable": true }
    }
  }
}

Arguments

| Configuration key | Description | |:------------------|:-------------------------------------------------------------------------| | arguments | use configuration arguments instead of given CLI arguments (except -c) |

The arguments key lets the user customize the command line arguments in the configuration file. This feature is a convenient way to save different client connection profiles.

Given the following configuration file conf.json:

{
  "ssf": {
    "arguments": "10.0.0.1 -p 443 -D 9000 -L 11000:localhost:12000 -v debug"
  }
}

SSF will extract the given arguments and use them as a replacement of the initial arguments (except -c).

For example, ssf -c conf.json will be equivalent to ssf 10.0.0.1 -p 443 -D 9000 -L 11000:localhost:12000 -v debug:

• connect to 10.0.0.1:443 (10.0.0.1 -p 443)
• start the SOCKS service (-D 9000)
• start the TCP port forwarding service (-L 11000:localhost:12000)
• set verbosity level to debug (-v debug)

Circuit

| Configuration key | Description | |:------------------|:--------------------------------------------------------------------------| | circuit | relay chain servers used to establish the connection to the remote server |

The circuit is a JSON array containing the bounce servers and ports which will be used to establish the connection. They are listed as follow:

{
  "ssf": {
    "circuit": [
      {"host": "SERVER1", "port":"PORT1"},
      {"host": "SERVER2", "port":"PORT2"},
      {"host": "SERVER3", "port":"PORT3"}
    ]
  }
}

This configuration will create the following connection chain:

CLIENT -> SERVER1:PORT1 -> SERVER2:PORT2 -> SERVER3:PORT3 -> TARGET

Proxy

SSF supports connection through:

• HTTP proxy by using the CONNECT HTTP method
• SOCKS proxy (v4 or v5)

HTTP proxy

| Configuration key | Description | |:----------------------------------|:----------------------------------------------------------------------------------------------------------| | http_proxy.host | HTTP proxy host | | http_proxy.port | HTTP proxy port | | http_proxy.user_agent | User-Agent header value in HTTP CONNECT request | | http_proxy.credentials.username | proxy username credentials (all platform: Basic or Digest, Windows: NTLM and Negotiate if reuse = false) | | http_proxy.credentials.password | proxy password credentials (all platform: Basic or Digest, Windows: NTLM and Negotiate if reuse = false) | | http_proxy.credentials.domain | user domain (NTLM and Negotiate auth on Windows only) | | http_proxy.credentials.reuse_ntlm | reuse current computer user credentials to authenticate with proxy NTLM auth (SSO)