feat: rename to @horizoneng/sentinel and streamline documentation

- Package renamed to @horizoneng/sentinel (private for initial NPM publish)
- README restructured for better reading flow
- Removed duplications across documentation
- Consolidated DATA_SOURCES.md priority tables

Author: Prince Tripathi

.npmignore

@@ -0,0 +1,40 @@
+# Test files
+sample-test-repo/
+tests/
+
+# GitHub specific
+.github/
+
+# Development files
+.cursorrules
+.cursorignore
+.gitignore
+
+# Contributing docs (GitHub only)
+CONTRIBUTING.md
+SECURITY.md
+CODE_OF_CONDUCT.md
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Temporary files
+*.zip
+temp.*
+test-*.json
+test-*.lock
+

README.md

@@ -2,38 +2,47 @@
 
 **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 increased **742%** in the past 3 years. The npm ecosystem is a prime target:
+Supply chain attacks have surged dramatically in recent years, with the npm ecosystem being a prime target:
 
-- **Shai-Hulud npm worm (2024-2025)**: Infected 795+ packages that steal credentials and self-replicate
-- **Existing tools are reactive**: `npm audit`, Snyk, and Dependabot scan **AFTER** installation - too late
+- **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
-- **No pre-install blocking**: No tool prevents compromised packages from being installed
 
 ### The Solution: Pre-Install Blocking
 
-Sentinel Package Manager is the **ONLY tool** that blocks compromised packages **BEFORE** installation:
+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
 
-- ✅ **Intercepts** package manager commands (`npm install`, `yarn add`, etc.)
-- ✅ **Validates** packages against blacklists and vulnerability databases **BEFORE** download
-- ✅ **Blocks** installation if compromised - malicious code never executes
-- ✅ **Works automatically** - transparent to developers, no learning curve
-- ✅ **Zero dependencies** - uses only Node.js built-ins (maximum security)
+- **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 | Dependabot | Sentinel |
-|---------|-----------|------|------------|----------|
-| **Pre-install blocking** | ❌ | ❌ | ❌ | ✅ |
-| **Command interception** | ❌ | ❌ | ❌ | ✅ |
-| **Custom blacklist** | ❌ | ❌ | ❌ | ✅ |
-| **Real-time providers** | ❌ | ❌ | ❌ | ✅ |
-| **Zero dependencies** | ❌ | ❌ | ❌ | ✅ |
+| 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 | ✅ |
 
-**Built to counter supply chain attacks like the Shai-Hulud npm worm and similar threats.**
+> **Note:** Comparison based on publicly available information as of November 2024. Features and pricing may vary.
 
 ---
 
@@ -43,16 +52,16 @@ Sentinel Package Manager is the **ONLY tool** that blocks compromised packages *
 
 | Method | Best For | Command |
 |--------|----------|---------|
-| **npm Global** | Individual developers | `npm install -g sentinel` |
-| **Dev Dependency** | Team projects, CI/CD | `npm install --save-dev sentinel` |
+| **npm Global** | Individual developers | `npm install -g @horizoneng/sentinel` |
+| **Dev Dependency** | Team projects, CI/CD | `npm install --save-dev @horizoneng/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 sentinel
+npm install -g @horizoneng/sentinel
 
 # Verify installation
 sentinel status
@@ -73,19 +82,19 @@ yarn add package-name
 
 # To uninstall later
 sentinel remove aliases
-npm uninstall -g sentinel
+npm uninstall -g @horizoneng/sentinel
 ```
 
 ### Option 2: Dev Dependency (Project-Level)
 ```bash
 # Install in your project
-npm install --save-dev sentinel
+npm install --save-dev @horizoneng/sentinel
 
 # Initialize config file
-npx sentinel init
+npx @horizoneng/sentinel init
 
 # Use for scanning
-npx sentinel scan
+npx @horizoneng/sentinel scan
 ```
 
 ### Option 3: Git Clone & Install (Manual Setup)
@@ -103,15 +112,41 @@ npm install package-name
 yarn add package-name
 ```
 
-## 🛡️ What It Does
+> **📖 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
 
-- ✅ **Intercepts** package manager commands before installation
-- ✅ **Validates** packages against a blacklist of 795+ known compromised packages (Shai-Hulud worm)
-- ✅ **Checks** vulnerability providers (OSV, GitHub Advisories, Snyk) for real-time vulnerability data
-- ✅ **Checks** npm audit for additional vulnerabilities
-- ✅ **Blocks** installation if compromised
-- ✅ **Auto-updates** blacklist when new threats detected
-- ✅ **Scans** entire repositories for compromised dependencies
+⚠️  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
 
@@ -124,55 +159,55 @@ yarn add package-name
 
 > **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.
 
-## ✨ Key Features
+---
 
-### Security
-- **Pre-install blocking** - Validates packages BEFORE installation, preventing malicious code execution
-- **795+ compromised packages** - Bundled blacklist covering Shai-Hulud worm and similar threats
-- **Real-time vulnerability checks** - Integrates with OSV, GitHub Advisories, and Snyk (runs automatically)
-- **Zero dependencies** - Uses only Node.js built-ins (maximum security, zero attack surface)
-- **Auto-updates** - Automatically adds new vulnerabilities to blacklist from npm audit and providers
+## 📚 Documentation
 
-### Developer Experience
-- **Transparent operation** - Use package managers normally, validation happens automatically
-- **All package managers** - Full support for npm, yarn, pnpm, and bun
-- **Flexible deployment** - User-wide or per-repository installation
-- **Clear error messages** - Explains exactly why installation was blocked
-- **Multiple data sources** - Local JSON files, API endpoints, or vulnerability providers
+- **[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
 
-### Enterprise Ready
-- **Company-wide protection** - User-wide installation for organization-wide security
-- **Custom blacklists** - Support for company-specific security policies
-- **CI/CD integration** - Works seamlessly in automated pipelines
-- **Comprehensive scanning** - Repository-wide analysis with recursive package.json scanning
+---
 
-## 📚 Documentation
+## ❓ FAQ
 
-- **[Usage Guide](docs/USAGE.md)** - Complete command reference and examples
-- **[Data Sources Guide](docs/DATA_SOURCES.md)** - Three ways to get vulnerability data (JSON files, API endpoints, providers)
-- **[Providers Guide](docs/PROVIDERS.md)** - Vulnerability providers (OSV, GitHub, Snyk) configuration
-- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+### Does Sentinel slow down installs?
 
-## 🔄 How It Works
+**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 @horizoneng/sentinel scan
 ```
-Developer: npm install package-name
-    ↓
-Wrapper: Intercepts command
-    ↓
-Validation: Checks blacklist + providers (OSV, GitHub, Snyk) + npm audit
-    ↓
-    ├─ Compromised → BLOCK ❌
-    └─ Safe → Install ✅
-```
 
-**Providers run automatically out of the box:**
+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 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
 
-| Provider | Default | Token Required | Rate Limit |
-|----------|---------|----------------|------------|
-| **OSV** | ✅ Enabled | ❌ No | High |
-| **GitHub Advisories** | ✅ Enabled | ⚠️ Optional | 60/hour (public), 5000/hour (with token) |
-| **Snyk** | ❌ Disabled | ✅ Required | High |
+**No Telemetry:** Sentinel sends zero telemetry and never uploads your dependency graph or package information.
 
 ## 🤝 Contributing