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

docs: fix 16 discrepancies found by cross-validating all docs against source code

Browse Source 
CLI syntax corrected across 5 files (concepts, demo-guide, demo-advanced,
architecture, features): list-certs→certs list, get-cert→certs get, etc.
Removed non-existent health/metrics commands, replaced with status.
Subcommand count 10→12 everywhere.

architecture.md: Go 1.22→1.25, endpoint count 91→93, ER diagram expanded
from 15 to 21 tables (added renewal_policies, certificate_revocations,
discovered_certificates, discovery_scans, network_scan_targets).

connectors.md: added GenerateCRL and SignOCSPResponse to issuer interface,
added Email and Webhook rows to notifier config table.

compliance docs: fixed keygen warning messages to match actual log output,
CERTCTL_STEPCA_PROVISIONER_KEY→CERTCTL_STEPCA_KEY_PATH, openssl genrsa→
crypto/ecdsa.GenerateKey, CERTCTL_SERVER_ADDR→CERTCTL_SERVER_HOST+PORT.

README.md: v2.0.0 version bump, solo developer mention, feature list,
table of contents, documentation table moved to top, 7 fact-check fixes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
2026-03-25 03:48:13 -04:00
parent 963821a681
commit 72cda5877a
10 changed files with 175 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+43 -3
View File
@@ -76,7 +76,7 @@ The control plane is a Go HTTP server backed by PostgreSQL. It manages state (ce
The server exposes a REST API under `/api/v1/` and optionally serves the web dashboard as static files from the `web/` directory.
**Key internals**: The server uses Go 1.22's `net/http` stdlib routing (no external router framework), structured logging via `slog`, and a handler → service → repository layered architecture. Handlers define their own service interfaces for clean dependency inversion.
**Key internals**: The server uses Go 1.25's `net/http` stdlib routing (no external router framework), structured logging via `slog`, and a handler → service → repository layered architecture. Handlers define their own service interfaces for clean dependency inversion.
### Agents
@@ -122,8 +122,11 @@ erDiagram
managed_certificates ||--o{ policy_violations : "violates"
managed_certificates ||--o{ audit_events : "logged in"
managed_certificates ||--o{ notification_events : "generates"
managed_certificates ||--o{ certificate_revocations : "revoked via"
agent_groups ||--o{ agent_group_members : "has members"
agents ||--o{ agent_group_members : "belongs to"
agents ||--o{ discovered_certificates : "discovers"
agents ||--o{ discovery_scans : "performs"
teams {
text id PK
@@ -242,6 +245,43 @@ erDiagram
text agent_id FK
text membership_type
}
renewal_policies {
text id PK
text certificate_id FK
int renewal_days_before
jsonb alert_thresholds_days
boolean auto_renew
text agent_group_id FK
}
certificate_revocations {
text id PK
text certificate_id FK
text serial_number
text reason
timestamp revoked_at
boolean issuer_notified
}
discovered_certificates {
text id PK
text agent_id FK
text fingerprint_sha256
text common_name
text source_path
text status
}
discovery_scans {
text id PK
text agent_id FK
int certs_found
timestamp scanned_at
}
network_scan_targets {
text id PK
text name
text[] cidrs
int[] ports
boolean enabled
}
```
Migrations are idempotent (`IF NOT EXISTS` on all CREATE statements, `ON CONFLICT (id) DO NOTHING` on all seed data) so they're safe to run multiple times — important for Docker Compose where both initdb and the server may run the same SQL.
@@ -608,7 +648,7 @@ All endpoints are under `/api/v1/` and follow consistent patterns:
Resources: certificates, issuers, targets, agents, jobs, policies, profiles, teams, owners, agent-groups, audit, notifications.
The full API is documented in an OpenAPI 3.1 specification at `api/openapi.yaml` with 91 endpoints across 19 resource domains (including health, readiness, auth, 7 discovery endpoints from M18b, 6 network scan endpoints from M21, and Prometheus metrics from M22), all request/response schemas, and pagination conventions. See the [OpenAPI Guide](openapi.md) for usage with Swagger UI and SDK generation.
The full API is documented in an OpenAPI 3.1 specification at `api/openapi.yaml` with 93 endpoints across 19 resource domains (91 under `/api/v1/` plus `/health` and `/ready`; includes auth, 7 discovery endpoints from M18b, 6 network scan endpoints from M21, and Prometheus metrics from M22), all request/response schemas, and pagination conventions. See the [OpenAPI Guide](openapi.md) for usage with Swagger UI and SDK generation.
Jobs support additional action endpoints: `POST /api/v1/jobs/{id}/cancel`, `POST /api/v1/jobs/{id}/approve`, `POST /api/v1/jobs/{id}/reject`.
@@ -654,7 +694,7 @@ The 78 tools are organized across 16 resource domains with typed input structs a
certctl ships with a command-line tool (`certctl-cli`, built from `cmd/cli/main.go`) that wraps the REST API for terminal workflows. The CLI uses Go's standard library only (`flag` + `text/tabwriter`) — no Cobra or other framework dependencies.
10 subcommands: `list-certs`, `get-cert`, `renew-cert`, `revoke-cert`, `list-agents`, `list-jobs`, `health`, `metrics`, and `import` (bulk PEM import). Output is available in table (default) or JSON format via `--format`. Connection is configured via `CERTCTL_SERVER_URL` and `CERTCTL_API_KEY` environment variables or CLI flags.
12 subcommands organized by resource: `certs list`, `certs get`, `certs renew`, `certs revoke`, `agents list`, `agents get`, `jobs list`, `jobs get`, `jobs cancel`, `import` (bulk PEM import), `status` (health + summary stats), and `version`. Output is available in table (default) or JSON format via `--format`. Connection is configured via `CERTCTL_SERVER_URL` and `CERTCTL_API_KEY` environment variables or CLI flags.
The bulk import command (`certctl-cli import <file.pem>`) parses multi-certificate PEM files and creates certificate records via the API — useful for bootstrapping certctl with existing certificate inventory.
docs/compliance-nist.md
+1 -1
View File
@@ -15,7 +15,7 @@ certctl generates certificate keys on agent infrastructure using Go's `crypto/ra
**Server-Side Key Generation (Demo Only)**
- Available for development and testing via `CERTCTL_KEYGEN_MODE=server`
- Explicitly logged as a warning at startup: "server-side keygen enabled (production deployments must use agent mode)"
- Explicitly logged as a warning at startup: "server-side key generation enabled (CERTCTL_KEYGEN_MODE=server) — private keys touch control plane, demo only"
- Docker Compose demo uses server mode for backward compatibility
- Not recommended for production; agent mode is the secure default
docs/compliance-pci-dss.md
+3 -3
View File
@@ -168,7 +168,7 @@ This requirement covers key generation, storage, rotation, and destruction. Cert
- **Server-Side Fallback** (demo/development only) — `CERTCTL_KEYGEN_MODE=server`:
- Control plane generates RSA 2048-bit or ECDSA P-256 keys using `crypto/rand` + `crypto/rsa`.
- Server signs CSR and stores the private key in the certificate version record for agent deployment. **Security note:** In server keygen mode, the control plane holds private keys — this is why agent keygen mode is the recommended default for production.
- **Must not be used in production.** Explicit warning logged: `Key generation mode is server; this should only be used for testing.`
- **Must not be used in production.** Explicit warning logged: `server-side key generation enabled (CERTCTL_KEYGEN_MODE=server) — private keys touch control plane, demo only`
- **Issuer-Specific Key Negotiation**:
- **ACME (Let's Encrypt, ZeroSSL)**: Let's Encrypt controls key types; certctl requests ECDSA P-256 by default.
@@ -178,7 +178,7 @@ This requirement covers key generation, storage, rotation, and destruction. Cert
**Evidence You Can Provide**:
- Deployment configuration: `CERTCTL_KEYGEN_MODE=agent` in production (verify in `docker-compose.yml`, Kubernetes manifests, or systemd units).
- Agent log excerpt showing key generation: `openssl genrsa...` or agent process logs with CSR submission timestamp.
- Agent log excerpt showing key generation: Go `crypto/ecdsa.GenerateKey(elliptic.P256())` via agent process logs with CSR submission timestamp.
- Certificate CSR audit: `GET /api/v1/audit?type=certificate_issued` showing CSR fingerprint (SHA-256 hash of CSR PEM).
- Renewal job logs showing agent-submitted CSR, not server-generated key.
@@ -205,7 +205,7 @@ This requirement covers key generation, storage, rotation, and destruction. Cert
- **Control Plane Key Storage** — Sensitive credentials managed via environment variables or `.env` files:
- CA private key path: `CERTCTL_CA_CERT_PATH` + `CERTCTL_CA_KEY_PATH` (for Local CA sub-CA mode).
- ACME account key: embedded in ACME issuer config (not stored separately; ACME library handles in memory).
- step-ca provisioner key: `CERTCTL_STEPCA_PROVISIONER_KEY` env var (JWK, in memory during runtime).
- step-ca provisioner key: `CERTCTL_STEPCA_KEY_PATH` env var (path to JWK private key file, loaded into memory during runtime).
- API keys: `CERTCTL_API_KEY` (SHA-256 hashed in database, plaintext never stored).
- Database credentials: `CERTCTL_DATABASE_URL` in `.env` file, not in source code.
docs/compliance-soc2.md
+2 -2
View File
@@ -89,7 +89,7 @@ Each section includes:
- **API Key Policy** — All API access requires an API key or explicit opt-out. Opt-out (`CERTCTL_AUTH_TYPE=none`) logs a warning: "WARNING: Auth disabled (CERTCTL_AUTH_TYPE=none) — this is insecure and only for development". Configuration choice is logged at startup.
- **Agent Authentication** — Agents authenticate to the server via API keys (same mechanism as users). Agent credentials are separate from user API keys.
- **Private Key Policy** — Agent-side key generation is the default (`CERTCTL_KEYGEN_MODE=agent`). Server-side keygen (`CERTCTL_KEYGEN_MODE=server`) requires explicit configuration and logs a warning: "Server-side keygen enabled — private keys will be stored in PostgreSQL (development only)".
- **Private Key Policy** — Agent-side key generation is the default (`CERTCTL_KEYGEN_MODE=agent`). Server-side keygen (`CERTCTL_KEYGEN_MODE=server`) requires explicit configuration and logs a warning: "server-side key generation enabled (CERTCTL_KEYGEN_MODE=server) — private keys touch control plane, demo only".
- **Password Policy** — Not applicable; certctl uses API keys exclusively. Password management is delegated to your organization's IAM system if you integrate OIDC/SSO (V3).
**Evidence Locations**:
@@ -119,7 +119,7 @@ Each section includes:
**certctl Implementation** (V2):
- **TLS for Control Plane** — All API communication occurs over HTTPS (TLS 1.2+). Server uses `tls.Dial()` for outbound connections to issuers and targets. Configuration: `CERTCTL_SERVER_ADDR` (default `:8443`).
- **TLS for Control Plane** — All API communication occurs over HTTPS (TLS 1.2+). Server uses `tls.Dial()` for outbound connections to issuers and targets. Configuration: `CERTCTL_SERVER_HOST` (default `127.0.0.1`) + `CERTCTL_SERVER_PORT` (default `8080`; Docker Compose maps to `8443`).
- **Agent-to-Server Communication** — Agents submit CSRs and heartbeats over HTTPS to the server using the same TLS stack.
- **Private Key Isolation** — Agents generate ECDSA P-256 private keys locally (`crypto/ecdsa` + `crypto/elliptic`). Private keys are never transmitted to the server — agents submit CSRs only. Private keys are stored on agent filesystem (`CERTCTL_KEY_DIR`, default `/var/lib/certctl/keys`) with 0600 (owner read/write only) permissions. Server-side keygen mode logs a development warning; production must use agent-side keygen.
- **Certificate Storage** — Signed certificates are stored in PostgreSQL as PEM text (along with metadata). Certificates are not secrets and may be transmitted plaintext. Private keys are never stored on the control plane in production (agent-side keygen mode).
docs/concepts.md
+1 -1
View File
@@ -180,7 +180,7 @@ certctl can alert you when certificates are expiring, when renewals fail, when d
### CLI
certctl ships with a command-line tool (`certctl-cli`) for operators who prefer terminal workflows or need to integrate certctl into shell scripts and CI/CD pipelines. The CLI wraps the REST API with 10 subcommands: `list-certs`, `get-cert`, `renew-cert`, `revoke-cert`, `list-agents`, `list-jobs`, `health`, `metrics`, and `import` (for bulk PEM import).
certctl ships with a command-line tool (`certctl-cli`) for operators who prefer terminal workflows or need to integrate certctl into shell scripts and CI/CD pipelines. The CLI wraps the REST API with 12 subcommands organized by resource: `certs list`, `certs get`, `certs renew`, `certs revoke`, `agents list`, `agents get`, `jobs list`, `jobs get`, `jobs cancel`, `import` (bulk PEM import), `status` (health + summary stats), and `version`.
The CLI supports both table and JSON output formats (`--format table` or `--format json`), connects to the server via `CERTCTL_SERVER_URL` and authenticates with `CERTCTL_API_KEY`. It's built with Go's standard library only — no external dependencies.
docs/connectors.md
+10
View File
@@ -37,6 +37,14 @@ type Connector interface {
// GetOrderStatus checks the status of an async issuance order
GetOrderStatus(ctx context.Context, orderID string) (*OrderStatus, error)
// GenerateCRL generates a DER-encoded X.509 CRL signed by this issuer.
// Returns nil if the issuer does not support CRL generation (e.g., ACME).
GenerateCRL(ctx context.Context, revokedCerts []RevokedCertEntry) ([]byte, error)
// SignOCSPResponse signs an OCSP response for the given certificate serial.
// Returns nil if the issuer does not support OCSP (e.g., ACME).
SignOCSPResponse(ctx context.Context, req OCSPSignRequest) ([]byte, error)
}
type IssuanceRequest struct {
@@ -474,6 +482,8 @@ Each notifier is enabled by its configuration env var:
| Notifier | Env Var | Description |
|----------|---------|-------------|
| Email | `CERTCTL_EMAIL_SMTP_HOST`, `CERTCTL_EMAIL_SMTP_PORT`, `CERTCTL_EMAIL_FROM` | SMTP email delivery. Optional: `CERTCTL_EMAIL_SMTP_USERNAME`, `CERTCTL_EMAIL_SMTP_PASSWORD` |
| Webhook | `CERTCTL_WEBHOOK_URL` | HTTP POST to any endpoint. Optional: `CERTCTL_WEBHOOK_SECRET` for HMAC signing |
| Slack | `CERTCTL_SLACK_WEBHOOK_URL` | Incoming webhook URL. Optional: `CERTCTL_SLACK_CHANNEL`, `CERTCTL_SLACK_USERNAME` |
| Teams | `CERTCTL_TEAMS_WEBHOOK_URL` | Incoming webhook URL (MessageCard format) |
| PagerDuty | `CERTCTL_PAGERDUTY_ROUTING_KEY` | Events API v2 routing key. Optional: `CERTCTL_PAGERDUTY_SEVERITY` (default: "warning") |
docs/demo-advanced.md
+10 -10
View File
@@ -875,28 +875,28 @@ export CERTCTL_SERVER_URL="http://localhost:8443"
export CERTCTL_API_KEY="test-key-123"
# List certificates (JSON or table format)
./certctl-cli list-certs --format table
./certctl-cli certs list
# Get certificate details
./certctl-cli get-cert mc-demo-api
./certctl-cli certs get mc-demo-api
# Trigger renewal
./certctl-cli renew-cert mc-demo-api
./certctl-cli certs renew mc-demo-api
# Revoke a certificate with RFC 5280 reason
./certctl-cli revoke-cert mc-demo-payments --reason keyCompromise
./certctl-cli certs revoke mc-demo-payments --reason keyCompromise
# List agents
./certctl-cli list-agents
./certctl-cli agents list
# List pending jobs
./certctl-cli list-jobs
./certctl-cli jobs list
# Check system health
./certctl-cli health
# Check system health and stats
./certctl-cli status
# Export metrics
./certctl-cli metrics --format json
# JSON output format
./certctl-cli --format json status
# Bulk import certificates from a PEM file
./certctl-cli import /path/to/certificates.pem
docs/demo-guide.md
+10 -11
View File
@@ -154,30 +154,29 @@ export CERTCTL_SERVER_URL="http://localhost:8443"
export CERTCTL_API_KEY="test-key-123"
# List certificates (JSON or table format)
./certctl-cli list-certs --format json
./certctl-cli list-certs --format table
./certctl-cli --format json certs list
./certctl-cli certs list
# Get certificate details
./certctl-cli get-cert mc-api-prod
./certctl-cli certs get mc-api-prod
# Trigger renewal
./certctl-cli renew-cert mc-api-prod
./certctl-cli certs renew mc-api-prod
# Revoke a certificate (with RFC 5280 reason)
./certctl-cli revoke-cert mc-api-prod --reason keyCompromise
./certctl-cli certs revoke mc-api-prod --reason keyCompromise
# List agents
./certctl-cli list-agents
./certctl-cli agents list
# List pending jobs
./certctl-cli list-jobs
./certctl-cli jobs list
# Bulk import certificates from PEM files
./certctl-cli import /path/to/certs.pem
# Check health and metrics
./certctl-cli health
./certctl-cli metrics
# Check system health and stats
./certctl-cli status
```
## MCP Server for AI Integration
@@ -243,7 +242,7 @@ If you're demoing to a team or customer, here's a suggested flow:
10. **Show certificate discovery** — "We discover certificates two ways: agents scan local filesystems, and the server actively probes TLS endpoints on your network. We deduplicate by fingerprint, show you what we found, and let you claim them or dismiss them"
11. **Show the immutable audit trail** — "Every action in the system is recorded: who did it, what they did, when, what changed. Export to CSV/JSON for compliance"
12. **Show advanced query features** — "Sort by any field, filter by date range, paginate efficiently with cursor-based pagination, select just the fields you need"
13. **Show the CLI and MCP server** — "Terminal users get `certctl-cli` with 10 subcommands. AI assistants get MCP integration with 78 tools. Everything is API-first"
13. **Show the CLI and MCP server** — "Terminal users get `certctl-cli` with 12 subcommands. AI assistants get MCP integration with 78 tools. Everything is API-first"
The whole walkthrough takes 5-10 minutes.
docs/features.md
+16 -14
View File
@@ -296,7 +296,7 @@ curl -H "$AUTH" "$SERVER/api/v1/policies/rp-standard/violations"
### step-ca
- **Protocol** — Native `/sign` and `/revoke` API (not ACME)
- **Authentication** — JWK provisioner with key file + password
- **Configuration** — `CERTCTL_STEPCA_URL`, `CERTCTL_STEPCA_PROVISIONER_NAME`, `CERTCTL_STEPCA_PROVISIONER_KEY_PATH`, `CERTCTL_STEPCA_PROVISIONER_PASSWORD`
- **Configuration** — `CERTCTL_STEPCA_URL`, `CERTCTL_STEPCA_PROVISIONER`, `CERTCTL_STEPCA_KEY_PATH`, `CERTCTL_STEPCA_PASSWORD`
- **Operations** — Issue, renew, revoke
- **Use Case** — Smallstep private CA, internal PKI with strong auth
@@ -903,16 +903,18 @@ The web dashboard is the primary operational interface for certctl. Built with *
| Subcommand | Usage | Output Format |
|------------|-------|----------------|
| **list-certs** | `certctl-cli list-certs [--filter]` | Table or JSON (--format=json) |
| **get-cert** | `certctl-cli get-cert <id>` | JSON cert details |
| **renew-cert** | `certctl-cli renew-cert <id>` | Job ID confirmation |
| **revoke-cert** | `certctl-cli revoke-cert <id> [--reason]` | Revocation confirmation |
| **list-agents** | `certctl-cli list-agents` | Table or JSON |
| **list-jobs** | `certctl-cli list-jobs [--filter]` | Table or JSON |
| **health** | `certctl-cli health` | Server status |
| **metrics** | `certctl-cli metrics` | JSON metrics |
| **certs list** | `certctl-cli certs list` | Table or JSON (--format=json) |
| **certs get** | `certctl-cli certs get <id>` | JSON cert details |
| **certs renew** | `certctl-cli certs renew <id>` | Job ID confirmation |
| **certs revoke** | `certctl-cli certs revoke <id> [--reason]` | Revocation confirmation |
| **agents list** | `certctl-cli agents list` | Table or JSON |
| **agents get** | `certctl-cli agents get <id>` | Agent details |
| **jobs list** | `certctl-cli jobs list` | Table or JSON |
| **jobs get** | `certctl-cli jobs get <id>` | Job details |
| **jobs cancel** | `certctl-cli jobs cancel <id>` | Cancellation confirmation |
| **status** | `certctl-cli status` | Health + summary stats |
| **import** | `certctl-cli import <pem-file>` | Bulk import cert count |
| **help** | `certctl-cli help [command]` | Command documentation |
| **version** | `certctl-cli version` | Version string |
**Implementation Details:**
- Stdlib-only (flag + text/tabwriter); no Cobra dependency
@@ -1092,9 +1094,9 @@ The web dashboard is the primary operational interface for certctl. Built with *
| Variable | Type | Default | Purpose |
|----------|------|---------|---------|
| `CERTCTL_STEPCA_URL` | string | (empty) | step-ca server URL |
| `CERTCTL_STEPCA_PROVISIONER_NAME` | string | (empty) | JWK provisioner name |
| `CERTCTL_STEPCA_PROVISIONER_KEY_PATH` | string | (empty) | Path to provisioner JWK private key |
| `CERTCTL_STEPCA_PROVISIONER_PASSWORD` | string | (empty) | Provisioner key password (if encrypted) |
| `CERTCTL_STEPCA_PROVISIONER` | string | (empty) | JWK provisioner name |
| `CERTCTL_STEPCA_KEY_PATH` | string | (empty) | Path to provisioner JWK private key |
| `CERTCTL_STEPCA_PASSWORD` | string | (empty) | Provisioner key password (if encrypted) |
#### OpenSSL/Custom CA Issuer
| Variable | Type | Default | Purpose |
@@ -1170,7 +1172,7 @@ Each guide includes an evidence summary table mapping specific criteria to certc
| Observability (charts, metrics, stats) | ✓ | ✓ | Shipped |
| REST API (91 endpoints) | ✓ | ✓ | Shipped |
| MCP server (78 tools) | ✓ | ✓ | Shipped v2.1 |
| CLI tool (10 subcommands) | ✓ | ✓ | Shipped |
| CLI tool (12 subcommands) | ✓ | ✓ | Shipped |
| Compliance mapping docs (SOC 2, PCI-DSS, NIST) | ✓ | ✓ | Shipped |
| Filesystem cert discovery (M18b) | ✓ | ✓ | Shipped |
| Network cert discovery (M21) | ✓ | ✓ | Shipped |