SPIRE plugins: Keylime node attestor (Go)
Tyler J King
83b1264ebc
NewClient no longer returns an error when Quartermaster is unreachable. grpc.DialContext without WithBlock is already non-blocking; the prior 10s timeout context was effectively a no-op. Removing it and adding explicit ConnectParams (BaseDelay 1s, Multiplier 1.5, Jitter 0.2, MaxDelay 30s, MinConnectTimeout 20s) makes the intended behavior explicit: the gRPC ClientConn retries connection in the background with exponential backoff, and RPCs return Unavailable until QM is up. The governance-notifier and substrate-keymanager plugins already log RPC errors via handleEvent and continue without aborting the SPIRE operation, so no call-site changes are needed. This unblocks SPIRE bootstrap when Quartermaster hasn't been deployed yet, breaking the SPIRE <-> QM circular deployment dependency. Added watchConnState helper that logs once per transition so operators see at SPIRE startup whether QM is reachable: a single WARN-style line when the connection is not yet Ready, and an INFO line when it becomes Ready. conn.Connect() is called eagerly so those logs fire at plugin load rather than waiting for the first RPC. Deferred: - Add a unit test for NewClient succeeding with an unreachable address (existing TestNewClientAcceptsTLSConfig is a pre-existing failure using placeholder cert paths; unrelated to this change). Signed-off-by: Tyler J King <tking@guildhouse.dev> |
||
|---|---|---|
| .github/workflows | ||
| cmd | ||
| deploy | ||
| docs | ||
| gen | ||
| pkg | ||
| proto | ||
| specs | ||
| test/fixtures | ||
| .gitignore | ||
| AUDIT.md | ||
| buf.gen.yaml | ||
| buf.yaml | ||
| CLAUDE.md | ||
| Containerfile.dev | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| SECURITY-AUDIT.md | ||
Guildhouse SPIRE Plugins
SPIRE plugins and specifications for governed SSH access via SPIFFE identity.
This repository extends the SPIFFE ecosystem with SSH certificate issuance, governance-aware credential lifecycle management, and Guildhouse platform integration.
Project Status
Stage: Active Development
| Component | Status |
|---|---|
Specifications (specs/) |
Draft — ready for SIG-Spec review |
pkg/shellstream |
Fully implemented with comprehensive tests |
pkg/config |
Implemented — HCL parsing + validation |
pkg/oidc |
Implemented — OIDC discovery, JWKS verification, JWT validation |
pkg/governance |
Implemented — gRPC client with mTLS, intent lifecycle, merkle anchoring |
pkg/sshcert |
Implemented — SSH certificate builder with Shellstream extensions |
Plugin binaries (cmd/) |
Implemented — go-plugin registration, Configure + core methods |
Proto codegen (gen/) |
Generated — quartermaster/v1 + bascule/v1 gRPC stubs |
| CI pipeline | Configured (.github/workflows/ci.yaml) |
Quick Start
# Clone and build
git clone https://github.com/guildhouse-cooperative/guildhouse-spire-plugins.git
cd guildhouse-spire-plugins
make build # Build all plugin binaries → bin/
# Run tests
make test # Run all unit tests
make lint # Run go vet
Specifications
The primary deliverables are three formal specifications in specs/:
- SPIFFE SSH-SVID — Defines SSH certificates whose identity derives from SPIFFE IDs
- Shellstream Extensions — Vendor-suffixed SSH certificate extensions for governance metadata
- Credential Governance — Credential lifecycle events as governed mutations with merkle anchoring
Plugins
Four SPIRE plugins in cmd/:
| Plugin | SPIRE Type | Runs In | Purpose |
|---|---|---|---|
oidc-attestor |
WorkloadAttestor | Agent | OIDC token verification, claim-to-selector mapping |
ssh-credential-composer |
CredentialComposer | Server | SSH certificate generation with Shellstream extensions |
governance-notifier |
Notifier | Server | Credential event notification, merkle anchoring |
substrate-keymanager |
KeyManager | Server | Governance-aware signing key management |
Packages
Shared Go libraries in pkg/:
shellstream— Encode/decode Shellstream SSH certificate extensions (comprehensive tests)oidc— OIDC discovery + JWKS key fetching + JWT signature verification (RS256, ES256)governance— GovernanceService + NotaryService gRPC client with mTLS, intent lifecycle, merkle anchoringsshcert— SSH certificate builder with Ed25519 keypair generation and Shellstream extension embeddingconfig— HCL configuration loading and validation
Documentation
Detailed documentation in docs/:
- Architecture — System design, data flow, package map
- Plugin Types — SPIRE plugin interfaces, method signatures, invocation timing
- SSH Certificate Flow — End-to-end certificate issuance sequence
- OIDC Attestation — Workload OIDC token verification flow
- Governance Integration — Intent lifecycle, MutationEnvelope construction
- Deployment — Kubernetes deployment with Kustomize
- Testing — Test strategy, fixtures, CI pipeline
Building
make build # Build all plugin binaries
make test # Run tests
make lint # Run go vet
make clean # Remove build artifacts
Proto Code Generation
Proto files in proto/ are copies from the Guildhouse
monorepo. To regenerate Go bindings:
make proto-gen
Requires buf to be installed.
License
Apache License 2.0 — see LICENSE.