SPIRE plugins: Keylime node attestor (Go)
Tyler J King
f3e1d161d0
Two-stage build. Builder stage: golang:1.23.6-bookworm (pinned to match the go directive in go.mod exactly), CGO_ENABLED=0, -trimpath and -s -w linker flags for reproducible, size-minimized static binaries. Compiles all four plugin binaries into /plugins/. Runtime stage: debian:bookworm-slim with the /plugins/ directory copied in and made world-readable. The image is inert — SPIRE server and agent Deployments consume it via an initContainer that runs `cp -r /plugins/ /opt/spire/plugins/` into a shared emptyDir volume, so no ENTRYPOINT is needed. Path: git.guildhouse.dev/tking/spire-plugins:v0.1.0. Not replacing Containerfile.dev, which remains the local-dev variant. 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 | ||
| Dockerfile | ||
| 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.