Skip to content

Add utils/netguard to refuse internal and reserved addresses - #2004

Merged
pksgit merged 3 commits into
mainfrom
pradeepsharma/netguard
Nov 21, 2026
Merged

pksgit merged 3 commits into
mainfrom
pradeepsharma/netguard

Conversation

@pksgit

@pksgit pksgit commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Several LiveKit components keep their own copy of a check that refuses internal and reserved addresses, each with a different range list, so an address one refuses another can let through. This adds one shared check, utils/netguard, to consolidate them, starting from the webhook dial guard's list in this repo (webhook/dial_guard.go). It imports only the standard library.

Nothing uses it yet, and no existing package changes. Each copy moves to netguard in its own PR and is then removed.

What it provides

  • IsBlockedIP(ip): refuses loopback, private (RFC 1918 and IPv6 ULA), link-local (including the cloud metadata address), multicast, unspecified, CGNAT, documentation, benchmarking and other reserved ranges, and the 6to4, IPv4-compatible, IPv4-translated and Teredo forms that carry an IPv4 address. A nil or malformed IP is reported as blocked.
  • CheckHost(host): refuses localhost, *.localhost, a blocked IP literal, or an IP literal with a zone (such as fe80::1%eth0), so a mistake surfaces when a destination is configured. A port, and brackets around an IPv6 literal, are accepted. It is an early check for configuration mistakes only: host names are not looked up, and IPv4 spellings such as 127.1 pass; the dial guard checks both after the lookup.
  • BlockInternal: a net.Dialer Control function that refuses every address IsBlockedIP reports, and any address with a zone. It runs after the name lookup, on the address being connected to, so it also covers names that resolve to internal addresses and redirects.
  • NewDialControl(blockPrivate, blocked, allowed): the same with custom blocked and allowed ranges. An allowed address is never refused, so a broad allowed range also opens loopback and the metadata address. ParseCIDR parses those ranges and converts an IPv4-mapped range to its IPv4 form.
  • ReportOnly(control, report): wraps a Control function so an address it would refuse is passed to report and the connection goes ahead. A client can run the check in a log-only mode, see what it would refuse, then enforce.
  • ReportOnlyContext(control, report): the same for net.Dialer.ControlContext, passing the dial context to report. Under http.Transport that context carries the values of the request that started the dial, so a caller can attach a host or tenant to its request. A request that reuses a pooled connection does not dial, so it is not reported.
  • ErrBlockedAddress: the refusal error.

The dial guard sees the address being connected to, which is the proxy's when a client uses one, so a guarded http.Transport should set Proxy to nil.

Differences from the webhook dial guard's copy

  • An address in the NAT64 well-known prefix 64:ff9b::/96 is judged by the IPv4 address it carries instead of always being refused.
    • On an IPv6-only network that uses DNS64/NAT64, every IPv4-only destination arrives in that prefix, so refusing all of it breaks connections to public IPv4 hosts.
    • 64:ff9b::8.8.8.8 is allowed. 64:ff9b::10.0.0.1, 64:ff9b::169.254.169.254 and 64:ff9b::127.0.0.1 are refused.
    • The local-use prefix 64:ff9b:1::/48 is refused whatever it carries.
  • CheckHost refuses IP literals with a zone and accepts bracketed IPv6 and a port.
  • The IPv4-translated range ::ffff:0:0:0/96 is refused.
  • IsBlockedIP refuses a nil or malformed IP.
  • ReportOnly and ReportOnlyContext are new.

Follow-ups (separate PRs)

  • Move each existing copy of the check onto netguard and remove it, one PR per component, behind a setting where behaviour changes, log-only (ReportOnly) before enforcing.
  • Move the webhook dial guard onto netguard once it has run in production elsewhere.
  • Possibly: name the range an address matched, for log and metric labels; and a helper that resolves a host name and checks every address returned, for checks made when a request is created.

Tests

  • Address, host, dial, ParseCIDR, ReportOnly and ReportOnlyContext tests in utils/netguard. The ReportOnlyContext test sends a request through http.Transport to a local server and checks that the request's context value reaches report and the request succeeds.
  • Each of these changes makes at least one test fail:
    • dropping a range;
    • BlockInternal letting private addresses through;
    • ParseCIDR skipping the IPv4-mapped conversion;
    • removing the NAT64 handling, or refusing all NAT64 again;
    • ReportOnly or ReportOnlyContext refusing, not reporting, or swallowing other errors;
    • ReportOnlyContext not passing the dial context to report.
    • CheckHost ignoring zones or brackets;
    • IsBlockedIP allowing a nil IP, or skipping the IPv4-mapped conversion;
    • CheckHost not stripping a port;
    • an allowed range no longer overriding refusals.
  • go test -race ./... and golangci-lint pass locally. TestURLNotifierFilter times out locally on main as well, so it was skipped in my local run.

🤖 Generated with Claude Code

A shared check for clients that connect to destinations a caller
supplies, consolidating copies that keep different range lists. It
starts from the webhook dial guard's list, judges NAT64 well-known
addresses by the IPv4 address they carry, refuses zoned IP literals
in CheckHost, and adds ReportOnly for a log-only mode. No existing
package changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@changeset-bot

changeset-bot Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 0b8c87b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
github.com/livekit/protocol Patch
@livekit/protocol Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@biglittlebigben biglittlebigben left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks solid overall. The dial guard (BlockInternal / NewDialControl) handled every edge case I tried, and CI is green. Most of the inline comments are about CheckHost and the docs.

On the PR description: "TestURLNotifierFilter times out locally on main as well, so it was skipped there" can be read as the test being skipped in CI. Maybe "skipped in my local run"?

🤖 Generated with Claude Code

Comment thread utils/netguard/netguard.go Resolved
Comment thread utils/netguard/netguard.go Resolved
Comment thread utils/netguard/netguard.go Resolved
Comment thread utils/netguard/netguard.go Resolved
Comment thread utils/netguard/netguard.go Resolved
Comment thread utils/netguard/netguard_test.go Resolved
Comment thread utils/netguard/netguard_test.go Resolved
Comment thread .changeset/netguard-package.md Resolved
- CheckHost strips a port, and its doc says it only catches
  configuration mistakes early.
- Refuse the IPv4-translated range ::ffff:0:0:0/96.
- Keep the range list as netip prefixes matched against the unmapped
  address, with NAT64 unwrapped in one place.
- Document proxies, and that an allowed range overrides every refusal.
- Test the plain and IPv4-mapped metadata address.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread utils/netguard/netguard.go Resolved
ReportOnlyContext is ReportOnly for net.Dialer.ControlContext. It passes
the dial context to report, so a caller can attach a host or tenant to
its request and see it next to a refusal in log-only mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pksgit

pksgit commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

I will merge after @anunaym14 has had a chance to take a look as well.

@pksgit

pksgit commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

Actually since this is urgent and there will PRs on top of this. I will go ahead with this one. @anunaym14 , if you have any comments on this then I will address as a follow up

@pksgit
pksgit merged commit fb74d2f into main Nov 21, 2026
11 checks passed
@pksgit
pksgit deleted the pradeepsharma/netguard branch November 21, 2026 01:15
@github-actions github-actions Bot mentioned this pull request Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants