Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 8 additions & 66 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ All notable changes to cloudpin are listed here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
[Semantic Versioning](https://semver.org/).

Versions 0.1.0 to 0.4.2 (2026-10-08 to 2026-10-10) are in [docs/changelog-0.x.md](docs/changelog-0.x.md).
Versions 1.0.0 to 1.1.2 are in [docs/changelog-1.0-1.1.md](docs/changelog-1.0-1.1.md), and 0.1.0 to 0.4.2 in
[docs/changelog-0.x.md](docs/changelog-0.x.md).

## [Unreleased]

Expand All @@ -20,10 +21,10 @@ Versions 0.1.0 to 0.4.2 (2026-10-08 to 2026-10-10) are in [docs/changelog-0.x.md
- winget manifests for `paureis.cloudpin` (#96) in `packaging/winget/`: a portable zip installing `cloudpin.exe` as
the `cloudpin` command. `node scripts/bump-installers.mjs X.Y.Z --winget <dir>` renders them for a release, after
checking the exe zip against `SHA256SUMS`, and `docs/winget.md` lists the maintainer's steps to submit them.
- MCP: a third read-only tool, `cloudpin_doctor` (#112): the same report as `cloudpin doctor --json` (cloudpin on
PATH, shell wrappers, agent hooks, on Windows the PowerShell execution policy, the pin file and each CLI's account,
each with its fix), so an agent can tell you why cloudpin isn't guarding. Account IDs are shortened, and it skips
the identity cache check, which writes a file.
- MCP: two more read-only tools (#112). `cloudpin_doctor`: `cloudpin doctor --json`'s report, so an agent can tell you
why cloudpin isn't guarding (IDs shortened; it skips the cache check, which writes a file). `cloudpin_switch_plan`: the
plan `cloudpin switch --json` prints without `--yes`, for you to run, pinned IDs in full; nothing is run. The plugin's
skill names both.
- Docs: [Guard a Claude Agent SDK app](docs/agent-sdk.md) (#142). An app that loads project settings needs no code;
for one that loads none, there is a Python and a TypeScript `PreToolUse` callback that denies on every error.
- `cloudpin switch [--yes] [--json] [--only <clouds>]` (#14) switches each pinned CLI to its pinned account. It shows a
Expand All @@ -44,6 +45,8 @@ Versions 0.1.0 to 0.4.2 (2026-10-08 to 2026-10-10) are in [docs/changelog-0.x.md

### Security

- An agent's `cloudpin exec -- bash -c 'gh ...'` or `cloudpin exec -- npx gh ...` was read as an unguarded `bash` or `npx`,
so it could run on the wrong account. What `cloudpin exec` starts is now read as a call of its own (#14).
- `cloudpin explain` (text and `--json`) and the MCP `cloudpin_check` tool no longer repeat a token or password from
the command line (#134): `--token`, kubectl's `--token` and `--password`, helm's `--kube-token` and the other
credential flags are masked, as in cloudpin's own block messages, also inside `cmd /c`, `powershell -Command` and
Expand Down Expand Up @@ -211,64 +214,3 @@ Wrangler account checks.
one (#125). A group's value also no longer passes for the command: `vercel -dT whoami deploy` isn't exempt.
- Vercel: `--scope` beats `--team` whatever their order, and with neither, the `scope` in `vercel.json` (or the
`-A` file) picks the team, as in Vercel; a local config that can't be read stops the command (#127).

## [1.1.2] - 2026-10-19

Completes the 1.1.1 security fix for Windows. Please upgrade.

### Security

- Windows: CLIs installed by npm (vercel, wrangler, ...) no longer start a `node` found in the current folder. npm's
`.cmd` shims run `node` by name when no node.exe sits beside them, and Windows looked for it in the current folder
first. cloudpin now tells Windows not to search the current folder for any process it starts, including the command
`cloudpin exec` runs, as PowerShell and Git Bash already do
([GHSA-3cf7-5v5w-q5vr](https://github.com/paureis/cloudpin/security/advisories/GHSA-3cf7-5v5w-q5vr)).

## [1.1.1] - 2026-10-18

A security fix for Windows. Please upgrade.

### Security

- Windows: cloudpin now runs each CLI it asks about (az, gh, vercel, aws, gcloud, kubectl, helm, supabase,
wrangler), and the command `cloudpin exec` runs, by its full path from PATH, skipping empty and relative PATH
entries. Before, Windows' own lookup checked the current folder first, so a file named like one of those CLIs
inside a repository could run in its place when cloudpin checked a command there
([GHSA-3cf7-5v5w-q5vr](https://github.com/paureis/cloudpin/security/advisories/GHSA-3cf7-5v5w-q5vr)).

## [1.1.0] - 2026-10-16

Claude Code gets a one-step plugin, and any MCP agent can ask cloudpin before it acts.

### Added

- A Claude Code plugin (#15): `claude plugin install cloudpin --marketplace paureis/cloudpin` installs the hook, a
read-only MCP server and a skill that tells the agent to check first and stop on a block. With the plugin enabled,
`install-hook claude` declines and `doctor` warns if a settings hook would also run.
- `cloudpin mcp` (#15): a read-only MCP server (stdio) with `cloudpin_status` and `cloudpin_check`, for any agent that
supports MCP. No new dependency.

## [1.0.0] - 2026-10-15

The first stable release: the `.cloudpin.yml` format is stable from here on (later versions only add sections and
keys), and every agent hook except Gemini CLI's is tested inside the real agent.

### Fixed

- Variables an agent sets earlier in its command line now count (#86). `export AWS_PROFILE=other; aws ...` and
PowerShell `$env:AWS_PROFILE = 'other'; aws ...` were checked against the default account and ran on another; and
`GH_TOKEN=$(cat other.token) gh ...` read the token as empty. cloudpin now follows `export`, `unset` and `$env:`
through the line, and stops a command whose account depends on a value only known when it runs, saying why. Found
in the threat-model review.
- Cursor: a command on your Cursor allowlist runs again when the account matches (#2). cloudpin answered `ask`, which
stopped even allowlisted commands; it now answers `allow`, which Cursor treats exactly like having no hook (measured
in Cursor CLI 2026.10.01: commands not on the allowlist still need your approval). Wrong accounts are still blocked.

### Added

- Antigravity hooks (#80): `cloudpin install-hook antigravity` guards Antigravity CLI, the IDE and Antigravity 2.0
(`.agents/hooks.json`, or `~/.gemini/config/hooks.json` with `--user`). Google replaced Gemini CLI with Antigravity
CLI for free and consumer accounts on 2026-06-18. The hook checks `run_command` and text typed into a running
terminal; it asks rather than allows when nothing is wrong, so Antigravity's own approvals still apply.
- The Copilot CLI and Antigravity CLI hooks are tested inside the real agents (#3): a wrong pin blocks the command, a
right one lets it run, and Antigravity's own approval still applies to commands you haven't allowed.
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -332,7 +332,7 @@ older than 2.1.47.

### Claude Code plugin

One install gives Claude Code the hook, three read-only tools it can call before acting, and a short skill telling it to
One install gives Claude Code the hook, four read-only tools it can call before acting, and a short skill telling it to
check first and to stop and ask you when cloudpin blocks a command. cloudpin itself must be installed first:

```sh
Expand All @@ -345,14 +345,14 @@ The plugin replaces `cloudpin install-hook claude`: with the plugin enabled, `in

### MCP server

`cloudpin mcp` is an MCP server (stdio) for any agent; the Claude Code plugin starts it for you. Its three tools,
`cloudpin_status`, `cloudpin_check` and `cloudpin_doctor`, report the accounts in use, if a command would be allowed,
and why cloudpin may not be guarding. None runs, switches or changes anything: an agent that could switch accounts
could switch to the wrong one.
[docs/mcp.md](docs/mcp.md) adds it to Codex, Cursor, VS Code and more. It gives advice, not enforcement: where the
`cloudpin mcp` is an MCP server (stdio) for any agent; the Claude Code plugin starts it. Its four tools,
`cloudpin_status`, `cloudpin_check`, `cloudpin_doctor` and `cloudpin_switch_plan`, report the accounts in use, if a
command would be allowed, why cloudpin may not guard, and what you'd run to switch. None runs or changes
anything: an agent that could switch accounts could switch to the wrong one.
[docs/mcp.md](docs/mcp.md) adds it to Codex, Cursor, VS Code and more. It is advice, not enforcement: where the
agent has a hook, install that too.

Building your own agent with the Claude Agent SDK? [docs/agent-sdk.md](docs/agent-sdk.md) shows how to guard it.
On the Claude Agent SDK? [docs/agent-sdk.md](docs/agent-sdk.md) shows how to guard it.

## Configuration

Expand Down
3 changes: 1 addition & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,8 @@ issues it ships. Open an [issue](https://github.com/paureis/cloudpin/issues) to
- **Threat model** ([#84](https://github.com/paureis/cloudpin/issues/84)): done. What cloudpin protects against and what
it doesn't, in THREAT_MODEL.md.
- **MCP: `cloudpin_switch_plan` and `cloudpin_doctor` tools** ([#112](https://github.com/paureis/cloudpin/issues/112)):
two more read-only tools: the commands you would run to move each CLI to the pinned account (from `cloudpin
done. Two more read-only tools: the commands you would run to move each CLI to the pinned account (from `cloudpin
switch`, nothing run), and `cloudpin doctor`'s report, so an agent can say why the hook isn't guarding.
`cloudpin_doctor` is done; `cloudpin_switch_plan` follows `cloudpin switch` (#14).
- **Write-up** ([#114](https://github.com/paureis/cloudpin/issues/114)): why AI agents need an account guardrail, and
how cloudpin does it, with numbers from the test suite.
- **Short flags joined with `=`** ([#118](https://github.com/paureis/cloudpin/issues/118)): read `-e=production`
Expand Down
4 changes: 2 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ What cloudpin protects against, what it trusts and what is out of scope: [THREAT
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 three tools report status, what cloudpin would decide and why it may not be guarding
for a command; they never run that command, log in, switch accounts or write anything.
- `cloudpin mcp`, the MCP server for agents, is read-only: its four tools report status, what cloudpin would decide for a command, why it may not be
guarding and what a person would run to switch; they never run any of those commands, log in, switch accounts or write anything.
- It has no telemetry and sends nothing about you or your accounts. Its one request of its own asks
registry.npmjs.org for the latest cloudpin version (public data; the request names only the package), at most once
a day, and only from cloudpin's own commands run in a terminal: never from the shell wrappers, `cloudpin exec` or the
Expand Down
4 changes: 4 additions & 0 deletions THREAT_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,10 @@ These are real limits, stated so nobody relies on cloudpin for them:
- **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.)
- **An agent that runs a CLI's own switch command.** `gh auth switch` or `az account set` is exempt, so a person is never
locked out of fixing a mismatch, and that holds for an agent too. `cloudpin switch` asks; those don't.
- **A name Cursor's hook filter can't see.** Cursor runs the hook only when its text matcher finds a guarded name on the
line, so `"cloud"pin` or `-EncodedCommand <base64>` never reach cloudpin there. Other agents have no such filter.
- **A command cloudpin doesn't guard.** Only the CLIs above are checked. A cloud SDK called from a program, `curl` to a
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.
Expand Down
5 changes: 3 additions & 2 deletions docs/agent-sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,8 +185,9 @@ your `can_use_tool` (`canUseTool`) callback. According to the SDK's types, an ap

## The MCP server: advice, not enforcement

`cloudpin mcp` gives the agent three read-only tools: which account each CLI uses here, whether cloudpin would allow
a command, and why cloudpin may not be guarding (see [cloudpin's MCP server](mcp.md)). An SDK app adds it like any stdio server:
`cloudpin mcp` gives the agent four read-only tools: which account each CLI uses here, whether cloudpin would allow
a command, why cloudpin may not be guarding, and what a person would run to switch (see
[cloudpin's MCP server](mcp.md)). An SDK app adds it like any stdio server:

```python
options = ClaudeAgentOptions(mcp_servers={"cloudpin": {"type": "stdio", "command": "cloudpin", "args": ["mcp"]}})
Expand Down
65 changes: 65 additions & 0 deletions docs/changelog-1.0-1.1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Changelog: 1.0 and 1.1

cloudpin's 1.0 and 1.1 releases, moved here from [CHANGELOG.md](../CHANGELOG.md) on 2026-11-04 to keep that file
short. Newer versions are listed there, and older ones in [changelog-0.x.md](changelog-0.x.md).

## [1.1.2] - 2026-10-19

Completes the 1.1.1 security fix for Windows. Please upgrade.

### Security

- Windows: CLIs installed by npm (vercel, wrangler, ...) no longer start a `node` found in the current folder. npm's
`.cmd` shims run `node` by name when no node.exe sits beside them, and Windows looked for it in the current folder
first. cloudpin now tells Windows not to search the current folder for any process it starts, including the command
`cloudpin exec` runs, as PowerShell and Git Bash already do
([GHSA-3cf7-5v5w-q5vr](https://github.com/paureis/cloudpin/security/advisories/GHSA-3cf7-5v5w-q5vr)).

## [1.1.1] - 2026-10-18

A security fix for Windows. Please upgrade.

### Security

- Windows: cloudpin now runs each CLI it asks about (az, gh, vercel, aws, gcloud, kubectl, helm, supabase,
wrangler), and the command `cloudpin exec` runs, by its full path from PATH, skipping empty and relative PATH
entries. Before, Windows' own lookup checked the current folder first, so a file named like one of those CLIs
inside a repository could run in its place when cloudpin checked a command there
([GHSA-3cf7-5v5w-q5vr](https://github.com/paureis/cloudpin/security/advisories/GHSA-3cf7-5v5w-q5vr)).

## [1.1.0] - 2026-10-16

Claude Code gets a one-step plugin, and any MCP agent can ask cloudpin before it acts.

### Added

- A Claude Code plugin (#15): `claude plugin install cloudpin --marketplace paureis/cloudpin` installs the hook, a
read-only MCP server and a skill that tells the agent to check first and stop on a block. With the plugin enabled,
`install-hook claude` declines and `doctor` warns if a settings hook would also run.
- `cloudpin mcp` (#15): a read-only MCP server (stdio) with `cloudpin_status` and `cloudpin_check`, for any agent that
supports MCP. No new dependency.

## [1.0.0] - 2026-10-15

The first stable release: the `.cloudpin.yml` format is stable from here on (later versions only add sections and
keys), and every agent hook except Gemini CLI's is tested inside the real agent.

### Fixed

- Variables an agent sets earlier in its command line now count (#86). `export AWS_PROFILE=other; aws ...` and
PowerShell `$env:AWS_PROFILE = 'other'; aws ...` were checked against the default account and ran on another; and
`GH_TOKEN=$(cat other.token) gh ...` read the token as empty. cloudpin now follows `export`, `unset` and `$env:`
through the line, and stops a command whose account depends on a value only known when it runs, saying why. Found
in the threat-model review.
- Cursor: a command on your Cursor allowlist runs again when the account matches (#2). cloudpin answered `ask`, which
stopped even allowlisted commands; it now answers `allow`, which Cursor treats exactly like having no hook (measured
in Cursor CLI 2026.10.01: commands not on the allowlist still need your approval). Wrong accounts are still blocked.

### Added

- Antigravity hooks (#80): `cloudpin install-hook antigravity` guards Antigravity CLI, the IDE and Antigravity 2.0
(`.agents/hooks.json`, or `~/.gemini/config/hooks.json` with `--user`). Google replaced Gemini CLI with Antigravity
CLI for free and consumer accounts on 2026-06-18. The hook checks `run_command` and text typed into a running
terminal; it asks rather than allows when nothing is wrong, so Antigravity's own approvals still apply.
- The Copilot CLI and Antigravity CLI hooks are tested inside the real agents (#3): a wrong pin blocks the command, a
right one lets it run, and Antigravity's own approval still applies to commands you haven't allowed.
14 changes: 13 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,32 @@
# cloudpin's MCP server

`cloudpin mcp` is an MCP server (stdio) for any agent that supports MCP. The
[Claude Code plugin](../README.md#claude-code-plugin) starts it for you. It has three tools:
[Claude Code plugin](../README.md#claude-code-plugin) starts it for you. It has four tools:

| Tool | Answers |
|---|---|
| `cloudpin_status` | which account each CLI is using here, what the project pins, which environment applies, which hooks are installed (the same as `cloudpin status --json`) |
| `cloudpin_check` | would cloudpin allow this command line, as an agent's: each call, the account it would use and why, and the verdict with its reason and fix (the same as `cloudpin explain --agent --json`). The line is read as bash; pass `shell: "powershell"` for a PowerShell command (`--powershell` for `explain`) |
| `cloudpin_doctor` | why cloudpin may not be guarding here: cloudpin on PATH, shell wrappers, agent hooks missing or out of date, on Windows the PowerShell execution policy and PATH, the pin file and each CLI's account, each with its fix (the same as `cloudpin doctor --json`, account IDs shortened; it skips the identity cache check, which writes a file, and says so) |
| `cloudpin_switch_plan` | on a mismatch, what you would run to move each CLI to its pinned account: the commands, what to do by hand, and any candidates to pick from (the same as `cloudpin switch --json` without `--yes`, plus a `note` saying who the plan is for). Nothing is run |

No tool runs, switches or changes anything, by design: an agent that could switch accounts could switch to the
wrong one, and only you know which account the work is for.

When an agent connects, the server also hands it a few lines of instructions: check first, and
on a block stop and tell you the reason and the fix, never work around it.

### A switch plan is for you to run

`cloudpin_switch_plan` tells the agent to show you the plan and never run its commands itself. That is advice: a CLI's
own switch command (`gh auth switch`, `az account set`) is never blocked, so that you can always switch, which means
neither the hook nor `cloudpin_check` stops an agent that runs one anyway. The plan adds no new way to do that; a
blocked command's fix already names the switch command.

A plan's commands hold the IDs from your pin file in full, because they have to run, plus the names they need from your
setup: the Vercel team's slug, a kube context, an AWS profile. Account IDs the active login reported are shortened, as
in `cloudpin_doctor`. A variable is named, never its value.

## Add it to your agent

Install cloudpin first (`npm install --global cloudpin`). Any MCP client that starts stdio servers takes the same
Expand Down
Loading
Loading