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

docs: add table of contents to all major documentation files

Browse Source 
Navigation menus for testing guide, architecture, concepts,
connectors, quickstart, advanced demo, and three compliance docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
2026-03-26 23:38:28 -04:00
parent f92d148881
commit 87355c3efb
9 changed files with 271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+36
View File
@@ -1,5 +1,41 @@
# Architecture Guide
## Contents
1. [Overview](#overview)
2. [System Components](#system-components)
- [Control Plane (Server)](#control-plane-server)
- [Agents](#agents)
- [Web Dashboard](#web-dashboard)
- [PostgreSQL Database](#postgresql-database)
3. [Data Flow: Certificate Lifecycle](#data-flow-certificate-lifecycle)
- [Create Managed Certificate](#1-create-managed-certificate)
- [Certificate Issuance](#2-certificate-issuance)
- [Deploy Certificate to Target](#3-deploy-certificate-to-target)
- [Revoke a Certificate](#35-revoke-a-certificate)
- [Automatic Renewal](#4-automatic-renewal)
4. [Connector Architecture](#connector-architecture)
- [IssuerConnectorAdapter (Dependency Inversion)](#issuerconnectoradapter-dependency-inversion)
- [Issuer Connector](#issuer-connector)
- [Target Connector](#target-connector)
- [Notifier Connector](#notifier-connector)
- [EST Server (RFC 7030)](#est-server-rfc-7030)
5. [Security Model](#security-model)
- [Private Key Management](#private-key-management)
- [Authentication](#authentication)
- [Audit Trail](#audit-trail)
- [API Audit Log](#api-audit-log)
- [Logging](#logging)
6. [API Design](#api-design)
7. [MCP Server](#mcp-server)
8. [CLI Tool](#cli-tool)
9. [Deployment Topologies](#deployment-topologies)
- [Docker Compose (Development / Small Deployments)](#docker-compose-development--small-deployments)
- [Production (Kubernetes)](#production-kubernetes)
10. [Discovery Data Flow (M18b + M21)](#discovery-data-flow-m18b--m21)
11. [Testing Strategy](#testing-strategy)
12. [What's Next](#whats-next)
## Overview
Certctl is a certificate management platform with a **decoupled control-plane and agent architecture**. The control plane orchestrates certificate issuance and renewal, while agents deployed across your infrastructure handle key generation, certificate deployment, and local validation — private keys never leave the infrastructure they were generated on.
docs/compliance-nist.md
+18
View File
@@ -2,6 +2,24 @@
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. [Key Generation (Section 6.1)](#key-generation-section-61)
2. [Key Storage and Protection (Sections 6.3, 6.4)](#key-storage-and-protection-sections-63-64)
3. [Cryptoperiods (Section 5.3, Table 1)](#cryptoperiods-section-53-table-1)
4. [Key States and Transitions (Section 5.2)](#key-states-and-transitions-section-52)
5. [Algorithm Recommendations (Section 5.1, SP 800-131A)](#algorithm-recommendations-section-51-sp-800-131a)
6. [Key Distribution and Transport (Section 6.2)](#key-distribution-and-transport-section-62)
7. [Revocation and Compromise (NIST SP 800-57 Part 3)](#revocation-and-compromise-nist-sp-800-57-part-3)
8. [Alignment Summary Table](#alignment-summary-table)
9. [Gaps and Remediation Roadmap](#gaps-and-remediation-roadmap)
- [V2 (Current)](#v2-current)
- [V3 (Planned: 2026)](#v3-planned-2026)
- [V5 (Planned: 2027+)](#v5-planned-2027)
- [Post-Quantum (2027+)](#post-quantum-2027)
10. [References](#references)
11. [Questions or Corrections?](#questions-or-corrections)
## Key Generation (Section 6.1)
certctl generates certificate keys on agent infrastructure using Go's `crypto/rand` for entropy, backed by `/dev/urandom` on Linux and `CryptGenRandom` on Windows. Key generation happens as follows:
docs/compliance-pci-dss.md
+28
View File
@@ -4,6 +4,34 @@ This guide maps certctl's existing capabilities to PCI-DSS 4.0 requirements rele
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.
## Contents
1. [How to Use This Guide](#how-to-use-this-guide)
2. [Requirement 4: Protect Data in Transit](#requirement-4-protect-data-in-transit)
- [4.2.1 — Strong Cryptography for Transmission](#421--strong-cryptography-for-transmission)
- [4.2.2 — Certificate Inventory and Validation](#422--certificate-inventory-and-validation)
3. [Requirement 3: Protect Stored Cardholder Data (Key Management)](#requirement-3-protect-stored-cardholder-data-key-management)
- [3.6 — Cryptographic Key Documentation](#36--cryptographic-key-documentation)
- [3.7 — Key Lifecycle Procedures](#37--key-lifecycle-procedures)
4. [Requirement 8: Identify and Authenticate](#requirement-8-identify-and-authenticate)
- [8.3 — Strong Authentication](#83--strong-authentication)
- [8.6 — Application Account Management](#86--application-account-management)
5. [Requirement 10: Log and Monitor](#requirement-10-log-and-monitor)
- [10.2 — Implement Automated Audit Logging](#102--implement-automated-audit-logging)
- [10.3 — Protect Audit Trail](#103--protect-audit-trail)
- [10.4 — Promptly Review and Address Audit Trail Exceptions](#104--promptly-review-and-address-audit-trail-exceptions)
- [10.7 — Retain and Protect Audit Trail History](#107--retain-and-protect-audit-trail-history)
6. [Requirement 6: Develop and Maintain Secure Systems and Applications](#requirement-6-develop-and-maintain-secure-systems-and-applications)
- [6.3.1 — Security Coding Practices](#631--security-coding-practices)
- [6.5.10 — Broken Authentication and Cryptography Prevention](#6510--broken-authentication-and-cryptography-prevention)
7. [Requirement 7: Restrict Access by Business Need-to-Know](#requirement-7-restrict-access-by-business-need-to-know)
- [7.2 — Implement Access Control](#72--implement-access-control)
8. [Evidence Summary Table](#evidence-summary-table)
9. [Operator Responsibilities](#operator-responsibilities)
10. [V3 Enhancements for PCI-DSS](#v3-enhancements-for-pci-dss)
11. [Next Steps for Compliance](#next-steps-for-compliance)
12. [Questions?](#questions)
## How to Use This Guide
Your QSA will request evidence that your certificate and key management systems meet specific PCI-DSS 4.0 requirements. For each applicable requirement, this guide identifies:
docs/compliance-soc2.md
+22
View File
@@ -14,6 +14,28 @@ Each section includes:
- **V2 vs V3 status** — whether feature is in the free community edition (V2) or paid Pro edition (V3)
- **Operator responsibility** — aspects your organization must handle outside of certctl
## Contents
1. [How to Use This Guide](#how-to-use-this-guide)
2. [CC6: Logical and Physical Access Controls](#cc6-logical-and-physical-access-controls)
- [CC6.1 — Logical Access Security](#cc61--logical-access-security)
- [CC6.2 — Prior to Issuing System Credentials](#cc62--prior-to-issuing-system-credentials)
- [CC6.3 — Authentication Policies](#cc63--authentication-policies)
- [CC6.7 — Information Transmission Protection](#cc67--information-transmission-protection)
3. [CC7: System Operations](#cc7-system-operations)
- [CC7.1 — System Monitoring](#cc71--system-monitoring)
- [CC7.2 — Anomaly Detection](#cc72--anomaly-detection)
- [CC7.3 — Incident Response](#cc73--incident-response)
- [CC7.4 — Identify and Develop Risk Mitigation Activities](#cc74--identify-and-develop-risk-mitigation-activities)
4. [A1: Availability](#a1-availability)
- [A1.1/A1.2 — Availability and Recovery](#a11a12--availability-and-recovery)
5. [CC8: Change Management](#cc8-change-management)
- [CC8.1 — Change Control](#cc81--change-control)
6. [Evidence Summary Table](#evidence-summary-table)
7. [What Requires Operator Action](#what-requires-operator-action)
8. [V3 Enhancements](#v3-enhancements)
9. [Conclusion](#conclusion)
## CC6: Logical and Physical Access Controls
### CC6.1 — Logical Access Security
docs/concepts.md
+35
View File
@@ -2,6 +2,41 @@
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. [What Is a TLS Certificate?](#what-is-a-tls-certificate)
2. [Why Do Certificates Expire?](#why-do-certificates-expire)
3. [The Cast of Characters](#the-cast-of-characters)
- [Certificate Authority (CA)](#certificate-authority-ca)
- [ACME Protocol](#acme-protocol)
- [EST Protocol (Enrollment over Secure Transport)](#est-protocol-enrollment-over-secure-transport)
- [Private Key](#private-key)
- [Subject Alternative Names (SANs)](#subject-alternative-names-sans)
- [Certificate Chain](#certificate-chain)
4. [How certctl Works](#how-certctl-works)
- [The Control Plane (Server)](#the-control-plane-server)
- [Agents](#agents)
- [Deployment Targets](#deployment-targets)
5. [The Certificate Lifecycle](#the-certificate-lifecycle)
6. [Why Not Just Use Certbot?](#why-not-just-use-certbot)
7. [Key Concepts in certctl](#key-concepts-in-certctl)
- [Teams and Owners](#teams-and-owners)
- [Agent Groups](#agent-groups)
- [Certificate Profiles](#certificate-profiles)
- [Interactive Renewal Approval](#interactive-renewal-approval)
- [Certificate Revocation](#certificate-revocation)
- [Short-Lived Certificates](#short-lived-certificates)
- [Policies](#policies)
- [Jobs](#jobs)
- [Audit Trail](#audit-trail)
- [Notifications](#notifications)
- [CLI](#cli)
- [MCP Server (AI Integration)](#mcp-server-ai-integration)
- [EST Enrollment (Device Certificates)](#est-enrollment-device-certificates)
- [Certificate Discovery](#certificate-discovery)
- [Observability](#observability)
8. [What's Next](#whats-next)
## What Is a TLS Certificate?
When you visit `https://yourbank.com`, your browser checks a digital document called a **TLS certificate** before sending any data. That certificate proves two things: (1) you're really talking to yourbank.com and not an imposter, and (2) everything sent between you and the server is encrypted.
docs/connectors.md
+43
View File
@@ -2,6 +2,49 @@
Connectors extend certctl to integrate with external systems for certificate issuance, deployment, and notifications. This guide covers the connector interfaces, built-in implementations, and how to build your own.
## Contents
1. [Overview](#overview)
2. [Issuer Connector](#issuer-connector)
- [Interface](#interface)
- [Built-in: Local CA](#built-in-local-ca)
- [Built-in: ACME v2 (Let's Encrypt, Sectigo, ZeroSSL)](#built-in-acme-v2-lets-encrypt-sectigo-zerossl)
- [Built-in: step-ca (Smallstep Private CA)](#built-in-step-ca-smallstep-private-ca)
- [OpenSSL / Custom CA](#openssl--custom-ca)
- [Revocation Across Issuers](#revocation-across-issuers)
- [EST Integration (GetCACertPEM)](#est-integration-getcacertpem)
- [Planned Issuers](#planned-issuers)
- [Building a Custom Issuer](#building-a-custom-issuer)
3. [Target Connector](#target-connector)
- [Interface](#interface-1)
- [Built-in: NGINX](#built-in-nginx)
- [Built-in: Apache httpd](#built-in-apache-httpd)
- [Built-in: HAProxy](#built-in-haproxy)
- [F5 BIG-IP (Interface Only)](#f5-big-ip-interface-only)
- [IIS (Interface Only, Dual-Mode)](#iis-interface-only-dual-mode)
4. [Notifier Connector](#notifier-connector)
- [Interface](#interface-2)
5. [Registering a Connector](#registering-a-connector)
- [IssuerConnectorAdapter](#issuerconnectoradapter)
- [Notifier Registration](#notifier-registration)
6. [Testing Connectors](#testing-connectors)
- [Unit Tests](#unit-tests)
- [Integration Tests](#integration-tests)
7. [Best Practices](#best-practices)
8. [Agent Discovery Scanner](#agent-discovery-scanner)
- [Configuration](#configuration)
- [How It Works](#how-it-works)
- [API Endpoints](#api-endpoints)
- [Use Cases](#use-cases)
9. [Network Certificate Scanner (M21)](#network-certificate-scanner-m21)
- [Configuration](#configuration-1)
- [Creating Scan Targets](#creating-scan-targets)
- [How It Works](#how-it-works-1)
- [API Endpoints](#api-endpoints-1)
- [Scheduler Integration](#scheduler-integration)
- [Use Cases](#use-cases-1)
10. [What's Next](#whats-next)
## Overview
Three types of connectors:
docs/demo-advanced.md
+34
View File
@@ -5,6 +5,40 @@ This demo goes beyond browsing pre-loaded data. You'll create a team, register a
**Time**: 15-20 minutes
**Prerequisites**: certctl running via Docker Compose (see [Quick Start](quickstart.md))
## Contents
1. [Setup](#setup)
2. [How the pieces fit together](#how-the-pieces-fit-together)
3. [Alternative Issuers Reference](#alternative-issuers-reference)
- [Sub-CA Mode](#sub-ca-mode-local-ca-chained-to-enterprise-root)
- [ACME with DNS-01 Challenges](#acme-with-dns-01-challenges-wildcard-certificates)
- [ACME with DNS-PERSIST-01](#acme-with-dns-persist-01-zero-touch-renewals)
- [step-ca (Smallstep Private CA)](#step-ca-smallstep-private-ca)
- [OpenSSL / Custom CA](#openssl--custom-ca-script-based)
4. [Part 1: Build the Organization Structure](#part-1-build-the-organization-structure)
5. [Part 2: Verify the Issuer](#part-2-verify-the-issuer)
6. [Part 3: Create a Managed Certificate](#part-3-create-a-managed-certificate)
7. [Part 4: Trigger Certificate Renewal](#part-4-trigger-certificate-renewal)
8. [Part 4.5: Manage Deployment Targets](#part-45-manage-deployment-targets)
9. [Part 5: Deploy the Certificate](#part-5-deploy-the-certificate)
10. [Part 6: View the Audit Trail](#part-6-view-the-audit-trail-immutable-api-audit-log)
11. [Part 7: Check Notifications](#part-7-check-notifications)
12. [Part 8: Create a Second Certificate and Compare](#part-8-create-a-second-certificate-and-compare)
13. [Part 8.5: Revoke a Certificate](#part-85-revoke-a-certificate)
14. [Part 9: Policy Violations](#part-9-policy-violations)
15. [Part 9.5: Dashboard Stats and Metrics](#part-95-dashboard-stats-and-metrics)
16. [Part 10: Certificate Profiles](#part-10-certificate-profiles)
17. [Part 11: Agent Groups](#part-11-agent-groups)
18. [Part 12: Interactive Approval Workflow](#part-12-interactive-approval-workflow)
19. [Part 13: Advanced Query Features](#part-13-advanced-query-features)
20. [Part 14: CLI Tool](#part-14-cli-tool-m16b)
21. [Part 15: MCP Server for AI Integration](#part-15-mcp-server-for-ai-integration-m18a)
22. [Part 16: Certificate Discovery](#part-16-certificate-discovery-m18b--m21)
23. [End-to-End Architecture Summary](#end-to-end-architecture-summary)
24. [Full Automated Script](#full-automated-script)
25. [What to Show Stakeholders](#what-to-show-stakeholders)
26. [Teardown](#teardown)
## Setup
Make sure certctl is running:
docs/quickstart.md
+24
View File
@@ -6,6 +6,30 @@ This guide gets you running in 5 minutes and walks you through everything certct
New to certificates? Read the [Concepts Guide](concepts.md) first — it explains TLS, CAs, and private keys in plain language.
## Contents
1. [Prerequisites](#prerequisites)
2. [Start Everything](#start-everything)
3. [Open the Dashboard](#open-the-dashboard)
4. [Explore the API](#explore-the-api)
- [Core operations](#core-operations)
- [Sorting, filtering, and pagination](#sorting-filtering-and-pagination)
- [Stats and metrics](#stats-and-metrics)
5. [Create Your First Certificate](#create-your-first-certificate)
- [Revoke a certificate](#revoke-a-certificate)
- [Interactive approval workflow](#interactive-approval-workflow)
6. [Certificate Discovery](#certificate-discovery)
- [Filesystem discovery (agent-based)](#filesystem-discovery-agent-based)
- [Network discovery (agentless)](#network-discovery-agentless)
- [Triage discovered certificates](#triage-discovered-certificates)
7. [CLI Tool](#cli-tool)
8. [MCP Server (AI Integration)](#mcp-server-ai-integration)
9. [Demo Data Reference](#demo-data-reference)
10. [Dashboard Demo Mode](#dashboard-demo-mode)
11. [Presenting to Stakeholders](#presenting-to-stakeholders)
12. [Tear Down](#tear-down)
13. [What's Next](#whats-next)
## Prerequisites
You need **Docker** and **Docker Compose** installed. That's it.
docs/testing-guide.md
+31
View File
@@ -2,6 +2,37 @@
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
- [Prerequisites](#prerequisites)
- [Part 1: Infrastructure & Deployment](#part-1-infrastructure--deployment)
- [Part 2: Authentication & Security](#part-2-authentication--security)
- [Part 3: Certificate Lifecycle (CRUD)](#part-3-certificate-lifecycle-crud)
- [Part 4: Renewal Workflow](#part-4-renewal-workflow)
- [Part 5: Revocation](#part-5-revocation)
- [Part 6: Issuer Connectors](#part-6-issuer-connectors)
- [Part 7: Target Connectors & Deployment](#part-7-target-connectors--deployment)
- [Part 8: Agent Operations](#part-8-agent-operations)
- [Part 9: Job System](#part-9-job-system)
- [Part 10: Policies & Profiles](#part-10-policies--profiles)
- [Part 11: Ownership, Teams & Agent Groups](#part-11-ownership-teams--agent-groups)
- [Part 12: Notifications](#part-12-notifications)
- [Part 13: Observability](#part-13-observability)
- [Part 14: Audit Trail](#part-14-audit-trail)
- [Part 15: Certificate Discovery (Filesystem + Network)](#part-15-certificate-discovery-filesystem--network)
- [Part 16: Enhanced Query API](#part-16-enhanced-query-api)
- [Part 17: CLI Tool](#part-17-cli-tool)
- [Part 18: MCP Server](#part-18-mcp-server)
- [Part 19: GUI Testing](#part-19-gui-testing)
- [Part 20: Background Scheduler](#part-20-background-scheduler)
- [Part 21: Error Handling](#part-21-error-handling)
- [Part 22: Performance Spot Checks](#part-22-performance-spot-checks)
- [Part 23: Structured Logging Verification](#part-23-structured-logging-verification)
- [Part 24: Documentation Verification](#part-24-documentation-verification)
- [Part 25: Regression Tests](#part-25-regression-tests)
- [Part 26: EST Server (RFC 7030)](#part-26-est-server-rfc-7030)
- [Release Sign-Off](#release-sign-off)
---
## Prerequisites