mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 17:02:43 +00:00

Files

T

shankar0123 e7a94b6080 auth-bundle-1 Phase 13: docs (rbac.md + threat model + migration guide + security.md update)

Closes the last Phase before the Bundle 1 Exit gate. Operators
now have authoritative reference + threat model + migration guide
covering every behavior change Bundles 0-12 introduced.

# New docs

* docs/operator/rbac.md (340 lines) — operator how-to:
  - Mental model (actors / roles / permissions / scopes)
  - 7 default roles seeded by migration 000029 + the 5
    admin-only fine-grained perms seeded by 000030
  - Permission catalogue table by namespace
  - Scope semantics (global beats specific) + the Bundle-2
    deferral on scope_id FK enforcement
  - Granting / revoking access from GUI + CLI + HTTP API + MCP
  - The auditor pattern (audit-only, no resource read)
  - Day-0 bootstrap flow (CERTCTL_BOOTSTRAP_TOKEN → curl →
    HTTP 410 thereafter)
  - Demo-mode (CERTCTL_AUTH_TYPE=none) caveat for production

* docs/operator/auth-threat-model.md (180 lines) — what the
  controls defend against:
  - 5 threat actors (external, wrong-role, compromised key,
    insider operator, compromised auditor)
  - Per-defense walk-through (API-key auth, RBAC, bootstrap,
    approval workflow + Phase 9 closure, audit trail,
    protocol-endpoint allowlist)
  - 9 explicit deferrals (OIDC, sessions, local accounts,
    JIT elevation, MFA, etc.) — Bundle 2 / future scope
  - Compliance mapping (SOC 2 CC6.1/CC6.3, HIPAA §164.312(b),
    NIST SSDF PO.5.2, FedRAMP AU-9, PCI-DSS §10)
  - 5 operator-runnable sanity checks (e.g.,
    'SELECT FROM audit_events WHERE actor=system-bypass' MUST
    return 0 in production)

* docs/migration/api-keys-to-rbac.md (200 lines) — v2.0.x →
  v2.1.0 upgrade flow:
  - The SECURITY: AUDIT YOUR API KEYS callout
  - Migration list (000029-000033) + what each does
  - 4-mode scope-down flow (interactive / non-interactive
    JSON / --suggest / --suggest --apply)
  - What changes for code that called auth.IsAdmin
  - Helm-specific upgrade flow with example post-upgrade Job
  - Docker Compose upgrade flow + the 5 examples folders
    that ride demo mode unchanged
  - Verification queries + rollback flow

# Updated docs

* docs/operator/security.md — Last-reviewed bumped to
  2026-05-09; existing Authentication-surface section
  extended to call out the Bundle 1 RBAC primitive,
  day-0 bootstrap path, and approval-bypass closure with
  cross-references to the new docs.

* docs/reference/profiles.md — Last-reviewed header
  formatting fixed (added the > blockquote prefix used
  consistently across the docs tree).

# docs/README.md navigation

* Operator section gains 2 new rows (RBAC + auth-threat-model)
  and Approval-workflow row updated to mention Phase 9
  closure.
* Reference section gains the Profiles row.
* Migration section gains the api-keys-to-rbac row with the
  AUDIT YOUR API KEYS callout in the link description.

# CHANGELOG.md v2.1.0 section refreshed

The Phase 7 commit landed the SECURITY: AUDIT YOUR API KEYS
callout. This commit appends the missing Phase 9-12 highlights:

  - Approval-bypass closure (profile-edit gate + flip-flop
    loophole + ErrApproveBySameActor invariant)
  - GUI: Roles / API Keys / Auth Settings / Approvals queue
  - 12 new MCP RBAC tools
  - Coverage gates on internal/auth + internal/service/auth
  - Protocol-endpoint allowlist pinned at 3 layers

Trailing cross-reference block now points at all 4 new docs.

# Verifications

* Every internal link in the 4 new/modified docs validated by
  shell sweep (find broken links → 0 hits).
* Every new doc carries 'Last reviewed: 2026-05-09' header
  with the > blockquote prefix matching the docs-tree
  convention.
* go vet ./... clean.
* staticcheck across every Bundle-1-touched Go package clean.
* gofmt -l clean repo-wide.
* go test -short -count=1 green across internal/auth (incl.
  bootstrap), internal/api/handler, internal/api/router,
  internal/cli, internal/service (incl. auth),
  internal/domain/auth, internal/mcp, cmd/cli (cmd/server
  has 1 environmental failure on the sandbox virtiofs-tmp:
  TestPreflightSCEPRACertKey_KeyWorldReadable_Refuses depends
  on tmpfs file-mode semantics that virtiofs propagates
  differently — pre-existing, unrelated to Bundle 1).
* Frontend: 19 Vitest tests across src/pages/auth/ +
  AuditPage all pass; tsc --noEmit clean.

2026-05-10 00:10:15 +00:00

9.8 KiB

Raw Blame History

certctl Documentation

Last reviewed: 2026-05-05

The full docs index, organized by audience. Pick the section that matches what you need to do; each link below opens a focused doc rather than a wall of text.

For the elevator pitch and quickstart commands, see the repo README.md at the root. For the marketing site, see certctl.io.

Getting Started

You're new to certctl, just cloned the repo, or want to understand what it does before installing.

Doc	What it covers
Concepts	TLS certificates explained for beginners — CAs, ACME, EST, private keys, the full glossary
Quickstart	Five-minute setup with Docker Compose, dashboard tour, API tour
Examples	Five turnkey scenarios — ACME+NGINX, wildcard DNS-01, private CA+Traefik, step-ca+HAProxy, multi-issuer
Advanced demo	End-to-end certificate lifecycle with technical depth at each step
Why certctl	Positioning vs ACME clients, agent-based SaaS, enterprise platforms; when to look elsewhere

Reference

You're operating certctl in production or building integrations and need authoritative technical detail.

Doc	What it covers
Architecture	System design, data flow, security model, deployment topologies
Profiles	CertificateProfile policy object — issuer wiring, EKUs, RequiresApproval gate (Phase 9 closure)
API	OpenAPI 3.1 spec, integration patterns, client SDK generation
CLI	certctl-cli command reference and CI/CD integration patterns
Configuration	`CERTCTL_*` environment variable reference (scheduler, rate limits, deploy verify, audit, agent)
MCP server	Model Context Protocol integration for AI assistants
Release verification	Cosign / SLSA / SBOM verification procedure
Intermediate CA hierarchy	Multi-level CA tree management — RFC 5280 §3.2/§4.2.1.9/§4.2.1.10 enforcement
Deployment model	Atomic write, post-deploy verify, rollback semantics across all targets
Vendor matrix	Tested vendor versions per target connector

Connectors

The connector index is the canonical catalog (interfaces, registry, scanners, plus an inline reference per built-in). Per-connector deep-dive siblings cover operator-grade material — vendor edges, troubleshooting, rotation playbooks, when-to-use vs alternatives.

Issuers (13 deep-dives): ACME · ADCS · AWS ACM Private CA · DigiCert · EJBCA / Keyfactor · Entrust · GlobalSign Atlas HVCA · Google CAS · Local CA · OpenSSL / Custom CA · Sectigo SCM · step-ca / Smallstep · Vault PKI

Targets (15 deep-dives): Apache · AWS Certificate Manager · Azure Key Vault · Caddy · Envoy · F5 BIG-IP · HAProxy · IIS · Java Keystore · Kubernetes Secrets · NGINX · Postfix / Dovecot · SSH (agentless) · Traefik · Windows Certificate Store

Protocols

Doc	What it covers
ACME server	Run certctl as an RFC 8555 + RFC 9773 ARI ACME server
ACME server threat model	Security posture for the ACME server endpoint
SCEP server	RFC 8894 native SCEP server — RA cert config, multi-profile dispatch, must-staple, mTLS sibling route
SCEP for Microsoft Intune	Intune-specific deployment guide — NDES replacement playbook
EST server	RFC 7030 EST server — 802.1X / Wi-Fi enrollment, IoT bootstrap, channel binding
CRL & OCSP	RFC 5280 CRL + RFC 6960 OCSP responder for relying parties
Async CA polling	Bounded polling for async-CA issuer connectors

Operator

You're running certctl in production and need operational guidance.

Doc	What it covers
Security posture	Auth, rate limits, encryption at rest, key rotation, RBAC primitive (Bundle 1), bootstrap
RBAC operator reference	Roles, permissions, scopes, scope-down + bootstrap flow (Bundle 1)
Auth threat model	API-key compromise, role-grant abuse, bootstrap-token leak, audit-mutation, compliance mapping (Bundle 1)
Control plane TLS	Self-signed bootstrap, operator-supplied Secret, cert-manager Certificate CR
Database TLS	PostgreSQL transport encryption
Approval workflow	Two-person integrity gate for high-stakes issuance + Phase 9 profile-edit closure
Helm deployment	Kubernetes installation via the bundled chart
Performance baselines	Operator-runnable benchmarks for regression spot checks
Legacy clients (TLS 1.2)	Reverse-proxy runbook for embedded EST/SCEP clients on TLS 1.2

Runbooks

Runbook	When
Cloud targets	AWS ACM + Azure Key Vault deployment, debugging, rollback
Expiry alerts	Per-policy multi-channel routing matrix, severity tiers
Disaster recovery	CRL cache, OCSP responder cert, CA private-key rotation, Postgres restore

Migration

You're moving from another cert-management tool to certctl, or running both in parallel.

From	Doc
Certbot	migration/from-certbot.md
acme.sh	migration/from-acmesh.md
cert-manager (coexistence, not replacement)	migration/cert-manager-coexistence.md
Caddy ACME (point Caddy at certctl)	migration/acme-from-caddy.md
cert-manager ACME (point cert-manager at certctl)	migration/acme-from-cert-manager.md
Traefik ACME (point Traefik at certctl)	migration/acme-from-traefik.md
API keys → RBAC (v2.0.x → v2.1.0)	migration/api-keys-to-rbac.md — AUDIT YOUR API KEYS post-upgrade

Contributor

You're contributing to certctl, running tests locally, or trying to understand the CI pipeline.

Doc	What it covers
Testing strategy	What we test and why; per-PR fast gates vs daily deep-scan
Test environment	Local environment with real CAs (Pebble, step-ca, etc.)
QA prerequisites	Before running QA: stack boot, demo data baseline, env vars
QA test suite	qa_test.go reference for release QA
GUI QA checklist	Manual GUI verification pass for release
Release sign-off	Release-day checklist — code state, automated gates, manual QA, artefact verification
CI pipeline	CI shape, regression guards, adding new checks

Doc	Why archived
Upgrade to TLS (v2.2)	Pre-v2.2 HTTPS-everywhere upgrade procedure
Upgrade past v2 JWT removal	G-1 milestone JWT auth removal procedure

Reading order by role

First-time operator: Concepts → Quickstart → Examples. About 90 minutes end to end.

Production operator: Architecture → Security posture → Control plane TLS → Disaster recovery runbook. About 4 hours end to end.

PKI engineer: ACME server → SCEP server → EST server → Intermediate CA hierarchy. About 6 hours end to end.

Contributor: Architecture → Testing strategy → Test environment → CI pipeline. About 3 hours end to end.

9.8 KiB Raw Blame History