netguard

package
v0.55.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package netguard restricts the network destinations the datasource proxy is allowed to reach.

The datasource proxy forwards requests to a URL (or connects to a SQL host) coming from the datasource spec, which is provided by the users. Without restriction, it can be used to reach any service accessible from the Perses server (Server-Side Request Forgery): the Perses API itself through the loopback interface, the cloud metadata endpoints, the Kubernetes API, etc. As the proxy reflects the response, it would be a full read channel on these services.

The Guard provides two levels of verification:

  • A static verification of the URL / host (ValidateURL, ValidateSQLHost, ValidateDatasourceSpec, ValidateOAuth), done when a datasource (or a secret) is saved and before a request is proxied. It provides an early and clear error message.
  • A verification at connection time (DialContext, DialResolvedContext, HTTPTransport), done on every IP address the destination resolves to, including the ones reached through a redirection. This is the actual protection, as it cannot be bypassed with a DNS name pointing to a forbidden IP address (including DNS rebinding) or with an alternative IP notation.

Index

Constants

This section is empty.

Variables

View Source
var ErrDenied = errors.New("destination not allowed")

ErrDenied is the error (wrapped) returned when a destination is not allowed. Use IsDenied or errors.Is to detect it.

Functions

func IsDenied

func IsDenied(err error) bool

IsDenied returns true if the error (or one of the errors it wraps) is due to a destination not allowed.

Types

type Guard

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

Guard verifies that a destination is allowed according to the datasource proxy configuration. Use New to create it: the zero value (and a nil *Guard) is not valid.

func New

New creates a Guard from the datasource proxy configuration. The configuration is expected to have been verified beforehand (see config.DatasourceProxyConfig.Verify and config.HTTPProxyConfig.Verify), which is the case of the configuration loaded by Perses: its values are valid and normalized.

func (*Guard) CheckIP

func (g *Guard) CheckIP(ip netip.Addr) error

CheckIP verifies that the IP address is allowed.

When the IP address is part of both an allowed and a denied network, the most specific network (the longest prefix) wins; on equal prefix lengths, the allowed network wins. For example, allowing 10.0.0.0/8 doesn't allow the Kubernetes API service IP (denied as a single IP address), while allowing this IP address explicitly does.

When the IP address is not part of any allowed or denied network, the IPv4 address it embeds (NAT64, 6to4), if any, is verified the same way.

func (*Guard) DialContext

func (g *Guard) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext establishes a TCP connection after having verified the destination. The host must be part of the allowed hosts (if configured), and the verification is done on each IP address the destination resolves to, just before connecting to it. It can be used as a dial function for the SQL drivers dialing the hostname (e.g. MySQL).

func (*Guard) DialResolvedContext

func (g *Guard) DialResolvedContext(ctx context.Context, network, address string) (net.Conn, error)

DialResolvedContext establishes a TCP connection after having verified the IP address of the destination. Unlike DialContext, the host is not verified against the allowed hosts: the address is expected to come from LookupHost (where the hostname has been verified) or from an existing connection (e.g. a cancel request).

func (*Guard) HTTPTransport

func (g *Guard) HTTPTransport(tlsConfig *tls.Config, connectTimeout time.Duration) *http.Transport

HTTPTransport returns an HTTP transport where every connection is verified by the Guard. As the verification is done at connection time, it also applies to the redirections followed by an HTTP client.

The HTTP proxy configured through the environment (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) is honored, and considered as trusted since it's configured by the administrator of the Perses server. As the proxy resolves the final destination, the destination is verified upfront instead. A request targeting the address of the proxy (directly or through it) is denied, as the connections to the proxy are not verified.

connectTimeout is the maximum amount of time allowed to establish a connection. When zero or negative, a default of 30s is used.

func (*Guard) LookupHost

func (g *Guard) LookupHost(ctx context.Context, host string) ([]string, error)

LookupHost verifies that the host is allowed (like ValidateSQLHost does) and resolves it. It is meant for the drivers resolving the hostname themselves and dialing the resolved IP addresses (e.g. pgx). Use it with DialResolvedContext.

func (*Guard) ValidateDatasourceSpec

func (g *Guard) ValidateDatasourceSpec(spec datasourceSpec.Spec) error

ValidateDatasourceSpec statically verifies the destination of the proxy defined in the datasource spec, if any. It doesn't resolve any DNS name; the resolved IP addresses are verified at connection time.

func (*Guard) ValidateOAuth

func (g *Guard) ValidateOAuth(oauth *secretModel.OAuth) error

ValidateOAuth statically verifies that the token URL of the OAuth configuration (of a secret) is allowed. A nil configuration is valid.

func (*Guard) ValidateProxyConfig

func (g *Guard) ValidateProxyConfig(cfg any, kind string) error

ValidateProxyConfig is the same as ValidateDatasourceSpec, for a proxy config already extracted from the datasource spec (see datasourcev1.ValidateAndExtract).

func (*Guard) ValidateSQLHost

func (g *Guard) ValidateSQLHost(hosts string) error

ValidateSQLHost statically verifies that the host (or the comma-separated list of hosts) of a SQL datasource is allowed. A host can contain a port. Unix sockets are not allowed.

func (*Guard) ValidateURL

func (g *Guard) ValidateURL(u *url.URL) error

ValidateURL statically verifies that the URL of an HTTP datasource is allowed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL