@dreamhorizonorg/sentinel

Sentinel Package Manager

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.

🚨 Why This Exists

The Problem: Supply Chain Attacks Are Rising

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

The Solution: Pre-Install Blocking

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

✨ Key Features

• 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

What Makes It Unique

Feature	npm audit	Snyk (free)	Dependabot	Socket.dev	Phylum.io	Sentinel
Blocks before download	❌	❌	N/A	⚠️ Platform	⚠️ Platform	✅ Local-only
No SaaS/account required	✅	❌	N/A	⚠️ Free tier	⚠️ Free tier	✅
Shell alias integration	❌	❌	N/A	❌	❌	✅
Multi-PM (npm/yarn/pnpm/bun)	❌	✅	❌	⚠️ npm focus	⚠️ varies	✅
Zero npm dependencies	✅	❌	N/A	❌	❌	✅
Open source	✅	❌	Partial	❌	❌	✅
Cost	Free	Freemium	Free	Freemium	Freemium	Free
Transparent (no workflow changes)	✅	❌	✅	⚠️ varies	⚠️ varies	✅

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

🚀 Quick Start

Installation Methods

Method	Best For	Command
npm Global	Individual developers	npm install -g @dreamhorizonorg/sentinel
Dev Dependency	Team projects, CI/CD	npm install --save-dev @dreamhorizonorg/sentinel
Git Clone	Development, contributing	git clone https://github.com/ds-horizon/sentinel.git && cd sentinel && ./bin/install.sh

Option 1: npm Global Install (Recommended)

# 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

Option 2: Dev Dependency (Project-Level)

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

# Initialize config file
npx @dreamhorizonorg/sentinel init

# Use for scanning
npx @dreamhorizonorg/sentinel scan

Option 3: Git Clone & Install (Manual Setup)

# 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.

🔄 How It Works

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.

📋 Supported Package Managers

Package Manager	Support	Auto-Validation	Lockfile Scanning
npm	✅ Full	✅ Yes	✅ package-lock.json
yarn	✅ Full	✅ Yes	✅ yarn.lock (v1 + v4)
pnpm	✅ Full	✅ Yes	✅ pnpm-lock.yaml (v5 + v6)
bun	✅ Full	✅ Yes	✅ bun.lock (v1.2+)

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.

📚 Documentation

• 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

❓ FAQ

Does Sentinel slow down installs?

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.

Can I use Sentinel in CI/CD?

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.

What if a package isn't in your blacklist yet?

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.

What if a package version is fixed?

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.

What are the limitations?

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.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🆘 Support

• Check Troubleshooting Guide
• Open an issue on GitHub