mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:01:32 +00:00
fix: correct stale counts across all docs (tables 19→21, MCP tools 76→78, tests 860→900+)
V2 audit found 3 critical number mismatches propagated across 8 files: - Table count was 19 everywhere but actual migrations create 21 tables - MCP tool count was 76 but tools.go registers 78 (M21/M22 additions) - README MCP breakdown claimed 83 tools with math summing to 90 - architecture.md still had stale 860+ test count - features.md OpenAPI claim said 93 ops but spec has 78 - mcp.md tool-per-domain table had wrong counts in 10 of 16 rows - Added 3 network_scan_targets to seed_demo.sql for demo completeness - Added curl examples to Agent Groups section in features.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
@@ -30,7 +30,7 @@ flowchart TB
|
||||
end
|
||||
|
||||
subgraph "Data Store"
|
||||
PG[("PostgreSQL 16\n19 tables\nTEXT primary keys")]
|
||||
PG[("PostgreSQL 16\n21 tables\nTEXT primary keys")]
|
||||
end
|
||||
|
||||
subgraph "Agent Fleet"
|
||||
@@ -634,7 +634,7 @@ flowchart LR
|
||||
AI["AI Assistant\n(Claude, Cursor)"] -->|"stdio"| MCP["MCP Server\ncmd/mcp-server/"]
|
||||
MCP -->|"HTTP + Bearer token"| API["certctl REST API\n:8443"]
|
||||
|
||||
subgraph "76 MCP Tools"
|
||||
subgraph "78 MCP Tools"
|
||||
T1["Certificate CRUD"]
|
||||
T2["Agent Management"]
|
||||
T3["Job Operations"]
|
||||
@@ -648,7 +648,7 @@ flowchart LR
|
||||
|
||||
The MCP server is a stateless HTTP proxy — every MCP tool call translates to an HTTP request to the certctl REST API. It adds no new state, no new dependencies, and no new attack surface beyond what the API already exposes. Configuration is minimal: `CERTCTL_SERVER_URL` and `CERTCTL_API_KEY` environment variables.
|
||||
|
||||
The 76 tools are organized across 16 resource domains with typed input structs and `jsonschema` struct tags for automatic LLM-friendly schema generation. Binary response support handles DER CRL and OCSP endpoints.
|
||||
The 78 tools are organized across 16 resource domains with typed input structs and `jsonschema` struct tags for automatic LLM-friendly schema generation. Binary response support handles DER CRL and OCSP endpoints.
|
||||
|
||||
## CLI Tool
|
||||
|
||||
@@ -773,7 +773,7 @@ This data flow is pull-based and non-blocking. Agents discover at their own pace
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
certctl uses a layered testing approach aligned with the handler → service → repository architecture, with 860+ tests across five layers (service, handler, integration, connector, and frontend). The goal is high-confidence regression prevention at the service and handler layers, where the most complex business logic lives, combined with integration tests that exercise the full request path from HTTP to database.
|
||||
certctl uses a layered testing approach aligned with the handler → service → repository architecture, with 900+ tests across five layers (service, handler, integration, connector, and frontend). The goal is high-confidence regression prevention at the service and handler layers, where the most complex business logic lives, combined with integration tests that exercise the full request path from HTTP to database.
|
||||
|
||||
**Service layer unit tests** (`internal/service/*_test.go`) — ~238 test functions across 15 files with mock repositories. These test all business logic in isolation: certificate CRUD with validation, certificate revocation (success, already-revoked, archived, invalid reason, all RFC 5280 reason codes, issuer notification, notification service integration, OCSP/CRL generation), agent lifecycle (registration, heartbeat, CSR submission with both keygen modes), job state machine (creation, processing, cancellation, retry logic), policy evaluation (all 5 rule types, violation creation), renewal and issuance flow (server-side and agent-side keygen paths), notification deduplication (threshold tag matching, channel routing), team/owner/agent group CRUD with pagination and audit recording, issuer service CRUD with connection testing, and the issuer connector adapter (type translation between connector and service layers including revocation). Mock repositories are simple structs with function fields, avoiding heavy mocking frameworks — this keeps tests readable and avoids coupling to mock library APIs.
|
||||
|
||||
|
||||
+1
-1
@@ -186,7 +186,7 @@ The CLI supports both table and JSON output formats (`--format table` or `--form
|
||||
|
||||
### MCP Server (AI Integration)
|
||||
|
||||
certctl includes an MCP (Model Context Protocol) server that exposes all 76 API endpoints as MCP tools. This enables AI assistants like Claude, Cursor, and other MCP-compatible tools to interact with your certificate infrastructure using natural language — "show me all expiring certificates," "revoke the VPN cert," or "what agents are offline?"
|
||||
certctl includes an MCP (Model Context Protocol) server that exposes all 78 API endpoints as MCP tools. This enables AI assistants like Claude, Cursor, and other MCP-compatible tools to interact with your certificate infrastructure using natural language — "show me all expiring certificates," "revoke the VPN cert," or "what agents are offline?"
|
||||
|
||||
The MCP server is a separate binary (`cmd/mcp-server/`) that communicates via stdio transport and acts as a stateless HTTP proxy to the certctl REST API. It requires no additional infrastructure — just point it at your certctl server URL and API key.
|
||||
|
||||
|
||||
@@ -875,7 +875,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
|
||||
## Part 15: MCP Server for AI Integration (M18a)
|
||||
|
||||
certctl exposes all 76 API endpoints as tools via the Model Context Protocol (MCP), enabling seamless integration with Claude, Cursor, and other AI assistants:
|
||||
certctl exposes all 78 API endpoints as tools via the Model Context Protocol (MCP), enabling seamless integration with Claude, Cursor, and other AI assistants:
|
||||
|
||||
```bash
|
||||
# Build the MCP server
|
||||
@@ -889,7 +889,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
./mcp-server
|
||||
```
|
||||
|
||||
**How it works:** The MCP server uses the official Model Context Protocol Go SDK to expose stateless HTTP proxies to all 76 API endpoints. Each MCP tool corresponds to one or more REST endpoints and includes:
|
||||
**How it works:** The MCP server uses the official Model Context Protocol Go SDK to expose stateless HTTP proxies to all 78 API endpoints. Each MCP tool corresponds to one or more REST endpoints and includes:
|
||||
|
||||
- **Input schema** — typed arguments with JSON schema hints for LLM-friendly introspection
|
||||
- **Binary support** — handles DER-encoded CRL and OCSP responses without mangling
|
||||
@@ -1028,7 +1028,7 @@ flowchart TB
|
||||
end
|
||||
|
||||
subgraph "Data Store"
|
||||
PG["PostgreSQL 16\n19 tables, TEXT PKs"]
|
||||
PG["PostgreSQL 16\n21 tables, TEXT PKs"]
|
||||
end
|
||||
|
||||
subgraph "Agent (certctl-agent)"
|
||||
|
||||
+3
-3
@@ -182,7 +182,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
|
||||
## MCP Server for AI Integration
|
||||
|
||||
certctl exposes its 76 API endpoints as tools via the Model Context Protocol (MCP), enabling integration with Claude, Cursor, and other AI assistants:
|
||||
certctl exposes its 78 API endpoints as tools via the Model Context Protocol (MCP), enabling integration with Claude, Cursor, and other AI assistants:
|
||||
|
||||
```bash
|
||||
# Build and run the MCP server
|
||||
@@ -195,7 +195,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
```
|
||||
|
||||
The MCP server:
|
||||
- Exposes all 76 API endpoints as MCP tools with typed schemas
|
||||
- Exposes all 78 API endpoints as MCP tools with typed schemas
|
||||
- Handles binary responses (DER CRL, OCSP responses)
|
||||
- Uses stdio transport for Claude/Cursor/OpenClaw integration
|
||||
- Zero external dependencies — pure Go with official MCP SDK
|
||||
@@ -243,7 +243,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 76 tools. Everything is API-first"
|
||||
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"
|
||||
|
||||
The whole walkthrough takes 5-10 minutes.
|
||||
|
||||
|
||||
+20
-6
@@ -417,7 +417,21 @@ Collected via runtime introspection and network utilities.
|
||||
| **Version** | Agent binary version (from build flags) | v2.1.0 |
|
||||
|
||||
### Agent Groups (M11b)
|
||||
Dynamic grouping and filtering for policy assignment and deployment targeting.
|
||||
Dynamic grouping and filtering for policy assignment and deployment targeting. Agent groups let you apply renewal policies to subsets of your fleet — for example, "all Linux amd64 agents in the 10.0.0.0/8 network" — without manually listing every agent.
|
||||
|
||||
```bash
|
||||
# Create a group matching all Linux agents in a specific subnet
|
||||
curl -X POST -H "$AUTH" -H "$CT" $SERVER/api/v1/agent-groups -d '{
|
||||
"id": "ag-linux-dc1", "name": "Linux DC1",
|
||||
"os_match": "linux", "ip_cidr_match": "10.0.1.0/24"
|
||||
}'
|
||||
|
||||
# List groups and their criteria
|
||||
curl -H "$AUTH" "$SERVER/api/v1/agent-groups" | jq '.items[] | {id, name, os_match, ip_cidr_match}'
|
||||
|
||||
# View members of a group (dynamically matched + manual includes)
|
||||
curl -H "$AUTH" "$SERVER/api/v1/agent-groups/ag-linux-dc1/members" | jq '.items[].agent_id'
|
||||
```
|
||||
|
||||
| Criterion | Details | Example |
|
||||
|-----------|---------|---------|
|
||||
@@ -842,7 +856,7 @@ The web dashboard is the primary operational interface for certctl. Built with *
|
||||
- **Transport** — stdio (stdin/stdout)
|
||||
- **Protocol** — Model Context Protocol v1
|
||||
- **SDK** — Official `modelcontextprotocol/go-sdk` v1.4.1
|
||||
- **Tools** — 76 MCP tools covering all API endpoints
|
||||
- **Tools** — 78 MCP tools covering all API endpoints
|
||||
- **Organization** — 16 resource domains (Certificates, Issuers, Targets, Agents, Jobs, etc.)
|
||||
- **Authentication** — Bearer token via `CERTCTL_API_KEY` env var
|
||||
- **Configuration** — `CERTCTL_SERVER_URL` (e.g., http://localhost:8080) + `CERTCTL_API_KEY`
|
||||
@@ -875,7 +889,7 @@ The web dashboard is the primary operational interface for certctl. Built with *
|
||||
|
||||
### OpenAPI 3.1 Specification
|
||||
- **File** — `api/openapi.yaml`
|
||||
- **Scope** — 93 operations (91 API + /health + /ready)
|
||||
- **Scope** — 78 documented operations (spec covers core API; discovery and network scan endpoints pending addition)
|
||||
- **Schemas** — Complete domain models with examples
|
||||
- **Enums** — Job types, states, policy rule types, notification types
|
||||
- **Pagination** — Standard envelope (data, total, page, per_page)
|
||||
@@ -932,7 +946,7 @@ The web dashboard is the primary operational interface for certctl. Built with *
|
||||
|
||||
### Deployment Architecture
|
||||
- **Server** — Go HTTP server (net/http stdlib) on `:8080` (default) or `:8443` (Docker)
|
||||
- **Database** — PostgreSQL 16 with 19 tables, TEXT primary keys (human-readable prefixed IDs)
|
||||
- **Database** — PostgreSQL 16 with 21 tables, TEXT primary keys (human-readable prefixed IDs)
|
||||
- **Agent** — Lightweight Go binary on target infrastructure
|
||||
- **Dashboard** — React SPA served from `/web/dist/` (Vite build)
|
||||
|
||||
@@ -943,7 +957,7 @@ The web dashboard is the primary operational interface for certctl. Built with *
|
||||
- **Credentials** — Environment variables in `.env` file; app.key for API key
|
||||
|
||||
### PostgreSQL Schema
|
||||
- **19 Tables** — Certificates, certificate versions, agents, deployment targets, renewal policies, jobs, audit events, notifications, issuers, policy rules, policy violations, certificate profiles, teams, owners, agent groups, agent group members, certificate revocations, discovered certificates, discovery scans, network scan targets
|
||||
- **21 Tables** — Certificates, certificate versions, agents, deployment targets, certificate-target mappings, renewal policies, jobs, audit events, notifications, issuers, policy rules, policy violations, certificate profiles, teams, owners, agent groups, agent group members, certificate revocations, discovered certificates, discovery scans, network scan targets
|
||||
- **TEXT Primary Keys** — Human-readable prefixed IDs: mc-*, t-*, a-*, j-*, p-*, etc.
|
||||
- **Indexes** — 5+ performance indexes on foreign keys, timestamps, status fields
|
||||
- **Migrations** — Idempotent migrations with `IF NOT EXISTS`, `ON CONFLICT`, numbered sequentially
|
||||
@@ -1120,7 +1134,7 @@ Each guide includes an evidence summary table mapping specific criteria to certc
|
||||
| Dashboard + 19 pages | ✓ | ✓ | Shipped |
|
||||
| Observability (charts, metrics, stats) | ✓ | ✓ | Shipped |
|
||||
| REST API (91 endpoints) | ✓ | ✓ | Shipped |
|
||||
| MCP server (76 tools) | ✓ | ✓ | Shipped v2.1 |
|
||||
| MCP server (78 tools) | ✓ | ✓ | Shipped v2.1 |
|
||||
| CLI tool (10 subcommands) | ✓ | ✓ | Shipped |
|
||||
| Compliance mapping docs (SOC 2, PCI-DSS, NIST) | ✓ | ✓ | Shipped |
|
||||
| Filesystem cert discovery (M18b) | ✓ | ✓ | Shipped |
|
||||
|
||||
+11
-11
@@ -6,7 +6,7 @@ This guide covers setup, configuration, and usage with Claude, Cursor, and other
|
||||
|
||||
## What Is MCP?
|
||||
|
||||
MCP is an open protocol that connects AI assistants to external tools and data sources. Instead of copying and pasting API responses into a chat window, MCP lets the AI call your tools directly. The certctl MCP server exposes all 76 API endpoints as MCP tools — the AI sees typed schemas describing what each tool does, what parameters it accepts, and what it returns.
|
||||
MCP is an open protocol that connects AI assistants to external tools and data sources. Instead of copying and pasting API responses into a chat window, MCP lets the AI call your tools directly. The certctl MCP server exposes all 78 API endpoints as MCP tools — the AI sees typed schemas describing what each tool does, what parameters it accepts, and what it returns.
|
||||
|
||||
The MCP server is a separate binary (`cmd/mcp-server/`) that communicates via stdio transport. It's a stateless HTTP proxy: every MCP tool call becomes an HTTP request to the certctl REST API. No new state, no new database tables, no new attack surface beyond what the API already exposes.
|
||||
|
||||
@@ -56,7 +56,7 @@ Add this to your Claude Desktop MCP configuration file (`~/Library/Application S
|
||||
}
|
||||
```
|
||||
|
||||
Restart Claude Desktop. You should see "certctl" appear in the MCP tools list with 76 available tools.
|
||||
Restart Claude Desktop. You should see "certctl" appear in the MCP tools list with 78 available tools.
|
||||
|
||||
## Setting Up with Cursor
|
||||
|
||||
@@ -94,26 +94,26 @@ Add certctl as an MCP server in your project's `.mcp.json`:
|
||||
|
||||
## Available Tools
|
||||
|
||||
The MCP server registers 76 tools organized across 16 resource domains:
|
||||
The MCP server registers 78 tools organized across 16 resource domains:
|
||||
|
||||
| Domain | Tools | Examples |
|
||||
|--------|-------|---------|
|
||||
| Certificates | 10 | List, get, create, update, archive, versions, renew, deploy, revoke, deployments |
|
||||
| Certificates | 9 | List, get, create, update, archive, versions, renew, deploy, revoke |
|
||||
| CRL & OCSP | 3 | Get JSON CRL, get DER CRL by issuer, check OCSP status |
|
||||
| Issuers | 5 | List, get, create, delete, test connection |
|
||||
| Issuers | 6 | List, get, create, update, delete, test connection |
|
||||
| Targets | 5 | List, get, create, update, delete |
|
||||
| Agents | 6 | List, get, register, heartbeat, get work, report job status |
|
||||
| Jobs | 4 | List, get, cancel, approve/reject |
|
||||
| Policies | 5 | List, get, create, update, delete, list violations |
|
||||
| Agents | 8 | List, get, register, heartbeat, CSR submit, certificate pickup, get work, report job status |
|
||||
| Jobs | 5 | List, get, cancel, approve, reject |
|
||||
| Policies | 6 | List, get, create, update, delete, list violations |
|
||||
| Profiles | 5 | List, get, create, update, delete |
|
||||
| Teams | 5 | List, get, create, update, delete |
|
||||
| Owners | 5 | List, get, create, update, delete |
|
||||
| Agent Groups | 5 | List, get, create, update, delete |
|
||||
| Agent Groups | 6 | List, get, create, update, delete, list members |
|
||||
| Audit | 2 | List events (with filters), get event by ID |
|
||||
| Notifications | 3 | List, get, mark as read |
|
||||
| Stats | 5 | Summary, certs by status, expiration timeline, job trends, issuance rate |
|
||||
| Metrics | 1 | System metrics (gauges, counters, uptime) |
|
||||
| Health | 3 | Health check, readiness probe, auth info |
|
||||
| Health | 4 | Health check, readiness probe, auth info, auth check |
|
||||
|
||||
Every tool has typed input parameters with `jsonschema` descriptions, so the AI knows exactly what arguments to provide and what each field means.
|
||||
|
||||
@@ -153,7 +153,7 @@ flowchart LR
|
||||
AI <-->|"stdio"| MCP
|
||||
MCP -->|"HTTP + Bearer token"| SERVER
|
||||
|
||||
MCP ~~~ TOOLS["76 tools · 16 domains\nTyped input structs"]
|
||||
MCP ~~~ TOOLS["78 tools · 16 domains\nTyped input structs"]
|
||||
```
|
||||
|
||||
The MCP server is intentionally thin:
|
||||
|
||||
Reference in New Issue
Block a user