netsleuth

TLS

The forward proxy intercepts HTTPS connections in order to inspect their contents. It dynamically generates TLS certificates on the fly to present to clients.

netsleuth has a built-in certificate authority (CA) to issue these certificates, but no device will trust this CA by default. In order for HTTPS connections to work properly, you need to enable trust of your netsleuth CA.

Your CA certificate is automatically generated when you first run netsleuth. It is stored (alongside its private key) in ~/.config/netsleuth/. The certificate is also available from http://localhost:9000/ca.cer.

⚠️ Importantly for security, the CA certificate is unique for every computer that runs netsleuth. Protect your CA private key, since it can be used to intercept HTTPS traffic on any device that trusts the certificate.

Installing on your computer

The netsleuth GUI will prompt you to install the CA certificate. Provide your administrative credentials and the certificate will be installed for you.

Alternatively, you can install from the command line:

sudo netsleuth setup --ca

(Windows doesn't have sudo; run without it and you will be prompted for elevation)

Installing on other devices

The exact steps to install a CA certificate will vary by device/OS. Generally, fetch your certificate from http://<computer-ip>:9000/ca.cer and install it into your root trust store. Search the web for step-by-step guides.

Validation of target TLS certificates

When netsleuth connects to a target HTTPS server, it will validate that its certificate is valid and trusted. By default, it uses node's builtin public CA list. Importantly, it does not use your OS CA store at this time, which means if you are using netsleuth on a network that transparently intercepts HTTPS connections (such as a corporate filter), no connection will validate.

When TLS certificate validation fails, the inspector GUI will show you a dialog that contains the certificate's information. You can:

• Temporarily accept the certificate. netsleuth will remember the certificate's public key and allow requests to complete. The certificate is remembered until you restart the netsleuth daemon.
• Permanently accept the certificate. netsleuth will store the certificate in ~/.config/netsleuth/trust/<hostname> and allow requests to complete.
• Reject the certificate. netsleuth will remember the certificate's public key and will not prompt you about it again until you restart the netsleuth daemon.

Note that whether you temporarily or permanently accept an invalid certificate, netsleuth will display next to request hostnames in the list to indicate that it was insecure.

Configuring a custom CA

When you configure a target, you may specify an alternate CA to use when validating certificates. The CA certificate can be the server's (self-signed) certificate itself, or a CA trust root certificate.

When you specify a custom CA, netsleuth will validate connections using that certificate and will not mark requests using the custom CA as insecure (assuming other aspects of the certificate like hostname and expiration date validate).

Alternatively, you may configure a target as "insecure", and netsleuth will not do any TLS certificate validation. This is dangerous behavior and is not recommended.