Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-06 10:48:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400)

Browse Source 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip provides CLI commands and guidance for operators and
agents
> - The `pnpm paperclipai` script can pass argument values through a
shell
> - Shell re-parsing can execute command substitutions inside quoted
values
> - This pull request routes guidance through inert-argv `npx
paperclipai` commands and adds regression coverage
> - The benefit is safer operator guidance across documentation and
runtime hints

## Linked Issues or Issue Description

This pull request fixes a command-injection-class defect in Paperclip
CLI guidance.

**What happened?**

The `pnpm paperclipai <sub> --flag "$VALUE"` form can re-parse argument
values through a shell. A command substitution inside a quoted value can
execute on the host.

**Expected behavior**

Paperclip guidance must pass CLI values as inert argument values.
Host-derived values must not appear in copyable commands.

**Steps to reproduce**

1. Run a Paperclip guidance command that uses the `pnpm paperclipai`
script.
2. Provide a quoted value that contains a command substitution.
3. Observe that the shell can evaluate the substitution before the CLI
starts.
4. Compare the result with the `npx paperclipai` form.

**Paperclip version or commit**

`5670984b75d109950c968542a0111ebb6967f4da`

**Deployment mode**

All deployment modes that show or use the affected CLI guidance.

**Installation method**

Built from source and installed CLI guidance.

**Agent adapter(s) involved**

Not adapter-specific (core bug).

**Database mode**

Not database-related.

**Access context**

Both.

**Additional context**

The earlier merged PR
[#11343](https://github.com/paperclipai/paperclip/pull/11343) used the
unsafe `pnpm exec paperclipai` form. This fresh PR replaces that
guidance with the safe `npx paperclipai` form.

## What Changed

- Standardize documentation and runtime hints on `npx paperclipai`.
- Remove the broken `pnpm exec paperclipai` guidance.
- Use a static `<host>` placeholder in private-hostname guidance.
- Add regression tests for unsafe forms, continued lines, static hosts,
and offline guidance.

## Verification

- `git diff --check
origin/master...origin/fix/paperclipai-cli-npx-safe-invocation` passes.
- The branch adds `server/src/__tests__/cli-invocation-safety.test.ts`
and updates private-hostname tests.
- CI must run the new tests, typecheck, lint, and build checks.
- Local Vitest execution was not available because this worktree has no
installed Vitest binary.

## Risks

- The change affects operator and agent documentation text.
- The runtime hints now show `<host>` instead of a request-derived host
value.
- No database schema or migration changes exist.
- CI will detect any missed unsafe invocation or type error.

## Model Used

OpenAI GPT-5, exact model ID `gpt-5`, with tool use and code-review
assistance. The model used repository inspection, Git operations, and PR
preparation.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] CI ran the test suites and they pass; local test execution was
unavailable in this worktree
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I addressed all Greptile and reviewer comments before requesting
merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Nicky LeachandPaperclip authored and GitHub committed 2026-08-14 22:11:16 -07:00
1 parent ea3a5ea7d2
commit fdb9a4880d
44 files changed
+1620 -658
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/adapters/claude-local.md
+1 -1
View File
@@ -102,7 +102,7 @@ therefore shadows any Codex login already present inside the sandbox image.
For manual local CLI usage outside heartbeat runs (for example running as `claudecoder` directly), use:
```sh
pnpm exec paperclipai agent local-cli claudecoder --company-id <company-id>
npx paperclipai agent local-cli claudecoder --company-id <company-id>
```
This installs Paperclip skills in `~/.claude/skills`, creates an agent API key, and prints shell exports to run as that agent.
docs/adapters/codex-local.md
+1 -1
View File
@@ -141,7 +141,7 @@ change.
For manual local CLI usage outside heartbeat runs (for example running as `codexcoder` directly), use:
```sh
pnpm exec paperclipai agent local-cli codexcoder --company-id <company-id>
npx paperclipai agent local-cli codexcoder --company-id <company-id>
```
This installs any missing skills, creates an agent API key, and prints shell exports to run as that agent.
docs/api/secrets.md
+2 -2
View File
@@ -114,7 +114,7 @@ credentials must not be stored in Paperclip `company_secrets`.
The equivalent CLI check is:
```sh
pnpm exec paperclipai secrets doctor --company-id {companyId}
npx paperclipai secrets doctor --company-id {companyId}
```
## Provider Vaults
@@ -485,7 +485,7 @@ as declarations in the package manifest. Exports omit secret values, secret IDs,
provider references, and encrypted provider material. Use:
```sh
pnpm exec paperclipai secrets declarations --company-id {companyId}
npx paperclipai secrets declarations --company-id {companyId}
```
to inspect the declarations that an export would emit before moving a package.
docs/cli/control-plane-commands.md
+38 -38
View File
@@ -9,39 +9,39 @@ Client-side commands for managing issues, agents, approvals, and more.
```sh
# List issues
pnpm exec paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
npx paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
# Get issue details
pnpm exec paperclipai issue get <issue-id-or-identifier>
npx paperclipai issue get <issue-id-or-identifier>
# Create issue
pnpm exec paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
npx paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
# Update issue
pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
npx paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
# Add comment
pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]
npx paperclipai issue comment <issue-id> --body "..." [--reopen]
# Checkout task
pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id>
npx paperclipai issue checkout <issue-id> --agent-id <agent-id>
# Release task
pnpm exec paperclipai issue release <issue-id>
npx paperclipai issue release <issue-id>
```
## Company Commands
```sh
pnpm exec paperclipai company list
pnpm exec paperclipai company get <company-id>
pnpm exec paperclipai company current [--company-id <company-id>]
npx paperclipai company list
npx paperclipai company get <company-id>
npx paperclipai company current [--company-id <company-id>]
# Export to portable folder package (writes manifest + markdown files)
pnpm exec paperclipai company export <company-id> --out ./exports/acme --include company,agents
npx paperclipai company export <company-id> --out ./exports/acme --include company,agents
# Preview import (no writes)
pnpm exec paperclipai company import \
npx paperclipai company import \
<owner>/<repo>/<path> \
--target existing \
--company-id <company-id> \
@@ -50,7 +50,7 @@ pnpm exec paperclipai company import \
--dry-run
# Apply import
pnpm exec paperclipai company import \
npx paperclipai company import \
./exports/acme \
--target new \
--new-company-name "Acme Imported" \
@@ -67,80 +67,80 @@ command.
## Agent Commands
```sh
pnpm exec paperclipai agent list
pnpm exec paperclipai agent get <agent-id>
npx paperclipai agent list
npx paperclipai agent get <agent-id>
```
## Skills Commands
```sh
# Browse app-shipped catalog skills without changing company state
pnpm exec paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
pnpm exec paperclipai skills search "pull request" [--json]
npx paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
npx paperclipai skills search "pull request" [--json]
# Inspect catalog metadata and file inventory before install
pnpm exec paperclipai skills inspect github-pr-workflow
npx paperclipai skills inspect github-pr-workflow
# Install a catalog skill into the company skill library
# This does not attach the skill to any agent.
pnpm exec paperclipai skills install github-pr-workflow --company-id <company-id>
pnpm exec paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
npx paperclipai skills install github-pr-workflow --company-id <company-id>
npx paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
# External sources still use import instead of catalog install
pnpm exec paperclipai skills import ./skills/my-skill --company-id <company-id>
pnpm exec paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
npx paperclipai skills import ./skills/my-skill --company-id <company-id>
npx paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
# Attach desired company skills to an agent after install/import
pnpm exec paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
npx paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
```
## Approval Commands
```sh
# List approvals
pnpm exec paperclipai approval list [--status pending]
npx paperclipai approval list [--status pending]
# Get approval
pnpm exec paperclipai approval get <approval-id>
npx paperclipai approval get <approval-id>
# Create approval
pnpm exec paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
npx paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
# Approve
pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]
npx paperclipai approval approve <approval-id> [--decision-note "..."]
# Reject
pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]
npx paperclipai approval reject <approval-id> [--decision-note "..."]
# Request revision
pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]
npx paperclipai approval request-revision <approval-id> [--decision-note "..."]
# Resubmit
pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"..."}']
npx paperclipai approval resubmit <approval-id> [--payload '{"..."}']
# Comment
pnpm exec paperclipai approval comment <approval-id> --body "..."
npx paperclipai approval comment <approval-id> --body "..."
```
## Activity Commands
```sh
pnpm exec paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
npx paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
```
## Dashboard
```sh
pnpm exec paperclipai dashboard get
npx paperclipai dashboard get
```
## Instance Settings
```sh
pnpm exec paperclipai instance settings:general
pnpm exec paperclipai instance settings:general:update --payload-json '{...}'
pnpm exec paperclipai instance settings:experimental
pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'
npx paperclipai instance settings:general
npx paperclipai instance settings:general:update --payload-json '{...}'
npx paperclipai instance settings:experimental
npx paperclipai instance settings:experimental:update --payload-json '{...}'
```
Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk.
@@ -148,5 +148,5 @@ Experimental features are opt-in and are provided without compatibility guarante
## Heartbeat
```sh
pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
npx paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
```
docs/cli/overview.md
+9 -9
View File
@@ -29,7 +29,7 @@ Company-scoped commands also accept `--company-id <id>`.
For clean local instances, pass `--data-dir` on the command you run:
```sh
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
npx paperclipai run --data-dir ./tmp/paperclip-dev
```
## Context Profiles
@@ -38,7 +38,7 @@ Store defaults to avoid repeating flags:
```sh
# Set defaults
pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <id>
npx paperclipai context set --api-base http://localhost:3100 --company-id <id>
# View current context
pnpm paperclipai context show
@@ -47,24 +47,24 @@ pnpm paperclipai context show
pnpm paperclipai context list
# Switch profile
pnpm paperclipai context use default
npx paperclipai context use default
```
To avoid storing secrets in context, use an env var:
```sh
pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
npx paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
```
Secret operations are available under `paperclipai secrets`:
```sh
pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret
pnpm exec paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
pnpm exec paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
pnpm exec paperclipai secrets doctor --company-id <company-id>
pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
npx paperclipai secrets declarations --company-id <company-id> --kind secret
npx paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
npx paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
npx paperclipai secrets doctor --company-id <company-id>
npx paperclipai secrets migrate-inline-env --company-id <company-id> --apply
```
Context is stored at `~/.paperclip/context.json`.
docs/cli/setup-commands.md
+4 -4
View File
@@ -22,7 +22,7 @@ Does:
Choose a specific instance:
```sh
pnpm paperclipai run --instance dev
npx paperclipai run --instance dev
```
## `paperclipai onboard`
@@ -104,7 +104,7 @@ This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and
Allow a private hostname for authenticated/private mode:
```sh
pnpm exec paperclipai allowed-hostname my-tailscale-host
npx paperclipai allowed-hostname my-tailscale-host
```
## Local Storage Paths
@@ -126,6 +126,6 @@ PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
Or pass `--data-dir` directly on any command:
```sh
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev
npx paperclipai run --data-dir ./tmp/paperclip-dev
npx paperclipai doctor --data-dir ./tmp/paperclip-dev
```
docs/deploy/deployment-modes.md
+1 -1
View File
@@ -42,7 +42,7 @@ pnpm paperclipai onboard
Allow custom Tailscale hostnames:
```sh
pnpm exec paperclipai allowed-hostname my-machine
npx paperclipai allowed-hostname my-machine
```
### `authenticated` + `public`
docs/deploy/local-development.md
+7 -6
View File
@@ -64,7 +64,7 @@ pnpm dev --authenticated-private
Allow additional private hostnames:
```sh
pnpm exec paperclipai allowed-hostname dotta-macbook-pro
npx paperclipai allowed-hostname dotta-macbook-pro
```
For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).
@@ -84,10 +84,10 @@ curl http://localhost:3100/api/companies
For safer parallel local experiments, initialize a dedicated worktree instance instead of reusing your main checkout:
```sh
pnpm paperclipai worktree:make local-lab --seed-mode minimal
npx paperclipai worktree:make local-lab --seed-mode minimal
cd ~/paperclip-local-lab
pnpm paperclipai worktree env # inspect generated env exports
eval "$(pnpm paperclipai worktree env)" # bash/zsh
eval "$(npx paperclipai worktree env)" # bash/zsh
pnpm paperclipai run
pnpm paperclipai doctor
```
@@ -95,14 +95,15 @@ pnpm paperclipai doctor
If the experiment gets noisy, repair or reseed the worktree without touching the main branch:
```sh
pnpm paperclipai worktree repair --branch paperclip-local-lab
pnpm paperclipai worktree reseed --from . --to paperclip-local-lab
# worktree repair rebuilds the local checkout metadata, so run the checked-out CLI through the direct-exec form.
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts worktree repair --branch paperclip-local-lab
npx paperclipai worktree reseed --from . --to paperclip-local-lab
```
When done, shut it down and remove the isolated state explicitly:
```sh
pnpm paperclipai worktree:cleanup local-lab --force
npx paperclipai worktree:cleanup local-lab --force
```
## Reset Dev Data
docs/deploy/secrets.md
+4 -4
View File
@@ -203,7 +203,7 @@ Validate secrets config:
```sh
pnpm paperclipai doctor
pnpm exec paperclipai secrets doctor --company-id <company-id>
npx paperclipai secrets doctor --company-id <company-id>
```
### Environment Overrides
@@ -475,8 +475,8 @@ store.
If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:
```sh
pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id>
pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
npx paperclipai secrets migrate-inline-env --company-id <company-id>
npx paperclipai secrets migrate-inline-env --company-id <company-id> --apply
# low-level script for direct database maintenance
pnpm secrets:migrate-inline-env # dry run
@@ -493,7 +493,7 @@ Company exports include only environment declarations. They do not include
secret IDs, provider references, encrypted material, or plaintext values.
```sh
pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret
npx paperclipai secrets declarations --company-id <company-id> --kind secret
```
Before importing a package into another instance, use those declarations to
docs/deploy/tailscale-private-access.md
+1 -1
View File
@@ -58,7 +58,7 @@ http://my-macbook.tailnet.ts.net:3100
If you access Paperclip with a custom private hostname, add it to the allowlist:
```sh
pnpm exec paperclipai allowed-hostname my-macbook.tailnet.ts.net
npx paperclipai allowed-hostname my-macbook.tailnet.ts.net
```
## 5. Verify the server is reachable
docs/feedback-voting.md
+2 -2
View File
@@ -36,7 +36,7 @@ Shows a color-coded summary: vote counts, per-trace details with reasons, and ex
paperclipai feedback report
# Point to a different server or company
pnpm exec paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>
npx paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>
# Include raw payload dumps in the report
pnpm paperclipai feedback report --payloads
@@ -112,7 +112,7 @@ Exports are full by default. `traces/` keeps the Paperclip envelope, while `full
```bash
# Custom server and output directory
pnpm exec paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export
npx paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export
```
### Reading an exported trace
docs/guides/board-operator/experimental-features.md
+1 -1
View File
@@ -23,7 +23,7 @@ The CLI exposes the same surface:
```sh
pnpm paperclipai instance settings:experimental
pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'
npx paperclipai instance settings:experimental:update --payload-json '{...}'
```
Those commands change the same opt-in settings that the UI manages.
docs/guides/openclaw-docker-setup.md
+2 -2
View File
@@ -82,7 +82,7 @@ PAPERCLIP_COOKIE="your_session_cookie=..." pnpm smoke:openclaw-join
- If Paperclip rejects the container-visible host with a hostname error, allow it from host:
```bash
pnpm exec paperclipai allowed-hostname host.docker.internal
npx paperclipai allowed-hostname host.docker.internal
```
Then restart Paperclip and rerun the smoke script.
@@ -90,7 +90,7 @@ Then restart Paperclip and rerun the smoke script.
- Authenticated/private mode: ensure hostnames are in the allowed list when required:
```bash
pnpm exec paperclipai allowed-hostname <host>
npx paperclipai allowed-hostname <host>
```
## Prerequisites