Threat model, defaults, and the framework-vs-application responsibility split for github.com/fastygo/framework. Read together with docs/ARCHITECTURE.md (the middleware order and lifecycle this document refers to) and docs/12-FACTOR.md (the env vars that toggle the defences described below).

If you discover a vulnerability, do not open a public issue. See §7 Reporting for the private disclosure path.

This document covers the framework's contribution to the security posture of an application built on top of it. The framework is a library, not a runtime: it ships hardening primitives wired into sensible defaults, but the application owns its data, its infrastructure, and its policy decisions.

In scope:

• The default HTTP middleware chain (pkg/web/security/*, pkg/web/middleware/*).
• HMAC-signed cookie sessions and the OIDC client (pkg/auth).
• The Prometheus text-format metrics endpoint (pkg/web/metrics) and health endpoints (pkg/web/health).
• The secure static-file server (pkg/web/security/staticfs.go).
• Resource lifecycle guarantees that affect denial-of-service resistance (graceful shutdown, panic recovery, cache cleanup).

Out of scope:

• Authorization logic (RBAC, ABAC, row-level filters): the framework provides typed sessions; what they grant is a feature decision.
• Cryptographic key management: the framework consumes SESSION_KEY; rotation, vaulting, and HSM integration are operational concerns.
• Network-layer protections (TLS termination, WAF, DDoS scrubbers): they belong at the edge, not in the process.
• Supply-chain vetting beyond the framework's own three-pillars rule (no unnecessary dependencies). Applications are responsible for vetting their own go.sum.

   ┌─────────────────────────────────────────────────────────────┐
   │ Untrusted network (clients, scanners, hostile bots)          │
   └──────────────────────────────┬──────────────────────────────┘
                                  │ TLS
                                  ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Trusted edge (reverse proxy / load balancer / WAF)           │  ← may set X-Forwarded-For
   └──────────────────────────────┬──────────────────────────────┘
                                  │ HTTP/1.1 keep-alive
                                  ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Application process                                          │
   │                                                              │
   │   ┌───────────────────────────────────────────────────┐      │
   │   │ Framework middleware chain  (defence in depth)    │      │
   │   │  Tracing → Metrics → RequestID → Recover →        │      │
   │   │  Headers → BodyLimit → MethodGuard → AntiBot →    │      │
   │   │  RateLimit → Logger                               │      │
   │   └───────────────────────────────────────────────────┘      │
   │                          │                                   │
   │                          ▼                                   │
   │   ┌───────────────────────────────────────────────────┐      │
   │   │ Feature handlers (application-owned trust)        │      │
   │   │   sessions, OIDC client, business logic, storage  │      │
   │   └───────────────────────────────────────────────────┘      │
   │                                                              │
   └─────────────────────────────────────────────────────────────┘

Two boundaries matter most:

1. Edge → application. The framework treats RemoteAddr as authoritative unless APP_SECURITY_TRUST_PROXY=true. When trust is opted in, ClientIP honours X-Real-IP and the first hop of X-Forwarded-For. Set this only when a trusted proxy strips client-supplied copies of those headers.
2. Middleware → handler. Everything past the middleware chain has already been validated for verb, body size, suspicious path, and rate. Handlers may assume r.Body will not exceed Config.MaxBodySize (it is wrapped in http.MaxBytesReader).

The framework defends against the threats below by default. Each row points at the package(s) that own the defence and at the mitigated attack class. Threats marked app are the application's responsibility (the framework provides plumbing, not policy).

T20–T22 are joint: the framework gives you the knobs, but only the application decides how strict the policy should be.

The defaults below are what app.New(cfg) produces with security.DefaultConfig(). Override per-deployment via APP_SECURITY_* env vars (see docs/12-FACTOR.md).

Two defaults are deliberately conservative-by-omission: the framework will not flip Secure / HTTPOnly on cookies behind your back, because doing so silently when the deployment is not yet HTTPS would appear to work and then break login. Configure both explicitly in main.

The matrix below is the contract. Anything not listed is the application's responsibility by default.

If a row reads "framework" you can rely on it without writing the code yourself. If it reads "application", the framework will not silently substitute a default — you will notice the gap during implementation.

Tick this list before exposing an application to the internet.

• SESSION_KEY is at least 32 random bytes (output of openssl rand -hex 32) and stored in a secret manager.
• OIDC_CLIENT_SECRET is delivered via the same channel; never committed to the repo.
• APP_SECURITY_HSTS=true once the entire site is HTTPS.
• APP_SECURITY_TRUST_PROXY matches the deployment topology. The default is false; set it to true only when a trusted reverse proxy strips client-supplied X-Forwarded-For / X-Real-IP.
• APP_SECURITY_CSP is set to a strict policy. As a starting point: default-src 'self'; script-src 'self' 'nonce-{nonce}'.
• APP_SECURITY_MAX_BODY_BYTES reflects your largest legitimate upload (and not more).
• APP_SECURITY_RATE_PER_IP / APP_SECURITY_RATE_BURST align with expected human traffic; monitor 429s after launch.
• HTTP_*_TIMEOUT values match your slowest legitimate request. Defaults are conservative; do not set anything to zero.

• Every auth.CookieSession literal in main.go sets Secure: true, HTTPOnly: true, and an explicit SameSite value (http.SameSiteLaxMode for typical SSR apps).
• TTL matches your idle-session policy; do not leave it unbounded.
• Secret rotation is documented for the on-call team. Rotation invalidates every active session — by design.

• All HTML is rendered via templ. Any templ.Raw or template.HTML call is reviewed for trusted input.
• Inline <script> blocks are nonce-bound (or removed) so the CSP can be 'strict-dynamic'-friendly.

• StaticDir does not contain dotfiles or source files. The SecureFileServer blocks them, but defence in depth means not putting them there in the first place.
• Build pipeline emits hashed filenames; the immutable-asset cache (max-age, immutable) is then safe.

• auth.audit events ship to a SIEM. Alert rules fire on session_tampered (Warn) and a sustained rate of session_issue_failed (Warn).
• http.panic events fire a paging alert.
• /metrics is reachable only from the scraper's network (segment via firewall or service mesh). The endpoint itself contains no secrets, but cardinality and timing data can leak operational topology.
• Health probes (/healthz, /readyz) are wired to the orchestrator; readiness includes the DB and any required upstream.

• make ci and make lint-go are required checks on the PR.
• golangci-lint is pinned to v1.64.x (matches .golangci.yml).
• govulncheck ./... runs on every release tag.
• Container base image is tracked; rebuild policy is documented.

• The process runs as a non-root user.
• The container is read-only filesystem (the framework writes no files at runtime).
• CPU/memory requests reflect the steady-state RSS. Monitor pkg/cache Stats() for unexpected cardinality, and keep Instant page snapshots within explicit byte budgets.
• Graceful shutdown is plumbed: orchestrator sends SIGTERM and waits at least HTTP_SHUTDOWN_TIMEOUT before SIGKILL.

Do not file public GitHub issues for security bugs.

Instead, contact the maintainers privately via the email on the project's GitHub profile. Please include:

• Affected version (commit SHA or tag).
• A minimal reproduction (curl invocation, snippet, or test case).
• Your assessment of impact and any suggested fix.

We aim to acknowledge within 72 hours, ship a coordinated fix, and credit reporters in the release notes (opt-out available). If a CVE is warranted, we will request one and announce via GitHub Security Advisories.

A reporter who follows this process in good faith will not face legal action from the project even if the test inadvertently touches a third-party deployment.

Material changes to the security posture are logged here in addition to CHANGELOG.md. Older changes are recorded in ADRs.

• Phase 1 (v0.1.0) — Goroutine leak hardening, panic recovery in workers, configurable HTTP timeouts, cache cleanup task. See ADR 0002.
• Phase 2 (v0.2.0) — Health/metrics endpoints with their own slim middleware chain (no scrape DoS surface), structured auth.audit events, slog correlation. See ADR 0003.
• Phase 2.5 — RequestIDMiddleware no longer depends on google/uuid; Registry.Write snapshot pattern (T29) removes scrape vs. observation contention. See CHANGELOG.md [0.2.1].