sshsignhost/AGENTS.md

AGENTS.md

Project Overview

sshsignhost signs SSH host certificates with Vault. It is a drop-in replacement for the Python script Puppet used to render at /opt/sshsignhost/sshsignhost, and is invoked by profiles::ssh::sign (puppet-prod) through generate() at /usr/local/bin/sshsignhost.

Structure

main.go          # cobra command, flag surface, stdout rendering
config.go        # YAML config loading, defaults, validation
vault.go         # Vault HTTP client: approle/kubernetes login + sign
main_test.go     # end-to-end tests against an httptest TLS stand-in for Vault
integration_test.go # -tags=integration: signs against a real dev-mode Vault
Makefile         # build / test / lint / integration-test / snapshot / version bump
.goreleaser.yaml # binaries + RPM + Gitea release assets, one driver
scripts/         # integration-test.sh (dev-mode Vault in a container)
.woodpecker/     # build, test, pre-commit, integration (PR) + release (tag)

Contract with Puppet

• Flags use underscores (--public_key, --valid_principals), matching the argv the manifest builds.
• --valid_principals is forwarded to Vault as the comma-separated string it was given; it is never split and rejoined.
• generate() uses failonfail: true, combine: true: stderr is duped onto stdout at spawn. On success nothing may reach stderr, or parsejson() fails and the catalog compile breaks. TestSuccessWritesNothingToStderr runs the real binary in a subprocess to hold that line.
• A 200 response without data.signed_key is a failure, never an empty result.

Vault

• AppRole: POST {addr}/v1/auth/{approle_path}/login with role_id only; the Vault role sets bind_secret_id: false.
• Kubernetes: POST {addr}/v1/auth/{k8s_mount}/login with role and the JWT read from jwt_path. There is no fallback between methods -- a rejected login or an unknown auth_method fails with the cause named.
• Sign: POST {addr}/v1/{mount_point}/sign/{role_name} with X-Vault-Token and cert_type: host.

Known blockers

The Vault ACL policy grants sshca/sign/host, but the only role that exists is signhost, so production signs 403 on sshca/sign/signhost even though auth succeeds. That is a terraform-vault fix, not a bug here -- do not change the requested path.

The signhost role sets allowed_domains: main.unkin.net,consul with allow_bare_domains: false, so the bare hostname and the IP the manifest sends alongside the FQDN are refused. TestIntegrationRejectsPrincipalsOutsideAllowedDomains pins that behaviour; fixing it is another terraform-vault change.

TLS

tls_skip_verify defaults to true, preserving the Python helper's verify=False behaviour, and is a config key so it can be flipped without a code change once certificates are trusted everywhere.