secure

Secure is a lightweight HTTP middleware for Go’s standard net/http package that helps developers apply common security headers to their web applications with minimal configuration. It implements the http.Handler interface directly, so it can be dropped into net/http, chi, Negroni, Gin, or virtually any router/framework that accepts http.Handler middleware. Rather than requiring hand-written boilerplate for each header, Secure exposes a single Options struct covering HSTS, X-Frame-Options, Content-Type sniffing protection, XSS filtering, CSP, referrer policy, and several newer cross-origin isolation headers.

Beyond header injection, Secure handles allowed-host validation (with optional regex matching), forced HTTPS redirects with configurable proxy header support, and per-request CSP nonce generation via a dedicated cspbuilder helper package. Because it ships as a single dependency-free Go module with a stable v1 API since 2014, teams add it once and rarely touch it again, making it a common first line of defense in production Go services behind reverse proxies like Nginx or Traefik.

What You Get

• Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, and CSP headers configurable through one Options struct
• Automatic HTTP-to-HTTPS redirection with proxy-header awareness for apps behind load balancers
• Allowed-host validation with optional regex matching to block Host-header spoofing
• A dedicated cspbuilder sub-package for composing Content-Security-Policy directives programmatically
• Per-request CSP nonce generation retrievable from the request context

Common Use Cases

• Adding baseline OWASP security headers to a new Go API or web service without hand-rolling each one
• Enforcing HTTPS and blocking Host-header attacks for services sitting behind Nginx, Traefik, or another reverse proxy
• Building and rotating per-request CSP nonces for inline scripts in server-rendered Go applications
• Retrofitting security headers onto an existing net/http, chi, or Negroni application with a single middleware wrap

Under The Hood

Architecture Secure is a single-file middleware (secure.go) implementing http.Handler through a functional wrapper pattern — Handler, HandlerForRequestOnly, HandlerFuncWithNext, and HandlerFuncWithNextForRequestOnly all delegate to a private processRequest method that returns computed headers, a possibly-modified request, and an error. Headers are either written immediately or stashed in the request context under a typed key (ctxSecureHeaderKey) for deferred application, letting the same core logic serve plain net/http, Negroni-style next-func middleware, and reverse-proxy response rewriting (ModifyResponseHeaders) without duplicating header logic. CSP nonce generation lives in its own file (csp.go) behind a typed context key, and CSP directive-string assembly is factored out entirely into the cspbuilder sub-package so consumers who want programmatic CSP construction don’t need to hand-format strings. There’s no external state beyond the Options struct and a couple of derived fields (compiled regex allowed-hosts, resolved context key), so extending the middleware with a new header means adding a field, a constant, and a branch inside processRequest.

Tech Stack go.mod declares go 1.13 with zero third-party dependencies (go.sum is empty) — the package uses only the standard library (net/http, regexp, context, crypto/rand, encoding/base64, strings, fmt). CI runs a golangci-lint job plus a test matrix spanning Go 1.21 through 1.26 on Ubuntu via a small Makefile (make ci). Distribution is purely as a Go module (import path github.com/unrolled/secure) alongside the cspbuilder sub-package for CSP directive composition.

Code Quality secure_test.go alone contains dozens of test functions covering nearly every Options permutation (allowed hosts, regex hosts, SSL redirect variants, proxy headers, STS combinations, CSP with and without nonce, AllowRequestFunc, custom bad-request/bad-host handlers), and the cspbuilder sub-package carries its own extensive test suite — an unusually high test-to-code ratio for a codebase this size. Error handling is explicit: processRequest returns a plain error on every rejection path (bad host, SSL redirect, disallowed request) rather than panicking or swallowing, with the single panic() in New() reserved for a genuinely unrecoverable case (an invalid regex supplied by the caller at startup). golangci-lint runs in CI on every push and pull request alongside the Go-version test matrix, and //nolint suppressions are used sparingly with inline justification.

What Makes It Unique Secure doesn’t invent new headers or protocols — every header it sets (HSTS, CSP, X-Frame-Options, COOP/COEP/CORP, Permissions-Policy) is a standard browser security header. What’s distinctive is the deferred-header pattern that lets identical core logic serve plain net/http, Negroni-style next() middleware, and proxied-response rewriting via ModifyResponseHeaders for httputil.ReverseProxy — a clever but narrow generalization rather than a novel technique overall.