Bruno

"No authority without attestation. Trust expires."

Bruno is a TPM-attested proxy network with zero-trust architecture. Nodes prove their integrity via hardware-bound cryptographic attestation before receiving short-lived mTLS certificates from the Governor.

Features

TPM 2.0 Attestation - Hardware-bound identity verification via TPM quotes
Ephemeral Certificates - 5-minute TTL, auto-renewed via heartbeat
mTLS Proxy - End-to-end encrypted traffic between Ingress and Nodes
Certificate Authority - Governor-managed PKI with CRL support
SOCKS5 Proxy - Standard protocol for client connections
API Key Authentication - Secure client access with rate limiting
Prometheus Metrics - Full observability across all components
Audit Logging - Structured JSON logs for security events
Docker Support - Production-ready container images
systemd Integration - Native Linux service management

Architecture

┌─────────────┐     gRPC/mTLS      ┌─────────────┐
│   Client    │◄──────────────────►│   Ingress   │
└─────────────┘                    └──────┬──────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    │                     │                     │
              ┌─────▼─────┐         ┌─────▼─────┐         ┌─────▼─────┐
              │   Node    │         │   Node    │         │   Node    │
              │  (mTLS)   │         │  (mTLS)   │         │  (mTLS)   │
              └─────┬─────┘         └─────┬─────┘         └─────┬─────┘
                    │                     │                     │
                    └─────────────────────┼─────────────────────┘
                                          │ Attestation + Heartbeat
                                    ┌─────▼─────┐
                                    │  Governor │
                                    │ (CA + DB) │
                                    └───────────┘

Project Structure

Component	Directory	Description
Governor	`bruno-governor/`	Central authority - attestation, CA, admin API
Node	`bruno-node/`	mTLS proxy with TPM attestation
Ingress	`bruno-ingress/`	Client entry point, SOCKS5 proxy
Client	`bruno-client/`	User-facing SOCKS5 client
Admin	`bruno-admin/`	CLI tools for node management
Proto	`proto/`	gRPC service definitions

Quick Start

Prerequisites

Rust 1.75+
Protobuf compiler (protoc)
Docker & Docker Compose (optional)

Option 1: Docker (Recommended)

# Start infrastructure (PostgreSQL, Redis)
docker compose -f infra/docker/docker-compose.yml up -d

# Build and start Bruno services
docker compose -f infra/docker/docker-compose.yml --profile bruno up -d

# Check services
docker compose -f infra/docker/docker-compose.yml ps

Option 2: Build from Source

# Build all components
cargo build --workspace --release

# Terminal 1: Start Governor
BRUNO_DEV_MODE=1 cargo run --bin bruno-governor

# Terminal 2: Start Node
cargo run --bin bruno-node

# Terminal 3: Start Ingress
cargo run --bin bruno-ingress

Connect as a Client

# Using bruno-client
cargo run --bin bruno-client -- --server localhost --key test-key

# Using curl directly
curl -x socks5h://test-key:@localhost:1080 https://example.com

# Configure Firefox
# Settings → Network → Manual proxy → SOCKS Host: localhost:1080

Verify Installation

# Check Governor health
curl http://localhost:9090/health

# Check Governor metrics
curl http://localhost:9090/metrics

# List nodes via Admin CLI
cargo run --bin bruno-admin -- list-nodes

Configuration

Governor

Environment Variable	Default	Description
`BRUNO_DEV_MODE`	`false`	Permissive attestation (dev only)
`BRUNO_GRPC_PORT`	`50051`	gRPC server port
`BRUNO_HTTP_PORT`	`9090`	HTTP/metrics port
`DATABASE_URL`	-	PostgreSQL connection string
`REDIS_URL`	-	Redis connection string (optional)

Node

Environment Variable	Default	Description
`BRUNO_GOVERNOR_ADDR`	`http://[::1]:50051`	Governor gRPC address
`BRUNO_NODE_ADDR`	auto-detect	Node's advertised address
`BRUNO_NODE_PORT`	`8081`	Node's proxy port
`BRUNO_NODE_SOCKS5_PORT`	`1080`	Node's SOCKS5 port

Ingress

Environment Variable	Default	Description
`BRUNO_GOVERNOR_ADDR`	`http://[::1]:50051`	Governor gRPC address
`BRUNO_HTTP_PORT`	`8080`	HTTP server port
`BRUNO_SOCKS5_PORT`	`1080`	SOCKS5 proxy port
`BRUNO_AUTH_ENABLED`	`true`	Enable API key authentication
`BRUNO_API_KEYS`	-	Comma-separated valid API keys

Client

Flag	Default	Description
`--server, -s`	-	Ingress server address
`--key, -k`	-	API key for authentication
`--port, -p`	`1080`	Local SOCKS5 port
`--bind, -b`	`127.0.0.1`	Local bind address

Deployment

Using systemd (Linux)

# Build release binaries
cargo build --release

# Install using provided script
sudo ./infra/scripts/install.sh all

# Start services
sudo systemctl enable --now bruno-governor
sudo systemctl enable --now bruno-node
sudo systemctl enable --now bruno-ingress

# View logs
sudo journalctl -u bruno-governor -f

Using Docker

# Build images
docker build -f docker/Dockerfile.governor -t bruno/governor .
docker build -f docker/Dockerfile.node -t bruno/node .
docker build -f docker/Dockerfile.ingress -t bruno/ingress .

# Or use docker-compose
docker compose -f infra/docker/docker-compose.yml --profile bruno up -d

API Reference

Governor gRPC API (:50051)

Method	Description
`GetChallenge`	Request attestation nonce for a node
`Attest`	Submit TPM quote and receive certificate
`Heartbeat`	Keep-alive with metrics, receive renewals
`GetActiveNodes`	List all attested nodes
`RevokeNode`	Revoke a node's certificate

Governor HTTP API (:9090)

Endpoint	Description
`GET /health`	Health check
`GET /metrics`	Prometheus metrics
`GET /nodes`	List active nodes

Ingress HTTP API (:8080)

Endpoint	Description
`GET /health`	Health check
`GET /metrics`	Prometheus metrics

Ingress SOCKS5 (:1080)

Standard SOCKS5 proxy with USERNAME/PASSWORD authentication. Username = API key, Password = (empty or any value)

Testing

# Run all tests
cargo test --workspace

# Run with output
cargo test --workspace -- --nocapture

# Run specific component tests
cargo test -p bruno-governor
cargo test -p bruno-ingress

Documentation

Architecture - System design and components
Deployment - Production deployment guide
API Reference - Complete API documentation
Attestation Protocol - TPM attestation flow
Threat Model - Security considerations

Security Principles

Zero Trust - No implicit trust; all nodes must attest
Hardware-Bound Identity - TPM-based cryptographic proof
Ephemeral Credentials - Certificates expire in minutes
Centralized Policy - Governor controls all authorization
Defense in Depth - Multiple layers of security controls

Troubleshooting

Governor won't start

# Check database connectivity
psql $DATABASE_URL -c "SELECT 1"

# Check port availability
ss -tlnp | grep 50051

# Enable debug logging
RUST_LOG=debug cargo run --bin bruno-governor

Node attestation fails

# Check TPM availability
ls -la /dev/tpm*

# Test TPM tools
tpm2_getcap properties-fixed

# Enable dev mode for testing
BRUNO_DEV_MODE=1 cargo run --bin bruno-governor

Client can't connect

# Test SOCKS5 directly
curl -x socks5h://your-key:@localhost:1080 https://httpbin.org/ip

# Check ingress logs
journalctl -u bruno-ingress -f

# Verify API key is valid
echo $BRUNO_API_KEYS | grep your-key

GeezerVison

Latest commit

History

Folders and files

Repository files navigation