Chaperone is a sidecar-style egress proxy that injects credentials into outgoing API requests. It runs within your infrastructure so that tokens, API keys, and OAuth2 credentials never reach the upstream platform.
- Credential isolation — Secrets stay in your infrastructure. The proxy adds them to outgoing requests and strips them from responses.
- Mutual TLS — Client certificate authentication between the platform and the proxy, with TLS 1.3 minimum.
- Plugin architecture — Credential providers compile directly into the binary (static recompilation, similar to Caddy). No runtime plugin loading, no serialization overhead.
- Structured observability — JSON logging via
log/slog, Prometheus metrics, and health/version endpoints. - Single static binary — Runs on a distroless container image under 50 MB.
# Build the Docker image
docker build -t chaperone:latest .
# Run with the tutorial config (allows httpbin.org as target)
docker run --rm -p 8443:8443 -p 9090:9090 \
-v $(pwd)/configs/getting-started.yaml:/app/config.yaml:ro \
chaperone:latest
# In another terminal — health check
curl -s http://localhost:9090/_ops/health
# {"status": "alive"}
# Proxy a request to httpbin.org
curl -s http://localhost:8443/proxy \
-H "X-Connect-Target-URL: https://httpbin.org/headers" \
-H "X-Connect-Vendor-ID: test-vendor"Chaperone requires an allow-list of permitted target hosts (default-deny). The tutorial config permits httpbin.org only. See Getting Started for the full walkthrough including credential injection.
To build from source instead:
make tools && make build-dev
./bin/chaperone -config configs/getting-started.yaml| Document | Description |
|---|---|
| Getting Started | Tutorial: build, run, and send your first proxied request |
| Plugin Development | Build a custom credential plugin |
| Deployment | Docker deployment, Kubernetes probes, production hardening |
| Certificate Management | mTLS setup, chaperone enroll, CA workflows |
| Configuration Reference | All config options, env overrides, timeout tuning |
| HTTP API Reference | Health, version, proxy, and metrics endpoints |
| SDK Reference | Plugin interfaces, types, and public API |
| Contrib Plugins Reference | Reusable auth building blocks, request multiplexer |
| Troubleshooting | Common issues and solutions |
| Design Specification | Architecture rationale and ADRs |
Chaperone is a multi-module monorepo. The Core and SDK are versioned independently so that plugin authors can depend on a stable SDK without pulling in proxy internals.
chaperone/
├── chaperone.go # Public API: Run(), Option types
├── cmd/chaperone/ # CLI entry point (wraps chaperone.Run)
├── sdk/ # Plugin SDK (separate Go module, sdk/v1.x.x)
│ ├── plugin.go # Plugin, CredentialProvider, CertificateSigner interfaces
│ └── compliance/ # Contract test kit for plugin authors
├── internal/ # Private implementation
│ ├── proxy/ # Reverse proxy, TLS termination, middleware
│ ├── config/ # YAML + env var configuration
│ ├── router/ # Request routing and validation
│ ├── telemetry/ # Prometheus metrics, admin server
│ └── ... # cache, context, observability, security
├── plugins/reference/ # Default file-based credential provider
├── plugins/contrib/ # Reusable auth building blocks (OAuth2, Microsoft SAM, mux)
└── configs/ # Example configuration files
make tools # Install dev tools (golangci-lint, goimports)
make build-dev # Dev build (HTTP targets allowed, debug symbols)
make build # Production build (HTTPS-only, stripped)
make test # Run all tests
make test-race # Tests with race detector
make lint # Run linters (Core + SDK modules)
make fmt # Format code
make gosec # Run gosec security scanner
make govulncheck # Run govulncheck vulnerability scanner
make ci # Run all CI checks locally
make gencerts # Generate test certificates for mTLS
make docker-test # End-to-end Docker validation suite (18 tests)
make help # Show all available targetsThis project is licensed under the Apache License 2.0 — see the LICENSE file for details.