mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:11:29 +00:00
shankar0123
3e91c7a1f0
CI run #484's Go Build & Test job failed govulncheck (M-024 hard gate). Six standard-library CVEs land in go1.25.9 + one golang.org/x/net CVE in v0.49.0; all are fixed in go1.25.10 + x/net v0.53.0 respectively. The advisories that fired were: GO-2026-4986 Quadratic string concat in net/mail.consumeComment — called via internal/api/handler/validation.go's ValidateCommonName -> mail.ParseAddress GO-2026-4977 Quadratic string concat in net/mail.consumePhrase — same call site GO-2026-4982 Bypass of meta-content URL escaping in html/template — called via internal/service/digest.go's RenderDigestHTML -> Template.Execute GO-2026-4980 Escaper bypass in html/template — same call site GO-2026-4971 Panic in net.Dial / LookupPort on Windows NUL bytes — many call sites (email notifier, SSH connector, ACME validators, validation.ValidateSafeURL, ...) GO-2026-4918 Infinite loop in net/http2 transport on bad SETTINGS_MAX_FRAME_SIZE — called via internal/connector/target/f5.go's F5Client.Authenticate -> http.Client.Do Bumps applied: * `go.mod`: `go 1.25.9` -> `go 1.25.10`; `golang.org/x/net v0.49.0` -> `v0.53.0` (kept indirect — the upgrade is force-pulled by the module-version directive; transitive deps will pick the higher). * `.github/workflows/{ci,codeql,release}.yml`: setup-go pin and the release.yml `GO_VERSION` env var bumped to 1.25.10. The security-deep-scan.yml workflow uses the major-minor `1.25` pin which auto-resolves to the latest 1.25.x and is unaffected. * `Dockerfile` + `Dockerfile.agent`: `golang:1.25-alpine@sha256:5caa...` re-pinned to `golang:1.25.10-alpine@sha256:8d22e29d960bc50cd0...` (digest looked up against `registry-1.docker.io/v2/library/golang/ manifests/1.25.10-alpine`; verified by the digest-validity ci-guard). The explicit `1.25.10-alpine` tag form replaces the moving `1.25-alpine` pin so the image-spec is reproducible end-to-end even without the digest reference. * `deploy/test/f5-mock-icontrol/Dockerfile`: `golang:1.25.9-bookworm @sha256:1a14...` re-pinned to `golang:1.25.10-bookworm@sha256: e3a54b77385b4f8a31c1...` (looked up the same way). * `deploy/test/f5-mock-icontrol/go.mod`: `go 1.25.9` -> `go 1.25.10`. * `internal/api/handler/version.go` + `api/openapi.yaml`: the `runtime.Version()`-shape comment + OpenAPI `example: go1.25.9` bumped to keep doc/example freshness. * `docs/contributor/ci-pipeline.md` + `docs/reference/connectors/ iis.md`: doc-only `Go 1.25.9` -> `Go 1.25.10` references. Verification done in-tree: * All `scripts/ci-guards/*.sh` pass locally including `digest-validity.sh` (the new digests resolve cleanly against Docker Hub). * `S-1-hardcoded-source-counts.sh` clean (the false-positive on "Bundle 1 migrations" was fixed in the prior commit). Operator step required post-push (sandbox has no Go toolchain): cd certctl && go mod tidy This regenerates go.sum's `golang.org/x/net v0.49.0` h1: lines into v0.53.0 ones. CI's `go mod tidy && git diff --exit-code go.mod go.sum` step will catch the drift if missed; in that case run the command, commit, and push the go.sum-only delta.
201 lines
6.8 KiB
Markdown
201 lines
6.8 KiB
Markdown
# Microsoft IIS Connector — Operator Deep-Dive
|
|
|
|
> Last reviewed: 2026-05-05
|
|
>
|
|
> Per Phase 14 of the deploy-hardening II master bundle. For the
|
|
> connector-development context (interface contract, registry, atomic
|
|
> deploy primitive shared across all targets), see the
|
|
> [connector index](index.md).
|
|
|
|
## Overview
|
|
|
|
The IIS connector (`internal/connector/target/iis/`) deploys TLS
|
|
certs to Windows IIS servers via PowerShell (`Import-PfxCertificate`
|
|
+ `New-WebBinding` + SNI binding). Pre-deploy snapshot of the
|
|
existing thumbprint allows rollback if the new binding fails.
|
|
|
|
## Vendor versions tested
|
|
|
|
- **Windows Server 2019** with IIS 10
|
|
- **Windows Server 2022** with IIS 10
|
|
|
|
## CI runner constraint
|
|
|
|
Per frozen decision 0.4: Windows containers run only on Windows
|
|
hosts. Linux CI runners CAN'T run the IIS sidecar. IIS e2e tests
|
|
run on a separate `windows-vendor-e2e` GitHub Actions matrix job
|
|
on `windows-latest` runners. Operators on Linux-only CI use
|
|
`//go:build integration && !no_iis` to skip.
|
|
|
|
## Per-quirk operator guidance
|
|
|
|
### App-pool recycle (opt-in)
|
|
|
|
`TestVendorEdge_IIS_AppPoolRecycle_OptInForCertChange_E2E`
|
|
|
|
By default, IIS picks up new SSL bindings without app-pool
|
|
recycle (the binding-edit path is hot). Some sites need recycle
|
|
to fully reload (e.g., apps that cache cert handles).
|
|
|
|
**Operator action:** set `AppPoolRecycle: true` per-target. The
|
|
connector then runs `Restart-WebAppPool <pool>` after binding update.
|
|
|
|
### SNI multi-binding per site
|
|
|
|
`TestVendorEdge_IIS_SNIMultiBindingPerSite_DeployUpdatesCorrectBinding_E2E`
|
|
|
|
When a site has multiple SNI bindings (different hostnames on
|
|
the same site), connector targets the binding matching the
|
|
operator-supplied hostname. Other bindings unchanged.
|
|
|
|
### CCS (Centralized Certificate Store)
|
|
|
|
`TestVendorEdge_IIS_CCSCentralizedCertStoreVariant_DeployToSharedStore_E2E`
|
|
|
|
CCS is the file-based variant where multiple IIS servers share
|
|
a UNC path of cert files. Connector writes to the shared path;
|
|
all IIS servers pick it up automatically.
|
|
|
|
### WinRM remote vs local PowerShell
|
|
|
|
`TestVendorEdge_IIS_WinRMRemotePath_vs_LocalPowerShellPath_BothWork_E2E`
|
|
|
|
Two code paths produce equivalent cert installs:
|
|
- `WinRMHost: ""` → local PowerShell (agent runs on the IIS server)
|
|
- `WinRMHost: "iis.example"` → remote PowerShell via WinRM
|
|
|
|
Both rotate the same way. WinRM path requires network reachability
|
|
to port 5985/5986.
|
|
|
|
### Server 2019 vs 2022 PowerShell compat
|
|
|
|
`TestVendorEdge_IIS_WindowsServer2019_vs_2022_PowerShellCompat_E2E`
|
|
|
|
`Import-PfxCertificate` + `New-WebBinding` semantics are stable
|
|
across server versions. PowerShell 5.1 (2019) + PowerShell 7.x
|
|
(2022) both work.
|
|
|
|
### Friendly name
|
|
|
|
`TestVendorEdge_IIS_FriendlyNameUpdatedOnRotation_E2E`
|
|
|
|
Connector preserves operator-supplied `FriendlyName` on the cert
|
|
across rotation. Useful for IIS GUI identification.
|
|
|
|
### HTTP/2 + ALPN
|
|
|
|
`TestVendorEdge_IIS_HTTP2ALPNPreserved_E2E`
|
|
|
|
IIS h2 negotiation preserved across cert rotation. The
|
|
`netsh http show sslcert` ALPN attribute survives the binding swap.
|
|
|
|
### Binding-type validation
|
|
|
|
`TestVendorEdge_IIS_BindingTypeHttpsValidated_E2E`
|
|
|
|
Connector refuses to deploy to non-`https` bindings (e.g., `http`,
|
|
`net.tcp`). Surfaces actionable error.
|
|
|
|
### ARR reverse-proxy
|
|
|
|
`TestVendorEdge_IIS_ARRReverseProxyCertRotation_E2E`
|
|
|
|
Sites using Application Request Routing as reverse proxy: cert
|
|
rotation does not invalidate ARR routes. The cert-binding edit
|
|
is independent of the ARR config.
|
|
|
|
### Atomic SNI binding swap
|
|
|
|
`TestVendorEdge_IIS_RemovePreviousBindingOnRotate_E2E`
|
|
|
|
Connector removes the previous SNI binding BEFORE inserting the
|
|
new one (atomicity at the IIS API level). Prevents brief
|
|
window where two bindings serve different certs for the same
|
|
hostname.
|
|
|
|
## Troubleshooting matrix
|
|
|
|
| Symptom | Test name | Operator action |
|
|
|---|---|---|
|
|
| Cert installed but app pool serving old cert | `AppPoolRecycle_OptInForCertChange_E2E` | set `AppPoolRecycle: true` |
|
|
| Wrong SNI binding updated | `SNIMultiBindingPerSite_E2E` | verify hostname selector |
|
|
| Permission denied on cert install | n/a | agent must run as administrator |
|
|
| WinRM connection failed | `WinRMRemotePath_vs_LocalPowerShellPath_E2E` | check WinRM port 5985/5986 reachability |
|
|
| h2 negotiation broken post-rotate | `HTTP2ALPNPreserved_E2E` | re-run `netsh http add sslcert` with `appid + clientcertnegotiation=enable` |
|
|
|
|
## V3-Pro deferrals
|
|
|
|
- IIS Application Initialization module integration (warm cert
|
|
cache after rotation).
|
|
- Azure Key Vault + IIS integration (operator opt-in).
|
|
|
|
## Related docs
|
|
|
|
- [Atomic deploy + post-verify + rollback](../deployment-model.md)
|
|
- [Vendor compatibility matrix](../vendor-matrix.md)
|
|
|
|
## Operator validation playbook (Windows host)
|
|
|
|
CI no longer runs the IIS + WinCertStore vendor-e2e tests on every
|
|
push. Per ci-pipeline-cleanup bundle frozen decision 0.5 (which
|
|
revises Bundle II decision 0.4), the Windows matrix was deleted
|
|
because (a) it couldn't physically work on `windows-latest` GitHub
|
|
runners (Docker not started in Windows-containers mode by default;
|
|
`bridge` network driver doesn't exist on Windows Docker — uses
|
|
`nat`), and (b) all IIS + WinCertStore vendor-edge tests are
|
|
`t.Log` placeholder stubs that exercise no IIS-specific behavior.
|
|
|
|
The real IIS connector validation lives in:
|
|
|
|
1. `internal/connector/target/iis/` unit tests (run on Linux in the
|
|
regular Go Build & Test job — already green on every push).
|
|
2. This playbook — operator manual smoke against a real Windows host
|
|
pre-release.
|
|
|
|
### Prerequisites
|
|
|
|
- Windows Server 2019 or 2022 host (or Windows 10/11 Pro with Hyper-V)
|
|
- Docker Desktop in Windows containers mode
|
|
(Settings → "Switch to Windows containers")
|
|
- Go 1.25.10 + git
|
|
|
|
### Procedure
|
|
|
|
```powershell
|
|
# Clone + checkout
|
|
git clone https://github.com/certctl-io/certctl.git
|
|
cd certctl
|
|
git fetch --tags
|
|
git checkout v2.X.0 # whichever release is being validated
|
|
|
|
# Bring up the Windows IIS sidecar
|
|
docker compose --profile deploy-e2e-windows `
|
|
-f deploy/docker-compose.test.yml `
|
|
up -d windows-iis-test
|
|
Start-Sleep -Seconds 30
|
|
|
|
# Run IIS + WinCertStore vendor-edge tests
|
|
$env:INTEGRATION = "1"
|
|
go test -tags integration -race -count=1 `
|
|
-run 'VendorEdge_(IIS|WinCertStore)' `
|
|
./deploy/test/... | Tee-Object -FilePath iis-validation.log
|
|
|
|
# Tear down
|
|
docker compose --profile deploy-e2e-windows `
|
|
-f deploy/docker-compose.test.yml `
|
|
down -v
|
|
```
|
|
|
|
### Acceptance
|
|
|
|
Per Bundle II frozen decision 0.14, the IIS / WinCertStore cells in
|
|
`docs/reference/vendor-matrix.md` flip from "CI" / "pending" → "✓"
|
|
only when ALL of the following are true:
|
|
|
|
- ≥1 happy-path e2e passes against the real Windows IIS sidecar
|
|
- ≥1 specific-quirk test for that Windows Server version passes
|
|
- This playbook's full procedure ran clean once on a real Windows host
|
|
|
|
Operator records the validation date + Windows Server version in
|
|
the project's per-bundle iis-validation receipts for audit trail.
|