Skip to content

Docker

Quickstart

You may download our sslsplit-quickstart script to install or remove sslsplit.

If you installed the collectors as a container, the sslsplit quickstart script needs to exec into the container during installation. For this reason, you must pass in the name of your collector container.

  • Run the command below, making sure to pass in your collector container name:
chmod +x sslsplit-quickstart.sh && \
PKG_TYPE=docker EPOCH_AOC_HOST=${your_epoch_host} COLLECTOR_CONTAINER_NAME=<your collector container name> ./sslsplit-quickstart.sh
  • Remove sslsplit
./sslsplit-quickstart.sh remove

Quickstart Configuration

The quickstart script can be parameterized with environment variables to fit your installation environment. Refer to the table below for details:

Parameter Default Choices Description
DEST_PORT 443 (https) 0 - 65536 The port to which your encrypted traffic is being sent.
PKG_TYPE n/a deb, rpm, docker Defines the sslsplit package type. It is automatically set based on the OS, but you can override it with docker on a DEB or RPM-based OS if you have installed the collectors via docker.
COLLECTOR_CONTAINER_NAME n/a String The container name of the collector with which we are setting up sslsplit. This defaults to epoch_collectors if PKG_TYPE is docker.

Manual Installation

Part 1 - Setup (not required for container collector)

Users of the containerized collectors need not perform any setup, since sslsplit is already installed inside the collector container.

Part 2 - Certificates

  1. Copy sslsplit's self-signed certificate to the certificates directory

    For Debian:

    sudo docker cp epoch_collectors:/opt/nutanix/epoch/sslsplit/certs/epoch-ca.crt \
        /usr/local/share/ca-certificates/
    

    For RHEL:

    sudo docker cp epoch_collectors:/opt/nutanix/epoch/sslsplit/certs/epoch-ca.crt \
        /etc/pki/ca-trust/source/anchors/
    
  2. Set the proper permissions on the self-signed certficate

    For Debian:

    sudo chmod 644 /usr/local/share/ca-certificates/epoch-ca.crt
    

    For RHEL:

    sudo chmod 644 /etc/pki/ca-trust/source/anchors/epoch-ca.crt
    
  3. Update the CA store

    For Debian:

    sudo update-ca-certificates
    

    For RHEL:

    sudo update-ca-trust
    

NOTE: Make sure to restart docker daemon as it won't reload the global ssl certs on its own and would experience certificate errors when trying to reach docker registry.

Applications with certificate bundles

Client applications such as MySQL and PostgreSQL use their own certificate bundles and don't use the root certificates on the host. To make these applications trust SSLsplit, provide the public certificate of SSlsplit along with the certificate(s) of the actual server to the application.

For example, Amazon's RDS has a standard set of public certificates available as a bundle. Add SSLsplit's public certificate to the trusted certificates (all the certificates concatenated into a single file). This is the location of SSLsplit's public certificate in the collector: /opt/nutanix/epoch/sslsplit/certs/epoch-ca.crt. Configure the MySQL client application via its SSL certs configuration to use the new trusted server certificates. The client should now be able to trust SSLsplit.

Part 3 - IPtables

Outgoing Traffic

The following are iptables rules for intercepting outgoing SSL traffic towards a destination port. See here for intercepting incoming traffic.

  1. Insert iptables rules

    Run the following command on the collector host to add iptables rules for destination port 443

    sudo iptables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner 65534 -m tcp --dport 443 -j REDIRECT --to-ports 10443
    
  2. Check that rules were inserted correctly

    sudo iptables -t nat -L
    

    If the iptables rule for sslsplit is installed an entry similar to the following will be seen in Chain OUTPUT:

    REDIRECT   tcp  --  anywhere             anywhere             ! owner UID match 65534 tcp dpt:https redir ports 10443
    

Incoming Traffic

For the most part, setting up outgoing traffic capture rules should suffice. For the edge cases, instructions for setting up incoming traffic capture rules are provided here.

  1. Insert iptables rules

    Run the following command on the collector host to add iptables rules for destination port 443

    sudo iptables -t nat -A PREROUTING -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 10443
    
  2. Check that rules were inserted correctly with the following command

    sudo iptables -t nat -L
    

    If the iptables rule for SSLsplit is installed an entry similar to the following will be seen in Chain PREROUTING:

    REDIRECT   tcp  --  anywhere             anywhere             tcp dpt:https redir ports 10443
    
  3. External clients can trust SSLsplit only if it presents a secure certificate. To do so, follow the directions below in Using your own Certificate.

Disabling SSL Capture

  1. Run the following command on the host to remove iptables rules for outgoing traffic on destination port 443:

    sudo iptables -t nat -D OUTPUT -p tcp -m owner ! --uid-owner 65534 -m tcp --dport 443 -j REDIRECT --to-ports 10443
    
  2. Run the following command on the host to remove iptables rules for incoming traffic on destination port 443 (can skip if you did not configure sslsplit for incoming traffic):

    sudo iptables -t nat -D PREROUTING -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 10443
    
  3. Stop the collector container and restart without passing the EPOCH_ENABLE_SSLSPLIT parameter.

  4. Remove collector's self-signed certificate from the certificates directory:

    For Debian:

    sudo rm /usr/local/share/ca-certificates/epoch-ca.crt
    

    For RHEL:

    sudo rm /etc/pki/ca-trust/source/anchors/epoch-ca.crt
    
  5. Update the CA store:

    For Debian:

    sudo update-ca-certificates
    

    For RHEL:

    sudo update-ca-trust
    

IMPORTANT: When uninstalling collectors or sslsplit, remember to follow the instrutions to disable SSL capture first so iptables rules are removed.

Advanced Configuration

Using your own Certificate

To use a custom certificate with SSLsplit, a custom container image may be created with your own certificate and key

  1. Create a working directory

  2. Put your-ca.crt and your-ca.key in working directory

  3. Create the following Dockerfile:

    FROM epoch/collectors:stable-*.*.*
    
    COPY your-ca.crt /opt/nutanix/epoch/sslsplit/certs/epoch-ca.crt
    COPY your-ca.key /opt/nutanix/epoch/sslsplit/certs/epoch-ca.key
    

    Note: Replace "..*" with the AOC version you are using

  4. Run:

    docker build . --tag=epoch-collectors-ca
    

    Note: You may use whatever image tag you wish

  5. Redeploy the collectors with your newly built image

Uninstalling

Docker

There is no need to uninstall sslsplit in the containers, you only need disable it.