From 977cdbdf44f45279598f28ecad2d9e9812152bad Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Sun, 10 May 2026 02:18:42 +0000 Subject: [PATCH] docs(README): surface Bundle 1 RBAC + signal Bundle 2 federation as roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pre-fix the README said nothing about role-based access control, the auditor role, the day-0 bootstrap path, or the four-eyes approval workflow — all shipped in Bundle 1 (commit 22c4971 + follow-ons). A prospective adopter landing on the README would read "API key auth enforced by default" and walk away thinking certctl had no authz primitive at all. The only OIDC reference was the cosign-keyless line at the artefact-signing section, unrelated to authentication. Three surgical edits: 1. Status block: extend the "production-quality core" enumeration with role-based authz, auditor split, day-0 bootstrap, four-eyes approval. Add a one-line callout that federated identity (OIDC, SAML, WebAuthn, server-side sessions, break-glass, JIT elevation) is roadmap-not-shipped — preempts the natural-but- wrong assumption that "RBAC means OIDC works". The two terms are linked inline: - "role-based authz" -> docs/operator/rbac.md (operator how-to: role table, permission catalogue, scope semantics, GUI/CLI/ HTTP/MCP grant flows, day-0 bootstrap). - "Federated identity" -> docs/operator/auth-threat-model.md #threats-bundle-1-does-not-close (canonical place where deferred Bundle-2 work is enumerated). Keeps the roadmap promise honest: a skeptic can click through to the explicit deferred-work list rather than taking prose at face value. 2. "What it does" feature list: insert a new bullet right after the approval-workflow bullet covering the 7 default roles, the 33- permission canonical catalogue, scope semantics, the auditor read-only invariant, the bootstrap path, and the privilege-escalation guard. Cross-links to docs/operator/rbac.md, the threat model, and the v2.0.x → v2.1.0 migration guide. 3. Security paragraph: replace "API key auth enforced by default with SHA-256 hashing and constant-time comparison" with the Bundle-1 reality — auth + RBAC + auditor + bootstrap + privilege- escalation guard — keeping the rest of the paragraph (CORS, SSRF, encryption-at-rest, TLS-1.3, audit trail, CI gates) unchanged. Verified: Both link targets exist on disk (docs/operator/rbac.md, docs/operator/auth-threat-model.md). Threat-model anchor heading "## Threats Bundle 1 does NOT close" is intact (line 138). All 24 ci-guards pass locally including S-1 (no hardcoded source counts re-introduced) and G-3 (no env-var docs drift). Updates the README to match Bundle 1's actually-shipped surface and to set honest expectations about Bundle 2 (federated identity) being the next slice, not yet landed. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 06f4649..e72ad44 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ certctl is a self-hosted platform that automates the entire TLS certificate life The CA/Browser Forum's [Ballot SC-081v3](https://cabforum.org/2025/04/11/ballot-sc081v3-introduce-schedule-of-reducing-validity-and-data-reuse-periods/) caps public TLS certificates at **200 days by March 2026**, **100 days by 2027**, and **47 days by 2029**. At 47-day lifespans, a team managing 100 certificates is processing 7+ renewals per week, every week, forever. Manual workflows stop being a choice. -> **Status: Early-access.** Production-quality core (Local CA, ACME, agent deployment, CRUD, audit) with broader feature surface (intermediate CA hierarchy, ACME/SCEP/EST servers, network appliances) still maturing. Lab and dev deployments encouraged; production deployments welcome with the understanding that customer-scale battle-testing is in progress. File GitHub issues for any rough edges. +> **Status: Early-access.** Production-quality core (Local CA, ACME, agent deployment, CRUD, audit, [role-based authz](docs/operator/rbac.md) with auditor split + day-0 bootstrap + four-eyes approval) with broader feature surface (intermediate CA hierarchy, ACME/SCEP/EST servers, network appliances) still maturing. [Federated identity](docs/operator/auth-threat-model.md#threats-bundle-1-does-not-close) (OIDC/SAML/WebAuthn, server-side sessions, break-glass accounts, JIT elevation) is the next slice on the roadmap, not yet shipped. Lab and dev deployments encouraged; production deployments welcome with the understanding that customer-scale battle-testing is in progress. File GitHub issues for any rough edges. > **Actively maintained, shipping weekly.** [Open an issue](https://github.com/certctl-io/certctl/issues) if something breaks. CI runs the full test suite with race detection, static analysis, and vulnerability scanning on every commit. @@ -64,7 +64,8 @@ certctl handles the full certificate lifecycle in one self-hosted control plane: - **Run as a SCEP server** for Microsoft Intune-managed phones, ChromeOS devices, network appliances. RFC 8894 native with full PKIMessage wire format, native Intune challenge dispatch with replay protection, per-profile dispatch with separate RA cert per profile. See [`docs/reference/protocols/scep-server.md`](docs/reference/protocols/scep-server.md). - **Run as an EST server** for HTTPS-based PKCS#10 enrollment. 802.1X / Wi-Fi authentication, IoT device enrollment, RFC 9266 channel binding. See [`docs/reference/protocols/est.md`](docs/reference/protocols/est.md). - **Manage multi-level CA hierarchies** with name constraints, path-length enforcement, and end-to-end RFC 5280 path validation. Root → intermediate → issuing chains, admin-gated CRUD, drain-first retirement. Patterns documented for 4-level boundary CAs, 3-level policy CAs with per-BU `PermittedDNSDomains`, and 2-level internal PKI. See [`docs/reference/intermediate-ca-hierarchy.md`](docs/reference/intermediate-ca-hierarchy.md). -- **Gate high-stakes issuance** behind two-person-integrity approval. Flag a profile as `RequiresApproval`, the request lands in a queue, a non-requester approves, the scheduler dispatches. See [`docs/operator/approval-workflow.md`](docs/operator/approval-workflow.md). +- **Gate high-stakes issuance** behind two-person-integrity approval. Flag a profile as `RequiresApproval`, the request lands in a queue, a non-requester approves, the scheduler dispatches. Profile-edit changes on approval-tier profiles route through the same gate so the flip-flop bypass is closed. See [`docs/operator/approval-workflow.md`](docs/operator/approval-workflow.md). +- **Authorize with role-based access control.** Seven default roles (admin, operator, viewer, agent, mcp, cli, auditor) over a 33-permission canonical catalogue with global / per-profile / per-issuer scope. Auditor role is read-only on the audit trail (`audit.read` + `audit.export`, nothing else) so a regulator's key cannot read certificates or mutate config. Day-0 admin via a one-shot `CERTCTL_BOOTSTRAP_TOKEN` endpoint that closes itself the moment any admin lands. Privilege-escalation guard requires `auth.role.assign` to grant or revoke a role. See [`docs/operator/rbac.md`](docs/operator/rbac.md), [`docs/operator/auth-threat-model.md`](docs/operator/auth-threat-model.md), and the v2.0.x → v2.1.0 [migration guide](docs/migration/api-keys-to-rbac.md). - **Discover** existing certs across your fleet via filesystem scanning on agents, network TLS probing across CIDR ranges, and cloud secret manager imports (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager). Triage workflow for claim / dismiss / investigate. - **Revoke** with full RFC 5280 reason codes, DER CRL generation per issuer (scheduler-pre-generated and ETag-cached), and an embedded RFC 6960 OCSP responder with dedicated per-issuer responder certs. Single + bulk revocation. See [`docs/reference/protocols/crl-ocsp.md`](docs/reference/protocols/crl-ocsp.md). - **Alert** via Slack, Microsoft Teams, PagerDuty, OpsGenie, email, webhooks. Per-policy multi-channel routing matrix with severity tiers and fault-isolating per-channel dispatch. See [`docs/operator/runbooks/expiry-alerts.md`](docs/operator/runbooks/expiry-alerts.md). @@ -74,7 +75,7 @@ certctl handles the full certificate lifecycle in one self-hosted control plane: Go 1.25 control plane with handler → service → repository layering. PostgreSQL 16 backend (35+ tables, idempotent migrations). Pull-only deployment model — the server never initiates outbound connections. Agents poll for work and generate ECDSA P-256 keys locally so private keys never touch the control plane. For network appliances and agentless servers, a proxy agent in the same network zone handles deployment via the target's API (WinRM, iControl REST, SSH/SFTP). See the [Architecture Guide](docs/reference/architecture.md) for full system diagrams. -Security: API key auth enforced by default with SHA-256 hashing and constant-time comparison. CORS deny-by-default. Shell injection prevention on all connector scripts. SSRF protection (reserved IP filtering) on the network scanner. Issuer and target credentials encrypted at rest with AES-256-GCM. HTTPS-only control plane with TLS 1.3 pinned and a fail-closed startup gate that refuses to boot if the TLS bundle is unusable. Every API call recorded to an immutable audit trail with actor attribution, body hash, and latency tracking. CI runs race detection, 11 linters, and vulnerability scanning on every commit. See [`docs/operator/security.md`](docs/operator/security.md) for the operator-facing security posture. +Security: API-key authentication with SHA-256 hashing + constant-time comparison, then role-based authorization on every gated handler with global / per-profile / per-issuer scope. Auditor split keeps regulator-class actors strictly read-only on the audit trail. Day-0 admin via a one-shot bootstrap token; granting or revoking roles requires the dedicated `auth.role.assign` permission. CORS deny-by-default. Shell injection prevention on all connector scripts. SSRF protection (reserved IP filtering) on the network scanner. Issuer and target credentials encrypted at rest with AES-256-GCM. HTTPS-only control plane with TLS 1.3 pinned and a fail-closed startup gate that refuses to boot if the TLS bundle is unusable. Every API call recorded to an immutable audit trail with actor attribution, body hash, and latency tracking. CI runs race detection, 11 linters, and vulnerability scanning on every commit. See [`docs/operator/security.md`](docs/operator/security.md) for the full posture and [`docs/operator/auth-threat-model.md`](docs/operator/auth-threat-model.md) for what's defended vs deferred. ## Quick Start