History

Nicky Leach fdb9a4880d fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400 ) ## 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>		2026-08-14 22:11:16 -07:00
..
scripts	Add kitchen sink plugin example	2026-03-13 23:03:51 -05:00
src	feat(mcp) [split 2/8]: add governed access contracts (#9557 )	2026-07-14 12:57:20 -05:00
README.md	fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400 )	2026-08-14 22:11:16 -07:00
package.json	build(deps-dev): bump @types/node from 22.19.21 to 22.20.1 (#10304 )	2026-07-28 10:48:45 -07:00
tsconfig.json	Add kitchen sink plugin example	2026-03-13 23:03:51 -05:00

README.md

@paperclipai/plugin-kitchen-sink-example

Kitchen Sink is the first-party reference plugin that demonstrates nearly the full currently implemented Paperclip plugin surface in one package.

It is intentionally broad:

full plugin page
dashboard widget
project and issue surfaces
comment surfaces
sidebar surfaces
settings page
worker bridge data/actions
events, jobs, webhooks, tools, streams
state, entities, assets, metrics, activity
local workspace and process demos

This plugin is for local development, contributor onboarding, and runtime regression testing. It is not meant as a production plugin template to ship unchanged.

Install

pnpm --filter @paperclipai/plugin-kitchen-sink-example build
npx paperclipai plugin install ./packages/plugins/examples/plugin-kitchen-sink-example

Or install it from the Paperclip plugin manager as a bundled example once this repo is built.

Notes

Local workspace and process demos are trusted-only and default to safe, curated commands.
The plugin settings page lets you toggle optional demo surfaces and local runtime behavior.
Some SDK-defined host surfaces still depend on the Paperclip host wiring them visibly; this package aims to exercise the currently mounted ones and make the rest obvious.