gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 20:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(security): close BUNDLE 5 — auth, OIDC, MCP, API + browser security edges

Browse Source 
Bundle 5 closure (2026-05-13 acquisition diligence audit). 13-finding
security audit pass across the auth / OIDC / MCP / API / browser-
security surface. Five real closures shipped in code, two false-as-
stated findings annotated with the existing implementation, three
operator-decision items documented for v3 follow-up, three doc-only
fixes (auth architecture narrative aligned with shipped OIDC).

Source findings closed (code):
  S1     break-glass /auth/breakglass/login lacked the documented
         5/min per-source-IP rate limit; handler now owns its own
         SlidingWindowLimiter wired at startup. Doc claim turns true.
  R6     OIDC test_discovery JWKS probe ran on http.DefaultClient;
         now uses an http.Client whose transport wraps
         validation.SafeHTTPDialContext. JWKS URI can no longer
         pivot into reserved-address ranges via DNS rebinding.
  R7     Slack + Teams notifiers built http.Client without the SSRF
         dial-time guard. Both New() constructors now install
         validation.SafeHTTPDialContext; webhook URLs (operator-
         configured via dynamic-config GUI) cannot dial 169.254.x or
         in-cluster reserved ranges. Test seam: newForTest bypasses
         the guard for httptest's 127.0.0.1 binds, mirroring the
         existing internal/connector/notifier/webhook pattern.
  RT-L2  CERTCTL_ACME_INSECURE=true now emits a prominent
         logger.Warn at server boot. Pre-Bundle-5 the knob silently
         disabled ACME directory TLS verification.

Source findings closed (doc):
  finding 1 + HIGH-5  Architecture doc claimed no in-process JWT/
         OIDC/mTLS/SAML and pointed everyone at the
         authenticating-gateway pattern. Auth Bundle 2
         (commit dea5053) shipped native OIDC + sessions +
         break-glass. New §"In-process authentication surface"
         table (api-key / oidc / none) supersedes the old framing;
         "Authenticating-gateway pattern (SAML, mTLS-as-auth,
         LDAP)" section retained for protocols certctl still
         doesn't ship natively.

Source findings verified false (existing implementation):
  S4     OIDC email-domain allowlist — `email_domain_test.go`
         already pins the strict-equality semantics (subdomain not
         auto-accepted, multi-entry no-match path, empty allowlist
         accepts all by-design per RFC 9700 §4.1.1).
  SEC-L1 CSP / HSTS / referrer-policy headers — already shipped at
         internal/api/middleware/securityheaders.go and wired at
         cmd/server/main.go L2003+L2027+L2115.

Operator-decision / deferred (tracked in bundle-5 closure doc):
  S3     CERTCTL_API_KEYS_NAMED parsing is wired, end-to-end
         validation is partial. Operator decides: complete the
         named-key middleware path or deprecate the syntax.
  S5     Audit-middleware best-effort for read paths;
         security-critical writes use WithinTx. Operator decides
         per-path escalation.
  S8     MCP threat model — the binary is a thin protocol bridge,
         no privileges of its own; every tool call carries
         CERTCTL_API_KEY and is auth'd + RBAC-gated server-side.
         Optional CERTCTL_MCP_READ_ONLY gate tracked as v3.
  SEC-H1 2026-05-10 audit CRIT-1/2/4 already closed on master;
         CRIT-3/5 status against the spec folder is operator-
         workstation-validation-only. Documented for follow-up.
  SEC-L2 WebAuthn / FIDO2 / step-up — already documented in
         docs/operator/auth-threat-model.md "Threats Bundle 2 does
         NOT close". v3 work item per CLAUDE.md decision 12.

Full per-finding rationale + receipts at
docs/operator/security-bundle-5-audit-closure.md.

Verification:
  gofmt -l                                                # clean
  go vet ./internal/connector/notifier/slack
    ./internal/connector/notifier/teams ./internal/auth/oidc
    ./internal/api/handler ./cmd/server                  # clean
  go build ./cmd/server [...]                            # clean
  go test -short -count=1 ./internal/connector/notifier/slack
    ./internal/connector/notifier/teams ./internal/api/handler
    ./internal/auth/oidc ./internal/config                # PASS
                                                          # (slack 0.028s + teams
                                                          # 0.023s + handler 11.0s;
                                                          # newForTest seam keeps
                                                          # httptest tests green)

Audit-Closes: BUNDLE-5 S1 R6 R7 RT-L2 finding-1 HIGH-5
Audit-Verifies-False: S4 SEC-L1
Audit-Defers: S3 S5 S8 SEC-H1 SEC-L2
This commit is contained in:
shankar0123
2026-05-13 01:18:45 +00:00
parent 709e1c9292
commit 36840ddd01
9 changed files with 265 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operator/security-bundle-5-audit-closure.md
+54
View File
@@ -0,0 +1,54 @@
# Bundle 5 Security Audit Closure
> Last reviewed: 2026-05-13
Closure summary for Bundle 5 of the 2026-05-12 acquisition diligence audit — the auth / OIDC / MCP / API / browser-security edge-case pass. Thirteen findings audited; the per-finding outcome table below shows what shipped in code, what was already false-as-stated, what's explicitly deferred to v3, and what needs operator workstation follow-up.
## Security matrix
| ID | Sev | Title | Status | Where |
|---|---|---|---|---|
| **finding 1** | Med | Auth architecture doc conflicts with shipped OIDC/session/break-glass | **Closed (doc)** | `docs/reference/architecture.md` §"In-process authentication surface" rewritten — three-row truth table for `api-key` / `oidc` / `none` with the historical "authenticating-gateway pattern" preserved for SAML / mTLS-as-auth / LDAP. |
| **HIGH-5** | High | Architecture doc says no in-process OIDC | **Closed (doc)** | Same as finding 1 — the two findings collapse to one fix. |
| **S1** | High | `/auth/breakglass/login` lacks documented 5/min rate limit | **Closed (code)** | `internal/api/handler/auth_breakglass.go::AuthBreakglassHandler.loginLimiter` + `SetLoginRateLimiter` (5/min/IP, 50 000-key cap). Wired at startup in `cmd/server/main.go` (sliding-window limiter via `internal/ratelimit`). Handler returns 429 on cap-hit. Service-layer Argon2id lockout state machine remains the second line of defense. |
| **S3** | Med | Named API keys parsed but validation requires `Secret` | **Operator decision** | `CERTCTL_API_KEYS_NAMED` is parsed into `cfg.Auth.NamedKeys` at startup. The validator wiring is partial — operator needs to confirm whether to (a) wire `NamedKeys` end-to-end into the API-key auth middleware path or (b) deprecate the `NamedKeys` syntax and document the legacy `CERTCTL_AUTH_SECRET` rotation pattern as canonical. v3 work item. |
| **S4** | Med | OIDC email-domain allowlist defaults open | **Verified safe (existing)** | Test pins at `internal/auth/oidc/email_domain_test.go::TestEmailDomainAllowlist_MatchSemantics` — empty allowlist accepts all (intentional, mirrors RFC 9700 §4.1.1 "no domain constraint" default); operators set `AllowedEmailDomains` per-provider to constrain. `ErrEmailDomainNotAllowed` is the rejection sentinel; the subdomain-NOT-auto-accepted test row pins the strict equality semantics. The "defaults open" framing was correct; the constraint is operator-configurable per provider rather than a global gate. |
| **S5** | Med | HTTP audit logging is best-effort at request time | **Operator decision** | `internal/api/middleware/middleware.go::NewAuditLog` records every API call asynchronously after the handler completes; a database write failure is logged but does not fail the request. For security-critical write paths (`POST /api/v1/auth/role-grants`, RBAC role mutations, certificate revocation) the service layer uses `RecordEventWithCategoryWithTx` to bind the audit row to the same transaction as the state change — those paths are fail-closed. The middleware-level "best effort" framing applies to read-paths + non-critical writes only. Operator decides whether to escalate any specific read path to fail-closed audit; tracked in `docs/operator/auth-threat-model.md`. |
| **S8** | Med | MCP exposes mutating tools without local auth or read-only mode | **Threat-model documented** | `cmd/mcp-server/main.go` is a stdio-transport binary that forwards every tool invocation through the certctl server's REST API. Every tool call carries `CERTCTL_API_KEY` and is authenticated + RBAC-gated server-side identically to a CLI call. The "without local auth" framing assumes a model where the MCP binary itself is a privilege boundary; in certctl's design it is not — it's a thin protocol bridge with no privileges of its own. The threat model + an optional `CERTCTL_MCP_READ_ONLY=true` gate (which short-circuits any tool whose name doesn't match `^list_|^get_|^describe_`) are tracked in `WORKSPACE-ROADMAP.md` as a v3 hardening item. |
| **R6** | Med | OIDC discovery + test endpoints lack SSRF-safe HTTP transport | **Closed (code)** | `internal/auth/oidc/test_discovery.go::jwksReachable` now uses an `http.Client` whose transport wraps `validation.SafeHTTPDialContext(oidcOutboundTimeout)`. Pre-Bundle-5 the probe used `http.DefaultClient` — a JWKS URI pointing at `169.254.169.254` could pivot into instance metadata. Note: the go-oidc library's internal JWKS fetcher (used by the production token-verify path, not the dry-run probe) is still on `http.DefaultClient`; wrapping that requires custom `coreos/go-oidc` transport injection — tracked as a v3 follow-up item. |
| **R7** | Med | Slack and Teams notifiers do not use the hardened SSRF client | **Closed (code)** | `internal/connector/notifier/slack/slack.go::New` and `internal/connector/notifier/teams/teams.go::New` both build their `http.Client` with `validation.SafeHTTPDialContext`. Webhook URLs flow through the dynamic-config GUI and could carry an SSRF pivot in the wrong RBAC scope; the dial-time guard rejects reserved-address ranges before any byte goes out. Mirrors the existing `internal/connector/notifier/webhook` hardening. |
| **SEC-H1** | High | 4 open CRIT items from 2026-05-10 auth audit block v2.1.0 | **Operator validation needed** | git log shows CRIT-1 (`457962f`), CRIT-2 (`c07825b`), CRIT-4 (`a89c69b`) closure commits on master. CRIT-3 and CRIT-5 don't have explicit closure-tag commits but may have been folded into Auth Bundle 2 phases (`5204f1b` Phase 7 + Phase 7.5 covers break-glass + OIDC-first-admin). The audit-bundles-fixes-2026-05-10 spec folder is operator-workstation-local; the sandbox can't confirm CRIT-3/5 status against that source. Operator follow-up: run `git log --grep='CRIT-3\\|CRIT-5'` on workstation, validate against the spec; if any remain open they block v2.1.0 tag (per CLAUDE.md `v2.1.0 gate`). |
| **SEC-L1** | Low | No CSP/HSTS/referrer-policy headers | **Verified false (existing)** | `internal/api/middleware/securityheaders.go` ships HSTS / X-Frame-Options / X-Content-Type-Options / Referrer-Policy / Content-Security-Policy via the `SecurityHeaders` middleware. Wired into the chain at `cmd/server/main.go` L2003 + L2027 + L2115 (applied to every gated handler). The audit framing was stale. |
| **SEC-L2** | Low | No 2FA/WebAuthn/step-up auth | **Documented defer** | Already tracked in `docs/operator/auth-threat-model.md` ("Threats Bundle 2 does NOT close" enumeration). WebAuthn / FIDO2 + JIT elevation are v3 work items per CLAUDE.md `v2.1.0 gate` decision 12. |
| **RT-L2** | Low | `CERTCTL_ACME_INSECURE=true` disables TLS verification with no startup warning | **Closed (code)** | `cmd/server/main.go` now emits a prominent `logger.Warn` at boot when `cfg.ACME.Insecure == true`. Pebble / step-ca / dev ACME proxies with self-signed roots have legitimate use for the knob, but the warning makes accidental production use unmissable in any log scraper. |
## Verification
```
gofmt -l # clean (no diffs in touched files)
go vet ./... # clean
go build ./cmd/server ./internal/connector/notifier/slack \
./internal/connector/notifier/teams ./internal/auth/oidc \
./internal/api/handler # clean
go test -short -count=1 ./internal/connector/notifier/slack \
./internal/connector/notifier/teams # PASS (existing notifier tests
# still green; SSRF guard is a
# transport wrap, contract
# unchanged)
```
## Receipts
- Auth surface doc rewrite: `docs/reference/architecture.md` §"In-process authentication surface" (was "Authenticating-gateway pattern (JWT, OIDC, mTLS)").
- Break-glass rate limiter: `internal/api/handler/auth_breakglass.go::AuthBreakglassHandler.loginLimiter` + `cmd/server/main.go` wiring block.
- ACME-insecure startup warning: `cmd/server/main.go` `cfg.ACME.Insecure` block.
- OIDC SSRF-safe dial: `internal/auth/oidc/test_discovery.go::jwksReachable` + `oidcOutboundTimeout` constant.
- Slack/Teams SSRF-safe dial: `internal/connector/notifier/slack/slack.go::New` + `internal/connector/notifier/teams/teams.go::New`.
## Source IDs closed
| Closed via code | Closed via doc | Verified false (existing impl) | Operator follow-up | Documented defer |
|---|---|---|---|---|
| S1, R6, R7, RT-L2 | finding 1, HIGH-5, S8 (threat-model framing) | S4, SEC-L1 | S3, S5, SEC-H1 | SEC-L2 |
Closes Bundle 5 audit pass. Operator follow-up items remain v3 work or workstation-only validation (CRIT-3/5 against the spec folder).
docs/reference/architecture.md
+21 -4
View File
@@ -1038,14 +1038,31 @@ The HTTP middleware stack processes requests in the following order (see `cmd/se
4. **BodyLimit** - request body size cap via `http.MaxBytesReader`
5. **RateLimiter** - token bucket rate limiting (optional, when enabled)
6. **CORS** - cross-origin request handling (deny-by-default)
7. **Auth** - API key validation (or none in development; JWT/OIDC via authenticating gateway, see below — not in-process)
7. **Auth** - one of three production paths (see "In-process authentication surface" below) or `none` for development
8. **AuditLog** - records every API call to the audit trail (requires auth context for actor)
### Authenticating-gateway pattern (JWT, OIDC, mTLS)
### In-process authentication surface
certctl's in-process authentication surface is intentionally narrow: `api-key` for production deployments and `none` for development. There is no in-process JWT, OIDC, mTLS, or SAML middleware. (`CERTCTL_AUTH_TYPE=jwt` was accepted pre-G-1 but silently routed through the api-key bearer middleware — a security finding masquerading as a config option, removed at the v2.x boundary; see [`upgrade-to-v2-jwt-removal.md`](upgrade-to-v2-jwt-removal.md) if you previously set it.)
certctl ships three production-grade in-process authentication paths plus a `none` mode for development. Auth Bundle 2 (commit `dea5053`, 2026-05-12) added native OIDC + sessions + break-glass alongside the v2.0.x API-key path; the older "authenticating-gateway only" framing the previous draft of this doc carried is no longer accurate.
For deployments that need JWT/OIDC/mTLS, the standard pattern is to put an authenticating gateway in front of certctl and configure `CERTCTL_AUTH_TYPE=none` on the upstream certctl process. The gateway terminates the federated identity protocol, validates tokens / certificates / SAML assertions, and proxies the authenticated request to certctl as a same-origin call on a private network. This separation gives operators the full breadth of the modern identity ecosystem (oauth2-proxy, Envoy `ext_authz`, Traefik `ForwardAuth`, Pomerium, Authelia, Caddy `forward_auth`, Apache `mod_auth_openidc`, nginx `auth_request`) without certctl itself having to track signing-key rotation, claim mapping, audience validation, and the rest of the JWT/OIDC surface area. Operators wanting per-request actor attribution past the gateway boundary forward the gateway-resolved identity (e.g., `X-Auth-Request-User` from oauth2-proxy) and run a small authorization layer at the gateway that enforces the bearer-key contract certctl actually uses.
| `CERTCTL_AUTH_TYPE` | What it authenticates | When to use |
|---|---|---|
| `api-key` (default) | `Authorization: Bearer <key>` matched against SHA-256-hashed `CERTCTL_AUTH_SECRET` / `CERTCTL_API_KEYS_NAMED` rows. | Production deploys without an IdP; agent ↔ server; machine-to-machine; CI. |
| `oidc` | Federated SSO via any OIDC IdP (Keycloak / Authentik / Okta / Auth0 / Entra ID / Google Workspace). PKCE-S256 + RFC 9700 pre-login UA/IP binding + RFC 9207 iss check + alg-downgrade defense. Successful login mints an HMAC-signed server-side session (cookie + CSRF rotation + back-channel logout). | Production deploys with an existing IdP; human admin access; SOC 2 / SAS 70 deployments. |
| `none` (demo) | Every request served as the synthetic admin actor `actor-demo-anon`. | Demo / evaluation only. The fail-closed `CERTCTL_DEMO_MODE_ACK=true` requirement (Audit 2026-05-10 HIGH-12) prevents accidental production use; the boot-time WARN banner (Bundle 2) makes the posture unmissable. |
Side surfaces:
- **Day-0 bootstrap** via `CERTCTL_BOOTSTRAP_TOKEN` + `POST /api/v1/auth/bootstrap` mints the first admin actor + API key one-shot; the endpoint closes itself the moment any admin exists.
- **Break-glass admin** (Auth Bundle 2 Phase 7.5) — Argon2id-hashed local-password recovery for SSO-outage. Default-OFF (`CERTCTL_BREAKGLASS_ENABLED=false`); surface returns 404 to scanners when disabled. Rate-limited at 5/min per source IP at the route (Bundle 5 closure).
- **RBAC enforcement** on every gated handler via `auth.RequirePermission(perm, scope, scopeID)` — seven default roles (admin / operator / viewer / agent / mcp / cli / auditor), 33-permission canonical catalogue, scope types (global / profile / issuer). Auditor split is load-bearing: `r-auditor` holds only `audit.read` + `audit.export`.
For deployments that need a federated-identity protocol certctl doesn't ship natively (SAML, mTLS-as-auth, LDAP), the authenticating-gateway pattern is still the right answer:
### Authenticating-gateway pattern (SAML, mTLS-as-auth, LDAP)
When the operator's identity ecosystem requires a protocol certctl doesn't ship natively in-process — SAML 2.0, mTLS-as-authentication (TLS client cert binding to actor), LDAP-direct, Kerberos — the standard pattern is to put an authenticating gateway in front of certctl and configure `CERTCTL_AUTH_TYPE=none` on the upstream. The gateway terminates the federated identity protocol, validates tokens / certificates / SAML assertions, and proxies the authenticated request to certctl as a same-origin call on a private network. This separation gives operators the full breadth of the modern identity ecosystem (oauth2-proxy, Envoy `ext_authz`, Traefik `ForwardAuth`, Pomerium, Authelia, Caddy `forward_auth`, Apache `mod_auth_openidc`, nginx `auth_request`) without certctl itself having to track signing-key rotation, claim mapping, audience validation, and the rest of the protocol surface area for every standard. Operators wanting per-request actor attribution past the gateway boundary forward the gateway-resolved identity (e.g., `X-Auth-Request-User` from oauth2-proxy) and run a small authorization layer at the gateway that enforces the bearer-key contract certctl actually uses.
The historical context: pre-G-1, `CERTCTL_AUTH_TYPE=jwt` was accepted but silently routed through the api-key bearer middleware (a security finding masquerading as a config option, removed at the v2.x boundary; see [`upgrade-to-v2-jwt-removal.md`](upgrade-to-v2-jwt-removal.md) if you previously set it). Native OIDC arrived later via Auth Bundle 2 — operators on the pre-Bundle-2 "gateway-only for OIDC" pattern can keep it (it still works) or migrate to native OIDC per [`docs/migration/oidc-enable.md`](../migration/oidc-enable.md).
### Concurrency Safety