SPIRE plugins: Keylime node attestor (Go)
f0268305ae
Document the trust withdrawal cascade: Keylime breach → posture degraded → sessions downgraded → SPIRE re-attestation fails → SVIDs expire → service mTLS fails → quorum degrades No new code for the cascade — it's emergent from existing re-attestation behavior + the Keylime attestor plugin. SPIRE federation handles cross-edge propagation through standard certificate expiration. Three timing profiles: Standard (~1hr), Enhanced (~15min), Critical (~5min) with SVID TTL configuration guidance. Example SPIRE server config with Keylime attestor + k8s_psat fallback for nodes without hardware TPM. 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.