netsleuth

Locally proxied hosts

When you add a target in local proxy mode, netsleuth starts a HTTP server on your machine. It listens for incoming requests and forwards them to the target HTTP server. You are able to use the inspector GUI to see the requests and responses.

Generally, only software running on your machine (or LAN, if allowed) can make requests through the proxy server. Servers and devices on the public internet will be unable to reach your proxy server – the public gateway helps you make local services available to the public internet.

The target server (that receives the forwarded traffic) can be any HTTP(S) server reachable from your machine – whether a server running locally, behind a VPN, or on the public internet.

Using the forward proxy

netsleuth automatically runs a forward proxy on port 9000.

To use the forward proxy, you must configure client apps and devices to use the HTTP proxy. How to do this depends on the client – you'll need to see its documentation.

Proxy: http://localhost:9000

Other devices on your LAN can also use this proxy server. Instead of localhost, use your machine's IP address (eg 192.168.1.x). Ensure that your local firewall allows incoming connections. Note that there is no access control on this proxy; you should not expose it to the internet (eg via port forwarding).

⚠️ In order for clients to make successful HTTPS requests, you will need to install your netsleuth CA certificate as a trusted CA.

In the GUI, click the first target ":9000" to open the forward proxy inspector.

Adding a local reverse proxy target

There are two ways to add a new target:

• GUI: Click the + button on http://localhost:9000 and select Local reverse proxy target
• CLI: Use netsleuth inspect --local

netsleuth will listen for HTTP and HTTPS connections. It will automatically self-issue a TLS certificate for the host's name and/or IP using the built-in CA.

The following options are available in both the GUI and CLI. See the CLI docs for exact usage.

Hostname

• If you do not specify a hostname: netsleuth will automatically find a free loopback IP address and bind to ports 80 and 443. For example, 127.0.0.2:80.
• If a name: same as above – binds to automatic loopback IP. You can check "Add hostname to system HOSTS file" (--add-host) and you can use the name instead of the IP anywhere on your machine. (Doing so requires root/elevated privileges; you will see your OS elevation UI when you click Add.)
• If an IP address: netsleuth will bind to ports 80 and 443 on the IP address. This is how you can allow devices on your LAN to send traffic to your proxy.
• Optionally, you can include a port, eg :8080.
  • netsleuth will bind a HTTP server to the specified port and a HTTPS server to the specified port +1 (eg 8081)
  • If you provide a port with a name or IP, netsleuth will bind to a loopback address/LAN IP on the specified port.
  • If you provide only a port, netsleuth will bind to that port on all addresses (ie, 0.0.0.0)
  • Keep in mind that browsers blacklist some ports. The GUI will warn you if you try to use a blacklisted port.
  • See the important note below regarding privileged ports

Target

The target is the destination HTTP server. It can be any HTTP(S) server reachable from your machine (local or remote).

• If you provide a protocol (http://example.com), netsleuth will always use that protocol to connect to the target (ie plaintext http or encrypted https), regardless of how the client connected to the proxy.
• Use a protocol-relative URL (//example.com) to use the same protocol as each client request.

Target TLS

This controls how netsleuth validates the target's TLS certificate when connecting over https.

• Normal: netsleuth will fully validate the certificate. The certificate must be unexpired and issued by a public CA to the server's DNS name. (Note: node.js does not use your OS trust store, so corporate CAs will not validate.)
• Insecure: netsleuth will ignore ALL TLS errors. It will accept any certificate, issued by anyone to anything with any expiration date. It is recommended that you do not use this mode.
• Custom CA: allows you to provide a custom CA certificate. This can be the server's certificate itself (for self-signed certs), or a CA cert.
  • For your convenience, in the GUI, you can click the Get… button, and netsleuth will attempt to fetch the server's certificate. You must manually verify that the certificate's fingerprint is correct.
  • You can also Choose File to select a PEM-encoded certificate file.
  • With the CLI, use --ca to specify the path to the PEM-encoded certificate file.
  In custom CA mode, netsleuth will still validate that the certificate is unexpired and issued to the target's DNS name.

Temporary

If you add a temporary target, netsleuth will not save it to your configuration file (.sleuthrc). This means the target will disappear the next time the netsleuth daemon restarts.

Require Basic auth from clients

Clients connecting to your proxy server will be required to provide this shared username and password over HTTP Basic auth before the request is forwarded to the target server.

Warning: this password is stored in plain text. Do not reuse credentials that you use for anything else.

⚠️ Privileged ports

On Unix systems (Linux and Mac OS), only programs running as root may bind to ports < 1024. (Windows has no such restriction; you can skip this section.)

netsleuth includes builtin support for authbind, which allows it to listen on privileged ports without actually running its daemon as root (which is unsafe).

If netsleuth is unable to listen on the default HTTP ports, you may need to ensure that authbind is correctly installed and configured. Full details here.

Note that netsleuth's default setup only allows it to listen on privileged ports 80 and 443, so if you want to add a proxy that listens on a port 1-79, 81-442, or 444-1023, you must manually grant that permission.