Hooks

network hook: Score URLs for SSRF

Score one or many fetch destinations for SSRF, straight from the command line.

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.

npx lagune read network --url 'http://example.com/'
# => safe

npx lagune read network --url 'http://0x7f000001/'
# => private-target

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​

VerdictMeaning
safeThe destination connects to a public host, and a sloppy validator would read the same host.
private-targetThe host resolves to a private, loopback, link-local, unspecified, or cloud-metadata address, or the destination is a file: URL with no host.
parser-divergentA sloppy text validator would read a different real host than the one the fetcher connects to.
invalid urlThe 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​

OptionValueDescription
--urla URL or hostCheck 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.

Why a flag value

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.

What it does not cover

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.

tip

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.