SPIRE plugins: Keylime node attestor (Go)
fe5e2cf3c6
SPIRE WorkloadAttestor that reads governance env vars from /proc/{pid}/environ
(walking up the process tree to find gsh) and emits gsap: selectors on workload
SVIDs. Maps BASCULE_* vars set by bascule-shell and future GSH_* vars to the
11-selector vocabulary defined in gsap-types/src/selectors.rs.
- pkg/gsap/selectors.go: shared Go constants mirroring Rust vocabulary
- cmd/gsap-attestor/: plugin implementation with /proc reading, process tree
walking, capability ceiling translation, and fail-open for non-governed processes
- 28 tests covering selector extraction, proc parsing, tree walking, and depth limits
- Makefile, Dockerfile, deploy config updated
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
||
|---|---|---|
| .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 | ||
| GSAP-ATTESTOR-DESIGN.md | ||
| 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.