netsleuth

Login

Getting started with netsleuth

netsleuth is a highly flexible tool for inspecting HTTP requests and responses using the Chrome DevTools Network GUI. HTTP traffic can be viewed natively (without proxying) in node.js apps, or between any client and server technologies via netsleuth's proxy server.

You can run the builtin proxy server on your own machine (known as "local mode"); or, with a subscription, traffic is forwarded through a secure tunnel from a cloud-hosted proxy to your machine, to your local development server.

Installation

netsleuth runs a daemon (background process) on your machine to make the magic happen. It is installed from npm (the package manager for node.js). If you do not already have it installed, download the latest node.js LTS version and install it first. Optionally, you should also ensure you have a working native build toolchain. (While not strictly required, doing so is recommended for full functionality.)

With node installed, open a terminal window and run:

npm install -g netsleuth

The -g installs netsleuth globally (instead of as a dependency of a node.js project in the current directory). This makes the netsleuth CLI commands available on your PATH.

On some configurations, installing globally may require sudo – try first without, but if you get an error, try again:

# only if installing without sudo does not work...
sudo npm install -g netsleuth
# ⚠️ if you are running npm < 7, you must add
#     --unsafe-perm so native builds work correctly

Starting the daemon

Once installation finishes, you can start the daemon.

netsleuth start

The GUI is now available at http://localhost:9000. You do have to view it in Chrome — unfortunately, the DevTools do not work in non-Chrome browsers.

Now you're ready to add your first target – a HTTP(S) server that you'd like to inspect requests to.

Understanding the different ways netsleuth can handle HTTP requests

netsleuth is able to handle HTTP(S) traffic in several different ways. We use this terminology to refer to different pieces of the HTTP transaction:

Client
The application that initiates the HTTP request. For example, a browser, mobile app, or code.
Target
The HTTP server that receives the request and generates a response. This can be any web server, whether running locally, on an embedded device, or in the cloud. Also sometimes referred to as an origin server.
Proxy
A HTTP server that receives requests from clients and forwards them to a target server.
Forward proxy
A client configured to use a forward proxy routes all its requests through the proxy, regardless of its final destination. The request includes the target server URL; the forward proxy knows where to send the request based on the data in the request itself.
Reverse proxy
A proxy that sits in front of target server(s). Production setups commonly use them for load balancing and caching. Clients connect to the reverse proxy as if it were the target server, and usually have no knowledge of the actual server behind the proxy. The reverse proxy is configured to know where to find its target server.
Public gateway
netsleuth operates its public gateway service to route requests from the public internet to target origin servers. The public gateway in concert with the netsleuth daemon on your machine effectively operate as a reverse proxy.
node.js native
netsleuth's native node.js integration allows you to inspect outgoing HTTP requests made from a node program. It does not use a proxy server; the node client connects directly to the target origin server.

Using the local forward proxy

The netsleuth daemon automatically runs a forward proxy on your machine; there is no additional configuration in netsleuth needed.

To use the forward proxy, you must reconfigure your clients to use the proxy server. 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).

Adding a local reverse proxy target

To add a new local reverse proxy configuration to netsleuth, open the GUI and click the button. Alternatively, you can use the CLI: netsleuth inspect --local.

As an example, let's create a reverse proxy to this server. In the New target dialog:

Or from the command line:

netsleuth inspect --local --add-host https://netsleuth.io ns-test

(On unix systems, you can optionally sudo this command for the --add-host part. If you don't, you'll get a GUI elevation prompt.)

If all went well, you can now open http://localhost:9000/inspect/ns-test and you'll see the DevTools Network tab. Now you can open http://ns-test/example.json in another tab, and you'll see the HTTP traffic from your browser! Also try:

curl http://ns-test/example.json

Now any client can make requests to ns-test as if it were making requests to netsleuth.io. In real-world use, you could reconfigure your client apps to make requests to this reverse proxy instead of directly to the target in order to inspect the requests.

Detailed local proxy docs are here.

Adding a public gateway target

To add a new public gateway configuration to netsleuth, open the GUI and click the button. Alternatively, you can use the CLI: netsleuth inspect. (This requires a subscription.)

Let's get a public URL for a server running on port 5000 on your machine. In the New target dialog:

Or from the command line:

netsleuth inspect http://localhost:5000 example.netsleuth.io

If the hostname was autoassigned, the GUI or CLI will tell you the new host's name. You can open the host in the GUI and you'll see the DevTools Network tab. Now you can open https://example.netsleuth.io in a new tab, use a CLI tool to make a request to the host, or open the site from a different device (like your phone), and:

  1. The requests will be forwarded to the target server (running on your machine), and
  2. You can see the requests in the inspector GUI, no matter where they came from

🎉

Using the native node.js integration

When you use the native node.js integration, all outgoing HTTP(S) requests are captured. Because netsleuth integrates into node's internal APIs, it is able to capture HTTPS requests without any impact on TLS operation. This means full security is maintained, client certificates will work correctly, and there is no need to deal with interception and decryption.

There are two ways to inspect requests made by a node.js program.

Start a script using snode

Simply type snode instead of node. Zero code changes are required. You'll see node.pid appear in the list of targets in the GUI.

snode myscript.js

Note that snode does not support any of the node command line options (although environment variables will work).

Use the netsleuth API in your project

To use the API, netsleuth should be installed as a dev dependency in your project. In your project folder:

npm install --save-dev netsleuth

Now go to the file that you run when starting your development environment. As the very first thing your application does, call netsleuth.attach().

if (process.env.NODE_ENV == 'dev') {
	require('netsleuth').attach();
}

This will attach the network debugger to your process and connect to the netsleuth daemon. If the daemon is not running, it will be launched.

Note that this happens asynchronously. If you app makes requests immediately at startup, they may be missed. Use attach's callback to wait until the process is connected to the daemon.

Detailed API documentation is here. You may also want to look at the project configuration docs. A .sleuthrc file in your project's repo allows netsleuth to automatically configure targets for everyone on your team.

Learning more

This guide covers the basics of installing netsleuth and adding your first targets.

The full documentation covers all the available options.