Security model

Vault’s security architecture is designed around the principle that credential exposure should be minimized in both duration and scope. Every design decision, from envelope encryption to lease-based access to agent attribution, serves this principle.

Encryption at rest

Every credential value is encrypted individually using AES-256-GCM with a per-credential data encryption key (DEK). DEKs are wrapped with tenant-scoped key encryption keys (KEKs), and KEKs are derived from a root key stored in an HSM or cloud KMS. No two tenants share key material. No two credentials share a DEK.

See Encryption Envelope for the full cryptographic architecture.

Encryption in transit

All communication with the Vault API occurs over TLS 1.3. The API server enforces TLS and does not accept plaintext HTTP connections. Certificate pinning is available for the TypeScript SDK.

MCP server communication uses stdio (standard input/output) between the AI coding tool and the Vault MCP server process, both running on the same machine. Credential values transmitted over stdio are not encrypted beyond the OS process isolation boundary, because both processes run under the same user context. The MCP server then communicates with the Vault API over TLS.

Key management

The root key is the top of the trust chain. It is stored in a hardware security module (HSM) or a cloud KMS provider (AWS KMS, Google Cloud KMS, or Azure Key Vault). The root key never leaves the secure boundary of the HSM/KMS. All cryptographic operations involving the root key (deriving tenant KEKs) are performed within the HSM/KMS.

KEK rotation is supported per tenant and does not require re-encrypting credential values. See Encryption Envelope for details.

Access control

Access to credentials is governed by three layers:

1. Authentication — Every request must include a valid API token or session token. Tokens are scoped to a single tenant.
2. Role-based access — Tokens carry a role (viewer, user, manager, admin) that determines which operations are permitted.
3. Credential-level ACLs — Individual credentials can restrict access to specific identity patterns.

See Team Sharing and ACLs for configuration details.

Lease-based access

Credential values are only accessible through time-limited leases. There is no API endpoint to read a credential value without creating a lease. This means every credential access has a defined start time, end time, and attributed identity. The lease model limits the window during which a credential value exists in plaintext outside of Vault.

Audit trail

Every credential access, lease operation, policy change, and administrative action is recorded in an immutable audit log. Audit entries cannot be modified or deleted by any user. See Audit Log for the full event catalog.

Threat model

Vault is designed to mitigate these threats:

Credential sprawl — Credentials copied to .env files, chat windows, and configuration files across developer machines. Vault centralizes credentials and distributes them through leases with defined lifetimes.

Agent over-retention — AI agents holding credentials in context windows or logs longer than necessary. Lease TTLs force credentials to expire, and the audit log makes retention visible.

Lateral movement — An attacker who compromises one credential gaining access to others. Per-credential encryption keys and tenant isolation limit blast radius.

Insider access — A team member accessing credentials beyond their role. ACLs and audit logging provide enforcement and visibility.

Key compromise — If a single encryption key is compromised, envelope encryption limits exposure to the credentials encrypted with that key’s DEK, not all credentials in the system.

Incident response + customer disclosure SLA

Vault’s incident response is governed by a documented severity matrix (Decision K2). Customer-facing commitments:

• P0 (confirmed breach, KMS material exposed, plaintext credential reads, audit-chain tamper) - operator action within 1 hour. Affected customers are notified within 72 hours of operator confirmation that the incident is real. Clock starts at confirmation, not at first signal. Mirrors GDPR Article 33.
• P1 (vault unreachable > 5 minutes, lease issuance failure > 5%, audit write failures) - operator paged; status page update within 30 minutes; customer-facing email if outage exceeds 1 hour.
• P2 (dashboard outage, single-tenant isolation regression with no exposure) - response within 24 hours.
• P3 (docs typo, cosmetic bug) - response next business day.

On any P0:

1. Immediate KEK rotation in the cloud KMS layer.
2. Audit-chain integrity check across the affected window.
3. Per-tenant impact analysis from the audit chain.
4. Customer disclosure to affected tenants within the 72-hour SLA above.
5. Customer post-mortem within 7 days for affected tenants, describing what happened, what data was exposed, what was rotated, and what the customer needs to do (typically nothing; vault rotates server-side and leases are short-lived).
6. Public post-mortem within 30 days, scrubbed of customer-identifying detail.

Vulnerability reporting

If you discover a security vulnerability in Vault, report it to security@ghoststack.dev. We follow responsible disclosure practices and will acknowledge your report within 48 hours. Do not open a public GitHub issue for security vulnerabilities.

Penetration testing

Vault undergoes annual third-party penetration testing. Results are available to Enterprise customers under NDA. If you want to conduct your own security assessment, contact us at security@ghoststack.dev to coordinate.