mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 14:21:37 +00:00
docs: Phase 14 — Last reviewed line sweep across docs/
Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/. Adds a `> Last reviewed: 2026-05-05` line right after the H1 heading of every doc that didn't already have one (41 files). This dates the freshness clock for the future Phase 4 per-doc review. The discipline going forward: when a doc's content gets a meaningful edit, bump the date. When the date gets old (e.g., >6 months), the doc earns a freshness-review pass. Mechanical insertion via awk one-liner, applied to every docs/*.md that didn't already match `grep -q 'Last reviewed:'`. Files that already carried the line from earlier Phase 2 work (the navigation index, the new connector docs, the new SCEP server / legacy-clients- TLS-1.2 / release-verification docs, and the 5 per-connector deep dives) were skipped to avoid duplicate insertion. Net: every doc in docs/ now has a Last reviewed line.
This commit is contained in:
@@ -1,5 +1,7 @@
|
||||
# Upgrading to HTTPS-Everywhere (v2.2)
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Archived 2026-05-05.** This upgrade guide applies to certctl < v2.2.
|
||||
> Current operators on v2.2+ already have HTTPS-only control planes and
|
||||
> don't need this procedure. For the steady-state TLS reference, see
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Upgrading past G-1 — `CERTCTL_AUTH_TYPE=jwt` removal
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Archived 2026-05-05.** This upgrade guide applies to operators
|
||||
> upgrading past the G-1 milestone (the `CERTCTL_AUTH_TYPE=jwt` removal).
|
||||
> Current operators on post-G-1 releases don't need this. For the
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Compliance Mapping Guides
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
certctl is a certificate lifecycle management tool, not a compliance product. It doesn't make you compliant — your organization, policies, and processes do that. What certctl provides is tooling that supports the technical controls auditors and evaluators look for when assessing certificate and key management practices.
|
||||
|
||||
These guides map certctl's features to three widely referenced compliance frameworks. They're designed for security engineers, IT auditors, and procurement teams evaluating certctl for environments with regulatory requirements.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# NIST SP 800-57 Key Management Alignment
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
NIST SP 800-57 Part 1 Rev 5 (May 2020) is the authoritative US government guidance on cryptographic key management. This document maps certctl's implementation to its recommendations. certctl follows NIST guidance where applicable; this guide documents the alignment and identifies gaps for future roadmap planning.
|
||||
|
||||
## Contents
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# PCI-DSS 4.0 Compliance Mapping
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This guide maps certctl's existing capabilities to PCI-DSS 4.0 requirements relevant to TLS certificate and cryptographic key management. It is **not a compliance attestation** — a qualified security assessor (QSA) must evaluate your organization's complete control environment. Rather, this document helps you understand which PCI-DSS control objectives certctl supports and where operator responsibility lies.
|
||||
|
||||
Organizations subject to PCI-DSS typically need to demonstrate control over certificate issuance, renewal, rotation, revocation, and key management. Certctl automates the technical controls for certificate lifecycle; compliance depends on how you deploy, monitor, and audit it.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# SOC 2 Type II Compliance Mapping
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This guide maps certctl's implemented features to AICPA SOC 2 Trust Service Criteria (TSC). It is **not a SOC 2 certification claim** — rather, it helps security engineers, auditors, and evaluators understand how certctl supports your organization's SOC 2 compliance posture. Use this as evidence input for your own control assessment during SOC 2 audits.
|
||||
|
||||
## How to Use This Guide
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# CI Pipeline — Operator Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> Authoritative guide to certctl's CI pipeline shape.
|
||||
> Per `cowork/ci-pipeline-cleanup-prompt.md` Phase 12.
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# QA Test Suite Guide (`qa_test.go`)
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Audience:** Anyone running release QA for certctl — whether you're a first-time contributor or the maintainer cutting a release tag.
|
||||
>
|
||||
> **Companion to:** `docs/testing-guide.md` (the *what* to test). This document explains the *how* — the automated test file, what it covers, what it skips, and how to fill the gaps manually.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# certctl Testing Environment
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
A step-by-step guide to running certctl locally with real certificate authorities. Every command is spelled out. Every expected output is shown. If something goes wrong, the troubleshooting section tells you exactly what to check.
|
||||
|
||||
---
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# certctl Testing Strategy & Deep-Scan Operator Runbook
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This doc covers the **testing topology** (per-PR fast gates vs. daily deep-scan
|
||||
gates), and the **operator runbook** for re-running each deep-scan tool locally
|
||||
when the CI receipt is ambiguous or when an operator wants to validate a fix
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Advanced Demo: Certificate Lifecycle End-to-End
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This demo goes beyond browsing pre-loaded data. You'll create a team, register an owner, set up an issuer, create a certificate, trigger renewal, and watch everything appear in the dashboard in real time. Each step includes a technical explanation of what's happening inside certctl and why the system is designed that way.
|
||||
|
||||
**Time**: 15-20 minutes
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Understanding Certificates: A Beginner's Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
If you've never worked with TLS certificates before, this guide will get you up to speed. By the end, you'll understand what certificates are, why they matter, and why the industry's move toward shorter certificate lifespans — down to 47 days by 2029 — makes automated lifecycle management essential.
|
||||
|
||||
## Contents
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Deployment Examples
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Five turnkey docker-compose scenarios, each runnable in under 5 minutes. Pick the one closest to your setup.
|
||||
|
||||
## Which Example Should I Use?
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Quick Start Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Certificate lifespans are dropping to **47 days by 2029**. At that cadence, a team managing 100 certificates is processing 7+ renewals per week — every week, forever. Manual processes break. certctl automates the entire lifecycle: issuance, renewal, deployment, revocation, and audit — with zero human intervention.
|
||||
|
||||
This guide gets you running in 5 minutes and walks you through everything certctl does.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Why certctl?
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Certificate management is broken at every scale between "one domain on Let's Encrypt" and "Fortune 500 budget for Venafi." certctl fills that gap: a self-hosted platform that automates the entire certificate lifecycle, works with any CA, deploys to any server, and keeps private keys on your infrastructure. It's free, source-available, and you own everything.
|
||||
|
||||
## The Math That Forces the Decision
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Caddy Integration Walkthrough
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Use this walkthrough when** you're already running Caddy 2.7+ and
|
||||
> want it to ACME-issue from certctl (your internal CA, your private
|
||||
> PKI, or a local sub-CA chained under an enterprise root) instead of
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# cert-manager Integration Walkthrough
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Use this walkthrough when** you're already running cert-manager
|
||||
> 1.15+ in Kubernetes and want it to issue certs from certctl (your
|
||||
> internal CA, your private PKI, or a local sub-CA chained under an
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Traefik Integration Walkthrough
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Use this walkthrough when** you're already running Traefik 3.0+
|
||||
> (Kubernetes or VM) and want it to ACME-issue from certctl (your
|
||||
> internal CA, your private PKI, or a local sub-CA chained under an
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# certctl for cert-manager Users
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
You run cert-manager inside Kubernetes and it works well for in-cluster certificates. But you also have VMs, bare-metal servers, network appliances, and legacy systems outside the cluster. cert-manager can't reach those. This guide shows how certctl complements cert-manager to give you unified certificate visibility and automation across your entire infrastructure.
|
||||
|
||||
## Not a Replacement
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Migrate from acme.sh to certctl
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
You use acme.sh to automate Let's Encrypt renewal across multiple servers. It works — but without centralized visibility, deployment verification, or policy enforcement.
|
||||
|
||||
This guide walks through moving your acme.sh workload to certctl while keeping your existing DNS provider setup.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Migrating from Certbot to certctl
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
You have 50 Let's Encrypt certificates across 10 servers, managed by a mix of Certbot cron jobs and manual renewals. Certbot handles issuance, but you lack inventory visibility, centralized alerting, and audit trails. This guide walks you through moving to certctl while keeping your existing certificates and ACME account.
|
||||
|
||||
## Why Migrate
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Issuance approval workflow
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
certctl can gate certificate issuance + renewal on a per-profile, two-person-integrity check. Compliance customers (PCI-DSS Level 1, FedRAMP Moderate / High, SOC 2 Type II, HIPAA) configure this on production-tier `CertificateProfile` rows so every renewal-loop tick or manual `POST /api/v1/certificates/{id}/renew` blocks at `JobStatusAwaitingApproval` until a different actor approves.
|
||||
|
||||
Closes the procurement-checklist question "How do you enforce two-person integrity on cert issuance?" — without this surface the answer is "we don't"; with `requires_approval=true` on the profile, the answer is "here's the RBAC contract + here's the audit query that proves bypass mode is off in production."
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Database TLS — Postgres Transport Encryption
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
**Audit reference:** Bundle B / M-018. PCI-DSS v4.0 Req 4 §2.2.5; CWE-319.
|
||||
|
||||
certctl talks to Postgres over a single connection-string URL controlled by the
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Runbook: cloud-target deployment connectors (AWS ACM + Azure Key Vault)
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This runbook covers the SDK-driven cloud target connectors that ship in
|
||||
certctl post-2026-05-03 (Rank 5 of the Infisical deep-research
|
||||
deliverable). It complements the operator-facing
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Disaster recovery runbook
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Status (this document):** Production hardening II Phase 10
|
||||
> deliverable. Codifies the fail-safe behaviors that already exist in
|
||||
> the codebase and the operator procedures for recovering from
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Runbook: certificate-expiry alerts (multi-channel)
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This runbook covers the per-policy multi-channel expiry-alert dispatch
|
||||
path that ships in certctl post-2026-05-03 (Rank 4 of the Infisical
|
||||
deep-research deliverable). It complements the operator-facing
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# certctl Security Posture & Operator Guidance
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This document collects the operator-facing security guidance that the source
|
||||
code's per-finding comment blocks reference. Each section names the audit
|
||||
finding it closes, the threat model, and the operator action required (if
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# TLS on the Control Plane
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
certctl's control plane is HTTPS-only as of v2.2. There is no plaintext `http://` listener, no `auto` mode, no dual-listener bridge, no TLS 1.2 escape hatch. The server refuses to start without a cert+key pair, the agent/CLI/MCP clients reject `http://` URLs at startup, and the Helm chart refuses to render without either an operator-supplied Secret or a cert-manager Certificate CR.
|
||||
|
||||
This doc covers four cert provisioning patterns, SIGHUP-based cert rotation, and the client-side CA-trust configuration agents and the CLI need to talk to the server. If you are upgrading from a pre-HTTPS release and want the step-by-step cutover procedure, read [`upgrade-to-tls.md`](upgrade-to-tls.md) first and come back here for reference.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# OpenAPI Specification Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
certctl ships with a complete OpenAPI 3.1 specification at `api/openapi.yaml`. This spec documents all 78 API operations currently specified, every request/response schema, pagination conventions, authentication requirements, and error formats. It's the single source of truth for the documented REST API. (Note: The spec will be updated to include 7 additional certificate discovery endpoints from M18b.)
|
||||
|
||||
This guide covers how to use the spec for API exploration, client SDK generation, and integration testing.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Architecture Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
## Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Deployment Atomicity, Post-Deploy Verification, and Rollback
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> Deploy-hardening I master bundle (v2.X.0). Operator + integrator
|
||||
> reference for the atomic-write + post-deploy TLS verify +
|
||||
> rollback pipeline that closes the procurement-checklist gap with
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Intermediate CA hierarchy — operator runbook
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Rank 8 of the 2026-05-03 deep-research deliverable. This page is the
|
||||
canonical reference for operators running certctl as a multi-level
|
||||
internal PKI.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# MCP Server Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
certctl ships with an MCP (Model Context Protocol) server that lets AI assistants manage your certificate infrastructure through natural language. Ask Claude to "show me all expiring certificates," "revoke the VPN cert," or "what agents are offline?" and the MCP server translates that into API calls against your certctl instance.
|
||||
|
||||
This guide covers setup, configuration, and usage with Claude, Cursor, and other MCP-compatible tools.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# ACME Server — Threat Model
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Security posture for the certctl ACME server endpoint
|
||||
(`/acme/profile/<id>/*`). Read this before opening a PR that changes
|
||||
the JWS verifier, the challenge validators, the rate limiter, or the
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# certctl ACME Server (Built-in)
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
certctl ships an RFC 8555 + RFC 9773 ARI ACME server endpoint at
|
||||
`/acme/profile/<profile-id>/*`. Any RFC 8555 client (cert-manager 1.15+,
|
||||
Caddy, Traefik, win-acme, certbot, Posh-ACME) can integrate with certctl
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Async-CA Polling — Operator Reference
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Closes audit fix #5 from the 2026-05-01 issuer-coverage acquisition-readiness audit.
|
||||
|
||||
## What this is
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# CRL & OCSP — Revocation Status for Relying Parties
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
This guide is the operator + relying-party reference for certctl's revocation
|
||||
status surfaces. It covers the wire format, endpoint URLs, configuration knobs,
|
||||
the OCSP responder cert lifecycle, and how to point common consumers
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# EST (RFC 7030) — Operator Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Status (this document):** EST RFC 7030 hardening master bundle Phases
|
||||
> 1–11 shipped on `master`; this guide is the Phase-12 deliverable
|
||||
> against the bundle. Every behavior described here is exercised by the
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Microsoft Intune SCEP enrollment via certctl
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> **Status (this document):** Phase 11 of the SCEP RFC 8894 + Intune master
|
||||
> bundle. The behavior described here is shipped on `master` and exercised
|
||||
> end-to-end by `internal/api/handler/scep_intune_e2e_test.go`. The
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Deployment Vendor Compatibility Matrix
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
> Deploy-hardening II master bundle deliverable. The procurement-team
|
||||
> headline doc — SOC 2 / PCI auditors paste this into evidence packs.
|
||||
> Per frozen decision 0.14: a (connector × vendor-version) cell is
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# certctl V2.1 Release QA Guide
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
|
||||
Comprehensive manual testing playbook. Every test has a concrete command, an explanation of what it validates and why it matters, exact expected output, and an unambiguous pass/fail criterion.
|
||||
|
||||
## Contents
|
||||
|
||||
Reference in New Issue
Block a user