Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (expecto-security) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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!

  ❌ event-stream@4.0.0
  🔍 reason: post-install script exfiltrates ~/.npm/credentials
  📋 rules: R2b, R1
  ✅ safe alternative: readable-stream@4.1.0

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