A secure wrapper for npm, yarn, pnpm, and bun that prevents installation of compromised packages.

Built to counter supply chain attacks like the Shai-Hulud npm worm.

Supply chain attacks have surged dramatically in recent years, with the npm ecosystem being a prime target:

• Shai-Hulud npm worm (2024-2025): Infected hundreds of packages (~800) that steal credentials and self-replicate
• Popular free tools are reactive: npm audit and Dependabot scan AFTER installation - too late to prevent credential theft
• Malicious code executes: By the time vulnerabilities are detected, postinstall scripts have already run

Sentinel is a free, open-source, zero-dependency tool that intercepts package manager commands locally on your machine to block installation BEFORE download.

• Pre-install blocking - Validates packages BEFORE download, preventing malicious code execution
• ~800 compromised packages - Bundled blacklist covering Shai-Hulud worm and similar threats (as of 2025-01)
• Real-time vulnerability checks - OSV, GitHub Advisories, and optional Snyk integration
• Zero npm dependencies - Uses only Node.js built-ins (reduces supply-chain attack surface)
• Multi-package manager - Full support for npm, yarn, pnpm, and bun
• Transparent operation - Works via shell aliases, no workflow changes
• CI/CD ready - Scan lockfiles in automated pipelines
• Custom blacklists - Add organization-specific security policies

Note: Comparison based on publicly available information as of November 2024. Features and pricing may vary.

# Install from npm
npm install -g @dreamhorizonorg/sentinel

# Verify installation
sentinel status

# Set up shell aliases for automatic validation
sentinel add aliases

# Reload shell
source ~/.zshrc  # or ~/.bashrc

# (Optional) Create config file in your project
cd your-project
sentinel init

# Use normally - validation happens automatically
npm install package-name
yarn add package-name

# To uninstall later
sentinel remove aliases
npm uninstall -g @dreamhorizonorg/sentinel

# Install in your project
npm install --save-dev @dreamhorizonorg/sentinel

# Initialize config file
npx @dreamhorizonorg/sentinel init

# Use for scanning
npx @dreamhorizonorg/sentinel scan

# Clone and install
git clone https://github.com/ds-horizon/sentinel.git
cd sentinel
./bin/install.sh

# Reload shell
source ~/.zshrc  # or ~/.bashrc

# Use normally - validation happens automatically
npm install package-name
yarn add package-name

📖 For more options (CI/CD setup, advanced configuration), see the Usage Guide.

Developer: npm install package-name
    ↓
Sentinel intercepts (via shell alias)
    ↓
Validation BEFORE download:
    ├─ Local blacklist (~800 known malicious packages)
    ├─ OSV database (real-time)
    ├─ GitHub Advisories (real-time)
    └─ npm audit (optional fallback)
    ↓
    ├─ Compromised → BLOCK ❌
    └─ Safe → Install ✅

Example - Blocked package:

$ npm install malicious-package

⚠️  BLOCKED: malicious-package@1.2.3
    Reason: Shai-Hulud worm - credential theft
    Source: Local blacklist

Installation aborted. No packages were downloaded.

📖 For provider configuration, see docs/PROVIDERS.md. For data sources, see docs/DATA_SOURCES.md.

Note: Bun's binary lockfile (bun.lockb) is not supported. Use the text-based bun.lock format (default in Bun v1.2+) or run bun install --save-text-lockfile to migrate.

• Usage Guide - Complete command reference and examples
• Data Sources Guide - Configure blacklists, API endpoints, and providers
• Providers Guide - OSV, GitHub Advisories, Snyk setup
• Troubleshooting - Common issues, limitations, and solutions

Minimal impact:

• Local blacklist check: <10ms (in-memory lookup)
• Network providers (OSV, GitHub): ~100-500ms per package (parallelized)
• npm audit: Variable (npm's own performance)

For most installs: <1 second overhead. You can disable network checks with --skipNpmAudit=true --enableOsv=false --enableGitHub=false for faster scans using only the local blacklist.

Yes! Add to your CI pipeline:

- name: Install dependencies
  run: npm ci
  
- name: Scan for compromised packages
  run: npx @dreamhorizonorg/sentinel scan

This provides defense in depth: lockfiles + validation.

Sentinel checks multiple sources: local blacklist (~800 packages), OSV (100k+ vulnerabilities), GitHub Advisories, and npm audit (when scanning projects with lockfiles). If a zero-day package isn't in any database yet, add it to your custom blacklist or report it to the community.

The local blacklist contains specific compromised versions of packages. If you're using a different version that's not listed in the compromisedVersions array, the scan will pass. For example, if package-name@1.2.3 is marked as compromised but you're using package-name@1.2.4 (a patched version), Sentinel will allow the installation. Always ensure you're using a version that has been patched and verified as safe.

See Troubleshooting Guide for detailed information about:

• Alias bypass scenarios
• Shell and OS compatibility
• npm audit limitations
• Version matching behavior

No Telemetry: Sentinel itself sends zero telemetry and never uploads your dependency graph or package information. However, when using third-party vulnerability providers (OSV and GitHub Advisories), these services may collect API usage information including package names and versions queried. For complete privacy, you can disable network providers and use only the local blacklist with --enableOsv=false --enableGitHub=false.

Contributions are welcome! See CONTRIBUTING.md for guidelines.

MIT License - see LICENSE for details.

• Check Troubleshooting Guide
• Open an issue on GitHub