Privacy and security

It runs on your machine and tells you what it sends

pinright is a local process that talks to your agent over stdio. No account, no telemetry. This page summarizes SECURITY.md and the hook threat model.

On your machine

  • No preinstall, install or postinstall scripts. Installing it runs no code.
  • Four runtime dependencies, pinned to exact versions. Releases are published from GitHub Actions with npm provenance.
  • It never executes what it downloads. Archives, READMEs and docs are parsed as text and handed to the agent as data.
  • It reads dependency files in your project, and writes only to its cache directory and, when you run init, to the agent config files it names.

What it sends, and to whom

Every request goes from your machine to a public service, for the package you asked about. pinright never sends your source code, file contents or environment. The names you check do reach these services, and that includes a private package name.

ServiceWhat it receivesWhen
api.deps.dev, api.osv.devecosystem, package name, versionevery check
Registries: npm, PyPI, pypistats, crates.io, RubyGems, Packagistpackage name, versionchecks, risk signals, docs
cdn.jsdelivr.net, data.jsdelivr.compackage name, version, file pathdocs from the published package
api.github.com, raw.githubusercontent.comrepository, tag, file pathrepo docs, upgrade guides, Actions audit
The package's own docs sitea request for /llms.txt and the pages it listswhen the package metadata names a site

The only credential, an optional GITHUB_TOKEN, goes only to api.github.com. URLs that come from package metadata go through a guard: https only, no private, loopback or cloud-metadata addresses (checked again after DNS and on each of at most 3 redirects), a 10 MB body cap.

The hook is a guardrail, not a sandbox

It reads command lines and file contents before the tool runs. It helps an honest agent that makes mistakes and slows down one that a prompt injection talks into an install. It does not watch the process or the network.

What it stops or asks about

  • Installs it can read, through bash -c, eval, $(…), cmd /c, powershell -Command, sudo, xargs and scripts run by name.
  • Writes to manifests and workflows: only new or changed dependencies count.
  • What it cannot read (a name in a variable, a git or URL source, another registry) asks by default.
  • Changes to .pinright.json or to the hook's own entry always go to a human.
  • More than 40 dependencies in one change asks, so padding cannot hide a bad one.

What gets past it

  • Code that installs from inside a program: python -c "subprocess.run(['pip', ...])".
  • Remote scripts such as curl … | sh: noted, not read.
  • Obfuscation beyond what a shell reader resolves, and variables set in an earlier tool call.
  • Tools the hook is not wired to, and anything after it said yes: a human typing npm install, a CI job.
  • What an allowed package does after install.

57 bypass vectors are listed in the threat model, each reproduced in test/hookBypass.test.ts. Pair the hook with a proxy registry, npm ci or pip install --require-hashes in CI, and an agent sandbox without long-lived credentials.

When deps.dev or OSV does not answer, the verdict is unknown, not ok. The starter .pinright.json then asks you; without a policy file the hook allows the change and tells the agent it was not verified.

Prompt injection in package text

pinright puts text written by package authors in front of your agent. It strips hidden characters and markup, drops passages that give the agent orders, and wraps every third-party block in an <untrusted-data> fence with a random id.

The detector matches wording. On attack phrasings written after its rules were frozen, it caught 20% to 40%. Treat it as a tripwire; the fence depends on the agent honoring it.

Two security reviews before 1.0.0

Both by separate AI agent sessions that did not write the code under review, with every finding checked by the author. The attackers modeled: a repository you open, a package publisher, a local user on a shared machine, and for the hook, the agent itself.

11 findings
Round 1, 2026-10-29: 5 high, 5 medium, 1 low, all fixed. 759 regex literals timed on about 900 inputs.
13 findings
Round 2, 2026-11-01, on the release candidate: 1 high, 9 medium, 3 low, all fixed. About 120 hook red-team cases.

Open items after both rounds, such as the self-hosted release runner and gaps in the hook's reader, are listed in docs/SECURITY-REVIEW.md.

Report a vulnerability

Report it privately through GitHub, not in a public issue. Include the version (pinright --version), the command or tool call, and what you expected. We aim to acknowledge within 3 business days and credit you in the advisory unless you ask us not to.