9c492d739a
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>
92 lines
3.5 KiB
Markdown
92 lines
3.5 KiB
Markdown
# 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.
|