Pre-install firewall against hallucinated packages and typosquats in npm and PyPI.
Run it with npx:
npx slopguard guard npm install <package>Coding assistants (Claude Code, Cursor, Copilot, Aider) often invent package names that sound plausible but do not exist (express-async-router-v4, fastapi-jwt-auth-pro).
Attackers monitor common prompts, find recurring hallucinated names, register them on npm or PyPI ("slopsquatting"), and attach install hooks that steal environment variables or drop reverse shells.
Standard vulnerability scanners (npm audit, Snyk, Dependabot) check for known CVEs. A newly registered phantom package has no advisory and zero entries in any CVE database. By the time npm install finishes downloading, the package's preinstall script has already run on your machine.
SlopGuard intercepts your package manager before it connects to the network. If a package does not exist, was published under 72 hours ago, or collides with a known library via typosquatting, SlopGuard halts the process before any code runs.
When an AI agent or a developer attempts to install a hallucinated package, SlopGuard halts execution before the package manager spawns:
$ npx slopguard guard npm install express-async-router-v4
╔════════════════════════════════════════════════╗
║ ║
║ 🚨 SLOPGUARD SECURITY ALERT 🚨 ║
║ DANGEROUS / HALLUCINATED PACKAGES DETECTED ║
║ BLOCKED: Hallucinated package detected ║
║ ║
╚════════════════════════════════════════════════╝
Execution blocked to prevent supply chain compromise or package hallucination attack.
Command: npm install express-async-router-v4
Detected Risk Findings:
• express-async-router-v4 [npm] - 404 NOT FOUND - CRITICAL (100/100)
↳ Phantom / Hallucinated Package (HTTP 404): Package 'express-async-router-v4' was NOT found in npm registry (HTTP 404). Likely an AI hallucination or phantom dependency.
↳ Remediation: Package does not exist on public registry. Attackers can register phantom packages to achieve RCE.
Summary:
• Blocked Packages: 1
❌ Gating Action: BLOCKED. High-risk dependencies detected exceeding threshold (HIGH).
Exit code: 1
Run directly without installing:
npx slopguard guard npm install <pkg>Or install globally:
npm install -g slopguardAdd aliases in ~/.zshrc or ~/.bashrc. SlopGuard passes safe packages straight to the underlying tool with inherited stdio. If a package triggers a high-risk heuristic, SlopGuard stops execution immediately:
# JavaScript / TypeScript
alias npm="slopguard guard npm"
alias pnpm="slopguard guard pnpm"
alias yarn="slopguard guard yarn"
alias bun="slopguard guard bun"
# Python
alias pip="slopguard guard pip"
alias poetry="slopguard guard poetry"
alias uv="slopguard guard uv"SlopGuard has three commands: guard (runtime wrapper), scan (manifest checker), and check-pr (diff analyzer for CI).
Intercepts package installations, extracts the target packages, runs heuristic checks against the registry, and executes the installer only if all packages pass:
# Node packages
slopguard guard npm install express lodash
slopguard guard pnpm add react
slopguard guard yarn add zustand
slopguard guard bun add trpc
# Python packages
slopguard guard pip install requests
slopguard guard pip install -r requirements.txt
slopguard guard poetry add fastapi
slopguard guard uv pip install torch| Flag | Default | Description |
|---|---|---|
--threshold <level> |
high |
Minimum risk level to block: low, medium, high, critical. |
--strict |
false |
Blocks on medium risk findings as well. |
--offline |
false |
Uses local fixtures/cache without making network requests. |
--verbose |
false |
Prints step-by-step diagnostic logs. |
Scans directories or manifest files (package.json, requirements.txt, pyproject.toml) for non-existent, young, or squatted dependencies:
# Scan working directory
slopguard scan .
# Scan specific files
slopguard scan ./frontend/package.json
slopguard scan ./backend/requirements.txt
slopguard scan ./pyproject.toml
# Generate SARIF for GitHub Code Scanning
slopguard scan . --format=sarif -o slopguard.sarif
# Strict scan with JSON output
slopguard scan . --strict --format=json| Flag | Default | Description |
|---|---|---|
--format <fmt> |
table |
Output format: table, json, or sarif. |
--json |
false |
Shorthand for --format=json. |
--threshold <level> |
high |
Risk threshold to trigger failure: low, medium, high, critical. |
--strict |
false |
Treats medium risk findings as errors. |
--offline |
false |
Disables network calls. |
--quiet |
false |
Hides banners and non-critical progress output. |
-o, --output <file> |
stdout |
Writes report to file. |
Scans git diffs or pull requests to catch risky dependencies before merge:
# Scan diff against origin/main
git diff origin/main | slopguard check-pr
# Scan a patch file
slopguard check-pr ./patch.diff --format=sarif -o alerts.sarif
# Specify base commit ref
slopguard check-pr --base origin/main --strictSlopGuard checks incoming dependencies against five heuristic vectors:
Target dependency
│
▼
┌───────────────────┐
│ H1: Registry 404 │ ──► HTTP 404? ──────────────► [ FATAL: Score 100 ]
└───────────────────┘ │ exists
▼
┌───────────────────┐
│ H2: Newborn Age │ ──► Published < 72 hours? ──► [ +60 Points ]
└───────────────────┘ │
▼
┌───────────────────┐
│ H3: Typosquatting │ ──► Distance <= 1 ► [ +70 Points ]
└───────────────────┘ Separator collision
Homoglyphs
│
▼
┌───────────────────┐
│ H4: Reputation │ ──► Zero downloads ► [ +20-30 Points ]
└───────────────────┘ No repository
Fresh author account
│
▼
┌───────────────────┐
│ H5: Install Hooks │ ──► preinstall / setup.py? ► [ +80 Points ]
└───────────────────┘ │
▼
┌───────────────────────────┐
│ Composite Risk Score │
│ 0-19: SAFE 20-39: LOW │
│ 40-69: MED 70-89: HIGH │
│ 90-100: CRITICAL │
└───────────────────────────┘
| Vector | Trigger condition | Why it matters | Score | Default action |
|---|---|---|---|---|
H1: Registry Existence (SG001) |
HTTP 404 from registry | The package does not exist. It is an AI hallucination that attackers can register at any time. | 100 |
BLOCK |
H2: Publication Age (SG002) |
Published < 72 hours ago | Attackers register hallucinated names immediately after discovery. | 60 |
WARN |
H3: Typosquatting (SG003) |
Damerau-Levenshtein crossenv vs cross-env), or homoglyphs (аxios) |
Attempts to impersonate top 1,200 npm or 500 PyPI packages. | 70 |
BLOCK |
H4: Reputation (SG004) |
Zero downloads, missing repository, novel author account | Package has no verifiable open-source history. | 20-30 |
WARN |
H5: Install Hooks (SG005) |
preinstall, postinstall, or setup.py on newborn packages |
Lifecycle scripts execute shell commands during installation. | 80 |
BLOCK |
| Score | Level | Default action | Strict action | Description |
|---|---|---|---|---|
| 0 – 19 | SAFE |
ALLOW | ALLOW | Verified clean metadata or top seed package. |
| 20 – 39 | LOW |
ALLOW | ALLOW | Minor anomalies (such as low download count on older niche libraries). |
| 40 – 69 | MEDIUM |
WARN | BLOCK | Moderate suspicion (newborn package with standard metadata). |
| 70 – 89 | HIGH |
BLOCK | BLOCK | Severe risk: typosquatting collision, newborn lifecycle scripts. |
| 90 – 100 | CRITICAL |
BLOCK | BLOCK | Fatal: HTTP 404 hallucination or known malicious payload. |
| Exit code | Meaning | Condition |
|---|---|---|
0 |
Clean | All dependencies passed below the risk threshold. The wrapped install command succeeded. |
1 |
Security block | A dependency exceeded the risk threshold (hallucinated 404, typosquat, newborn hook). Installation was halted. |
2 |
Error | Invalid flags, missing files, or corrupted manifest syntax. |
SlopGuard outputs OASIS SARIF 2.1.0, uploading findings directly to GitHub Code Scanning.
name: SlopGuard Security Gate
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
security-scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g slopguard
- name: Scan PR diff
if: github.event_name == 'pull_request'
run: |
git diff origin/${{ github.base_ref }}...HEAD | slopguard check-pr \
--format=sarif \
-o slopguard-results.sarif \
--strict
- name: Scan repository manifests
if: github.event_name == 'push'
run: |
slopguard scan . \
--format=sarif \
-o slopguard-results.sarif \
--strict
- name: Upload SARIF report
uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: slopguard-results.sarif
category: slopguard-firewall- Offline mode: Use
--offlineorexport SLOPGUARD_OFFLINE=1for isolated builds and air-gapped systems. - Custom registry mirrors: Point SlopGuard to internal Verdaccio, Artifactory, or Nexus registries:
export SLOPGUARD_NPM_REGISTRY="https://artifactory.internal/api/npm/npm-repo" export SLOPGUARD_PYPI_REGISTRY="https://artifactory.internal/api/pypi/pypi-repo/json"
- In-memory cache: LRU cache stores evaluated package metadata so repeat runs evaluate in under 2.5ms per dependency.
Run the test suite:
# Run all 351 automated tests (runs 100% offline via loopback mock fixtures)
npm test
# Enforce strict offline air-gap
SLOPGUARD_OFFLINE=1 npm test
# Compile TypeScript
npm run buildMIT
