Security | Ghostable CLI 3.x | Ghostable Menu Security Security resources ------------------ Review the upstream [security policy](https://github.com/ghostable-dev/ghostable/security/policy), [threat model](https://github.com/ghostable-dev/ghostable/blob/main/docs/security/threat-model.md), and [test vectors](https://github.com/ghostable-dev/ghostable/blob/main/docs/security/test-vectors.md) when evaluating Ghostable for a sensitive environment. They document the disclosure process, modeled threats and residual risks, and stable cryptographic behavior. Cryptographic model ------------------- `Ed25519` Device signatures for public devices, policy, grants, events, key metadata, value payloads, and other signed records. `X25519` Per-device key exchange used to grant environment access. `XChaCha20-Poly1305` Authenticated value encryption with random 24-byte nonces. `HKDF-SHA256` Derives separate environment encryption and HMAC material scoped to project and environment. `Environment key grants` Environment keys are wrapped and shared to authorized devices through per-device encrypted grants. Signatures provide origin and integrity checks. They do not make an authorized but harmful change safe to merge. Trust boundaries ---------------- Plaintext secret values are encrypted locally before Ghostable writes repository-backed value records. Ghostable does not operate a hosted service that receives those values. Authorized local devices, process memory, generated env files, CI runners, shell or terminal tooling, and deployment providers may receive decrypted values when a user intentionally performs those operations. - **Local machine:** private device identities and decrypted process memory exist outside the repository boundary. - **Repository:** encrypted values and signed metadata are committed, but repository writers can propose malicious policy or grant changes. - **Automation:** `GHOSTABLE_CI_TOKEN` is an out-of-band secret trusted for its configured grants. - **Deployment providers:** Forge, Vapor, Cloud, local files, and injected processes receive plaintext after decryption. Protected production access --------------------------- Protected local operations that write, print, inject, validate, or deploy decrypted values require user-presence verification. Explicit production tokens are protected, and neutral names such as `preview`, `staging`, `qa`, and custom names are protected by default. Only names carrying a recognized local, development, test, or CI token use the unprotected fallback. See [environment types](https://ghostable.dev/docs/3.x/workflows/environments#types) for the exact classification. macOS uses LocalAuthentication with Touch ID biometric verification. Linux uses the local PAM-backed `sudo` confirmation, which may use fingerprint verification when configured. Windows requests Windows Hello or the machine's configured fallback. A non-interactive local session cannot satisfy this prompt. CI and deployment jobs must use a scoped automation credential. Dry runs that neither write nor print decrypted values do not require confirmation. Threats and residual risk ------------------------- Ghostable is designed to resist: - Passive repository readers without a valid device identity, environment key, or automation credential. - Undetected modification of signed value, device, policy, access, activity, and key-metadata records. - Continued authorized use of stale grants after reviewed revocation and key rotation. - Non-interactive use of production-like local identities without a scoped automation token. Ghostable is not designed to fully resist: - A compromised authorized device, process, terminal, editor, or CI runner. - Plaintext exposure after values are written to files or passed to a deployment provider. - Reviewers accepting malicious repository changes. - Secrets placed in annotations, schema descriptions, change reasons, commit messages, or other plaintext metadata. Operational responsibilities ---------------------------- - Protect local identity stores, CI tokens, and provider credentials. - Never commit plaintext env files or private identity records. - Review device, policy, access, suppression, and encrypted-value changes like code. - Revoke lost or retired identities across all environments; Ghostable rotates the affected environment keys automatically. - Rotate the underlying database passwords, API keys, or provider credentials when an authorized device or token may have exposed their plaintext. - Use `env clean` to reduce local plaintext after sensitive work. - Keep the CLI updated and reassess the threat model when your workflow changes. Report a vulnerability ---------------------- Do not open a public GitHub issue for a suspected vulnerability. Email with the affected version, operating system, installation method, impact, reproduction steps, and redacted supporting evidence. The published policy commits to acknowledging reports within 24 hours. On this page [ ![Ghostable](https://ghostable.dev/images/logo-dark.svg) ![Ghostable](https://ghostable.dev/images/logo-light.svg) ](https://ghostable.dev) CLI 3.x [ CLI 3.x ](https://ghostable.dev/docs/3.x) [ Desktop ](https://ghostable.dev/docs/desktop) CLI 3.x introduction Documentation local first no login encrypted repository plaintext hosted service Installation Documentation brew homebrew npm npx linux windows PATH version update Start a new project Getting Started setup seed dotenv owner initialize Adopt an existing project Getting Started existing env import authoritative source adopt Onboard a team member Getting Started join request approve roles offboarding pull request Repository and storage Core Concepts .ghostable git conflict merge worktree private identity metadata Environments Core Concepts protected production preview staging push sync pull replace run mask-output Variables and promotions Core Concepts var promote copy context annotation key Access and devices Core Concepts identity reader writer grantor owner revoke rotate leave delete Daily development workflow Workflows pull diff validate review clean daily Review and secret scanning Workflows scan sarif github suppress secrets drift Hygiene and rotation Workflows rotation stale unused suppression environment key Automation credentials Automation & CI GHOSTABLE\_CI\_TOKEN ci deploy credential powershell revoke replace Continuous integration Automation & CI GitHub Actions fork pull request JSON stdout stderr exit codes mask-output Deployments Automation & CI Forge Vapor Cloud provider CLI dry-run preserve remote keys temporary files Validation Reference schema required nullable regex min max different\_from Command reference Reference --help --json NO\_COLOR flags aliases exit code automation Configuration Reference ghostable.yaml activity mode auditEnvironments scan ignores deployTarget dotenv syntax Security Reference cryptography XChaCha20 Poly1305 HKDF user presence threat model Backups & Offline Reference recovery offline restore clone key identity Agent integration Reference AGENTS.md capabilities allowlist coding agent Troubleshooting Reference no project found revoked identity stale policy user presence invalid CI token provider CLI git conflict diagnostics Ghostable Desktop overview Desktop Installation Desktop Projects and setup Desktop Interface tour Desktop Environments and variables Desktop Local environment files Desktop Validation and review Desktop Activity Desktop Access and automation Desktop Project settings Desktop Application settings Desktop Licensing and updates Desktop Security and storage Desktop Troubleshooting Desktop No results found