kg-header-audit

v0.1 draft. Single-binary security-headers auditor. Grades a domain (or a list of them) against an opinionated CSP/HSTS/COOP/COEP/Permissions-Policy rubric and emits either a terminal scorecard or JSON. Both CLI and HTTP-service modes.

Part of the Kinetic Gain Protocol Suite. Third Go binary in the portfolio. Designed so its output can become a Procurement Pulse measurement axis on top of the existing /.well-known/ document checks.

What it does

$ kg-header-audit https://kineticgain.com https://github.com

  target                                                        grade  score
  ────────────────────────────────────────────────────────────  ─────  ─────
  https://github.com                                            C         70
  https://kineticgain.com                                       F         20

Verbose mode shows every finding:

$ kg-header-audit --verbose https://example.com

  target                          grade  score
  ──────────────────────────────  ─────  ─────
  https://example.com             F         15
    pass      x-content-type-options       X-Content-Type-Options: nosniff
    high      hsts                         Strict-Transport-Security missing
    high      csp                          Content-Security-Policy missing
    high      clickjacking                 no X-Frame-Options or CSP frame-ancestors — clickjacking exposure
    medium    referrer-policy              Referrer-Policy missing
    info      permissions-policy           Permissions-Policy missing
    info      coop                         Cross-Origin-Opener-Policy missing
    info      coep                         Cross-Origin-Embedder-Policy missing
    info      corp                         Cross-Origin-Resource-Policy missing

JSON for piping:

kg-header-audit --json https://kineticgain.com | jq '.[0].findings[] | select(.severity == "high")'

HTTP service mode

kg-header-audit --serve --addr :8080

# single-target audit
curl ":8080/audit?target=https://kineticgain.com" | jq

# batch audit (parallel)
curl -X POST :8080/audit -d '{"targets":["https://a.example","https://b.example"]}' | jq

The batch endpoint audits all targets concurrently — Go's goroutines are why this fits a single binary instead of a worker pool.

The rubric

Scores 0–100, mapped to A/B/C/D/F. Biased toward "what a procurement reviewer cares about," not toward "what would win the OWASP leaderboard."

Check	Severity if missing	Max points
Required
Strict-Transport-Security	high	15 (+5 if preload + 1y+ max-age)
X-Content-Type-Options: nosniff	medium	10
Referrer-Policy	medium	10
X-Frame-Options OR CSP frame-ancestors	high	10
Content-Security-Policy	high	10
Strongly encouraged
Permissions-Policy	info	5
Cross-Origin-Opener-Policy	info	5
Cross-Origin-Embedder-Policy	info	5
Cross-Origin-Resource-Policy	info	5
TLS 1.3 (5pts for TLS 1.2)	—	10
Penalties
Server header discloses version	medium	-3
X-Powered-By header present	medium	-3
TLS < 1.2	critical	-10

Grades:

Grade	Range
A	90–100
B	75–89
C	60–74
D	40–59
F	<40

What's in the binary

Package	Purpose
pkg/probe	Fetches one URL via GET. Follows up to 5 redirects, 10s timeout, no body read. Captures the ten security-relevant response headers + TLS version + cipher suite.
pkg/score	Grades a ProbeResult against the rubric. Returns {Score, Grade, Findings[]}. Pure function, no I/O.
pkg/report	Renders results as JSON or as a terminal table. Same scoring drives both CLI and HTTP service.
internal/server	net/http mux: POST /audit, GET /audit, GET /healthz. Batch endpoint audits in parallel.
cmd/kg-header-audit	The binary. Two modes: --serve for the HTTP service, or pass URLs as args for the CLI.

Flags

Flag	Default	Purpose
--serve	false	Run as an HTTP service. Without this, treat positional args as URLs.
--addr	:8080	Listen address (server mode only)
--json	false	Emit JSON to stdout (CLI mode only)
--verbose	false	Show per-check findings in terminal output
--timeout	10s	Per-target probe timeout

Composes with

Repo	Role
procurement-pulse-engine	Phase 1: kg-header-audit becomes a measurement axis on Pulse Issue #6+ — "Of the 1,007 universe domains, what percentage publish a Content-Security-Policy header?"
well-known-probe-js	Sibling — checks /.well-known/* documents; this binary checks response headers. Different axis, same buyer question.
kg-token-validator	Sibling Go binary; this one runs read-only, that one enforces
kg-utm-attribution	Sibling Go binary; different vertical (marketing/GTM)

Phase 1 roadmap

• CT-log + DNS checks alongside the response-header set (CAA records, missing CT, weak DNSSEC)
• Per-domain trend store so a buyer running this in CI sees their score over time
• Pulse axis — wire the auditor into the Procurement Pulse engine so vendor security posture lands in the same quarterly issue as governance-doc publishing rate
• Custom rubric weights — buyers in regulated verticals (healthcare, gov) want to up-weight specific checks
• v1.0-prod hardening pass per the standing squad discipline

Compliance posture

Security-posture readiness scaffolding. The grade and findings support a buyer's program toward OWASP Secure Headers, NIST SP 800-218 (SSDF) practice PO.5, and CISA Hardening Guide expectations — does not by itself establish compliance with any of them. Per the standing public-language guardrail: readiness · evidence · posture · controls · scaffolding — never "secure" or "hardened" without an external attestation.

License

MIT.