SHA256

Tyler J King 9c492d739a docs: add ARCHITECTURE.md, CHANGELOG, fix Cargo metadata

ARCHITECTURE.md explains the governed shell stack, Keylime integration
model, ShellClass derivation, and implementation status for reviewer
orientation.

CHANGELOG documents v0.1.0-rc.1 deliverables.

Cargo.toml metadata (license, repository) added to bascule-core,
bascule-agent, bascule-gateway.

Signed-off-by: Tyler King <tking@guildhouse.dev>
Signed-off-by: Tyler J King <tking727@gmail.com>

2026-04-15 15:37:27 -04:00

3.5 KiB

Raw Blame History

Bascule — Governed Shell Access Control

Bascule is an SSH-over-HTTPS proxy with identity-aware sessions and ceremony-gated access control. It terminates operator identity (SSH certs, OIDC tokens, Entra), evaluates Accord policy, classifies sessions by the host's hardware attestation posture, and emits Chronicle audit events for every governed operation.

Component Map

Operator
  │
  ▼
bascule-gateway (cluster-side gRPC)
  ├─ OIDC auth → OperatorIdentity
  ├─ Ceremony engine (self-grant / single-approval / break-glass)
  ├─ Posture-current ConfigMap → ShellClass derivation
  ├─ OPA policy evaluation (via accord-opa)
  ├─ 8-stage filter chain (auth→session→classify→policy→budget→execute→response→audit)
  ├─ Breach evaluator (30s posture poll, BreachResponse enforcement)
  └─ Audit pipeline → Quartermaster merkle anchoring
  │
  ▼
bascule-agent (application sidecar)
  ├─ Shellstream protocol (msgpack over Unix socket)
  ├─ 8 namespace handlers (Crypto, Identity, Secrets, Governance,
  │   Attestation, Audit, Network, Intelligence)
  ├─ PostureReader → posture-current ConfigMap (cached, 30s TTL)
  └─ Optional SSH server on port 2222

bascule-core (shared types)
  ├─ SessionScope, ShellClass, DelegationScope
  ├─ CeremonyGrant, CeremonyType, Evidence
  ├─ derive_shell_class(PostureLevel) → ShellClass
  └─ BreachAction evaluation

Keylime Integration Model

Bascule consumes Keylime attestation — it does not reimplement or compete with it. The integration boundary is the posture-current ConfigMap written by the substrate-operator's posture evaluator:

Keylime verifier (CNCF)
  → substrate-operator / TpmAttestationValid checker
    → posture-current ConfigMap (level: 1-5)
      → bascule-agent PostureReader
      → bascule-gateway ceremony grant (ShellClass derivation)
      → bascule-gateway breach evaluator (session downgrade)

The keylime-client crate (in the substrate workspace) is the single Keylime consumer. Neither bascule-agent nor bascule-gateway imports it directly. They read the ConfigMap output.

ShellClass Model

Sessions are classified at ceremony grant time based on the host's operational posture level:

PostureLevel	ShellClass	Operations Permitted
Normal (5)	System	Kernel modules, firmware, network config, storage
Elevated (4)	Application	Deploy, query APIs, run playbooks
Restricted (3)	Application	Deploy, query APIs, run playbooks
Critical (2)	Application	Deploy, query APIs, run playbooks
Lockdown (1)	Application	Deploy, query APIs, run playbooks

No mid-session upgrade. Downgrade only (on posture breach).
Upgrade requires a new ceremony.
DelegationScope enables "Infrastructure shells" — Application sessions that orchestrate System operations on remote hosts (Ansible pattern).

What's Implemented vs Planned

Component	Status
Ceremony engine (3 types)	Implemented
8-stage filter chain	Implemented
PostureReader (ConfigMap)	Implemented
ShellClass derivation	Implemented
DelegationScope + pre-flight	Implemented (target posture query stubbed)
Breach evaluator + downgrade	Implemented
Accord hot-reload	Not implemented (static at startup)
Helm chart	Exists, not updated for posture fields
LabelSelector delegation	Type defined, async resolution deferred

License

Apache-2.0. All source files carry SPDX headers.

3.5 KiB Raw Blame History