docs: Phase 4 follow-on batch 4 — 5 final target per-pages

Extracts the remaining target connectors: - ssh.md (194 lines) — agentless SSH/SFTP deploy with full host-key-acceptance threat model (what's accepted, what's not, mitigations including known_hosts enforcement and SSH cert auth); V3-Pro forward path - wincertstore.md (118 lines) — non-IIS Windows services via local PowerShell or WinRM proxy mode; store selection (My / Root / WebHosting); private-key permissions guidance - jks.md (189 lines) — JKS / PKCS#12 via keytool with full atomic snapshot+rollback contract (Bundle 8 'snapshot → delete → import → reload'), keytool argv password exposure threat model + mitigations - aws-acm.md (208 lines) — ACM target with full IAM policy, IRSA / instance-profile / SSO auth recipes, atomic-rollback contract, ALB attachment Terraform recipe, procurement-checklist crib - azure-kv.md (195 lines) — Key Vault target with managed-identity / workload-identity / service-principal auth recipes, version- semantics rollback caveat (no in-place restore without soft-delete), App Gateway / Front Door attachment recipe Index forward-list expanded to enumerate all 15 target connectors (5 from Phase 4 structural + 5 from batch 3 + 5 from this batch) in alphabetical order. This is part 4 of 4 for the Phase 4 follow-on (per-connector page extraction) tracked in cowork/docs-overhaul-phase-2-restructure-2026-05-04/log.md. Net add: 5 files, 904 lines. No content removed from index.md. End-state of Phase 4 follow-on: - 13 issuer per-pages (5 batch 1 + 8 batch 2) - 15 target per-pages (5 Phase 4 structural + 5 batch 3 + 5 batch 4) - index.md keeps its inline reference content; per-pages add operator depth on top, matching the pattern set by apache/f5/iis/k8s/nginx in Phase 4 structural
2026-06-07 13:51:36 +00:00 · 2026-05-05 04:07:21 +00:00
parent 082b8cf660
commit 969853ee53
6 changed files with 909 additions and 0 deletions
@@ -0,0 +1,194 @@
+# SSH (Agentless) Connector — Operator Deep-Dive
+
+> Last reviewed: 2026-05-05
+>
+> Operator-grade documentation for the SSH agentless target
+> connector. For the connector-development context (interface
+> contract, registry, atomic deploy primitive shared across all
+> targets), see the [connector index](index.md).
+
+## Overview
+
+The SSH connector enables agentless certificate deployment to any
+Linux/Unix server via SSH/SFTP. Instead of installing the certctl
+agent binary on every target, a single "proxy agent" in the same
+network zone deploys certificates to remote servers over SSH.
+
+This is ideal for environments where installing agents on every
+server is impractical — air-gapped servers, legacy fleets, or
+brownfield environments where agent installation requires change-
+control tickets per host.
+
+Implementation lives at `internal/connector/target/ssh/`.
+
+## When to use this connector
+
+Use the SSH connector when:
+
+- Installing the certctl agent on every target is impractical or
+  politically expensive.
+- The agent-to-target network path is operator-controlled.
+- You're deploying to known, registered infrastructure where the
+  operator implicitly trusts the host (you're already shipping it
+  a TLS cert).
+
+Look elsewhere when:
+
+- You're deploying across the public internet to dynamic /
+  multi-tenant hosts. The connector accepts any host key
+  (`InsecureIgnoreHostKey`); MITM resistance requires the
+  mitigations below.
+- Your environment has strict regulatory MITM-resistance
+  requirements (PCI-DSS Level 1, FedRAMP High). The inline-comment
+  "out of scope" framing on host-key acceptance doesn't satisfy
+  auditors who want documented host-key verification at the
+  connector level.
+
+## Configuration
+
+### Key authentication (recommended)
+
+```json
+{
+  "host": "web-server.internal",
+  "port": 22,
+  "user": "certctl",
+  "auth_method": "key",
+  "private_key_path": "/home/certctl/.ssh/id_ed25519",
+  "cert_path": "/etc/ssl/certs/cert.pem",
+  "key_path": "/etc/ssl/private/key.pem",
+  "chain_path": "/etc/ssl/certs/chain.pem",
+  "reload_command": "systemctl reload nginx",
+  "timeout": 30
+}
+```
+
+### Password authentication
+
+```json
+{
+  "host": "legacy-server.internal",
+  "user": "deploy",
+  "auth_method": "password",
+  "password": "s3cret",
+  "cert_path": "/etc/ssl/cert.pem",
+  "key_path": "/etc/ssl/key.pem",
+  "reload_command": "systemctl reload apache2"
+}
+```
+
+### Field reference
+
+| Field | Default | Description |
+|---|---|---|
+| `host` | (required) | SSH hostname or IP address |
+| `port` | 22 | SSH port |
+| `user` | (required) | SSH username |
+| `auth_method` | `"key"` | `"key"` or `"password"` |
+| `private_key_path` | — | Path to SSH private key file (key auth) |
+| `private_key` | — | Inline SSH private key PEM (alternative to path) |
+| `password` | — | SSH password (password auth) |
+| `passphrase` | — | Passphrase for encrypted private keys |
+| `cert_path` | (required) | Remote path for certificate file |
+| `key_path` | (required) | Remote path for private key file |
+| `chain_path` | — | Remote path for chain file (if empty, chain appended to cert) |
+| `cert_mode` | `"0644"` | File permissions for cert (octal) |
+| `key_mode` | `"0600"` | File permissions for private key (octal) |
+| `reload_command` | — | Command to execute after deployment |
+| `timeout` | 30 | SSH connection timeout in seconds |
+
+## Security baseline
+
+- **Key-based authentication is recommended** over password
+  authentication. Encrypted private keys are supported via
+  `passphrase`.
+- **Reload commands are validated against shell injection** (same
+  validation as Postfix/Dovecot connectors).
+- **Host field is regex-validated** to prevent shell metacharacters.
+- **Private keys are written with 0600 permissions** by default.
+- **Host key verification is intentionally skipped.** See the
+  threat model below.
+
+## Operator playbook: SSH host-key verification
+
+certctl's SSH connector dials each target with
+`HostKeyCallback: ssh.InsecureIgnoreHostKey()`, meaning **the
+connector accepts any server host key without comparison against
+`known_hosts`**. This is a documented design choice, not an
+oversight.
+
+### Why the connector accepts any host key
+
+- certctl deploys to operator-configured target infrastructure.
+  Each target is registered explicitly in the control plane with
+  hostname + auth credentials + cert/key paths; the operator
+  implicitly trusts the host they're deploying to (otherwise why
+  give it a TLS cert).
+- Mirrors the same posture certctl applies to the network scanner
+  (`InsecureSkipVerify` for cert-monitoring TLS handshakes) and
+  the F5 connector (`Insecure` flag for self-signed BIG-IP
+  management interfaces).
+- Avoids a heavyweight per-target `known_hosts` management layer
+  that would shift complexity onto operators with no
+  proportional security gain when the network model is
+  "operator-configured infrastructure on operator-controlled
+  network".
+
+### Threat model the design accepts
+
+- A passive eavesdropper on the agent-to-target link. SSH's
+  transport encryption still applies — host-key acceptance
+  affects MITM vulnerability, not on-the-wire confidentiality.
+- A MITM attacker on the agent-to-target link who can intercept
+  the SSH TCP handshake AND has positioned themselves on a
+  hostname the operator has registered as a deploy target.
+  Layered authentication (per-target SSH keys with strong
+  passphrases stored at the agent) limits the blast radius — the
+  MITM gets one target's cert+key payload, not the agent's
+  broader credentials.
+
+### Threat model the design does NOT accept
+
+- Deploying across the public internet to a host whose IP
+  rotates (e.g. ephemeral cloud instances behind a load balancer
+  that doesn't pin SSH host keys). In that scenario,
+  `InsecureIgnoreHostKey` opens an MITM window during IP
+  rotation — register a `known_hosts` file path or use SSH
+  certificates (below) instead.
+- Multi-tenant networks where another tenant could plausibly
+  impersonate the target host. certctl's design assumes
+  operator-controlled network paths.
+
+### Mitigations operators can layer on
+
+- **`known_hosts` enforcement**: implement a custom `SSHClient`
+  (the connector's `SSHClient` interface accepts injected clients
+  via `NewWithClient`) whose `Connect` method builds an
+  `ssh.ClientConfig` with `HostKeyCallback` set to
+  `knownhosts.New("/path/to/known_hosts")` from
+  `golang.org/x/crypto/ssh/knownhosts`.
+- **SSH certificate authentication**: use OpenSSH 5.4+ host
+  certificates signed by an organizational CA. Configure the
+  agent's `known_hosts` CA pinning via `@cert-authority` lines so
+  any host presenting a certificate signed by the CA is trusted,
+  regardless of IP rotation.
+- **Network segmentation**: run the certctl agent on the same
+  private network segment as its targets; require VPN tunnels
+  for cross-network deploys; use bastion hosts with their own
+  host-key validation.
+- **Per-target SSH keys**: rotate the agent's SSH credentials
+  per target so a successful MITM compromise is bounded to that
+  one target's cert+key, not the agent's broader credential set.
+
+### V3-Pro forward path
+
+The operator-managed `known_hosts` integration (config field +
+`HostKeyCallback` plumbing + per-target root-of-trust enforcement)
+is documented as V3-Pro work. Tracking:
+`WORKSPACE-ROADMAP.md` (search for "SSH known_hosts").
+
+## Related docs
+
+- [Connector index](index.md) — interface contract, registry, deploy primitive
+- [F5 BIG-IP](f5.md) — comparable proxy-agent target where the agent doesn't run on the appliance itself
+- [Kubernetes Secrets](k8s.md) — agent-in-cluster alternative when the targets are workloads rather than VMs