Sentinel-AI

A CLI tool to prevent AI slopsquatting (hallucinated package imports) and detect general vulnerabilities in your codebase.

Features

• AI Hallucination Detection — catches imports of packages that do not exist on npm
• Shadow Code Detection — flags packages used in imports but missing from package.json
• Typosquatting Detection — detects packages with names suspiciously similar to popular ones (e.g., lodah vs lodash)
• Vulnerability Scan — checks all packages against the OSV database (single batch request)
• Malicious Package Alerts — warns on packages with known malware (MAL-* entries)
• Package Age Check — flags suspiciously new packages (< 72 hours on npm)
• Pre-Install Guard — intercepts npm install to block hallucinated or vulnerable packages before they reach your disk
• Node.js Built-in Filter — ignores fs, path, crypto, node:fs, node:path, and other runtime modules
• Concurrent Requests — configurable parallelism + retry with exponential backoff

Quick Start

Install as a dependency (recommended)

npm i @moriito/sentinel-ai

# Basic scan
npx sentinel

# Full vulnerability scan
npx sentinel --deep

Local development

git clone https://github.com/MoriitoDev/sentinel-ai.git
cd sentinel-ai
npm install

npm run scan
npm run scan:deep

CLI Reference

| Flag | Alias | Description | Default | |------|-------|-------------|---------| | --deep | -d | Enable full scanning (age + vulns + transitive deps + typosquatting) | off | | --concurrency | -c | Max parallel requests to npm | 5 | | --include-dev | -i | Include dev-only transitive deps in deep mode | off | | --output | -o | Save report to file (plain text or JSON, console still shows) | — | | --format | -f | Output format: text (ANSI) or json | text | | --verbose | -v | Enable debug logging | off | | --typosquatting-threshold | — | Similarity threshold for typosquatting (0-1) | 0.85 | | --refresh-popular-packages | — | Force refresh of popular packages cache | off |

Standard mode

Only checks for hallucinations and shadow code:

# Via npm dependency
npx sentinel

# Or locally: npm run scan

Deep mode

Adds age checks and OSV vulnerability scanning for all packages:

# Via npm dependency
npx sentinel --deep

# Or locally: npm run scan:deep
npx tsx src/main.ts --deep --concurrency 10

Output

────────────────────────────────────────────────────────
 Sentinel Report  — 4 packages, 860ms, deep mode
────────────────────────────────────────────────────────

 AI HALLUCINATIONS (1)
   ai-slopsquatting         ← not found on npm

 SHADOW CODE (1)
   @swc

 TYPO SQUATTING SUSPECTS (2)
   expres                   ← similar to express (86%)
   lodah                    ← similar to lodash (83%)

 VULNERABILITIES (0)

 CLEAN (2)
   @swc
   fast-glob            v3.3.3

────────────────────────────────────────────────────────

Output to file

# Default text report (no ANSI codes)
npx sentinel --output report.txt

# JSON report
npx sentinel --deep --format json --output report.json

The console always shows the colorized output. The file receives a clean copy.

Configuration file

Create .sentinelrc.json in the project root to set defaults:

{
  "concurrency": 10,
  "includeDev": true,
  "outputFormat": "json",
  "typosquatting": {
    "enabled": true,
    "threshold": 0.85,
    "minPackageLength": 3
  }
}

CLI flags always override config file values.

Typosquatting Detection

Typosquatting detection uses the Levenshtein distance algorithm to compare package names against a curated list of the 500 most popular npm packages. When a package name is suspiciously similar (default: 85% similarity) to a popular package, it's flagged as a potential typosquatting attempt.

Popular packages are cached in .sentinel/popular-packages.json for 24 hours. Use --refresh-popular-packages to force a refresh.

Documentation

Full documentation is available as a VitePress site. To run it locally:

npm run docs:dev

Or browse the markdown source in docs/.

How it works

1. Scans source files with SWC AST parser
2. Reads package.json for declared dependencies and package-lock.json for exact versions
3. Fetches npm registry metadata in parallel (configurable concurrency)
4. Queries OSV vulnerability database in a single batch request (including transitive deps)
5. Reports findings grouped into Hallucinations, Shadow Code, Vulnerabilities, Transitive Vulnerabilities, and Clean

License

MIT