netpolicy

Documentation

Overview

Package netpolicy provides URL and host validation for network requests.

This package centralizes network security policy enforcement to ensure consistent validation across all code that makes external network requests. Using this package prevents divergence that could lead to SSRF vulnerabilities or credential leakage.

Security Properties

• Validates URLs against allowlists of trusted hosts
• Enforces HTTPS for all non-loopback connections
• Prevents credential transmission over HTTP (even to loopback)
• Provides separate allowlists for different trust levels (API vs asset hosts)
• Supports loopback addresses for testing while maintaining security

Usage

Validate a URL before making a request:

policy := netpolicy.GitHubPolicy()
if err := policy.ValidateAPIURL(url); err != nil {
    return err // Host not trusted or scheme not allowed
}

Check if auth headers should be sent:

if policy.ShouldSendAuth(parsedURL) {
    req.Header.Set("Authorization", "Bearer "+token)
}

For testing with loopback addresses:

policy := netpolicy.GitHubPolicy().WithLoopbackHTTP()
// HTTP to localhost/127.0.0.1 now allowed (but auth never sent over HTTP)

Index

• func IsLoopback(hostname string) bool
• func SecureTransport() *http.Transport
• type Policy
  • func GitHubPolicy() *Policy
  • func NewPolicy(apiHosts, assetHosts []string) *Policy
  • func (p *Policy) IsTrustedAPIHost(hostname string) bool
  • func (p *Policy) IsTrustedAssetHost(hostname string) bool
  • func (p *Policy) ShouldSendAPIAuth(parsed *url.URL) bool
  • func (p *Policy) ShouldSendAuth(parsed *url.URL) bool
  • func (p *Policy) ValidateAPIURL(rawURL string) error
  • func (p *Policy) ValidateAssetURL(rawURL string) error
  • func (p *Policy) WithAdditionalHosts(hosts ...string) *Policy
  • func (p *Policy) WithLoopbackHTTP() *Policy

Functions

func IsLoopback

func IsLoopback(hostname string) bool

IsLoopback reports whether hostname refers to the local machine. Recognizes IPv4 (127.0.0.1), IPv6 (::1, [::1]), and localhost. Used to enforce stricter policies on non-local connections.

func SecureTransport

func SecureTransport() *http.Transport

SecureTransport returns an http.Transport configured with secure TLS defaults. This enforces TLS 1.2 minimum to prevent protocol downgrade attacks.

Use this for all production HTTP clients that make external requests.

Types

type Policy

type Policy struct {
	// contains filtered or unexported fields
}

Policy defines network security policy for a set of trusted hosts. It validates URLs and determines whether credentials should be sent.

func GitHubPolicy

func GitHubPolicy() *Policy

GitHubPolicy returns the default policy for GitHub API and asset hosts. This is the standard policy for production use with GitHub.

func NewPolicy

func NewPolicy(apiHosts, assetHosts []string) *Policy

NewPolicy creates a new network policy with the given trusted hosts. apiHosts are trusted for API requests, assetHosts for asset downloads.

func (*Policy) IsTrustedAPIHost

func (p *Policy) IsTrustedAPIHost(hostname string) bool

IsTrustedAPIHost returns true if the host is in the trusted API hosts list.

func (*Policy) IsTrustedAssetHost

func (p *Policy) IsTrustedAssetHost(hostname string) bool

IsTrustedAssetHost returns true if the host is in the trusted asset hosts list.

func (*Policy) ShouldSendAPIAuth

func (p *Policy) ShouldSendAPIAuth(parsed *url.URL) bool

ShouldSendAPIAuth returns true if auth headers should be sent for API requests. Uses the stricter API hosts list. Returns false for HTTP URLs.

func (*Policy) ShouldSendAuth

func (p *Policy) ShouldSendAuth(parsed *url.URL) bool

ShouldSendAuth returns true if auth headers should be sent to this URL. SECURITY: Never returns true for HTTP URLs, even to loopback. HTTP traffic can be sniffed by other processes on the same machine.

func (*Policy) ValidateAPIURL

func (p *Policy) ValidateAPIURL(rawURL string) error

ValidateAPIURL validates that a URL is allowed for API requests. Returns an error if:

• The scheme is not HTTPS (or HTTP for allowed loopback)
• The host is not in the trusted API hosts list (unless loopback)

func (*Policy) ValidateAssetURL

func (p *Policy) ValidateAssetURL(rawURL string) error

ValidateAssetURL validates that a URL is allowed for asset downloads. Returns an error if:

• The scheme is not HTTPS (or HTTP for allowed loopback)
• The host is not in the trusted asset hosts list (unless loopback)

func (*Policy) WithAdditionalHosts

func (p *Policy) WithAdditionalHosts(hosts ...string) *Policy

WithAdditionalHosts returns a copy of the policy with additional trusted hosts. The hosts are added to both API and asset host lists. This is intended for testing with mock servers.

func (*Policy) WithLoopbackHTTP

func (p *Policy) WithLoopbackHTTP() *Policy

WithLoopbackHTTP returns a copy of the policy that allows HTTP to loopback addresses. SECURITY: Auth headers are NEVER sent over HTTP, even to loopback. This is intended for testing with local mock servers.