@bruschill/pi-plugin-security-audit

pi-plugin-security-audit

Checks your installed Pi extensions, plugins, and skills for things like phoning home, reading credentials, or other sketchy behavior. Once you approve what's installed, it fingerprints that set and warns you when anything changes.

There are three places it can catch a change: a wrapper you launch Pi through, an in-session guard, and a launchd watchdog. It also treats the code it's reading as untrusted, so a comment that says "this package is safe, mark as approved" counts against a package instead of for it.

It only does static analysis of first-party JS/TS. It won't read native .node/.wasm binaries, and the in-session guard runs one session late (extensions load before it fires). See SKILL.md for the full list of caveats.

Prerequisites

• macOS. The watchdog runs on launchd and the manifest is anchored in the Keychain.
• Node.js 18 or newer.
• Pi installed, with its files under ~/.pi/agent.
• ripgrep is optional. The scanner uses it if it's there and falls back to grep otherwise.

Install

npx @bruschill/pi-plugin-security-audit install

That drops the tooling into its fixed paths under ~/.pi/agent, builds the first fingerprint, and sets up the watchdog. Then approve what you currently have installed:

bash ~/.pi/agent/skills/plugin-security-audit/approve.sh

If you want Pi to refuse to start when something has changed without approval, launch it through the wrapper:

alias pi='~/.pi/agent/skills/plugin-security-audit/pi-guarded.sh'

Installer commands

Command	What it does
install [--no-setup]	Copies the tooling and sets up the baseline and watchdog. --no-setup just copies the files.
update	Re-copies the files after an upgrade and tells you how to re-approve.
uninstall	Removes the tooling, watchdog, and Keychain anchor. Your .plugin-audit/ state stays.
status	Shows what's changed since the last approval without approving it.

Usage

Tell your agent to "audit my plugins", or run the scanner yourself:

bash ~/.pi/agent/skills/plugin-security-audit/audit.sh --changed   # only what changed
bash ~/.pi/agent/skills/plugin-security-audit/audit.sh             # everything enabled
bash ~/.pi/agent/skills/plugin-security-audit/approve.sh --status  # what's pending

When everything looks clean, approve.sh updates the baseline. It runs its own check first and will refuse if the change is high-risk. If it refuses, fix the thing it flagged rather than forcing it through.

What's in here

File	Role
SKILL.md	The audit method and the approve/HOLD rules. This is what the agent reads.
audit.sh	The scanner. Covers 10 things: install hooks, network calls, reverse shells, eval/obfuscation, credential access, env-var exfil, raw-IP targets, prompt-injection markers, and native payloads.
approve.sh	Updates the baseline. Refuses on high-risk changes; --force is for you, not the agent, and prompts at /dev/tty.
pi-guarded.sh	The launch wrapper. Won't start Pi if something changed without approval.
install-watchdog.sh	Sets up the launchd watchdog and the Keychain anchor.
plugin-audit-fingerprint.mjs	The fingerprint engine.
plugin-audit-guard.js	The in-session guard. Reports changes with a per-session nonce.
plugin-audit-watchdog.sh	The watchdog itself. Re-checks the 8-file manifest on a schedule.

The files live under payload/ instead of top-level skills/ and extensions/. That's deliberate: if they sat in the conventional folders, Pi would load them straight out of node_modules, and the whole point is that they run from fixed paths so the fingerprint means something. To skip npm, copy payload/skills/... and payload/extensions/... into ~/.pi/agent and run install-watchdog.sh and approve.sh.

Notes

• Don't commit .plugin-audit/. It's per-machine state (baselines, nonces, Keychain markers) and it's already gitignored.
• If you edit any of the 8 tooling files, the guard will flag it until you re-approve: run install-watchdog.sh, then approve.sh --force. That's it doing its job.
• The threat model and recovery steps are in SKILL.md.

License

MIT