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

feat(M39): IIS target connector + README overhaul

Browse Source 
Implement full IIS target connector with PEM-to-PFX conversion via
go-pkcs12, PowerShell-based deployment (Import-PfxCertificate, IIS
binding management), SHA-1 thumbprint computation, and SNI support.
Injectable PowerShellExecutor interface enables cross-platform testing.
Regex-validated config fields prevent PowerShell injection. 28 tests.

Restructure README from 563 to 313 lines: outcome-focused feature
descriptions, "Who Is This For" persona section, examples promoted
above the fold, configuration/API/security reference moved to docs.
All numbers verified against repo (25 GUI pages, 97 OpenAPI ops,
CI thresholds service 55%/handler 60%/domain 40%/middleware 30%).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
2026-04-02 20:27:27 -04:00
parent adfb682754
commit 8b52da6aef
6 changed files with 1594 additions and 434 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+1 -1
View File
@@ -417,7 +417,7 @@ The agent deploys certificates using target connectors. Each connector knows how
- **Apache httpd**: Writes separate cert/chain/key files, validates with `apachectl configtest`, graceful reload
- **HAProxy**: Builds a combined PEM file (cert + chain + key), optionally validates config, reloads via systemctl or signal
- **F5 BIG-IP** (planned): A proxy agent in the same network zone calls the iControl REST API to upload certificate and update SSL profile bindings. The server assigns the work; the proxy agent executes it.
- **IIS** (planned, dual-mode): (1) Agent-local (recommended) — a Windows agent on the IIS box runs PowerShell `Import-PfxCertificate` + `Set-WebBinding` directly. (2) Proxy agent WinRM — for agentless IIS targets, a nearby Windows agent reaches the IIS box via WinRM.
- **IIS** (implemented, dual-mode): (1) Agent-local (recommended) — a Windows agent on the IIS box runs PowerShell `Import-PfxCertificate` + `Set-WebBinding` directly with PFX conversion and SHA-1 thumbprint computation. (2) Proxy agent WinRM — for agentless IIS targets, a nearby Windows agent reaches the IIS box via WinRM.
The agent handles both the certificate (public) and the private key (read from local key store at `CERTCTL_KEY_DIR`). The control plane never sees the private key and never initiates outbound connections to agents or targets (pull-only model).
docs/connectors.md
+25 -12
View File
@@ -23,7 +23,7 @@ Connectors extend certctl to integrate with external systems for certificate iss
- [Built-in: Traefik](#built-in-traefik)
- [Built-in: Caddy](#built-in-caddy)
- [F5 BIG-IP (Interface Only)](#f5-big-ip-interface-only)
- [IIS (Interface Only, Dual-Mode)](#iis-interface-only-dual-mode)
- [IIS (Implemented, Dual-Mode)](#iis-implemented-dual-mode)
4. [Notifier Connector](#notifier-connector)
- [Interface](#interface-2)
5. [Registering a Connector](#registering-a-connector)
@@ -52,7 +52,7 @@ Connectors extend certctl to integrate with external systems for certificate iss
Three types of connectors:
1. **Issuer Connector** — Obtains certificates from CAs (Local CA with sub-CA support, ACME with HTTP-01 + DNS-01 + DNS-PERSIST-01, step-ca, OpenSSL/Custom CA implemented; additional CA integrations planned)
2. **Target Connector** — Deploys certificates to infrastructure (NGINX, Apache httpd, HAProxy, Traefik, Caddy implemented; F5 via proxy agent, IIS dual-mode interface only; additional cloud and network targets planned)
2. **Target Connector** — Deploys certificates to infrastructure (NGINX, Apache httpd, HAProxy, Traefik, Caddy, IIS implemented; F5 via proxy agent planned; additional cloud and network targets planned)
3. **Notifier Connector** — Sends alerts about certificate events (Email, Webhooks, Slack, Microsoft Teams, PagerDuty, OpsGenie implemented)
All connectors accept JSON configuration at initialization, support config validation, and are registered in the service layer. Issuer connectors run on the control plane; target connectors run on agents. For network appliances where agents can't be installed, a **proxy agent** in the same network zone handles deployment — the server never initiates outbound connections.
@@ -611,28 +611,41 @@ Note: F5 credentials are stored on the proxy agent, not on the control plane ser
Location: `internal/connector/target/f5/f5.go`
### IIS (Interface Only, Dual-Mode)
### IIS (Implemented, Dual-Mode)
The IIS target connector supports two planned deployment modes:
The IIS target connector supports two deployment modes — agent-local (recommended) and proxy agent WinRM for agentless targets.
**Agent-local (recommended):** A Windows agent runs directly on the IIS server and deploys certificates using PowerShell — `Import-PfxCertificate` to install into the certificate store and `Set-WebBinding` to bind to the IIS site. This is the preferred approach: no remote access needed, no credential management, same pull-based model as NGINX/Apache/HAProxy.
**Agent-local (recommended):** A Windows agent runs directly on the IIS server and deploys certificates using PowerShell — `Import-PfxCertificate` to install into the certificate store and `Set-WebBinding` to bind to the IIS site. The agent handles PEM-to-PFX conversion via `go-pkcs12`, computes SHA-1 thumbprint from the certificate, and executes parameterized PowerShell scripts for injection-safe binding management. This is the preferred approach: no remote access needed, no credential management, same pull-based model as NGINX/Apache/HAProxy.
**Proxy agent WinRM (for agentless targets):** For Windows servers where you don't want to install an agent, a nearby Windows agent acts as a proxy and reaches the IIS box via WinRM. The proxy agent picks up the deployment job, transfers the PFX bundle over WinRM, and runs the PowerShell commands remotely. WinRM credentials are stored on the proxy agent, not on the control plane.
Configuration (defined, not yet functional):
Configuration:
```json
{
"mode": "local",
"hostname": "iis-server.example.com",
"site_name": "Default Web Site",
"cert_store": "WebHosting",
"winrm_host": "",
"winrm_username": "",
"winrm_password": "",
"winrm_use_https": true
"port": 443,
"sni": true,
"ip_address": "*",
"binding_info": "IP:443:iis-server.example.com"
}
```
When `mode` is `"local"`, the `winrm_*` fields are ignored. When `mode` is `"proxy"`, the agent connects to the remote IIS server via WinRM using the provided credentials.
**Configuration Fields:**
- `hostname` (string, required): IIS server hostname or FQDN
- `site_name` (string, required): IIS website name (e.g., "Default Web Site")
- `cert_store` (string, required): Certificate store for import (e.g., "WebHosting", "My")
- `port` (number, default 443): HTTPS binding port
- `sni` (boolean, default true): Enable Server Name Indication (SNI)
- `ip_address` (string, default "*"): Specific IP to bind to, or "*" for all IPs
- `binding_info` (string, optional): Custom binding string for advanced scenarios
**Security Model:**
- PFX files are transient — generated with random passwords, deleted after import
- PowerShell commands are parameterized (no string interpolation) to prevent injection
- Field names are regex-validated before script execution
- Certificate thumbprints computed via SHA-1 for IIS binding lookups
Location: `internal/connector/target/iis/iis.go`
docs/testing-guide.md
+132
View File
@@ -46,6 +46,7 @@ Comprehensive manual testing playbook. Every test has a concrete command, an exp
- [Part 39: DigiCert Connector (M37)](#part-39-digicert-connector-m37)
- [Part 40: Issuer Catalog Page (M33)](#part-40-issuer-catalog-page-m33)
- [Part 41: Frontend Audit Fixes](#part-41-frontend-audit-fixes)
- [Part 42: IIS Target Connector (M39)](#part-42-iis-target-connector-m39)
- [Release Sign-Off](#release-sign-off)
---
@@ -5557,6 +5558,137 @@ Comprehensive frontend coverage audit closed 60 gaps between backend capabilitie
---
## Part 42: IIS Target Connector (M39)
The IIS target connector (M39) brings Windows infrastructure lifecycle management to certctl. Dual-mode implementation: agent-local PowerShell (primary) for servers with certctl agent, proxy agent WinRM for agentless Windows targets. Full test suite (28 tests) with mock executor pattern for cross-platform testing. Supports PEM-to-PFX conversion, SHA-1 thumbprint computation, and parameterized PowerShell execution.
### Test Suite Coverage
| Layer | Test Count | Focus | Cross-Platform |
|-------|-----------|-------|-----------------|
| ValidateConfig | 9 | Field validation, defaults, regex enforcement | Yes |
| DeployCertificate | 7 | PFX conversion, script execution, error handling | Yes |
| ValidateDeployment | 5 | Thumbprint verification, binding checks | Mock executor |
| PFX Conversion | 4 | Certificate chain handling, password generation | Yes |
| Helpers | 3 | Thumbprint computation, Windows time conversion | Yes |
| **Total** | **28** | | **26 pass, 2 skip on non-Windows** |
### Automated Tests (qa-smoke-test.sh Part 42)
| # | Test | Assertion |
|---|------|-----------|
| 42.1 | IIS connector imports without error | `internal/connector/target/iis/` builds cleanly |
| 42.2 | ValidateConfig rejects missing hostname | Validation fails when `hostname` absent |
| 42.3 | ValidateConfig rejects missing site_name | Validation fails when `site_name` absent |
| 42.4 | ValidateConfig applies defaults | `port` defaults to 443, `ip_address` to "*" |
| 42.5 | ValidateConfig validates field regex | Rejects field names with invalid characters |
| 42.6 | PEM-to-PFX conversion succeeds | PKCS#12 bundle created with random password |
| 42.7 | SHA-1 thumbprint computed correctly | Matches Go crypto/sha1 output, hex-encoded |
| 42.8 | PowerShell script is parameterized | No unescaped interpolation in generated commands |
| 42.9 | Mock executor pattern works cross-platform | Tests pass on Linux/macOS via mock executor |
| 42.10 | DeployCertificate calls Import-PfxCertificate | PowerShell command includes correct cert store |
| 42.11 | DeployCertificate calls Set-WebBinding | PowerShell command includes site name + thumbprint |
| 42.12 | ValidateDeployment executes Get-IISSiteBinding | Thumbprint comparison happens post-deployment |
| 42.13 | Error cases logged and propagated | TLS verify failure, script timeout errors handled |
| 42.14 | Windows time conversion helpers work | FileTime ↔ time.Time round-trip accurate |
### Manual Tests (Windows Only)
These tests require a real Windows Server 2019+ environment with IIS 10+. Skip on non-Windows platforms.
**42.M1: Agent-Local Deployment — Happy Path**
1. Provision a Windows Server 2019+ VM with IIS installed
2. Download and install certctl-agent binary for windows-amd64
3. Register agent with certctl server via heartbeat endpoint
4. Create IIS target in certctl dashboard:
```json
{
"hostname": "iis-server.local",
"site_name": "Default Web Site",
"cert_store": "WebHosting",
"port": 443,
"sni": true,
"ip_address": "*"
}
```
5. Issue a certificate (e.g., via Local CA)
6. Create deployment job targeting the IIS target
7. Agent polls work endpoint, executes PowerShell
8. Verify on IIS: `Get-IISSiteBinding` shows new binding with correct thumbprint
9. Verify in dashboard: Deployment job shows status=Completed, verified_at timestamp present
**PASS if** certificate deployed to IIS binding with matching thumbprint, deployment job shows Completed with verification success.
**42.M2: Agent-Local Deployment — Renewal**
1. On the same IIS target, trigger renewal of the certificate
2. Verify old certificate remains bound during renewal (until new one succeeds)
3. Verify new certificate is imported and bound after deployment
4. Verify old binding removed or updated in IIS
**PASS if** renewal completes without downtime, old binding replaced with new.
**42.M3: PFX Import to WebHosting Store**
1. Manually generate a test PKCS#12 certificate
2. Via certctl-agent on Windows, verify PowerShell can import to WebHosting store:
```powershell
$pfx = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$pfx.Import([System.IO.File]::ReadAllBytes("C:\temp\test.pfx"), $password, "Exportable")
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store("WebHosting", "LocalMachine")
$store.Open("MaxAllowed")
$store.Add($pfx)
```
3. Verify certificate appears in IIS Certificate Manager
**PASS if** certificate imports to WebHosting store successfully.
**42.M4: Binding Verification — Thumbprint Match**
1. Deploy a certificate to an IIS site via certctl
2. Manually run on IIS server:
```powershell
Get-IISSiteBinding -Name "Default Web Site" | Select-Object Thumbprint
```
3. Verify thumbprint matches certificate's SHA-1 hash (as shown in certctl GUI)
**PASS if** thumbprints match exactly (hex-encoded, no colons).
**42.M5: Error Handling — Invalid Site Name**
1. Create IIS target with non-existent site name (e.g., "NonExistentSite")
2. Trigger deployment
3. Verify job fails with error message about invalid site
4. Verify error is logged in agent and audit trail
**PASS if** error handled gracefully, job marked Failed with reason.
**42.M6: Field Validation — Config Injection Attempt**
1. Try to create IIS target with site_name containing PowerShell metacharacters:
```json
{
"site_name": "Default Web Site'; Get-Process; #"
}
```
2. Verify regex validation rejects this (field validation error, not API error)
3. Verify no PowerShell execution occurs
**PASS if** injection attempt blocked by field validation.
**42.M7: SNI vs Non-SNI Binding**
1. Create two IIS targets: one with `sni: true`, one with `sni: false`
2. Deploy certificates to both
3. Verify Set-WebBinding with `-SslFlags 1` (SNI) for first target
4. Verify Set-WebBinding without SslFlags (no SNI) for second target
5. Test TLS connection to both sites, verify SNI-enabled site handles multiple domains correctly
**PASS if** SNI bindings configured correctly per target config.
---
## Release Sign-Off
All tests below must pass before tagging v2.1.0. Each row is one individual test from the guide above. The **Method** column indicates whether `qa-smoke-test.sh` covers the test automatically (**Auto**) or requires hands-on verification (**Manual**).