Skip to content
SubakizPublic

About

Pre-install firewall against hallucinated packages and typosquats in npm and PyPI

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SlopGuard

Pre-install firewall against hallucinated packages and typosquats in npm and PyPI.

Build Status Tests License: MIT Node

Run it with npx:

npx slopguard guard npm install <package>

The problem

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.


Terminal demo

SlopGuard Terminal Demo

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

Quickstart

Run directly without installing:

npx slopguard guard npm install <pkg>

Or install globally:

npm install -g slopguard

Shell aliases

Add 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"

Commands

SlopGuard has three commands: guard (runtime wrapper), scan (manifest checker), and check-pr (diff analyzer for CI).

1. slopguard guard <command...>

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

Flags

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.

2. slopguard scan [target]

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

Flags

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.

3. slopguard check-pr [diffFile]

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 --strict

Detection heuristics

SlopGuard 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     │
                  └───────────────────────────┘

Heuristic vectors

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 $\le 1$, separator collisions (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

Risk score ranges

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 codes

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.

GitHub Actions

SlopGuard outputs OASIS SARIF 2.1.0, uploading findings directly to GitHub Code Scanning.

Workflow: .github/workflows/slopguard.yml

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

Air-gapped environments and private registries

  • Offline mode: Use --offline or export SLOPGUARD_OFFLINE=1 for 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.

Tests

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 build

License

MIT

About

Pre-install firewall against hallucinated packages and typosquats in npm and PyPI

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages