{"id":48081595,"url":"https://github.com/ceejbot/zerolease","last_synced_at":"2026-04-04T14:54:04.138Z","repository":{"id":347640542,"uuid":"1192808816","full_name":"ceejbot/zerolease","owner":"ceejbot","description":"A secrets vault that issues leases over vsock; intended for use with lightweight VMs like QEMU and FireCracker ","archived":false,"fork":false,"pushed_at":"2026-03-28T20:26:15.000Z","size":139,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"latest","last_synced_at":"2026-03-28T20:41:31.127Z","etag":null,"topics":["rustlang","secret-management","vault","vsock"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ceejbot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T15:26:27.000Z","updated_at":"2026-03-28T20:26:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ceejbot/zerolease","commit_stats":null,"previous_names":["ceejbot/zerolease"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ceejbot/zerolease","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceejbot%2Fzerolease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceejbot%2Fzerolease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceejbot%2Fzerolease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceejbot%2Fzerolease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ceejbot","download_url":"https://codeload.github.com/ceejbot/zerolease/tar.gz/refs/heads/latest","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ceejbot%2Fzerolease/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rustlang","secret-management","vault","vsock"],"created_at":"2026-04-04T14:54:00.410Z","updated_at":"2026-04-04T14:54:04.132Z","avatar_url":"https://github.com/ceejbot.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zerolease\n\nA credential vault for AI agent environments. Stores secrets encrypted at rest and grants access through leases: time-bounded, scope-restricted handles that expire automatically and can be revoked at any time.\n\n[![Tests](https://github.com/ceejbot/zerolease/actions/workflows/test.yaml/badge.svg)](https://github.com/ceejbot/zerolease/actions/workflows/test.yaml) [![audit-dependencies](https://github.com/ceejbot/zerolease/actions/workflows/audit.yaml/badge.svg)](https://github.com/ceejbot/zerolease/actions/workflows/audit.yaml) [![codecov](https://codecov.io/github/ceejbot/zerolease/graph/badge.svg?token=XGD9GA2H66)](https://codecov.io/github/ceejbot/zerolease)\n\n## Why\n\nWhen AI agents use tools that need credentials — API tokens, SSH keys, database passwords — giving the agent direct access to the credential is dangerous. An agent with a raw GitHub PAT can use it against any endpoint, keep it indefinitely, and leak it to any tool it invokes.\n\n`zerolease` sits between agents and credentials. Instead of handing out a token, the vault issues a _lease_: a handle that grants access to a specific credential, for a specific domain, for a limited time. A Jira PAT can only be injected into requests to `*.atlassian.net`. A GitHub token expires after 15 minutes. Every access is logged.\n\n## Design\n\nThe vault is a Rust library that agents connect to over Unix domain sockets (developer machines), TCP with token auth (QEMU VMs), or vsock (Firecracker). Credentials never leave the vault as plaintext over a network — the transport is local to the host or hypervisor.\n\n**Encryption.** Secrets are encrypted at rest using `AES-256-GCM` or `XChaCha20-Poly1305` (configurable per secret, with algorithm migration support). The data encryption key is managed by a pluggable key source: OS keychain for developer machines, AWS KMS for production, or an environment variable for CI.\n\n**Policy.** Access is deny-by-default. A flat list of grant rules specifies which agents can access which secrets for which domains. First match wins. The policy format is intentionally simple — easier to audit than a policy language.\n\n**Leases.** Every credential access goes through a lease. Leases have a TTL, an optional use count, and a list of allowed target domains. The vault tracks active leases in memory, enforces per-agent caps, and garbage-collects expired ones. Secret values are zeroized from memory when the lease guard is dropped.\n\n**Authentication.** Connections are authenticated via a pluggable `Authenticator` trait that maps transport-level peer identity to roles. Three roles exist: Admin (full access), Agent (bound to a single identity, can only use leases), and Orchestrator (trusted to assert agent identity per request). TCP transports present a bearer token in the handshake; UDS/vsock rely on OS-level identity.\n\n**Audit.** Every lease grant, secret access, revocation, and policy denial is logged. The core crate includes `TracingAuditLog` (emits structured `tracing` events for external log aggregation). Queryable backends are available in the store crates.\n\n## Workspace\n\nzerolease is a Cargo workspace. The core crate defines traits; storage and provider crates are chosen at compile time.\n\n| Crate | Purpose |\n|-------|---------|\n| **zerolease** | Core: `Vault`, traits (`SecretStore`, `AuditLog`, `KeySource`), transports, policy engine |\n| **zerolease-store-rusqlite** | SQLite storage via rusqlite — `SecretStore` + `AuditLog` |\n| **zerolease-store-postgres** | PostgreSQL storage via sqlx — `SecretStore` + `AuditLog` |\n| **zerolease-store-aws-sm** | AWS Secrets Manager — `SecretStore` only (pair with `TracingAuditLog`) |\n| **zerolease-provider** | `CredentialProvider` trait for AI agent tool integration |\n\nPick a store crate and an audit backend independently:\n\n- **Developer laptop:** rusqlite store + `RusqliteAuditLog` (single file, zero config)\n- **Cloud VMs:** AWS SM store + `TracingAuditLog` (logs to stdout → CloudWatch)\n- **Shared infra:** PostgreSQL store + `PostgresAuditLog`\n\n## Transports\n\n| Transport | Use case | Identity source |\n|-----------|----------|-----------------|\n| **Unix domain socket** | Developer machines, local processes | OS peer credentials (UID/PID) |\n| **TCP + token** | QEMU VMs via host-forwarded ports | Bearer token in `ClientHello` handshake |\n| **vsock** | Firecracker/QEMU via virtio | Guest CID (Linux only, feature `vsock`) |\n\nTCP listeners bind to `127.0.0.1` only. The `TokenAuthenticator` maps pre-registered tokens to connection identities. Raw tokens are never stored — only SHA-256 hashes.\n\n## Quick start\n\n```bash\n# Generate a data encryption key\nexport ZEROLEASE_KEY=$(openssl rand -hex 32)\n\n# Run the example (direct vault API, no server)\ncargo run --example basic_vault\n```\n\n## Building\n\nRequires Rust edition 2024.\n\n```bash\ncargo build                    # core + rusqlite store\ncargo test --workspace         # run workspace tests\ncargo clippy --workspace       # lint\n\n# Excluded crate (built separately due to sqlx/rusqlite conflict):\ncargo build --manifest-path crates/zerolease-store-postgres/Cargo.toml\n```\n\n### Feature flags (core crate)\n\n| Flag    | Default | What it enables |\n|---------|---------|-----------------|\n| `vsock` | No      | vsock transport for Firecracker/QEMU VMs (Linux only) |\n| `kms`   | No      | AWS KMS envelope encryption key source |\n\n## Testing\n\n```bash\n# Workspace tests\ncargo test --workspace\n\n# PostgreSQL integration tests (requires running Postgres)\ncargo test --manifest-path crates/zerolease-store-postgres/Cargo.toml \\\n  --run-ignored ignored-only --test-threads=1\n\n# AWS Secrets Manager tests (requires credentials + IAM permissions)\nZEROLEASE_SM_TEST_PREFIX=zerolease_test_ \\\n  cargo test -p zerolease-store-aws-sm --run-ignored ignored-only --test-threads=1\n\n# AWS KMS integration tests\ncargo test -p zerolease --features kms -E 'test(keysource::kms)' --run-ignored ignored-only\n\n# OS keychain integration test\ncargo test -p zerolease keysource::keychain -- --ignored\n```\n\n## Wire protocol\n\nJSON over length-prefixed frames (4-byte big-endian length + payload). Each connection begins with a `ClientHello`/`ServerHello` handshake (TCP clients include a bearer token). Requests carry a UUID v7 identifier for correlation. Eight methods: `store_secret`, `request_lease`, `access_secret`, `revoke_lease`, `revoke_all_for_agent`, `list_secrets`, `renew_lease`, `delete_secret`.\n\n## Security\n\n- Secret material zeroized on drop (`Zeroize`, `SecretString`, `Zeroizing\u003cVec\u003cu8\u003e\u003e`)\n- Decryption errors are generic (no information leakage)\n- Domain scope matching rejects edge cases (empty subdomains, path traversal)\n- Policy engine is deny-by-default; empty prefix patterns are warned\n- Lease renewal capped at 24 hours; per-agent lease count capped\n- SQL injection prevented by parameterized queries\n- Debug impls redact secret material\n- Role-based access control prevents agents from calling admin operations\n- Agent identity bound at transport level, not self-asserted\n- Auth tokens stored as SHA-256 hashes, never in plaintext\n- TCP listener binds localhost only\n\n## Documentation\n\n- **[Design](docs/design.md)** — Threat model, core abstractions, design decisions, what this is not.\n- **[Credential Sidecar — Embedded](docs/design-credential-sidecar-embedded.md)** — Session-scoped credential access for single-binary deployments (Raspberry Pi, laptop). Process supervisor, fd-based credential delivery, tool-to-secret binding.\n- **[Embedded guide](docs/guide-embedded.md)** — Integrating zerolease into a Rust application (e.g., zeroclaw). In-process vault, no server.\n- **[Cloud service guide](docs/guide-cloud-service.md)** — Running the vault as a server with PostgreSQL or AWS Secrets Manager. Multiple clients over UDS/TCP.\n- **[VM deployment guide](docs/guide-vm-deployment.md)** — Full production deployment with QEMU VMs, credential provisioner, lease-aware proxy, and iptables network jail.\n\n## Status\n\nEarly development. Core traits and backend implementations are functional. The VM agent (provisioner + proxy + credential helper) is implemented and security-audited. A standalone server binary is planned.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fceejbot%2Fzerolease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fceejbot%2Fzerolease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fceejbot%2Fzerolease/lists"}