SPIRE plugins: Keylime node attestor (Go)
5f62da6ca9
Custom SPIRE NodeAttestor that queries Keylime attestation status instead of performing independent TPM attestation. Keylime remains the single TPM authority in the stack. Two data source strategies: - ConfigMap (default): reads posture-current ConfigMap (recommended, consistent with single-consumer principle) - Verifier: queries Keylime verifier REST API directly (for out-of-cluster SPIRE servers) Fail-closed: unknown nodes, unreachable sources, degraded posture all result in non-attested verdict — no SVID issued. Maps posture level to attestation verdict: Normal(5)/Elevated(4) → Attested Restricted(3) → Pending Critical(2)/Lockdown(1) → Failed 8 unit tests covering ConfigMap source, verifier mapping, edge cases. Signed-off-by: Tyler King <tking@guildhouse.dev> Signed-off-by: Tyler J King <tking727@gmail.com> |
||
|---|---|---|
| .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.