ipwhitelist

Documentation

Overview

Package ipwhitelist provides IP-based allowlist and denylist filtering for HTTP services.

It supports CIDR ranges for both IPv4 and IPv6, a configurable mode (allowlist-first or denylist-first), trusted-proxy handling for X-Forwarded-For, and a net/http middleware.

Modes

The package supports two modes:

• ModeAllowList (default): only IPs that match an allow CIDR are permitted. Deny CIDRs always override allow CIDRs, so an IP that matches both is denied.
• ModeDenyList: any IP that is not in a deny CIDR is permitted. Allow CIDRs may be used as an optional refinement to further restrict access.

Quick Start

Construct a List with functional options, then use it directly or as an HTTP middleware:

list, err := ipwhitelist.New(
    ipwhitelist.WithMode(ipwhitelist.ModeAllowList),
    ipwhitelist.AllowAll("10.0.0.0/8", "192.168.0.0/16"),
    ipwhitelist.Deny("10.0.0.5/32"),
    ipwhitelist.WithTrustedProxies("10.0.0.0/8"),
)
if err != nil {
    log.Fatal(err)
}

ok, err := list.IsAllowed("10.0.0.1")
if err != nil {
    log.Fatal(err)
}
if !ok {
    log.Fatal("ip not allowed")
}

// As an HTTP middleware:
handler := list.Middleware()(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
}))
_ = handler

Fail-secure

The package is fail-secure: by default (ModeAllowList with no allow CIDRs) every IP is denied. Errors returned from IsAllowed or ClientIP should be treated as a denial by callers.

Index

• Variables
• type List
  • func New(opts ...Option) (*List, error)
  • func (l *List) ClientIP(r *http.Request) (string, error)
  • func (l *List) IsAllowed(ip string) (bool, error)
  • func (l *List) IsAllowedCIDR(cidr string) (bool, error)
  • func (l *List) Middleware(opts ...MWOption) func(http.Handler) http.Handler
• type MWOption
  • func WithDeniedHandler(h http.HandlerFunc) MWOption
  • func WithErrorHandler(fn func(http.ResponseWriter, *http.Request, error)) MWOption
  • func WithSkipper(fn func(*http.Request) bool) MWOption
• type Mode
• type Option
  • func Allow(cidr string) Option
  • func AllowAll(cidrs ...string) Option
  • func Deny(cidr string) Option
  • func DenyAll(cidrs ...string) Option
  • func WithForwardedHeader(name string) Option
  • func WithMode(m Mode) Option
  • func WithTrustedProxies(cidrs ...string) Option

Variables

var (
	// ErrInvalidIP is returned when an IP address string cannot be parsed.
	ErrInvalidIP = errors.New("ipwhitelist: invalid IP address")
	// ErrInvalidCIDR is returned when a CIDR string cannot be parsed.
	ErrInvalidCIDR = errors.New("ipwhitelist: invalid CIDR")
)

Sentinel errors returned by this package.

Types

type List

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

List holds the allow, deny, and trusted-proxy CIDRs along with the evaluation mode. The zero value is not safe to use; construct a List with New.

func New

func New(opts ...Option) (*List, error)

New constructs a List from the provided options. All CIDR strings are parsed eagerly; any invalid input results in an error.

func (*List) ClientIP

func (l *List) ClientIP(r *http.Request) (string, error)

ClientIP determines the real client IP for the given request.

If the RemoteAddr host is within the configured trusted-proxy CIDRs, the leftmost entry of the forwarded header is used. Otherwise the RemoteAddr host is used. The port, if present, is stripped.

func (*List) IsAllowed

func (l *List) IsAllowed(ip string) (bool, error)

IsAllowed reports whether ip is permitted according to the configured rules. An invalid IP string returns an error.

Evaluation order:

1. If ip matches any deny CIDR, it is denied.
2. In ModeAllowList: if ip matches any allow CIDR, it is allowed; otherwise it is denied.
3. In ModeDenyList: if ip is not in any deny CIDR, it is allowed.

func (*List) IsAllowedCIDR

func (l *List) IsAllowedCIDR(cidr string) (bool, error)

IsAllowedCIDR reports whether every address in cidr is permitted by the configured rules. It parses the CIDR and checks its network address against the rules. This is a simple approximation suitable for subnet membership checks.

func (*List) Middleware

func (l *List) Middleware(opts ...MWOption) func(http.Handler) http.Handler

Middleware returns an net/http middleware that enforces the IP rules.

The client IP is determined via ClientIP and checked with IsAllowed. If the client is denied, the denied handler (default: 403 JSON) is invoked. If an error occurs, the error handler (default: 500 JSON) is invoked. Allowed requests are passed to the next handler.

type MWOption

type MWOption func(*mwConfig)

MWOption configures the middleware returned by List.Middleware.

func WithDeniedHandler

func WithDeniedHandler(h http.HandlerFunc) MWOption

WithDeniedHandler sets the handler invoked when a client is denied. If unset, a default 403 JSON response is sent.

func WithErrorHandler

func WithErrorHandler(fn func(http.ResponseWriter, *http.Request, error)) MWOption

WithErrorHandler sets the handler invoked when extracting or checking the client IP fails. If unset, a default 500 JSON response is sent.

func WithSkipper

func WithSkipper(fn func(*http.Request) bool) MWOption

WithSkipper sets a function that, if it returns true for a request, bypasses the IP check entirely.

type Mode

type Mode int

Mode controls how allow and deny lists are evaluated.

const (
	// ModeAllowList is the default mode. Only IPs that match an allow CIDR
	// are permitted. Deny CIDRs always override allow CIDRs.
	ModeAllowList Mode = iota
	// ModeDenyList permits any IP that is not in a deny CIDR. Allow CIDRs
	// may be used as an optional refinement.
	ModeDenyList
)

type Option

type Option func(*config)

Option configures a List.

func Allow

func Allow(cidr string) Option

Allow adds a single allow CIDR.

func AllowAll

func AllowAll(cidrs ...string) Option

AllowAll adds multiple allow CIDRs.

func Deny

func Deny(cidr string) Option

Deny adds a single deny CIDR. Deny always wins over allow.

func DenyAll

func DenyAll(cidrs ...string) Option

DenyAll adds multiple deny CIDRs.

func WithForwardedHeader

func WithForwardedHeader(name string) Option

WithForwardedHeader sets the name of the header used to extract the forwarded client IP. Defaults to "X-Forwarded-For".

func WithMode

func WithMode(m Mode) Option

WithMode sets the evaluation mode.

func WithTrustedProxies

func WithTrustedProxies(cidrs ...string) Option

WithTrustedProxies sets the CIDRs of proxies whose X-Forwarded-For header can be trusted.