The network hook decides whether a server-side fetch destination is safe from SSRF (a request that can be aimed at internal services, cloud metadata, or private hosts). It is the deterministic engine behind the network specialization, and you can run it yourself.
Run it
Pass each destination with --url. The hook prints one word per destination, read in the table below.
- One destination
- Several destinations
npx lagune read network --url 'http://example.com/'
# => safe
npx lagune read network --url 'http://0x7f000001/'
# => private-target
Repeat --url to score a whole allowlist or denylist in one call, one verdict per line, in order.
npx lagune read network \
--url 'http://example.com/' \
--url 'http://[::1]/' \
--url 'http://allowed.com@evil.example/'
# => safe
# => private-target
# => parser-divergent
It reads each destination as the WHATWG URL parser does, the one browsers and Node.js's fetch use, so encoded forms of an internal address do not slip past: hex, octal, dotless decimal, shorthand, IPv6, and IPv4-mapped all read private-target, and so does a file: URL with no host, which reads the server's own disk. Where a sloppy validator and the real fetcher would read different hosts, the verdict is parser-divergent. A client that parses URLs another way, such as Python's urllib, can connect somewhere else, so a verdict holds only for a client that parses the same way.
How to read the verdict
| Verdict | Meaning |
|---|---|
safe | The destination connects to a public host, and a sloppy validator would read the same host. |
private-target | The host resolves to a private, loopback, link-local, unspecified, or cloud-metadata address, or the destination is a file: URL with no host. |
parser-divergent | A sloppy text validator would read a different real host than the one the fetcher connects to. |
invalid url | The string names no host the parser can read. |
Only safe is an allow. Treat private-target, parser-divergent, and invalid url all as a block.
CLI options
| Option | Value | Description |
|---|---|---|
--url | a URL or host | Check one destination. Repeat to check several, one verdict per line. |
At least one --url is required. The destination is never a bare positional, so it cannot be mistaken for a flag.
Each destination is passed as a flag value, never interpolated into the command. A value with quotes or backticks stays inert and cannot inject into the shell. Always wrap it in single quotes so your shell does not expand it first.
The hook is pure and never resolves DNS, so two runtime gaps are out of scope: DNS rebinding (a name that resolves public when checked, internal when fetched) and redirect chains (a first hop that passes, then redirects inward). Close those by resolving once and connecting to the validated address, and by refusing redirects. It pins the reserved loopback names (localhost and the .localhost family) to internal with no lookup, but any other DNS name reads safe, because asserting it resolves inward would require resolution: the allowlist guards those, and is what this checker validates.
This is the same check the network specialization runs to prove a destination filter holds.
Frequently Asked Questions
Run the network hook. It scores a fetch destination and returns safe, private-target, parser-divergent, or invalid url. Only safe is an allow.
A URL that different parsers read differently, which is a classic SSRF bypass. The network hook flags it rather than allowing it.
