HeaderCheck

Offline HTTP response header and cookie security checks.

A small Go library and CLI that reviews saved HTTP response headers and reports configuration concerns. Useful during deployment reviews, debugging and CI. No AI integration, model calls, network scanning or external dependencies are required.

Go 1.23+ · Standard library only · MIT

    +-------------------+
    | HTTP/2 200        |    H E A D E R C H E C K
    | [x] HTTPS         |    Check the headers.
    | [x] CSP           |
    | [x] Secure        |    Offline HTTP security audit
    +-------------------+

Quick start

From this project's directory:

go test ./...
go build -o bin/headercheck ./cmd/headercheck
./bin/headercheck
./bin/headercheck -scheme https testdata/headers-insecure.txt
./bin/headercheck -scheme https -fail-on medium testdata/headers-hardened.txt

CLI

./bin/headercheck -scheme https response-headers.txt
./bin/headercheck -scheme https -json -fail-on medium response-headers.txt
cat response-headers.txt | ./bin/headercheck -scheme https

The input is one response-header block, optionally starting with an HTTP status line. Repeated fields, including Set-Cookie, remain separate. Bodies, redirect chains and obsolete folded fields are rejected. Save the final response's headers separately from its body and supply its actual scheme.

Flags must precede the optional file argument. An omitted file or - reads stdin. Starting without arguments in a terminal displays ASCII art and help. Data commands keep stdout free of banners.

-fail-on high|medium|low|info|none defaults to none. Exit 0 means the requested threshold was not met; exit 1 means it was met; exit 2 signals an input, usage or I/O error. A report is still emitted with exit 1. Input is limited to 1 MiB and can be restricted further with -max-bytes.

Checks include:

Area	Examples of findings
Transport	Plaintext HTTP; unknown transport context; absent, invalid, disabled or short HSTS
Browser protection	Missing nosniff; HTML CSP script-source concerns; framing policy; permissive referrer policy
CORS	Invalid origin lists; wildcard with credentials; null origin; conditional Vary: Origin review
Cookies	Missing Secure; HttpOnly review; implicit SameSite; None/Partitioned without Secure; invalid security prefixes
Disclosure	Server/runtime headers advertising technology or versions
Redirects	An HTTPS response's Location pointing to HTTP

HTML-only checks run for text/html and application/xhtml+xml. An API is not expected to have the same document policies. Public wildcard CORS is informational; wildcard with credentials is reported as a configuration error, not a demonstrated data leak. Each CSP policy is checked separately and labeled accordingly.

Every finding has a stable code, severity, fixed subject, explanation and advice. Audit output contains no raw header values or cookie names/values. See rules and sources for interpretation.

Go API

headers, err := headercheck.ParseHeaders(strings.NewReader(rawHeaders))
if err != nil {
    return err
}
issues, err := headercheck.AuditHeaders(headers, headercheck.AuditOptions{
    Scheme: "https",
})
if err != nil {
    return err
}
if headercheck.HasSeverity(issues, headercheck.Medium) {
    // Ask for review or fail the deployment check.
}

Install the CLI with go install github.com/dc9-dev/headercheck/cmd/headercheck@latest. Import the library as github.com/dc9-dev/headercheck. This is a standalone module; no sibling project is required.

Scope

Findings are configuration hints, not proof of exploitability. A saved response cannot establish certificate validity, a server's CORS allowlist or application security. CSP analysis is per policy, not a full browser evaluator; other policies may impose further restrictions. HTML/meta policies and response bodies are outside scope.

An empty report only means these checks found nothing. Library callers should limit untrusted inputs and must not concurrently mutate supplied header maps. Parsing is bounded to 1 MiB.

Development

go test -race -cover ./...
go vet ./...
go test -run '^$' -fuzz FuzzParseHeaders -fuzztime 10s .

Contributing · Security · GitHub description · MIT license

The banner was generated with an AI image tool; its original prompt and provenance are included.