Tyler King
2fa92f8635
New files: CONTRIBUTING.md — dev setup, code style, PR process CLAUDE.md — workspace context for Claude Code Makefile — build, test, lint, fmt, docker, helm-lint, dev, ci .editorconfig — consistent formatting rustfmt.toml — Rust formatting config docs/kubernetes.md — Helm install, values, architecture docs/bascule-shell.md — client shell install, config, TPM charts/bascule/README.md — Helm quick start Updated: README.md — accurate feature matrix, clear shipped vs planned config/bascule.example.toml — full reference (72 lines, all fields) All 15 README links verified valid. Helm lint clean. Build passes. 0 substrate deps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
82 lines
1.9 KiB
Markdown
82 lines
1.9 KiB
Markdown
# bascule-shell
|
|
|
|
Identity-aware login shell with TPM attestation.
|
|
|
|
## What it does
|
|
|
|
`bascule-shell` wraps your preferred shell (bash/zsh/fish) and:
|
|
|
|
1. Detects your identity (Entra, Kerberos, SSH key)
|
|
2. Reads TPM PCR values and IMA measurements
|
|
3. Displays a banner with identity + attestation summary
|
|
4. Sets `BASCULE_*` environment variables
|
|
5. Execs into the inner shell
|
|
|
|
Every SSH connection from inside the shell carries your identity and platform attestation.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
cargo install --path crates/bascule-shell
|
|
# or
|
|
cargo build --release -p bascule-shell
|
|
cp target/release/bascule-shell /usr/local/bin/
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Start the shell
|
|
bascule-shell
|
|
|
|
# Show identity + attestation (dry run)
|
|
bascule-shell --info
|
|
|
|
# JSON output
|
|
bascule-shell --info --json
|
|
|
|
# Run a single command
|
|
bascule-shell --exec "env | grep BASCULE_"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
`~/.config/bascule/shell.toml`:
|
|
|
|
```toml
|
|
inner_shell = "/bin/bash"
|
|
show_banner = true
|
|
pcr_indices = [0, 1, 2, 7, 10, 14]
|
|
|
|
# Auto-configure SSH for Bascule servers
|
|
# [[servers]]
|
|
# alias = "jumphost"
|
|
# hostname = "bascule.example.com"
|
|
# port = 2222
|
|
```
|
|
|
|
## Identity Detection
|
|
|
|
Priority order:
|
|
|
|
| Method | Source | When detected |
|
|
|--------|--------|---------------|
|
|
| Entra (WSL2) | `cmd.exe` interop | WSL2 with Entra-joined Windows |
|
|
| Azure CLI | `az account show` | `az` installed and logged in |
|
|
| Kerberos | `klist -s` | Valid TGT present |
|
|
| Cached OIDC | `~/.config/bascule/token.json` | Token file exists and not expired |
|
|
| System user | `$USER` | Always (fallback) |
|
|
|
|
## Environment Variables
|
|
|
|
After startup, the inner shell has:
|
|
|
|
| Variable | Example |
|
|
|----------|---------|
|
|
| `BASCULE_PRINCIPAL` | `tking` |
|
|
| `BASCULE_AUTH_METHOD` | `ssh-key` |
|
|
| `BASCULE_ATTESTATION_HASH` | `sha256:e9b95f...` |
|
|
| `BASCULE_TPM_AVAILABLE` | `true` |
|
|
| `BASCULE_PCR_COUNT` | `6` |
|
|
| `BASCULE_IMA_COUNT` | `1247` |
|
|
| `BASCULE_PLATFORM_SUMMARY` | `tpm:6pcr,ima:1247` |
|