Core Concepts

Understand how sus protects AI agents from malicious packages

Overview

sus is a security-first package gateway for AI agents. It answers one simple question: is this package sus?

Traditional package managers were built for human developers who can review code, recognize suspicious patterns, and make judgment calls. AI agents don't have these instincts. They trust what they're told and execute what they're given. This makes them uniquely vulnerable to a new class of attacks designed specifically to exploit autonomous code execution.

sus solves this by scanning every package before installation, detecting both traditional security threats and agentic-specific attacks, and providing a centralized docs index so agents know how to use packages correctly.

Why Traditional Package Managers Fail AI Agents

npm, yarn, pnpm, and bun were never designed with AI agents in mind. Here's what they're missing:

The Agentic Threat Landscape

AI agents face threats that human developers would catch but automated systems miss:

• Prompt Injection in READMEs: Malicious instructions hidden in package documentation that hijack agent behavior
• Error Message Attacks: Crafted error messages that trick agents into executing harmful commands
• Hidden Instructions: Comments in source code designed to override agent instructions
• Install Script Exploits: postinstall scripts that target autonomous execution contexts
• Repo Poisoning: Legitimate packages with compromised versions targeting agents

These attacks don't show up in CVE databases. Traditional security tools don't scan for them. sus does.

How sus Works

sus uses a distributed architecture where packages are pre-scanned in the cloud, so lookups are instant:

The Scanning Pipeline

When sus scans a package, it runs a comprehensive analysis pipeline:

1. Metadata Fetch: Pull package info from the registry (maintainers, downloads, repository)
2. Tarball Download: Fetch and extract the package contents
3. Parallel Analysis: Run all scanners concurrently for speed
4. Risk Calculation: Combine all signals into a final risk assessment
5. Store & Serve: Cache results for instant lookups

Risk Levels

Every package gets assigned one of three risk levels:

Clean

No issues detected. Safe to install.

$ sus add express
🔍 checking express@4.21.0...
✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   ├─ cves: 0
   └─ install scripts: none
📦 installed
📝 updated AGENTS.md docs index

Warning

Minor issues that warrant attention but don't block installation.

$ sus add lodash@4.17.20
🔍 checking lodash@4.17.20...
⚠️  kinda sus
   ├─ cve: CVE-2021-23337 (prototype pollution, medium)
   └─ fix available: 4.17.21
📦 installed (use --strict to block warnings)

Critical

Major threats that block installation by default.

$ sus add event-stream@3.3.6
🔍 checking event-stream@3.3.6...
🚨 MEGA SUS
   ├─ malware: flatmap-stream injection
   ├─ targets: cryptocurrency wallets
   └─ status: COMPROMISED
❌ not installed. use --yolo to force (don't)

Threat Detection

sus detects two categories of threats:

Traditional Threats

• CVEs: Known vulnerabilities from OSV, NVD, and GitHub Advisory databases
• Known Malware: Packages like event-stream, node-ipc that have been compromised
• Typosquatting: Packages like expresss or lodahs designed to trick users
• Suspicious Install Scripts: postinstall scripts that download or execute code
• Maintainer Hijacking: Signs that a package maintainer account was compromised

Agentic Threats

Detected using AI-powered analysis:

• Prompt Injection: Instructions in READMEs designed to hijack agent behavior
• Error Message Attacks: Crafted error strings that manipulate agents
• Hidden Instructions: Comments in code that override agent instructions
• Repo Poisoning: Malicious code disguised as legitimate updates
• Instruction Override: Attempts to change agent behavior through package content

Capability Extraction

sus performs static analysis to detect what a package can do:

This information helps agents understand what permissions a package needs and whether its capabilities match its stated purpose.

$ sus check axios
🔍 checking axios@1.6.0...
✅ not sus
 
capabilities:
   ├─ network: http, https (api calls)
   ├─ filesystem: none
   ├─ process: none
   └─ environment: HTTP_PROXY, HTTPS_PROXY

AGENTS.md Docs Index

For every scanned package, sus generates documentation that helps AI agents use the package correctly. This documentation is:

1. Saved to .sus-docs/ in your project
2. Indexed in AGENTS.md for easy discovery

Each package doc includes:

• Quick Start: Minimal code to get started
• Key APIs: Most important functions and their usage
• Best Practices: Recommended patterns and configurations
• Common Gotchas: Mistakes to avoid
• Permissions: What capabilities the package requires

Why Docs Index?

Based on Vercel's research, passive context in AGENTS.md outperforms active skill retrieval:

This is why sus uses a centralized docs index instead of per-agent-folder skills.

Trust Score

Every package gets a trust score from 0-100 based on multiple signals:

A higher trust score doesn't mean a package is safe. It means the package has more signals of legitimacy. Even high-trust packages can have CVEs or be compromised.

Scan Priority

sus continuously monitors package registries and prioritizes scans:

This ensures that when you run sus add, the package has likely already been scanned and results are instant.

Summary

sus protects AI agents by:

1. Scanning before installing - Unlike npm audit, sus blocks threats before they touch your system
2. Detecting agentic threats - Prompt injection, repo poisoning, and other attacks targeting AI
3. Extracting capabilities - Understanding what packages can actually do
4. Maintaining a docs index - Centralized documentation in AGENTS.md for instant agent access
5. Calculating trust scores - Multiple signals combined into actionable risk levels

The result: AI agents can safely install packages without falling victim to attacks designed to exploit their autonomous nature.