tking/bascule-oss
SHA256
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update all documentation for management API + dashboard

Browse source 
Updated 9 files to reflect:
  Management API (axum, port 9090) — embedded in bascule-server
  Dioxus dashboard components (WASM web target)
  6 crates in workspace (was 4)

README.md:
  Added Management API + Dashboard features section
  Added dashboard row to comparison table

docs/architecture.md:
  Updated diagram showing dual-listener architecture
  Added Management API section explaining Arc<SessionStore> sharing
  Updated crate table (6 crates)

docs/configuration.md:
  Added [dashboard] config section reference

docs/observability.md:
  Added Management API monitoring section with curl examples

docs/quickstart.md:
  Added Management API quick start section

docs/comparison.md:
  Added dashboard and TPM attestation rows

CLAUDE.md + CONTRIBUTING.md:
  Updated crate lists and feature flags

config/bascule.example.toml:
  Added [dashboard] section

All 17 README links verified valid. Build clean.

Signed-off-by: Tyler King <tking@guildhouse.dev>
This commit is contained in:
Tyler King 2026-04-05 17:17:18 -04:00
parent 72fa8cee92
commit 6eb2de5dc0
9 changed files with 102 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
CLAUDE.md
View file

@ -6,10 +6,12 @@ Bascule is an identity-aware SSH proxy. It authenticates operators via SSH keys
## Workspace
- `crates/bascule-core/` — Library: SSH server, auth, session backends, hooks
- `crates/bascule-server/` — Binary: CLI wrapper, config loading, telemetry setup
- `crates/bascule-core/` — Library: SSH server, auth, session backends, hooks, session store
- `crates/bascule-server/` — Binary: SSH proxy + embedded management API (axum)
- `crates/bascule-auth-agent-id/` — Optional: Entra Agent ID auth provider
- `crates/bascule-shell/` — Binary: Identity-aware login shell with TPM attestation
- `crates/bascule-dashboard/` — Library: Dioxus UI components
- `crates/bascule-dashboard-web/` — Binary: WASM web dashboard target
- `charts/bascule/` — Helm chart for K8s deployment
- `images/` — Curated container images for operator environments
@ -30,6 +32,7 @@ make dev # Run locally in dev mode
## Feature flags (bascule-server)
- `dashboard` — Management API on port 9090 (default on)
- `agent-id` — Entra Agent ID auth
## Rules

8
CONTRIBUTING.md
View file

@ -15,10 +15,12 @@ Bascule is a Rust workspace:
| Crate | Purpose |
|-------|---------|
| `bascule-core` | Library — SSH server, auth, PTY, proxy, container, hooks |
| `bascule-server` | Binary — CLI, config, telemetry |
| `bascule-core` | Library — SSH server, auth, PTY, proxy, container, hooks, store |
| `bascule-server` | Binary — SSH proxy + management API (axum) |
| `bascule-auth-agent-id` | Optional — Entra Agent ID auth |
| `bascule-shell` | Binary — Identity-aware login shell |
| `bascule-shell` | Binary — Identity-aware login shell with TPM |
| `bascule-dashboard` | Library — Dioxus UI components |
| `bascule-dashboard-web` | Binary — WASM web dashboard target |
## Testing

10
README.md
View file

@ -41,10 +41,19 @@ See [docs/quickstart.md](docs/quickstart.md) for Docker, Helm, and container mod
- Read-only rootfs option
- NetworkPolicy for Kubernetes deployments
### Management API + Dashboard
Built-in HTTP management API (port 9090, `--features dashboard`):
- `GET /api/sessions` — active sessions with auth/backend/TPM status
- `GET /api/stats` — aggregate analytics (auth breakdown, peak concurrent, TPM %)
- `GET /api/health` — server health and version
- WASM dashboard at `/dashboard/` *(coming soon)*
### Observability
- Structured JSON logging (`BASCULE_LOG_FORMAT=json`)
- Tracing spans on auth, session lifecycle, exec requests
- Management API for real-time session monitoring
## Client: bascule-shell
@ -76,6 +85,7 @@ See [docs/bascule-shell.md](docs/bascule-shell.md).
| Container sessions | Yes | No | No |
| AI Agent Identity | Yes (Entra Agent ID) | No | No |
| Binary size | ~7MB | ~150MB | ~100MB |
| Built-in dashboard | Yes (port 9090) | Yes | No |
See [docs/comparison.md](docs/comparison.md).

6
config/bascule.example.toml
View file

@ -79,6 +79,12 @@ mode = "accept-all"
# shell_container = "shell"
# shell = "/bin/bash"
# ─── Dashboard / Management API ─────────────────────────
# Enabled by default with --features dashboard
[dashboard]
enabled = true
listen = "0.0.0.0:9090"
# ─── Telemetry ──────────────────────────────────────────
# [telemetry]
# otlp_endpoint = "http://localhost:4317"

45
docs/architecture.md
View file

@ -2,20 +2,28 @@
## Overview
Bascule is a single-binary SSH proxy with three pluggable layers:
Bascule is a single-binary SSH proxy with a built-in management API:
```
Client SSH → Bascule Server
│
├── AuthProvider (SSH keys / OIDC / Agent ID)
│
├── SessionHandler hooks
│ on_session_start → build_session_env → on_exec → on_session_end
│
└── SessionBackend
├── LocalPty (portable-pty → /bin/bash)
├── RemoteProxy (upstream SSH → target host)
└── Container (docker/podman → ephemeral image)
┌─────────────────────────────────────┐
Operator workstation │ bascule (single binary) │
┌───────────────┐ │ │
│ bascule-shell │ SSH │ Port 2222: SSH Proxy (russh) │
│ identity + │─────▶│ ├── AuthProvider │
│ TPM attest │ │ ├── SessionHandler hooks │
└───────────────┘ │ └── SessionBackend │
│ ├── Local PTY │
Browser / curl │ ├── Remote Proxy │
┌───────────────┐ HTTP │ └── Container │
│ Dashboard │─────▶│ │
│ /api/* │ │ Port 9090: Management API (axum) │
└───────────────┘ │ ├── /api/sessions │
│ ├── /api/stats │
│ ├── /api/health │
│ └── /dashboard (WASM, planned) │
│ │
│ Arc<SessionStore> shared │
└─────────────────────────────────────┘
```
## Session Backends
@ -81,10 +89,19 @@ When `ephemeral = true` (default), the container is `--rm` and destroyed on disc
Set `network = "none"` to completely isolate the container from the network. The operator can run local tools but can't reach external services.
## Management API
The management API runs alongside the SSH proxy in the same process. Both share an `Arc<SessionStore>` — when a session starts via SSH, the store updates; when the dashboard polls `/api/sessions`, it reads the same store. Zero serialization, zero IPC.
Enable via `[dashboard]` config section or `--features dashboard` (default on).
## Crate Structure
| Crate | Purpose |
|-------|---------|
| `bascule-core` | Library — server, handler, auth, PTY, proxy, container, hooks |
| `bascule-server` | Binary — CLI, config loading, tracing setup |
| `bascule-core` | Library — server, handler, auth, PTY, proxy, container, hooks, store |
| `bascule-server` | Binary — CLI, config, tracing, management API |
| `bascule-auth-agent-id` | Optional — Entra Agent ID authentication |
| `bascule-shell` | Binary — Identity-aware login shell with TPM |
| `bascule-dashboard` | Library — Dioxus UI components |
| `bascule-dashboard-web` | Binary — WASM web dashboard target |

2
docs/comparison.md
View file

@ -14,6 +14,8 @@
| Extensibility | SessionHandler trait | Plugin system | No | No |
| Proxy mode | Built-in | Built-in | Built-in | SaaS |
| Config | Single TOML file | Complex YAML | Complex HCL | Web UI |
| Built-in dashboard | Yes (port 9090) | Yes | No | Yes (SaaS) |
| TPM attestation | Yes (bascule-shell) | No | No | No |
## When to choose Bascule

11
docs/configuration.md
View file

@ -111,6 +111,17 @@ memory_limit = "512m"
network = "none"
```
## `[dashboard]`
Management API and dashboard (requires `--features dashboard`, default on).
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Enable management API |
| `listen` | string | `0.0.0.0:9090` | Listen address for HTTP API |
## Example Configs
### Jumphost (proxy)
```toml

17
docs/observability.md
View file

@ -38,6 +38,23 @@ RUST_LOG=bascule=debug ./bascule --config config.toml # debug bascule only
| Upstream connected | INFO | Proxy session connected to target |
| Session ended | INFO | Disconnect or exit |
## Management API
The built-in management API (port 9090) provides real-time session monitoring:
```bash
# Active sessions
curl http://localhost:9090/api/sessions
# Aggregate stats (auth breakdown, TPM %, peak concurrent)
curl http://localhost:9090/api/stats
# Server health
curl http://localhost:9090/api/health
```
Configure via `[dashboard]` in your config file. See [configuration.md](configuration.md).
## OTel Tracing (Planned)
OpenTelemetry OTLP export is planned as an optional feature flag (`--features telemetry`). Not yet implemented. Session lifecycle will map to OTel spans:

15
docs/quickstart.md
View file

@ -56,6 +56,21 @@ TOML
./target/release/bascule --config proxy-config.toml
```
## Management API
The management API starts automatically on port 9090:
```bash
# Check server health
curl http://localhost:9090/api/health
# View active sessions
curl http://localhost:9090/api/sessions
# Aggregate stats
curl http://localhost:9090/api/stats
```
## Next Steps
- [Configuration Reference](configuration.md)