@dreamhorizonorg/sentinel/docs/USAGE.md

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

# Usage Guide

Complete guide for using Sentinel Package Manager in your daily workflow.

## 📑 Table of Contents

- [Quick Start](#-quick-start) - Get up and running in minutes
- [Basic Commands](#-basic-commands) - Essential commands you'll use daily
- [Scanning Packages](#-scanning-packages) - Validate packages before installation
- [Scanning Repositories](#-scanning-repositories) - Check existing codebases
- [Configuration](#-configuration) - Customize Sentinel for your needs
- [Shell Aliases](#-shell-aliases) - Automatic validation setup
- [CI/CD Integration](#cicd-integration) - Use in automated pipelines
- [Advanced Usage](#-advanced-usage) - Power user features

> **New to Sentinel?** Start with [Quick Start](#-quick-start).  
> Need help? See [Troubleshooting](TROUBLESHOOTING.md).  
> Want to configure providers? See [Providers Guide](PROVIDERS.md).

---

## 🚀 Quick Start

### Option 1: npm Global Install (Recommended)

**Best for:** Individual developers, most use cases

Install from npm registry:

```bash
# Install globally
npm install -g @dreamhorizonorg/sentinel

# Set up shell aliases for automatic validation
sentinel add aliases

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

# Done! Now use package managers normally
npm install express
yarn add axios
pnpm add react
```

**What happens:** The `add aliases` command adds aliases to your shell config that intercept package manager commands and validate packages before installation.

### Option 2: Dev Dependency (Recommended for Teams)

**Best for:** Team projects, CI/CD pipelines, project-specific security

Add to your project:

```bash
# Install as dev dependency
npm install --save-dev @dreamhorizonorg/sentinel
# or
yarn add -D @dreamhorizonorg/sentinel
# or
pnpm add -D @dreamhorizonorg/sentinel

# Initialize config file in your project
npx @dreamhorizonorg/sentinel init
```

Add to your `package.json` scripts:

```json
{
  "scripts": {
    "scan": "sentinel scan",
    "security-check": "sentinel scan",
    "check-package": "sentinel scan package.json",
    "check-lockfile": "sentinel scan package-lock.json"
  }
}
```

Then use:

```bash
# Scan your repository
npm run scan

# Check before committing
npm run security-check

# Check package.json
npm run check-package

# Check lockfile
npm run check-lockfile
```

### Option 3: Git Clone & Install (Manual Setup)

**Best for:** Development, contributing, or environments without npm registry access

Install once, use everywhere:

```bash
# Clone the repository
git clone https://github.com/ds-horizon/sentinel.git
cd sentinel

# Install user-wide
./bin/install.sh

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

# Done! Now use package managers normally
npm install express
yarn add axios
pnpm add react
```

**What happens:** Every `npm install`, `yarn add`, `pnpm add`, or `bun add` command automatically validates packages before installation.

### Option 4: Manual Local Installation (For Specific Projects)

**Best for:** Project-specific usage without installing globally

```bash
# Clone into your project
git clone https://github.com/ds-horizon/sentinel.git .sentinel

# Use directly
./.sentinel/bin/cli.mjs scan
./.sentinel/bin/cli.mjs scan package-name@1.2.3
```

---

## 📋 Common Usage Scenarios

### **Quick Reference**

| Scenario | Command | Description |
|----------|---------|-------------|
| **Install package** | `npm install package-name` | Auto-validates if aliases are set |
| **Scan repository** | `sentinel scan` | Scans entire repository |
| **Check package** | `sentinel scan package-name@1.0.0` | Validates specific package |
| **Check lockfile** | `sentinel scan package-lock.json` | Validates lockfile |
| **List blacklist** | `sentinel list` | Lists all compromised packages |
| **Check status** | `sentinel status` | Verifies installation |

---

### Scenario 1: Installing a New Package

**With User-Wide Installation:**
```bash
# Just use npm/yarn/pnpm normally
npm install express
# ✅ Automatically validates before installing
```

**With Dev Dependency:**
```bash
# Install package normally
npm install express

# Then scan to check
npm run scan
```

### Scenario 2: Checking Your Existing Project

```bash
# Scan entire repository
npx @dreamhorizonorg/sentinel scan

# Or if installed as dev dependency
npm run scan

# Check specific lockfile
npx @dreamhorizonorg/sentinel scan package-lock.json

# Check package.json
npx @dreamhorizonorg/sentinel scan package.json
```

### Scenario 3: CI/CD Pipeline

Add to your GitHub Actions workflow:

```yaml
name: Security Check

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Sentinel Package Manager
        run: npm install -g @dreamhorizonorg/sentinel
      
      - name: Check for compromised packages
        run: sentinel scan
```

### Scenario 4: Pre-commit Hook

Create `.git/hooks/pre-commit`:

```bash
#!/bin/bash
# Check package.json before commit
npx @dreamhorizonorg/sentinel scan package.json

if [ $? -ne 0 ]; then
  echo "❌ Security check failed. Commit blocked."
  exit 1
fi
```

Make it executable:
```bash
chmod +x .git/hooks/pre-commit
```

### Scenario 5: Validating a Specific Package

```bash
# Check if a package is safe before installing
npx @dreamhorizonorg/sentinel scan package-name@1.2.3

# Or with user-wide installation
~/.sentinel/bin/cli.mjs scan package-name@1.2.3
```

### Scenario 6: Listing All Compromised Packages

```bash
# See all packages in the blacklist
npx @dreamhorizonorg/sentinel list

# Output:
# 📋 Compromised Packages (~800):
# 1. get-them-args
#    Versions: 1.3.3, 1.3.4
# 2. kill-port
#    Versions: ALL VERSIONS
# ...
```

---

## 🔍 Command Reference

### **Available Commands**

| Command | Description | Usage |
|---------|-------------|-------|
| `scan [target]` | Scan for compromised packages | `sentinel scan [package\|lockfile\|package.json\|directory]` |
| `list` | List all compromised packages | `sentinel list` |
| `add aliases` | Add shell aliases for automatic validation | `sentinel add aliases` |
| `remove aliases` | Remove shell aliases | `sentinel remove aliases` |
| `status` | Check installation status | `sentinel status` |
| `init` | Initialize config file | `sentinel init` |
| `--version`, `-v` | Show version number | `sentinel --version` |
| `--help`, `-h` | Show help message | `sentinel --help` |

### **Command Options**

| Option | Description | Default | Example |
|--------|-------------|---------|---------|
| `--localDataSource=<path>` | Local file or folder path for blacklist | Auto-detect | `--localDataSource="./config/blacklist.json"` |
| `--remoteDataSource=<url>` | HTTP/HTTPS endpoint for blacklist | None | `--remoteDataSource="https://api.example.com/blacklist.json"` |
| `--skipNpmAudit=<true\|false>` | Skip npm audit checks | `false` | `--skipNpmAudit=true` |
| `--logMode=<mode>` | Output verbosity: `verbose` \| `normal` \| `quiet` | `normal` | `--logMode=verbose` |
| `--enableOsv=<true\|false>` | Enable/disable OSV provider | `true` | `--enableOsv=false` |
| `--enableGitHub=<true\|false>` | Enable/disable GitHub Advisories | `true` | `--enableGitHub=false` |
| `--githubToken=<token>` | GitHub API token (optional) | None | `--githubToken="ghp_..."` |
| `--enableSnyk=<true\|false>` | Enable/disable Snyk provider | `false` | `--enableSnyk=true` |
| `--snykToken=<token>` | Snyk API token (required if enabling) | None | `--snykToken="..."` |

---

### `init`

Initialize a configuration file (`sentinel.config.json`) in your current directory.

**Usage:**
```bash
# In your project directory
cd your-project
sentinel init

# Or using short alias
sentinel-pm init
```

**What it does:**
1. Creates `sentinel.config.json` in the current directory
2. Adds default configuration with helpful comments
3. Shows available configuration options

**Example output:**
```
🚀 Sentinel Package Manager - Initialize Configuration

✅ Configuration file created successfully!

Created file:
   /path/to/your-project/sentinel.config.json

📋 Default Configuration:

   {
     "skipNpmAudit": false,
     "logMode": "normal"
   }

⚙️  Configuration Options:

   skipNpmAudit - Skip npm audit checks (default: false)
   logMode      - Output verbosity: "verbose" | "normal" | "quiet"
   dataSourcePath - Local file/folder path for custom blacklist
   endpoint    - HTTP/HTTPS URL for custom blacklist
   providers   - Vulnerability provider configuration (OSV, GitHub, Snyk)
                See [Providers Guide](PROVIDERS.md) for details

📝 Next Steps:

   1. Edit the config file to customize behavior:
      nano sentinel.config.json

   2. Run scan to test your configuration:
      sentinel scan

   3. (Optional) Set up shell aliases for automatic validation:
      sentinel add aliases
```

**Created file content:**
```json
{
  // Skip npm audit checks (faster, but less secure)
  // Default: false
  "skipNpmAudit": false,

  // Output verbosity: "verbose" | "normal" | "quiet"
  // - verbose: detailed output with all messages
  // - normal: standard output (default)
  // - quiet: minimal output (errors only)
  "logMode": "normal"

  // Optional: Local file or folder path for custom blacklist
  // "dataSourcePath": "./config/compromised-packages.json",

  // Optional: HTTP/HTTPS endpoint for custom blacklist
  // "endpoint": "https://example.com/api/compromised-packages.json"
}
```

**Note:** If `sentinel.config.json` already exists, the command will skip creation to avoid overwriting your existing configuration.

---

### `status`

Check installation status and verify configuration.

**Usage:**
```bash
sentinel status
# or
sentinel-pm status
```

**What it checks:**
1. ✅ Package installation and version
2. ✅ Shell aliases configuration
3. ✅ Config file presence and validity
4. ✅ Security blacklist availability
5. ✅ Wrapper script integrity

**Example output:**
```
🔍 Sentinel Package Manager - Status Check

📦 Package Installation:
   ✅ Installed: v1.0.0

🔗 Shell Aliases:
   ✅ Aliases configured in /Users/you/.zshrc
      - npm, yarn, pnpm, bun aliases active

⚙️  Configuration:
   ✅ Local config found: /path/to/project/sentinel.config.json
      - logMode: normal
      - skipNpmAudit: false

🛡️  Security Blacklist:
   ✅ Blacklist loaded: ~800 compromised packages

🔧 Wrapper Script:
   ✅ Wrapper script found
      Location: /usr/local/lib/node_modules/sentinel/bin/sentinel.sh

════════════════════════════════════════════════════════════

✅ Everything looks good! Sentinel Package Manager is ready.

💡 Quick Commands:

   sentinel add aliases  # Set up shell aliases
   sentinel init             # Create config file
   sentinel scan             # Scan repository
   sentinel list             # List compromised packages
```

**When to use:**
- After installation to verify everything is set up correctly
- When troubleshooting issues
- To check if aliases are installed
- To verify blacklist is loaded

---

### `add aliases`

Install shell aliases (npm, yarn, pnpm, bun) for automatic package validation.

**Usage:**
```bash
# After global npm install
sentinel add aliases

# Or using short alias
sentinel-pm add aliases
```

**What it does:**
1. Detects your shell (bash/zsh)
2. Adds aliases to your shell config file (`.zshrc`, `.bashrc`, `.bash_profile`)
3. Intercepts package manager commands (npm, yarn, pnpm, bun)
4. Automatically validates packages before installation

**Example output:**
```
🔧 Sentinel Package Manager - Install Shell Aliases

This command will:
  1. Detect your shell (bash/zsh)
  2. Add aliases to your shell config file (.zshrc, .bashrc, etc.)
  3. Intercept npm/yarn/pnpm/bun commands for automatic validation

📋 Detected shell: zsh
📄 Config file: /Users/yourname/.zshrc

✅ Shell aliases installed successfully!

Created aliases:
   npm  → Validates packages before npm install/add
   yarn → Validates packages before yarn add
   pnpm → Validates packages before pnpm add
   bun  → Validates packages before bun add

📝 Next Steps:
   1. Reload your shell to activate aliases:
      source /Users/yourname/.zshrc
```

**After installation:**
```bash
# Reload your shell
source ~/.zshrc  # or ~/.bashrc

# Now use package managers normally - validation is automatic!
npm install express    # ✅ Automatically validated
yarn add axios         # ✅ Automatically validated
pnpm add react         # ✅ Automatically validated
```

---

### `remove aliases`

Remove shell aliases from your shell configuration.

**Usage:**
```bash
sentinel remove aliases
# or
sentinel-pm remove aliases
```

**What it does:**
1. Detects your shell (bash/zsh)
2. Finds your shell config file (`.zshrc`, `.bashrc`, `.bash_profile`)
3. Removes all Sentinel Package Manager aliases
4. Provides instructions to reload your shell

**Example output:**
```
🗑️  Sentinel Package Manager - Uninstall Shell Aliases

📋 Detected shell: zsh
📄 Config file: /Users/you/.zshrc

✅ Shell aliases removed successfully!

Removed from:
   /Users/you/.zshrc

Removed 5 line(s)

📝 Next Steps:

   1. Reload your shell to apply changes:
      source /Users/you/.zshrc

   2. Or open a new terminal

   3. (Optional) Uninstall the package:
      npm uninstall -g @dreamhorizonorg/sentinel

💡 Your package managers (npm, yarn, pnpm, bun) will now work normally without validation.
```

**When to use:**
- Before uninstalling the package
- When disabling automatic validation
- When troubleshooting alias conflicts
- When switching to manual scanning only

**Complete uninstall flow:**
```bash
# 1. Remove aliases
sentinel remove aliases

# 2. Reload shell
source ~/.zshrc

# 3. Uninstall package
npm uninstall -g @dreamhorizonorg/sentinel
```

---

### `scan [target]`

Unified scan command that intelligently detects the target type.

**Scan Targets:**

| Target | Description | Example |
|--------|-------------|---------|
| No argument | Scans entire repository | `sentinel scan` |
| Package spec | Scans single package | `sentinel scan express@4.18.0` |
| Lockfile | Scans lockfile | `sentinel scan package-lock.json` |
| package.json | Scans package.json | `sentinel scan package.json` |
| Directory | Scans directory recursively | `sentinel scan ./path/to/repo` |

**Examples:**

```bash
# Scan entire repository (no argument)
npx @dreamhorizonorg/sentinel scan

# Scan a single package
npx @dreamhorizonorg/sentinel scan express@4.18.0
npx @dreamhorizonorg/sentinel scan @scope/package@1.0.0

# Scan lockfile
npx @dreamhorizonorg/sentinel scan package-lock.json
npx @dreamhorizonorg/sentinel scan yarn.lock
npx @dreamhorizonorg/sentinel scan pnpm-lock.yaml
npx @dreamhorizonorg/sentinel scan bun.lock

# Scan package.json
npx @dreamhorizonorg/sentinel scan package.json
npx @dreamhorizonorg/sentinel scan ./path/to/package.json

# Scan specific directory
npx @dreamhorizonorg/sentinel scan ./path/to/repo

# With options
npx @dreamhorizonorg/sentinel scan --logMode=verbose
npx @dreamhorizonorg/sentinel scan express --enableOsv=false
npx @dreamhorizonorg/sentinel scan express --enableSnyk=true --snykToken="..."
```

### `list`

List all compromised packages:

```bash
npx @dreamhorizonorg/sentinel list

# Or with global install
sentinel list
```

**Example output:**
```
📋 Compromised Packages (~800):

1. get-them-args
   Versions: 1.3.3, 1.3.4

2. kill-port
   Versions: ALL VERSIONS

3. @pkg/malicious
   Versions: 1.0.0, 1.0.1, 1.0.2
...
```

---

## ⚙️ Configuration

You can create a configuration file (`sentinel.config.json`) to customize Sentinel Package Manager's behavior. The config file is automatically detected and loaded when you run commands.

### Quick Start

**Recommended: Use the `init` command** (creates config file automatically):
```bash
cd your-project
sentinel init
```

This creates `sentinel.config.json` with helpful comments and default values.

**Alternative config file names:**
- `sentinel.config.json` (recommended)
- `.sentinelrc`
- `.sentinelrc.json`

### Basic Configuration

For simple use cases, you only need:

```json
{
  "skipNpmAudit": false,
  "logMode": "normal"
}
```

### Configuration Options

**Configuration Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dataSourcePath` | String | Auto-detect | Local file or folder path for blacklist |
| `endpoint` | String | None | HTTP/HTTPS URL for blacklist API |
| `skipNpmAudit` | Boolean | `false` | Skip npm audit checks |
| `logMode` | String | `"normal"` | Output verbosity: `"verbose"` \| `"normal"` \| `"quiet"` |
| `providers.osv.enabled` | Boolean | `true` | Enable/disable OSV provider |
| `providers.osv.timeout` | Number | `5000` | OSV API timeout (ms) |
| `providers.github.enabled` | Boolean | `true` | Enable/disable GitHub Advisories |
| `providers.github.token` | String | `null` | GitHub API token (optional) |
| `providers.github.timeout` | Number | `5000` | GitHub API timeout (ms) |
| `providers.snyk.enabled` | Boolean | `false` | Enable/disable Snyk provider |
| `providers.snyk.token` | String | `null` | Snyk API token (required if enabled) |

**Data Source Options:**

| Source | Config Key | Priority | Description |
|--------|------------|----------|-------------|
| **Local JSON Files** | `dataSourcePath` | 1st | Local file or folder path (smart detection) |
| **API Endpoints** | `endpoint` | 2nd | HTTP/HTTPS URL returning JSON array |
| **Vulnerability Providers** | `providers.*` | 3rd | Real-time databases (OSV, GitHub, Snyk) |

**Log Mode Options:**

| Mode | Description | Use Case |
|------|-------------|----------|
| `verbose` | Detailed output with all messages | Debugging, troubleshooting |
| `normal` | Standard output (default) | Daily use |
| `quiet` | Minimal output (errors only) | CI/CD, scripts |

**See [Data Sources Guide](DATA_SOURCES.md) for complete details on all three options.**

### Priority Order

**For Blacklist Data (JSON/API):**
1. `dataSourcePath` (if specified - file or folder, smart detection)
2. `endpoint` (if specified)
3. Default locations (root file pattern):
   - `./config/compromised-packages.json` (repo)
   - `~/.sentinel/config/compromised-packages.json` (user-wide)

**For Vulnerability Detection:** See [Data Sources Guide](DATA_SOURCES.md#priority--conflict-resolution) for complete priority and conflict resolution details.

**See [Data Sources Guide](DATA_SOURCES.md) for complete details.**

### Blacklist JSON Format

The blacklist file (`compromised-packages.json`) uses this format:

```json
[
  {
    "name": "malicious-package",
    "compromisedVersions": ["1.0.0", "1.0.1"],
    "notes": "Shai-Hulud worm"
  },
  {
    "name": "another-package",
    "compromisedVersions": [],
    "notes": "All versions compromised"
  }
]
```

Configuration files are automatically detected from:
- `sentinel.config.json`
- `sentinel.config.js`
- `sentinel.config.mjs`
- `.sentinelrc`
- `.sentinelrc.json`
- `.sentinelrc.js`
- `.sentinelrc.mjs`

---

## 🎯 Real-World Examples

### Example 1: New Developer Onboarding (Recommended)

```bash
# 1. Install globally from npm
npm install -g @dreamhorizonorg/sentinel

# 2. Set up shell aliases
sentinel add aliases
source ~/.zshrc

# 3. Start using package managers normally
npm install
yarn add some-package
# ✅ All packages automatically validated!
# ✅ OSV + GitHub Advisories run automatically (no config needed)
```

### Example 1 (Alternative): New Developer Onboarding (Git Clone)

```bash
# 1. Clone the tool
git clone https://github.com/ds-horizon/sentinel.git
cd sentinel

# 2. Install user-wide
./bin/install.sh
source ~/.zshrc

# 3. Start using package managers normally
npm install
yarn add some-package
# ✅ All packages automatically validated!
```

### Example 2: Team Project Setup

```bash
# 1. Add to project
npm install --save-dev @dreamhorizonorg/sentinel

# 2. Add scripts to package.json
# (see Option 2 above)

# 3. Team members can now run
npm run scan
npm run security-check
```

### Example 3: Checking Before Production Deploy

```bash
# Before deploying, scan the entire repo
npx @dreamhorizonorg/sentinel scan

# If issues found, fix them
# Then deploy with confidence
```

### Example 4: Validating a Suspicious Package

```bash
# Someone suggests installing a package
# Check it first:
npx @dreamhorizonorg/sentinel scan suspicious-package@1.0.0

# If blocked, find an alternative
```

### Example 5: Using Provider CLI Arguments

```bash
# Disable OSV provider
sentinel scan package-name --enableOsv=false

# Disable GitHub provider
sentinel scan package-name --enableGitHub=false

# Enable Snyk with token
sentinel scan package-name --enableSnyk=true --snykToken="your-token"

# Add GitHub token for higher rate limits (optional)
sentinel scan package-name --githubToken="ghp_..."

# Combine multiple options
sentinel scan package-name --enableOsv=false --logMode=verbose
```

**Note:** See [Providers Guide](PROVIDERS.md) for complete provider setup and configuration.

---

## 🚨 What Happens When a Package is Blocked?

When you try to install a compromised package:

```bash
$ npm install get-them-args@1.3.3

🔍 Validating packages against security blacklist...
❌ BLOCKED: Package "get-them-args@1.3.3" is compromised!
⚠️  This specific version has known security vulnerabilities.
   Please use a different version or an alternative package.

╔════════════════════════════════════════════════════════════════╗
║                    INSTALLATION BLOCKED                       ║
╚════════════════════════════════════════════════════════════════╝

❌ The following package(s) are compromised and cannot be installed:
   • get-them-args@1.3.3

⚠️  Security Policy: Compromised packages are blocked to prevent
   security vulnerabilities and supply chain attacks.

💡 Alternatives:
   • Use a different version of the package
   • Find an alternative package
   • Contact the security team for exceptions
```

**What to do:**
1. Check if a different version is safe
2. Find an alternative package
3. Contact your security team if you need an exception

---

## 🔄 Updating the Tool

### User-Wide Installation
```bash
cd sentinel
git pull
./bin/install.sh
```

### Dev Dependency
```bash
npm update @dreamhorizonorg/sentinel
# or
yarn upgrade @dreamhorizonorg/sentinel
```

---

## ❓ Troubleshooting

### "CLI script not found"
- Re-run the installation script
- Check if `~/.sentinel/bin/cli.mjs` exists

### "Aliases not working"
- Reload your shell: `source ~/.zshrc` or `source ~/.bashrc`
- Check if aliases are in your shell config file

### "Validation always fails"
- Check if JSON file exists: `ls ~/.sentinel/config/compromised-packages.json`
- Update the tool to get latest blacklist

### "npm audit takes too long"
- Add to config: `{ "skipNpmAudit": true }`
- Note: This disables npm audit checks but still validates against blacklist

---

## 💡 Tips

1. **Use user-wide installation** for personal development
2. **Use dev dependency** for team projects
3. **Add to CI/CD** to catch issues early
4. **Run `scan` regularly** to check your dependencies
5. **Keep the tool updated** to get latest security data

---

## 📚 More Information

- [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions
- [README](../README.md) - Quick start and overview