@dreamhorizonorg/sentinel/README.md

Open-source, zero-dependency tool that blocks compromised packages BEFORE download. Built to counter supply chain and credential theft attacks like Shai-Hulud.

# 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)
```bash
# 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)
```bash
# 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)
```bash
# 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](docs/USAGE.md).

---

## 🔄 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:**
```bash
$ 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](docs/PROVIDERS.md). For data sources, see [docs/DATA_SOURCES.md](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](docs/USAGE.md)** - Complete command reference and examples
- **[Data Sources Guide](docs/DATA_SOURCES.md)** - Configure blacklists, API endpoints, and providers
- **[Providers Guide](docs/PROVIDERS.md)** - OSV, GitHub Advisories, Snyk setup
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - 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:

```yaml
- 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](docs/DATA_SOURCES.md) 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](docs/TROUBLESHOOTING.md) 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](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🆘 Support

- Check [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
- Open an issue on GitHub