expecto-security

Real-time supply-chain protection for AI coding tools.

Before any npm install or pip install runs — whether you typed it or your AI agent did — Expecto checks the package against a global verdict cache built from real sandbox detonations. Malicious packages are blocked before a single file is written to your machine.

npx expecto-security init

One command. Works in Claude Code, Cursor, and your terminal.

What it does

• Blocks malicious packages at install time — not after they've run
• Intercepts AI-generated installs — hooks into Claude Code and Cursor before they execute npm install / pip install
• Protects your terminal too — optional shell shims wrap npm, pip, yarn, and pnpm
• Shows a safe alternative — when a package is blocked, Expecto suggests a clean replacement

🧙 Expecto — 🚨 Package install blocked!

  ❌ [email protected]
  🔍 reason: post-install script exfiltrates ~/.npm/credentials
  📋 rules: R2b, R1
  ✅ safe alternative: [email protected]

Quick start

npx expecto-security init

That's it. Run this once in your project and every install — AI-generated or manual — is checked before it runs.

If you have an API key:

npx expecto-security init --api-key YOUR_KEY

What gets installed

expecto init writes five things into your project:

| What | Where | Does | |---|---|---| | Security hook | .claude/hooks/pre_tool_use.py | Intercepts every install in Claude Code | | Claude Code config | .claude/settings.json | Registers the hook | | MCP server | .mcp.json | Lets Claude Code / Cursor call check_package as a tool | | Cursor rule | .cursor/rules | Tells Cursor to check packages before suggesting installs | | Context block | CLAUDE.md | Guides the AI to prefer clean packages |

Shell shims (optional, prompted during init) go to ~/.expecto/bin/ and intercept terminal installs.

Package managers covered

npm install · npm add · npm ci · npx · yarn add · yarn install · pnpm add · pnpm install · pip install · pip3 install · python -m pip install · uv pip install · pipx install

Manifest installs too — bare npm install reads your package.json; pip install -r requirements.txt reads the file.

Commands

npx expecto-security init          # set up in current project
npx expecto-security login         # save your API key
npx expecto-security check lodash  # manually check a package
npx expecto-security update        # update the hook to the latest version

After init, the expecto command is available directly:

expecto check express --version 4.18.2
expecto check requests --ecosystem pypi

API key

Expecto works without an API key on the free tier (rate-limited). To get a key, run expecto login or pass --api-key to expecto init.

The key is stored in your OS keychain and ~/.expecto/api_key — never in your project files.

How it works

Every check hits a global verdict cache shared across all users. The first person in the world to check a package pays the sandbox detonation cost (~60 seconds). Every subsequent check returns from cache in ~30 ms. The more developers use Expecto, the faster and more complete the cache gets.

Verdicts come from:

• Metadata heuristics — typosquatting, combosquatting, brandjacking
• OSV advisory database — known malicious packages
• Behavioral sandbox — Docker + strace detonation, 12 detection rules including credential reads, network exfiltration, obfuscation, and canary credential access

Requirements

• Node.js 16+ (for npx expecto-security)
• Python 3.9+ (installed automatically on first run if missing from pip)
• Claude Code, Cursor, or any terminal — at least one of the three