Tyler King
4aa7e9d816
DCO (Developer Certificate of Origin): Standard DCO 1.1 (Linux kernel, CNCF, Kubernetes standard) Contributors retain copyright — no rights assignment NOTICE: Copyright attribution (Guildhouse LLC) Contributors retain copyright, own their implementations SessionHandler/AuthProvider as public API boundary Tribal jurisdiction for voluntary dispute resolution GOVERNANCE.md: Project governance model and decision making IP framework: Guildhouse brand vs contributor code vs shared Apache 2.0 SessionHandler trait IS the product boundary Tribal dispute resolution: voluntary, technically informed Tribal partnership mission CI: DCO sign-off check on pull requests Existing commits on main exempt README + CONTRIBUTING: Governance section, DCO instructions, corporate guidance Signed-off-by: Tyler King <tking@guildhouse.dev>
145 lines
4.4 KiB
Markdown
145 lines
4.4 KiB
Markdown
# Bascule
|
|
|
|
Identity-aware SSH proxy for modern infrastructure.
|
|
|
|
Bascule authenticates operators via SSH keys or AI agent tokens, then connects them to a local shell, remote host, or ephemeral container. No agents to install. No control plane. One binary.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cargo build --release -p bascule-server
|
|
./target/release/bascule --config config/bascule.example.toml
|
|
# In another terminal:
|
|
ssh -p 2222 localhost
|
|
```
|
|
|
|
See [docs/quickstart.md](docs/quickstart.md) for Docker, Helm, and container mode.
|
|
|
|
## Features
|
|
|
|
### Session Backends
|
|
|
|
| Mode | Config | Description |
|
|
|------|--------|-------------|
|
|
| Local PTY | (default) | Spawn a local shell process |
|
|
| Remote Proxy | `[proxy]` | Forward to a remote SSH host |
|
|
| Container | `[container]` | Ephemeral container per session (Docker/Podman/nerdctl) |
|
|
| Kubernetes | `[k8s]` | Shared jumphost with shell sidecar *(config ready, runtime coming)* |
|
|
|
|
### Authentication
|
|
|
|
- **SSH Keys** — standard OpenSSH authorized_keys files
|
|
- **Accept All** — development only, accepts any key
|
|
- **Entra Agent ID** — Microsoft AI agent identity (`--features agent-id`)
|
|
- **SPIFFE/SPIRE** — workload identity *(config ready, runtime coming)*
|
|
|
|
### Security
|
|
|
|
- Session limiting (semaphore-based `max_sessions`)
|
|
- Container hardening (`--cap-drop ALL`, `--security-opt no-new-privileges`)
|
|
- Container config validation (injection prevention)
|
|
- Read-only rootfs option
|
|
- NetworkPolicy for Kubernetes deployments
|
|
|
|
### Observability
|
|
|
|
- Structured JSON logging (`BASCULE_LOG_FORMAT=json`)
|
|
- Tracing spans on auth, session lifecycle, exec requests
|
|
|
|
## Client: bascule-shell
|
|
|
|
Identity-aware login shell with TPM attestation:
|
|
|
|
```bash
|
|
./target/release/bascule-shell --info
|
|
```
|
|
|
|
```
|
|
╔═══════════════════════════════════════════════════════╗
|
|
║ Bascule Shell v0.1.0 ║
|
|
║ Principal: tking ║
|
|
║ Method: ssh-key ║
|
|
║ TPM: available (6 PCRs verified) ║
|
|
║ Platform: sha256:e9b95f002f54222d... ║
|
|
╚═══════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
See [docs/bascule-shell.md](docs/bascule-shell.md).
|
|
|
|
## Comparison
|
|
|
|
| | Bascule | Teleport | Boundary |
|
|
|---|---|---|---|
|
|
| License | Apache 2.0 | AGPL / Commercial | MPL / Commercial |
|
|
| Agents required | No | Yes | Yes |
|
|
| Control plane | No | Required | Required |
|
|
| Container sessions | Yes | No | No |
|
|
| AI Agent Identity | Yes (Entra Agent ID) | No | No |
|
|
| Binary size | ~7MB | ~150MB | ~100MB |
|
|
|
|
See [docs/comparison.md](docs/comparison.md).
|
|
|
|
## Deployment
|
|
|
|
- **Standalone**: `cargo build --release -p bascule-server`
|
|
- **Docker**: `docker build -t bascule .`
|
|
- **Kubernetes**: `helm install bascule charts/bascule/` — see [docs/kubernetes.md](docs/kubernetes.md)
|
|
|
|
## Extending Bascule
|
|
|
|
Implement `SessionHandler` to add custom policy:
|
|
|
|
```rust
|
|
use bascule_core::hooks::{SessionHandler, SessionInfo};
|
|
|
|
struct AuditHandler;
|
|
|
|
#[async_trait]
|
|
impl SessionHandler for AuditHandler {
|
|
async fn on_session_start(&self, s: &SessionInfo) -> anyhow::Result<()> {
|
|
println!("{} connected from {}", s.principal, s.source_ip);
|
|
Ok(())
|
|
}
|
|
}
|
|
```
|
|
|
|
See [docs/architecture.md](docs/architecture.md).
|
|
|
|
## Governance
|
|
|
|
Bascule is maintained by [Guildhouse LLC](https://guildhouse.dev).
|
|
Contributions are accepted under the [DCO](DCO) — you retain
|
|
copyright to your contributions.
|
|
|
|
The `SessionHandler` and `AuthProvider` traits are public APIs.
|
|
Implementations are the intellectual property of their authors.
|
|
See [GOVERNANCE.md](GOVERNANCE.md).
|
|
|
|
## Roadmap
|
|
|
|
Not yet implemented:
|
|
|
|
- OIDC authentication (Keycloak, Entra, Okta)
|
|
- K8s API exec backend runtime
|
|
- SPIFFE/SPIRE auth runtime
|
|
- OpenTelemetry OTLP exporter
|
|
- Prometheus metrics endpoint
|
|
- Session recording
|
|
- Per-session Pod isolation
|
|
|
|
## Documentation
|
|
|
|
- [Quick Start](docs/quickstart.md)
|
|
- [Configuration](docs/configuration.md)
|
|
- [Authentication](docs/authentication.md)
|
|
- [Architecture](docs/architecture.md)
|
|
- [Observability](docs/observability.md)
|
|
- [Kubernetes](docs/kubernetes.md)
|
|
- [bascule-shell](docs/bascule-shell.md)
|
|
- [Comparison](docs/comparison.md)
|
|
- [Container Images](images/README.md)
|
|
- [Contributing](CONTRIBUTING.md)
|
|
|
|
## License
|
|
|
|
Apache 2.0
|