From a4622d5e9a3706865a5f223af9a826b835f2fd59 Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Wed, 25 Mar 2026 00:36:47 -0400 Subject: [PATCH] =?UTF-8?q?fix:=20correct=20stale=20counts=20across=20all?= =?UTF-8?q?=20docs=20(tables=2019=E2=86=9221,=20MCP=20tools=2076=E2=86=927?= =?UTF-8?q?8,=20tests=20860=E2=86=92900+)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 8 ++++---- docs/architecture.md | 8 ++++---- docs/concepts.md | 2 +- docs/demo-advanced.md | 6 +++--- docs/demo-guide.md | 6 +++--- docs/features.md | 26 ++++++++++++++++++++------ docs/mcp.md | 22 +++++++++++----------- migrations/seed_demo.sql | 7 +++++++ 8 files changed, 53 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 76e89a9..7673144 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,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 "Agents" @@ -225,7 +225,7 @@ Docker Compose overrides these for the demo stack (see `deploy/docker-compose.ym ## MCP Server (AI Integration) -certctl ships a standalone MCP (Model Context Protocol) server that exposes all 76 API endpoints as tools for AI assistants — Claude, Cursor, Windsurf, OpenClaw, VS Code Copilot, and any MCP-compatible client. +certctl ships a standalone MCP (Model Context Protocol) server that exposes all 78 API endpoints as tools for AI assistants — Claude, Cursor, Windsurf, OpenClaw, VS Code Copilot, and any MCP-compatible client. ```bash # Install @@ -254,7 +254,7 @@ mcp-server } ``` -83 tools organized by resource: certificates (9), CRL/OCSP (3), issuers (6), targets (5), agents (8), discoveries (7), jobs (5), policies (6), profiles (5), teams (5), owners (5), agent groups (6), audit (2), notifications (3), stats (5), metrics (1), health (4). +78 tools organized by resource: certificates (9), CRL/OCSP (3), issuers (6), targets (5), agents (8), jobs (5), policies (6), profiles (5), teams (5), owners (5), agent groups (6), audit (2), notifications (3), stats (5), metrics (1), health (4). ## CLI @@ -518,7 +518,7 @@ All nine development milestones (M1–M9) are complete. The backend covers the f - **M15b: OCSP + Revocation GUI** ✅ — embedded OCSP responder (GET /api/v1/ocsp/{issuer_id}/{serial}), DER-encoded X.509 CRL (GET /api/v1/crl/{issuer_id}), short-lived cert exemption (TTL < 1h skip CRL/OCSP), revocation GUI with reason modal, ~31 new tests - **M13: GUI Operations** ✅ — bulk cert operations (multi-select → renew, revoke, reassign owner), deployment status timeline, inline policy/profile editor, target connector configuration wizard, audit trail export (CSV/JSON), short-lived credentials dashboard view - **M14: Observability** ✅ — dashboard charts (expiration heatmap, cert status distribution, job trends, issuance rate), agent fleet overview with OS/arch grouping, JSON metrics endpoint, stats API (5 endpoints), structured logging with request IDs, deployment rollback -- **M18a: MCP Server** ✅ (V2.1) — AI-native integration, all 76 REST API endpoints exposed as MCP tools for Claude, Cursor, OpenClaw, and any MCP-compatible client +- **M18a: MCP Server** ✅ (V2.1) — AI-native integration, all 78 REST API endpoints exposed as MCP tools for Claude, Cursor, OpenClaw, and any MCP-compatible client - **M19: Immutable API Audit Log** ✅ — every API call recorded to immutable audit trail (method, path, actor, SHA-256 body hash, status, latency), async recording via goroutine, configurable path exclusions - **M16a: Notifier Connectors** ✅ — Slack (incoming webhook), Microsoft Teams (MessageCard), PagerDuty (Events API v2), OpsGenie (Alert API v2) — config-driven enablement via env vars - **M17: Additional Connectors** ✅ — OpenSSL/Custom CA issuer connector (script-based signing with configurable timeout) diff --git a/docs/architecture.md b/docs/architecture.md index e1ebe45..d491bfe 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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. diff --git a/docs/concepts.md b/docs/concepts.md index 39d369b..93237b2 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -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. diff --git a/docs/demo-advanced.md b/docs/demo-advanced.md index 0aa56b4..9129eb7 100644 --- a/docs/demo-advanced.md +++ b/docs/demo-advanced.md @@ -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)" diff --git a/docs/demo-guide.md b/docs/demo-guide.md index 9d036b9..802c736 100644 --- a/docs/demo-guide.md +++ b/docs/demo-guide.md @@ -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. diff --git a/docs/features.md b/docs/features.md index c1c45de..761ac40 100644 --- a/docs/features.md +++ b/docs/features.md @@ -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 | diff --git a/docs/mcp.md b/docs/mcp.md index 5481872..b146466 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -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: diff --git a/migrations/seed_demo.sql b/migrations/seed_demo.sql index b989643..d34e86e 100644 --- a/migrations/seed_demo.sql +++ b/migrations/seed_demo.sql @@ -201,6 +201,13 @@ INSERT INTO agent_groups (id, name, description, match_os, match_architecture, m ('ag-manual', 'Manual Group', 'Manually managed agent group (no dynamic criteria)', '', '', '', '', false, NOW(), NOW()) ON CONFLICT (id) DO NOTHING; +-- Network Scan Targets +INSERT INTO network_scan_targets (id, name, cidrs, ports, enabled, scan_interval_hours, timeout_ms, created_at, updated_at) VALUES + ('nst-dc1-web', 'DC1 Web Servers', '{10.0.1.0/24}', '{443,8443}', true, 6, 5000, NOW(), NOW()), + ('nst-dc2-apps', 'DC2 Application Tier', '{10.0.2.0/24,10.0.3.0/24}', '{443}', true, 6, 5000, NOW(), NOW()), + ('nst-dmz', 'DMZ Public Endpoints', '{192.168.100.0/24}', '{443,8443,9443}', true, 12, 3000, NOW(), NOW()) +ON CONFLICT (id) DO NOTHING; + -- Agent Group Members (manual membership for the manual group) INSERT INTO agent_group_members (agent_group_id, agent_id, membership_type, created_at) VALUES ('ag-manual', 'ag-web-prod', 'include', NOW()),