From 5e69536e2a8658ca7351bb062048487667f7101c Mon Sep 17 00:00:00 2001 From: Alvaro Reis <133926455+paureis@users.noreply.github.com> Date: Mon, 12 Oct 2026 15:36:49 -0400 Subject: [PATCH 1/3] Threat model (#84) THREAT_MODEL.md: what cloudpin protects (cloud accounts, and never the credentials), whom it trusts (the person, the agent's good faith, the project's pin file, each CLI's own identity answer), the controls with the code behind each, and what is out of scope, notably a malicious or prompt-injected agent, which can edit the pin file or its own hook settings. SECURITY.md links to it; ROADMAP lists it under 1.1.0. Co-Authored-By: Claude Opus 5.5 --- ROADMAP.md | 2 ++ SECURITY.md | 2 ++ THREAT_MODEL.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+) create mode 100644 THREAT_MODEL.md diff --git a/ROADMAP.md b/ROADMAP.md index 661ce96..f3e3f0c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -24,6 +24,8 @@ The `.cloudpin.yml` format is stable from 1.0 on. Everything that changes it shi - **Claude Code plugin and MCP server** ([#15](https://github.com/paureis/cloudpin/issues/15)): one-click install, and read-only tools agents can call to check the account before acting. +- **Threat model** ([#84](https://github.com/paureis/cloudpin/issues/84)): what cloudpin protects against, what it + trusts and what it doesn't try to stop, in [THREAT_MODEL.md](THREAT_MODEL.md). ## 1.2.0: GitHub Action (target 2026-10-30) diff --git a/SECURITY.md b/SECURITY.md index b769126..617c88f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,6 +15,8 @@ Examples of what counts as a security problem here: ## What cloudpin does with your accounts +What cloudpin protects against, what it trusts and what is out of scope: [THREAT_MODEL.md](THREAT_MODEL.md). + - It runs each CLI's own identity command (`az account show`, `aws sts get-caller-identity`, `gcloud config list`, `vercel teams ls`, `gh api user`, `supabase projects list`, `wrangler whoami --json`) with the same flags and environment as your command, and reads the result. For Kubernetes, Supabase and Wrangler it also reads project diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md new file mode 100644 index 0000000..be4c57f --- /dev/null +++ b/THREAT_MODEL.md @@ -0,0 +1,78 @@ +# Threat model + +What cloudpin protects against, what it trusts, and what it deliberately does not try to stop. Each control names +the code that implements it, so a claim here can be checked rather than taken on trust. Report a gap through +[SECURITY.md](SECURITY.md). + +## What cloudpin is for + +cloudpin stops a cloud CLI command (`az`, `aws`, `gcloud`, `vercel`, `gh`, `kubectl`, `helm`, `supabase`, `wrangler`) +from running when it would act on a different account than the one the project pins in `.cloudpin.yml`. The command +can come from a person in a terminal or from an AI coding agent. + +The threat is a **mistake**, not an adversary: a person or agent that is logged in to the wrong account, or whose +command picks another account through a flag, an environment variable or a linked project file, without noticing. +cloudpin is a seatbelt, not a sandbox. + +## Assets + +- **The cloud accounts** a project pins, and the resources in them. The harm being prevented is a deploy, change or + delete landing on the wrong account. +- **The credentials** the CLIs hold. cloudpin must never expose them while checking. + +## Actors and how much cloudpin trusts them + +| Actor | Trust | What follows | +|---|---|---| +| The person at the terminal | Trusted | `CLOUDPIN_SKIP=1` and `CLOUDPIN_CONFIRM` let them override a check on purpose (`src/guard.ts`, shell mode). | +| An AI agent running commands through a hook | Trusted to mean well, not to check | The agent can't skip, confirm or pick an environment from inside its own command: hook mode drops `CLOUDPIN_SKIP`, `CLOUDPIN_CONFIRM` and `CLOUDPIN_ENV` set there (`withoutUserOnlyVars` in `src/hooks/agents.ts`), and `cloudpin use` needs the user's OK. | +| The project's `.cloudpin.yml` | Trusted as the project's own policy | Whoever controls the repository decides the pins, the protected environments and extra `read_only` commands. Cloning a repository means accepting its pin file, as with any other project configuration. | +| Each cloud CLI and its config files | Trusted to report its own identity | cloudpin asks the CLI who it is (or reads its config, for kubeconfig and linked-project files) and never second-guesses the answer. | + +## Controls + +- **Resolve the account the specific command will use**, not the CLI's default: its flags beat its environment + variables, which beat its config files (`src/providers/*.ts`, one per CLI, each citing the CLI's documentation). +- **Pin stable IDs, not names**: subscription IDs, account numbers, team IDs, API server URLs (`src/config.ts`). + Several Azure subscriptions can share the name "Azure subscription 1". +- **Fail closed, and explain**: when cloudpin can't tell which account a command would use (an expired login, a + broken token, no network), it blocks the command and says why (`src/guard.ts`, `uncertain`). A pin file it can't + parse also blocks every guarded command except login, logout, switch, whoami, help and version (#62, #67). +- **Agent hooks never fail open**: an error inside the hook, or a check slower than 45 seconds, becomes an explicit + deny (`runHook` in `src/hooks/agents.ts`), because some agents (Claude Code and Codex among them) run the command + when a hook crashes or times out. +- **"No objection" never weakens the agent's own approvals**: each hook answers so that the agent's normal rules still + apply. This was measured inside Cursor and Antigravity (#2, #80). +- **Whole command lines, not just the first word**: pipes, `&&`, subshells, `bash -c`, `eval`, `xargs`, `find -exec`, + `npx` and heredocs are searched for guarded CLIs (`src/shellwords.ts`, with fuzz tests in + `test/shellwords-fuzz.test.ts`). +- **Never touch credentials**: cloudpin only runs each CLI's read-only identity command, never prints, logs or caches + a token, and never runs commands that print secrets (`aws configure list`, `--show-token`, `--reveal`). Error + messages name environment variables, never their values. +- **No shell when spawning**: every process starts through `realExec` with arguments as a list + (`src/exec.ts`, cross-spawn), so a command line is never re-interpreted by a shell. +- **A short cache that can't go stale on a switch**: a successful identity is reused for at most 5 minutes, keyed by a + salted HMAC of the command, its identity-relevant environment variables and the CLI's account files, so + `az account set` or a changed `GH_TOKEN` is seen immediately. Failures are never cached (`src/cache.ts`). +- **Supply chain**: two runtime dependencies (`yaml`, `cross-spawn`), npm provenance, signed GitHub Releases with build + attestations, GitHub Actions pinned by commit, CodeQL and Socket on every pull request, and OpenSSF Scorecard + weekly. + +## Out of scope + +These are real limits, stated so nobody relies on cloudpin for them: + +- **A malicious or prompt-injected agent.** An agent that can write files can edit `.cloudpin.yml` to pin its current + account, remove the hook from its own settings, or write a script and run it later (`bash deploy.sh`), which + cloudpin can't see into. cloudpin catches an agent's honest mistake; it is not a sandbox. Use the agent's own + permission system for that. +- **A command cloudpin doesn't guard.** Only the CLIs above are checked. A cloud SDK called from a program, `curl` to a + cloud API or a Terraform run acts on whatever credentials it finds. +- **A compromised machine or PATH.** A fake `az` earlier on PATH, a tampered kubeconfig or a malicious shell profile + can make the CLI report any identity. +- **Environment set up by someone else.** Variables set before the agent starts are the user's choice and are + honoured, including `CLOUDPIN_ENV` and an `AWS_PROFILE` pointing at another account. +- **A shell without the wrapper.** In a terminal, protection exists only where `cloudpin shell-init` was loaded; an + alias that runs another program instead of the CLI bypasses it, and cloudpin warns about that at shell start (#69). +- **CLIs not tested on a real account**: Wrangler (#56) and Gemini CLI are built to their documentation and tested + with fakes, as the README says. From 7a2c27a9ab791f4d6a49e1c0afca5c7caeae09a9 Mon Sep 17 00:00:00 2001 From: Alvaro Reis <133926455+paureis@users.noreply.github.com> Date: Wed, 14 Oct 2026 15:41:10 -0400 Subject: [PATCH 2/3] Threat model: the review's four points (#84) - "Agent hooks never fail open" was too strong: if cloudpin can't start at all, Claude Code and Codex run the command. Now "fail closed once cloudpin is running", with that case stated and doctor named. - Variables set earlier in the line, and values only known when it runs, are a control now that #86 handles them. - Out of scope: which resource inside the account (repo, Vercel project, region); an agent's MCP tools for a cloud provider. - Advice: deny the agent edits to .cloudpin.yml and its hook settings. Co-Authored-By: Claude Opus 5.5 --- THREAT_MODEL.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md index be4c57f..ceb3ee0 100644 --- a/THREAT_MODEL.md +++ b/THREAT_MODEL.md @@ -38,14 +38,18 @@ cloudpin is a seatbelt, not a sandbox. - **Fail closed, and explain**: when cloudpin can't tell which account a command would use (an expired login, a broken token, no network), it blocks the command and says why (`src/guard.ts`, `uncertain`). A pin file it can't parse also blocks every guarded command except login, logout, switch, whoami, help and version (#62, #67). -- **Agent hooks never fail open**: an error inside the hook, or a check slower than 45 seconds, becomes an explicit - deny (`runHook` in `src/hooks/agents.ts`), because some agents (Claude Code and Codex among them) run the command - when a hook crashes or times out. +- **Agent hooks fail closed once cloudpin is running**: an error inside the hook, or a check slower than 45 seconds, + becomes an explicit deny (`runHook` in `src/hooks/agents.ts`), because some agents (Claude Code and Codex among + them) run the command when a hook crashes or times out. If cloudpin can't start at all (uninstalled, or not on the + agent's PATH), there is nothing to answer and those agents run the command; `cloudpin doctor` checks that cloudpin + is on PATH and which hooks are installed. - **"No objection" never weakens the agent's own approvals**: each hook answers so that the agent's normal rules still apply. This was measured inside Cursor and Antigravity (#2, #80). - **Whole command lines, not just the first word**: pipes, `&&`, subshells, `bash -c`, `eval`, `xargs`, `find -exec`, `npx` and heredocs are searched for guarded CLIs (`src/shellwords.ts`, with fuzz tests in - `test/shellwords-fuzz.test.ts`). + `test/shellwords-fuzz.test.ts`). Variables the line sets before a call count (`export AWS_PROFILE=other;`, + PowerShell `$env:`), and a call whose account depends on a value only known when it runs (`GH_TOKEN=$(cat f) gh`) + is blocked as "can't tell" (#86). - **Never touch credentials**: cloudpin only runs each CLI's read-only identity command, never prints, logs or caches a token, and never runs commands that print secrets (`aws configure list`, `--show-token`, `--reveal`). Error messages name environment variables, never their values. @@ -65,9 +69,13 @@ These are real limits, stated so nobody relies on cloudpin for them: - **A malicious or prompt-injected agent.** An agent that can write files can edit `.cloudpin.yml` to pin its current account, remove the hook from its own settings, or write a script and run it later (`bash deploy.sh`), which cloudpin can't see into. cloudpin catches an agent's honest mistake; it is not a sandbox. Use the agent's own - permission system for that. + permission system for that, and in it deny the agent edits to `.cloudpin.yml` and to its own hook settings file. +- **Which resource inside the account.** cloudpin checks the identity a command acts as and the account or project it + lands in, not which repository, Vercel project, region or resource group it targets. `gh repo delete other/repo` + passes if you are logged in as the pinned user. (A pinned Kubernetes namespace is the exception.) - **A command cloudpin doesn't guard.** Only the CLIs above are checked. A cloud SDK called from a program, `curl` to a - cloud API or a Terraform run acts on whatever credentials it finds. + cloud API, a Terraform run, or an agent's MCP tools for a cloud provider (which never go through the shell hook) act + on whatever credentials they find. - **A compromised machine or PATH.** A fake `az` earlier on PATH, a tampered kubeconfig or a malicious shell profile can make the CLI report any identity. - **Environment set up by someone else.** Variables set before the agent starts are the user's choice and are From 5b47abbd2c8e87b2fa0906d39b62ca5e996e2454 Mon Sep 17 00:00:00 2001 From: Alvaro Reis <133926455+paureis@users.noreply.github.com> Date: Mon, 26 Oct 2026 17:34:20 -0400 Subject: [PATCH 3/3] Threat model: Wrangler's .env files, the parser's limits, and current names (#84) From the review's approval: the .env files Wrangler loads can hold CLOUDFLARE_API_TOKEN, so they join the kubeconfig as credential files cloudpin reads, in THREAT_MODEL.md and SECURITY.md (the same SECURITY.md wording is on release/1.2.0, with the README line). Brought up to date with main: the user-only variables now live in src/user-env.ts (CLOUDPIN_BRANCH included, set or unset), help and version exempt only where the CLI stops on them (#146), redirections (#154), and a new control that says plainly the command-line parser is the weak point, links the 2026-10-26 audit issues and states the fail-closed aim. Co-Authored-By: Claude Opus 5.5 --- SECURITY.md | 6 ++++-- THREAT_MODEL.md | 23 ++++++++++++++++------- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 7aba7b6..a427a8d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -22,8 +22,10 @@ What cloudpin protects against, what it trusts and what is out of scope: [THREAT environment as your command, and reads the result. For Kubernetes, Supabase and Wrangler it also reads project files that name the target (the kubeconfig, `supabase/.temp/`, the Wrangler config and its account cache). - It never logs in, logs out or switches accounts, and never uses or stores a token or key. Credential files are not - read, with one exception: the kubeconfig, which can hold credentials next to the cluster list; cloudpin takes only - the server and namespace from it. For Vercel it checks whether a login file exists, without reading it. + read, with two exceptions: the kubeconfig, which can hold credentials next to the cluster list (cloudpin takes only + the server and namespace from it), and the project's `.env` files that Wrangler loads, which can hold + `CLOUDFLARE_API_TOKEN` (cloudpin reads the account variables from them, and keys its cache on a salted hash of the + credential variables; it never prints, logs or stores their values). For Vercel it checks whether a login file exists, without reading it. - It stores successful identity answers for up to five minutes in a cache file in your user cache folder. Keys are salted hashes, so tokens and command arguments are never written in clear. - `cloudpin mcp`, the MCP server for agents, is read-only: its two tools report status and what cloudpin would decide diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md index ceb3ee0..a8c4732 100644 --- a/THREAT_MODEL.md +++ b/THREAT_MODEL.md @@ -25,9 +25,9 @@ cloudpin is a seatbelt, not a sandbox. | Actor | Trust | What follows | |---|---|---| | The person at the terminal | Trusted | `CLOUDPIN_SKIP=1` and `CLOUDPIN_CONFIRM` let them override a check on purpose (`src/guard.ts`, shell mode). | -| An AI agent running commands through a hook | Trusted to mean well, not to check | The agent can't skip, confirm or pick an environment from inside its own command: hook mode drops `CLOUDPIN_SKIP`, `CLOUDPIN_CONFIRM` and `CLOUDPIN_ENV` set there (`withoutUserOnlyVars` in `src/hooks/agents.ts`), and `cloudpin use` needs the user's OK. | +| An AI agent running commands through a hook | Trusted to mean well, not to check | The agent can't skip, confirm or pick an environment from inside its own command: hook mode ignores `CLOUDPIN_SKIP`, `CLOUDPIN_CONFIRM`, `CLOUDPIN_ENV` and `CLOUDPIN_BRANCH` set or unset there (`USER_ONLY_VARS` and `envFor` in `src/user-env.ts`), and `cloudpin use` needs the user's OK. | | The project's `.cloudpin.yml` | Trusted as the project's own policy | Whoever controls the repository decides the pins, the protected environments and extra `read_only` commands. Cloning a repository means accepting its pin file, as with any other project configuration. | -| Each cloud CLI and its config files | Trusted to report its own identity | cloudpin asks the CLI who it is (or reads its config, for kubeconfig and linked-project files) and never second-guesses the answer. | +| Each cloud CLI and its config files | Trusted to report its own identity | cloudpin asks the CLI who it is (or reads its config, for kubeconfig, linked-project files and the `.env` files Wrangler loads) and never second-guesses the answer. | ## Controls @@ -37,7 +37,8 @@ cloudpin is a seatbelt, not a sandbox. Several Azure subscriptions can share the name "Azure subscription 1". - **Fail closed, and explain**: when cloudpin can't tell which account a command would use (an expired login, a broken token, no network), it blocks the command and says why (`src/guard.ts`, `uncertain`). A pin file it can't - parse also blocks every guarded command except login, logout, switch, whoami, help and version (#62, #67). + parse also blocks every guarded command except login, logout, switch, whoami, help and version (#62, #67). Help and + version count only where the CLI really stops on them, so `vercel deploy --prod -v` is checked (#146). - **Agent hooks fail closed once cloudpin is running**: an error inside the hook, or a check slower than 45 seconds, becomes an explicit deny (`runHook` in `src/hooks/agents.ts`), because some agents (Claude Code and Codex among them) run the command when a hook crashes or times out. If cloudpin can't start at all (uninstalled, or not on the @@ -47,12 +48,20 @@ cloudpin is a seatbelt, not a sandbox. apply. This was measured inside Cursor and Antigravity (#2, #80). - **Whole command lines, not just the first word**: pipes, `&&`, subshells, `bash -c`, `eval`, `xargs`, `find -exec`, `npx` and heredocs are searched for guarded CLIs (`src/shellwords.ts`, with fuzz tests in - `test/shellwords-fuzz.test.ts`). Variables the line sets before a call count (`export AWS_PROFILE=other;`, - PowerShell `$env:`), and a call whose account depends on a value only known when it runs (`GH_TOKEN=$(cat f) gh`) - is blocked as "can't tell" (#86). + `test/shellwords-fuzz.test.ts`), and redirections such as `2>&1` are not arguments (#154). Variables the line sets + before a call count (`export AWS_PROFILE=other;`, PowerShell `$env:`), and a call whose account depends on a value + only known when it runs (`GH_TOKEN=$(cat f) gh`) is blocked as "can't tell" (#86). +- **The parser is the weak point, and it is meant to fail closed.** An agent hook gets the whole command line as text, + so cloudpin has to read it the way the agent's shell will. An audit against real Git Bash and Windows PowerShell + (2026-10-26) found shapes it read differently, some of which hid a flag that picks the account. Each is tracked + in a public issue with its repro line (#159 to #163, #165, #168). Where cloudpin can't follow a line, the aim is + "can't tell", never a silent allow; a shape that still slips through is a security bug to report (see + [SECURITY.md](SECURITY.md)). - **Never touch credentials**: cloudpin only runs each CLI's read-only identity command, never prints, logs or caches a token, and never runs commands that print secrets (`aws configure list`, `--show-token`, `--reveal`). Error - messages name environment variables, never their values. + messages name environment variables, never their values. Two files it reads can hold credentials: the kubeconfig + (it takes only the server and namespace) and the `.env` files Wrangler loads, which can hold `CLOUDFLARE_API_TOKEN` + (it takes the account variables, and keys its cache on a salted hash of the credential variables). - **No shell when spawning**: every process starts through `realExec` with arguments as a list (`src/exec.ts`, cross-spawn), so a command line is never re-interpreted by a shell. - **A short cache that can't go stale on a switch**: a successful identity is reused for at most 5 minutes, keyed by a