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

fix(security): standardize paperclipai CLI guidance on safe npx path (#11343)

Browse Source 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip provides CLI guidance to agents and operators through
documentation and runtime messages.
> - Content-bearing `pnpm paperclipai` examples send arguments through a
shell.
> - Shell evaluation can execute command substitutions in untrusted
argument content.
> - Runtime hostname guidance can also place request-derived content
inside a shell command.
> - This pull request uses `npx paperclipai` for content-bearing
guidance and uses a static hostname placeholder.
> - The benefit is safer copy-paste guidance for agents and operators.

## Linked Issues or Issue Description

**Issue type**
Incorrect information

**Where is the issue?**
CLI guidance in `doc/CLI.md`, `skills/paperclip/SKILL.md`,
documentation, and runtime-generated hints.

**What's wrong?**
Content-bearing `pnpm paperclipai` commands can pass argument text
through `/bin/sh`. Shell command substitution in an argument can execute
before the CLI receives the value.

**Suggested fix**
Use `npx paperclipai` for content-bearing commands. Use a static
`<host>` placeholder when runtime guidance displays the allowed-hostname
command.

## What Changed

- Replace content-bearing `pnpm paperclipai` examples with `npx
paperclipai` across the documentation and agent-facing guidance.
- Update runtime-generated CLI hints to use a static `<host>`
placeholder.
- Add safety notes to `doc/CLI.md` and `skills/paperclip/SKILL.md`.
- Add scans and regression tests for unsafe invocation and hostile
hostname headers.
- Keep fixed lifecycle commands and `pnpm --filter @paperclipai/*` build
commands unchanged.

## Verification

- Run `tsc --noEmit` for the changed server files.
- Run `cli-invocation-safety.test.ts`.
- Run `private-hostname-guard.test.ts`.
- Confirm that hostile hostname headers do not enter shown shell
commands.
- Confirm that the three commits contain the required Paperclip
co-author trailer.

## Risks

- This change updates documentation and diagnostic text across many
surfaces.
- Fixed lifecycle and setup commands remain unchanged.
- The tests fail if content-bearing `pnpm paperclipai` guidance returns.
- The change does not alter the CLI argument parser.

## Model Used

OpenAI Codex, GPT-5, tool use, code execution, and repository review
assistance.

## 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] I have run tests locally and they pass
- [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 will address 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-13 16:43:21 -07:00
1 parent 05d58cd884
commit 5ca7b4c1fe
27 files changed
+899 -472
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

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 paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
pnpm exec paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
# Get issue details
pnpm paperclipai issue get <issue-id-or-identifier>
pnpm exec paperclipai issue get <issue-id-or-identifier>
# Create issue
pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
pnpm exec paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
# Update issue
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
# Add comment
pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]
# Checkout task
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>
pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id>
# Release task
pnpm paperclipai issue release <issue-id>
pnpm exec paperclipai issue release <issue-id>
```
## Company Commands
```sh
pnpm paperclipai company list
pnpm paperclipai company get <company-id>
pnpm paperclipai company current [--company-id <company-id>]
pnpm exec paperclipai company list
pnpm exec paperclipai company get <company-id>
pnpm exec paperclipai company current [--company-id <company-id>]
# Export to portable folder package (writes manifest + markdown files)
pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents
pnpm exec paperclipai company export <company-id> --out ./exports/acme --include company,agents
# Preview import (no writes)
pnpm paperclipai company import \
pnpm exec paperclipai company import \
<owner>/<repo>/<path> \
--target existing \
--company-id <company-id> \
@@ -50,7 +50,7 @@ pnpm paperclipai company import \
--dry-run
# Apply import
pnpm paperclipai company import \
pnpm exec paperclipai company import \
./exports/acme \
--target new \
--new-company-name "Acme Imported" \
@@ -67,80 +67,80 @@ command.
## Agent Commands
```sh
pnpm paperclipai agent list
pnpm paperclipai agent get <agent-id>
pnpm exec paperclipai agent list
pnpm exec paperclipai agent get <agent-id>
```
## Skills Commands
```sh
# Browse app-shipped catalog skills without changing company state
pnpm paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
pnpm paperclipai skills search "pull request" [--json]
pnpm exec paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
pnpm exec paperclipai skills search "pull request" [--json]
# Inspect catalog metadata and file inventory before install
pnpm paperclipai skills inspect github-pr-workflow
pnpm exec 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 paperclipai skills install github-pr-workflow --company-id <company-id>
pnpm paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
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>
# External sources still use import instead of catalog install
pnpm paperclipai skills import ./skills/my-skill --company-id <company-id>
pnpm paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
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>
# Attach desired company skills to an agent after install/import
pnpm paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
pnpm exec paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
```
## Approval Commands
```sh
# List approvals
pnpm paperclipai approval list [--status pending]
pnpm exec paperclipai approval list [--status pending]
# Get approval
pnpm paperclipai approval get <approval-id>
pnpm exec paperclipai approval get <approval-id>
# Create approval
pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
pnpm exec paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
# Approve
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]
# Reject
pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]
# Request revision
pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]
# Resubmit
pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']
pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"..."}']
# Comment
pnpm paperclipai approval comment <approval-id> --body "..."
pnpm exec paperclipai approval comment <approval-id> --body "..."
```
## Activity Commands
```sh
pnpm paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
pnpm exec paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
```
## Dashboard
```sh
pnpm paperclipai dashboard get
pnpm exec paperclipai dashboard get
```
## Instance Settings
```sh
pnpm paperclipai instance settings:general
pnpm paperclipai instance settings:general:update --payload-json '{...}'
pnpm paperclipai instance settings:experimental
pnpm paperclipai instance settings:experimental:update --payload-json '{...}'
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 '{...}'
```
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 paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
```
docs/cli/overview.md
+7 -7
View File
@@ -38,7 +38,7 @@ Store defaults to avoid repeating flags:
```sh
# Set defaults
pnpm paperclipai context set --api-base http://localhost:3100 --company-id <id>
pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <id>
# View current context
pnpm paperclipai context show
@@ -53,18 +53,18 @@ pnpm paperclipai context use default
To avoid storing secrets in context, use an env var:
```sh
pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
```
Secret operations are available under `paperclipai secrets`:
```sh
pnpm paperclipai secrets declarations --company-id <company-id> --kind secret
pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
pnpm paperclipai secrets doctor --company-id <company-id>
pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
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
```
Context is stored at `~/.paperclip/context.json`.
docs/cli/setup-commands.md
+1 -1
View File
@@ -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 paperclipai allowed-hostname my-tailscale-host
pnpm exec paperclipai allowed-hostname my-tailscale-host
```
## Local Storage Paths