mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 21:11:30 +00:00

Files

T

shankar0123 7c134d0575 docs: retire compliance subtree + sweep framework name-drops from prose

Per operator decision the framework-mapping docs are gone. They
were aspirational (no audit, no certification, no validated
mapping); keeping them around was misleading.

Files deleted (1,883 lines):
- docs/compliance/index.md
- docs/compliance/soc2.md
- docs/compliance/pci-dss.md
- docs/compliance/nist-sp-800-57.md

Hyperlinks removed:
- README.md: 'Auditor / compliance' row in the doc table; the
  '(compliance mapping included)' parenthetical in the
  positioning paragraph
- docs/README.md: the '## Compliance' section table; the
  'Auditor / compliance team' reading-order-by-role row

Prose name-drops swept across 24 files:
- README.md: 'FedRAMP boundary CAs / financial-services policy
  CAs' → '4-level boundary CAs / 3-level policy CAs';
  'Compliance-grade for PCI-DSS Level 1, FedRAMP Moderate / High,
  SOC 2 Type II, HIPAA' → cut entirely
- getting-started/{quickstart,concepts,examples,why-certctl,
  advanced-demo}.md: 'compliance' → 'audit' / 'policy';
  'PCI-DSS / SOC 2 / NIST SP 800-57' framework lists cut;
  ''pci': 'true'' tag example → ''environment': 'production''
- migration/cert-manager-coexistence.md: 'compliance rules' →
  'policy rules'
- operator/approval-workflow.md: 'Compliance customers (PCI-DSS
  Level 1, FedRAMP Moderate / High, SOC 2 Type II, HIPAA)' →
  'Operators'; entire 'Compliance control mapping' table
  (PCI-DSS §6.4.5 / NIST SP 800-53 SA-15 / SOC 2 Type II CC6.1
  / HIPAA §164.308(a)(4)) deleted; 'compliance contract' →
  'two-person-integrity contract'; 'compliance auditors' →
  'reviewers'
- operator/legacy-clients-tls-1.2.md: 'PCI-DSS v4.0 Req 4 §2.2.5'
  audit-reference → CWE-326 (kept); 'PCI-DSS Req 4 §2.2.5
  attestation' section retitled to 'TLS posture summary' and
  rewritten without framework framing; 'PCI-DSS, NIST, and
  major browsers will eventually deprecate TLS 1.2' →
  'Major browsers and OS vendors will eventually deprecate
  TLS 1.2'
- operator/database-tls.md: PCI-DSS Req 4 §2.2.5 audit-ref →
  CWE-319 only; 'PCI-DSS scope' → 'sensitive data'; PCI-DSS
  Req 4 v4.0 prose footing → cut
- operator/runbooks/disaster-recovery.md: 'SOC 2 / PCI
  procurement-team deliverable' → 'on-call deliverable';
  'compliance auditors' → 'reviewers'
- reference/connectors/{acme,aws-acm,azure-kv,globalsign,
  local-ca,openssl,ssh,index}.md: 'compliance reporting
  (PCI-DSS §3.6, HIPAA §164.312)' → 'audit reporting';
  'Compliance environments (PCI-DSS Level 1, FedRAMP High,
  HIPAA)' → 'Regulated environments'; 'compliance audits' →
  'audit'; 'FedRAMP boundary CA' pattern names →
  '4-level boundary CA' (technically descriptive)
- reference/protocols/est.md: 'compliance-hook seam' →
  'device-state hook seam'; 'compliance gating' → 'device-state
  gating'; 'est_compliance_failed' → 'est_device_state_failed'
- reference/protocols/scep-intune.md: 'Optional compliance
  check' → 'Optional device-state check'; failure-counter
  'compliance_failed' → 'device_state_failed'; 'Conditional
  Access compliance gating' → 'Conditional Access
  device-state gating'
- reference/intermediate-ca-hierarchy.md: 'FedRAMP boundary-CA
  deployments where the regulator requires...' →
  'Boundary-CA deployments where you want separation of policy
  and issuing authorities'; pattern A retitled '4-level FedRAMP
  boundary CA' → '4-level boundary CA'
- reference/architecture.md: broken Related-docs link to
  compliance.md removed; the rest of that block had stale
  pre-Phase-2 paths (quickstart.md, demo-advanced.md,
  connectors.md, openapi.md, testing-guide.md, test-env.md) —
  retargeted to current locations
- reference/deployment-model.md: 'SOC 2 evidence-report
  generator' → 'Audit-evidence report generator'
- reference/vendor-matrix.md: 'SOC 2 / PCI auditors paste this
  into evidence packs' → 'reviewers paste this into
  vendor-evaluation packs'
- contributor/qa-test-suite.md: 'compliance exist' coverage
  description cut; 'Compliance (PCI / SOC2 / HIPAA-relevant)'
  risk-class label → 'Audit-relevant'

What was kept:
- CWE references (legitimate technical pointers)
- Microsoft API/feature names that happen to use 'compliance'
  literally ('Microsoft Graph compliance API',
  'device-compliance validators' — these are MS product names,
  not framework name-drops)
- 'NIST PQC' on the landing page (Post-Quantum Cryptography is
  the actual NIST standard family, not a compliance framework)

Verified: zero hyperlinks into docs/compliance/ remain. All 24
ci-guards/*.sh pass locally. qa-doc-seed-count.sh clean.
Net diff: 26 files / -1,883 deletions in compliance/ + -32 net
across the prose sweep.

Companion edits in cowork/ (CLAUDE.md doc-tree summary +
WORKSPACE-CHANGELOG.md retirement note) land separately.

2026-05-05 05:26:44 +00:00

9.1 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
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
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
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

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.1 KiB Raw Blame History