Usage Guide

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

📑 Table of Contents

Quick Start - Get up and running in minutes
Basic Commands - Essential commands you'll use daily
Scanning Packages - Validate packages before installation
Scanning Repositories - Check existing codebases
Configuration - Customize Sentinel for your needs
Shell Aliases - Automatic validation setup
CI/CD Integration - Use in automated pipelines
Advanced Usage - Power user features

New to Sentinel? Start with Quick Start.
Need help? See Troubleshooting.
Want to configure providers? See Providers Guide.

🚀 Quick Start

Option 1: npm Global Install (Recommended)

Best for: Individual developers, most use cases

Install from npm registry:

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

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

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

Then use:

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

# 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

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

# Just use npm/yarn/pnpm normally
npm install express
# ✅ Automatically validates before installing

With Dev Dependency:

# Install package normally
npm install express

# Then scan to check
npm run scan

Scenario 2: Checking Your Existing Project

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

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:

#!/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:

chmod +x .git/hooks/pre-commit

Scenario 5: Validating a Specific Package

# 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

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

# In your project directory
cd your-project
sentinel init

# Or using short alias
sentinel-pm init

What it does:

Creates sentinel.config.json in the current directory
Adds default configuration with helpful comments
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:

{
  // 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:

sentinel status
# or
sentinel-pm status

What it checks:

✅ Package installation and version
✅ Shell aliases configuration
✅ Config file presence and validity
✅ Security blacklist availability
✅ 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:

# After global npm install
sentinel add aliases

# Or using short alias
sentinel-pm add aliases

What it does:

Detects your shell (bash/zsh)
Adds aliases to your shell config file (.zshrc, .bashrc, .bash_profile)
Intercepts package manager commands (npm, yarn, pnpm, bun)
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:

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

sentinel remove aliases
# or
sentinel-pm remove aliases

What it does:

Detects your shell (bash/zsh)
Finds your shell config file (.zshrc, .bashrc, .bash_profile)
Removes all Sentinel Package Manager aliases
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:

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

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

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):

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:

{
  "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 for complete details on all three options.

Priority Order

For Blacklist Data (JSON/API):

dataSourcePath (if specified - file or folder, smart detection)
endpoint (if specified)
Default locations (root file pattern):
- ./config/compromised-packages.json (repo)
- ~/.sentinel/config/compromised-packages.json (user-wide)

For Vulnerability Detection: See Data Sources Guide for complete priority and conflict resolution details.

See Data Sources Guide for complete details.

Blacklist JSON Format

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

[
  {
    "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)

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

# 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

# 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

# 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

# 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

# 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 for complete provider setup and configuration.

🚨 What Happens When a Package is Blocked?

When you try to install a compromised package:

$ 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:

Check if a different version is safe
Find an alternative package
Contact your security team if you need an exception

🔄 Updating the Tool

User-Wide Installation

cd sentinel
git pull
./bin/install.sh

Dev Dependency

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

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

📚 More Information

Troubleshooting - Common issues and solutions
README - Quick start and overview

FilesExpand file tree

USAGE.md

Latest commit

History

USAGE.md

File metadata and controls

Usage Guide

📑 Table of Contents

🚀 Quick Start

Option 1: npm Global Install (Recommended)

Option 2: Dev Dependency (Recommended for Teams)

Option 3: Git Clone & Install (Manual Setup)

Option 4: Manual Local Installation (For Specific Projects)

📋 Common Usage Scenarios

Quick Reference

Scenario 1: Installing a New Package

Scenario 2: Checking Your Existing Project

Scenario 3: CI/CD Pipeline

Scenario 4: Pre-commit Hook

Scenario 5: Validating a Specific Package

Scenario 6: Listing All Compromised Packages

🔍 Command Reference

Available Commands

Command Options

init

status

add aliases

remove aliases

scan [target]

list

⚙️ Configuration

Quick Start

Basic Configuration

Configuration Options

Priority Order

Blacklist JSON Format

🎯 Real-World Examples

Example 1: New Developer Onboarding (Recommended)

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

Example 2: Team Project Setup

Example 3: Checking Before Production Deploy

Example 4: Validating a Suspicious Package

Example 5: Using Provider CLI Arguments

🚨 What Happens When a Package is Blocked?

🔄 Updating the Tool

User-Wide Installation

Dev Dependency

❓ Troubleshooting

"CLI script not found"

"Aliases not working"

"Validation always fails"

"npm audit takes too long"

💡 Tips

📚 More Information

`init`

`status`

`add aliases`

`remove aliases`

`scan [target]`

`list`