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:
- Select Local reverse proxy target.
- Set the hostname to
ns-test
. - The target is
https://netsleuth.io
. - Check "add hostname to system HOSTS file" so we can access this reverse proxy by name. (This will write to your HOSTS file, which requires elevated/root privileges. You will be prompted to grant permission when you click Add.)
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:
- Select Public gateway target.
- Pick a hostname (or leave it blank for an auto-assigned one).
- The region is the cloud datacenter where your server will be hosted. Generally, you should pick the one that is physically closest to you.
- Target should be
http://localhost:5000
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:
- The requests will be forwarded to the target server (running on your machine), and
- 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.