guard

Documentation

Overview

Package guard keeps a local admin page local. The page has no login: it listens on loopback only, answers only to a loopback Host (DNS rebinding), refuses writes another site started (CSRF), caps request bodies, and runs on an http.Server with timeouts that a slow client cannot hold open.

Index

• Constants
• func CrossSite(r *http.Request) bool
• func Handler(next http.Handler, opts Options) http.Handler
• func HostAllowed(host, expected string) bool
• func ListenAndServe(ctx context.Context, addr string, h http.Handler, ready func(host string)) error
• func LoopbackAddr(addr string) error
• func Serve(ctx context.Context, srv *http.Server, l net.Listener) error
• func Server(h http.Handler, writeTimeout time.Duration) *http.Server
• type Options

Constants

const MaxBody = 16 << 10

MaxBody is the default request body cap: forms on these pages are a few fields.

Functions

func CrossSite

func CrossSite(r *http.Request) bool

CrossSite reports whether another site started the request. Browsers send Sec-Fetch-Site on every request, and it wins when present: under a strict referrer policy a same-origin form still sends Origin: null. same-site is refused too, since another port on this machine is the same site. Without it, an Origin naming a foreign host is enough to refuse.

func Handler

func Handler(next http.Handler, opts Options) http.Handler

Handler wraps next with the Host check, the cross-site check on writes, the security headers, and the body cap. A POST form is parsed here, so a body over the cap is a 413 rather than a form read as empty.

func HostAllowed

func HostAllowed(host, expected string) bool

HostAllowed reports whether a browser addressed this page by a name that cannot be an attacker's. DNS rebinding lets an attacker-controlled name resolve to 127.0.0.1, and in that attack the browser still sends the foreign Host it was told to use, so the Host must be the address the server was started on, or a loopback literal, which no public DNS name can be. It is not meant to stop a local process that forges Host; that process already has the port.

func ListenAndServe

func ListenAndServe(ctx context.Context, addr string, h http.Handler, ready func(host string)) error

ListenAndServe checks addr is loopback, listens, reports the bound address (the port may have been 0) to ready, then wraps h with Handler and serves until ctx ends.

func LoopbackAddr

func LoopbackAddr(addr string) error

LoopbackAddr refuses a listen address that is not loopback, so the page, and the credentials behind it, never reach the network.

func Serve

func Serve(ctx context.Context, srv *http.Server, l net.Listener) error

Serve serves srv on l until ctx ends, then shuts down with a 5s grace.

func Server

func Server(h http.Handler, writeTimeout time.Duration) *http.Server

Server is an http.Server with timeouts for a local page. WriteTimeout is long because a page may wait on remote APIs; pass a shorter one if not.

Types

type Options

type Options struct {
	// Host is the address the server listens on; a request naming it is
	// always accepted. Loopback literals and localhost are accepted too.
	Host string
	// MaxBody caps a request body; 0 means MaxBody.
	MaxBody int64
	// Headers sets the response headers; nil means toolshell.SetHeaders.
	Headers func(http.Header)
}

Options tunes Handler.