Defender's Handbook ↔ Grit

Grit's scaffolded Docker setup exposes only port 8080 for the API and lets the reverse proxy terminate everything else. The SecurityHeaders middleware strips identifying server banners:Server and X-Powered-By never appear in responses, so version-to-CVE lookup is starved.

Sentinel WAF's Anomaly module flags fast sequential probes (the canonical scan signature) and the IP lands in the dashboard's suspicious-actors list. In production mode rate-limiting kicks in after the first burst.

APP_ENV=production            # release-mode Gin, no debug banners
SENTINEL_ENABLED=true
SENTINEL_TRUSTED_PROXIES=10.0.0.0/8   # trust the LB, no one else

Every admin route lives behind middleware.RequireRoles("admin") and returns 404 — not 403 — when access is denied, so brute-force tools can't distinguish "does exist, you're blocked" from "doesn't exist". No path leaks via status code.

Sentinel rate-limits requests per IP (default: 100/min) and triggers AuthShield lockouts on high-velocity 401/404 patterns. The WAF's ruleset already blocks dotfile probes (/.git/, /.env, .bak, .swp) by default.

admin := api.Group("/admin")
admin.Use(middleware.RequireRoles("admin"))   // role gate
{
    admin.GET("/users", ...)   // brute-forcer sees 404, never 403
}

Sentinel rate-limits /api/auth/login to 5 attempts / 15 min per IP. After repeated failures, AuthShield places the account in a cool-down window per user, not just per IP — defeating distributed brute-force from a botnet.

RateLimit: sentinel.RateLimitConfig{
    Enabled: true,
    ByIP:    &sentinel.Limit{Requests: 100, Window: time.Minute},
    ByRoute: map[string]sentinel.Limit{
        "/api/auth/login": {Requests: 5, Window: 15 * time.Minute},
    },
},
AuthShield: sentinel.AuthShieldConfig{
    Enabled: true,
    LoginRoute: "/api/auth/login",
},

The handler returns the literal string "invalid credentials" whether the email exists, the password is wrong, or the account is locked. The response time is equalised by always running bcrypt.CompareHashAndPassword against either the real hash or a precomputed dummy hash, so the timing channel is closed too.

if err := db.First(&user, "email = ?", payload.Email).Error; err != nil {
    bcrypt.CompareHashAndPassword(dummyHash, []byte(payload.Password))   // constant-time
    c.JSON(401, gin.H{"error": gin.H{"code":"INVALID_CREDENTIALS","message":"invalid credentials"}})
    return
}

Three layers ship by default. First, TOTP 2FA via internal/totp — a leaked password isn't enough. Second, Sentinel's Anomaly module flags repeated logins with bot-shaped headers. Third, the user model exposes an optional BreachedPasswordCheck hook that you can wire to an offline copy of HaveIBeenPwned's k-anonymity API at registration / password change.

Grit's production Docker setup never exposes the API container directly — only the reverse-proxy (Traefik / Caddy / nginx) faces the internet. The scaffolded docker-compose.prod.yml binds Postgres and Redis to 127.0.0.1 so they aren't reachable from outside the host even if the firewall is misconfigured.

For server access, the scaffold's deploy guide (/docs/infrastructure/deployment) defaults to SSH-key-only authentication, with password auth disabled in the recommended sshd_config.

Closed at the protocol level by GORM. Every Where, First, Create, Update, and db.Raw uses parameterised queries. The Grit codebase has zero string-concatenated SQL.

// OK — parameterised
db.Where("email = ?", email).First(&user)
db.Raw("SELECT * FROM users WHERE email = ?", email).Scan(&user)

// NEVER do this
db.Raw("SELECT * FROM users WHERE email = '" + email + "'")

The DB account used by the API is created via docker-compose.prod.yml with the minimum privileges needed — no SUPERUSER, no CREATE on other schemas. Sentinel WAF's SQLi ruleset gives a second layer if a custom db.Raw ever slips a hostile string in.

Errors never leak. The error handler returns the generic { "code": "INTERNAL_ERROR" } envelope in production — no SQL fragments, no driver messages, no DB column hints reach the client.

Grit only hashes passwords with bcrypt via golang.org/x/crypto/bcrypt. Verify is constant-time. The library default cost (10) is rotated up by internal/auth.RehashIfWeak on successful login, so when the recommended cost moves to 12 the next time a user signs in their hash upgrades silently.

hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
// ...
err := bcrypt.CompareHashAndPassword(user.PasswordHash, []byte(payload.Password))

bcrypt generates and stores a unique 16-byte salt per password as part of the hash output. Two identical passwords produce two different hashes. Rainbow tables are useless against the column.

v3.25.1 generates a 32-byte hex JWT_SECRET (64 characters) at scaffold time via crypto/rand — no more shipping with your-super-secret-jwt-key-change-in-production. The config loader refuses to boot if the secret is shorter than 32 characters. The verifier pins the signing algorithm so the alg:none attack is impossible.

Grit's TOTP module stores the seed encrypted with AES-GCM, keyed by a derivative of JWT_SECRET. SQLi or a DB dump leaks only ciphertext — useless without the env-var key, which lives outside the database. The decryption happens at the moment of code verification and the plaintext seed never lands in any log.

func (s *Store) StoreSeed(userID, seed string) error {
    encrypted, err := s.aead.Seal(nil, nonce, []byte(seed), nil)
    // ...
    return s.db.Save(&UserTOTP{UserID: userID, EncryptedSeed: encrypted}).Error
}

SMS-OTP is intentionally not a built-in factor in Grit. The scaffolded internal/totp module is app-based TOTP only. The doc'd 2FA upgrade path is FIDO2 / WebAuthn passkeys via the planned internal/webauthn package — phishing-resistant and bound to the real site's origin, defeating both SIM swap and real-time proxy phishing.

Three controls ship today. (1) Session cookies are HttpOnly, Secure, SameSite=Strict. (2) JWTs are bound to a device fingerprint at issue time — token reuse from a different UA / IP family triggers a forced re-auth via the Anomaly module. (3) Access tokens are short-lived (15 min); the refresh ceremony re-validates the fingerprint.

Server-side, Grit can't stop the click — but it can stop the consequences from spreading. The scaffolded jobs/worker.go and main.go never run as root. The Docker setup uses an unprivileged grit user inside the container; the host firewall config in docs/infrastructure/deployment blocks all inbound except 80/443. internal/storage never executes uploaded files — uploads go to object storage by content-hash filename, no execution bit.

Grit's production Docker network is egress-filtered by default: the API container can talk to Postgres + Redis + the AI Gateway + the configured S3 endpoint, and nothing else. A reverse shell trying to call out to a random IP gets a packet-drop instead of a TCP handshake. The compose file:

api:
  networks: [internal]
networks:
  internal:
    driver: bridge
    internal: false   # we toggle this to true when you list explicit egress hosts

Grit's admin / web apps never invite browser password autofill for the Sentinel and Pulse dashboards — both surfaces use autocomplete="off" on credential inputs and ship hardware-key prompts where the password manager would normally pop. Recommended: route admin auth through SSO (Auth0 / WorkOS / Clerk) so the local credential cache never holds valid material.

SecurityHeaders middleware emits Strict-Transport-Security: max-age=63072000; includeSubDomains; preload the moment the connection lands on TLS. The Grit deploy guide submits the production domain to the Chrome HSTS preload list so even the first-ever request never sees plain HTTP.

The scaffolded Traefik / Caddy templates auto-issue Let's Encrypt certs and enforce TLS 1.2+ with the Mozilla Modern cipher suite — TLS 1.0 / 1.1 and weak ciphers are disabled.

Web-side defence is the same as SSL stripping above: HSTS+preload makes the browser refuse to talk HTTP no matter what DNS or AP it's on. Any cert that doesn't match preload-pinned settings triggers a hard fail — no "proceed anyway" button.

Layered: Sentinel does per-IP and per-route rate limiting at app level. The deploy guide puts Cloudflare (or BunnyShield) in front of the origin for L3/L4 absorption — a free Cloudflare account stops volumetric floods you'd never survive at the origin.

Pulse's real-time metrics dashboard at /pulse/ui exposes p50/p95/p99 latency, RPS, and per-route 4xx/5xx rates so the on-call sees the spike before the customer does. Hook the alerts webhook to PagerDuty / Slack and you're paged within seconds.

Grit's production Docker runs as an unprivileged user (added in v3.25 review patch). The Postgres role used by the API hasCREATE only on its own schema, no SUPERUSER, and no read access to pg_authid. Role-based access in app code uses middleware.RequireRoles — every privileged route is explicit, none are gated by "is-authenticated" alone.

middleware.LogSecurityEvent(ctx, db, userID, event, ip, ua) writes typed events (login, logout, password change, role change, AuthZ denial, suspicious request, TOTP enable/disable, account lock) into the tamper-evident activity log — every row stores a SHA-256 hash of the previous row + its canonical fields, so retroactive deletion breaks the chain at verification time. Use this for SOC 2 / ISO 27001 / GDPR audits.

Alerts route through Sentinel webhooks to Slack / PagerDuty / email for spikes in failed logins, AuthZ denials, or WAF blocks. The dashboard at /sentinel/ui shows everything in real time.

Every scaffolded project ships:

• .github/dependabot.yml — weekly PRs for Go modules, npm, and GitHub Actions.
• .github/workflows/security.yml — runs govulncheck (Go CVE DB) + pnpm audit (high+ gate) + CodeQL static analysis on every PR and weekly.
• go.sum checksum verification on every go mod command and pnpm install --frozen-lockfile in CI — a supply-chain typosquat or compromised tag fails the build.

No secret ever lives in code. .env is in .gitignore from the first commit; the scaffold ships only .env.example. As of v3.25.1 every fresh .env ships with crypto-random JWT_SECRET, SENTINEL_SECRET_KEY, SENTINEL_PASSWORD, and PULSE_PASSWORD — no "change-me-in-production" placeholders that someone forgot to change.

Production deploys are documented to read from a secrets manager (AWS Secrets Manager, Doppler, Infisical, Vault) via the same env-var interface — no app-code change needed to move from .env to a vault.