@dreamhorizonorg/sentinel/docs/TROUBLESHOOTING.md

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

# Troubleshooting

Common issues and solutions for Sentinel Package Manager.

## 📑 Table of Contents

- [Aliases Not Working](#aliases-not-working) - Shell aliases not triggering
- [Commands Bypassing Sentinel](#commands-bypassing-sentinel) - Validation not running
- [CLI Script Not Found](#cli-script-not-found-error) - Installation issues
- [Validation Always Fails](#validation-always-fails) - Packages always blocked
- [npm audit Takes Too Long](#npm-audit-takes-too-long) - Performance issues
- [Provider Errors](#provider-errors) - OSV, GitHub, Snyk issues
- [Configuration Issues](#configuration-issues) - Config file problems

> **Need help?** Check [Usage Guide](USAGE.md) for detailed commands.  
> **Provider issues?** See [Providers Guide](PROVIDERS.md).

---

## Common Issues

### Aliases Not Working

**Problem:** Package manager commands don't trigger validation.

**Solution:**
```bash
# Check if aliases are set
grep "sentinel" ~/.zshrc  # or ~/.bashrc

# If not found, reinstall
./bin/install.sh
source ~/.zshrc  # or ~/.bashrc
```

### Commands Bypassing Sentinel

**Problem:** Validation not running even though aliases are set.

**Common causes:**
- **Absolute paths**: `/usr/bin/npm install` or `/usr/local/bin/yarn add` (bypasses alias)
- **IDE integrations**: VS Code, WebStorm, or other IDE package installers don't use shell aliases
- **Corepack**: `corepack enable` then `corepack npm install`
- **Bunx**: `bunx <package>` (use `bun add` instead)
- **Direct binary execution**: Running package managers without aliases
- **Non-interactive shells**: Shells that don't load `.zshrc`/`.bashrc`

**Solution:**
- Always use the aliased commands (`npm`, `yarn`, `pnpm`, `bun`) after running `sentinel add aliases`
- For CI/CD, use `npx @dreamhorizonorg/sentinel scan` explicitly
- Check shell config is loaded: `echo $PATH` should include Sentinel's bin directory
- Avoid using absolute paths to package manager binaries

### Shell & OS Compatibility Issues

**Problem:** Sentinel not working on your system.

**Supported:**
- **Shells**: bash, zsh (fully supported)
- **OS**: macOS, Linux (fully supported)

**Limited Support:**
- **Windows**: PowerShell support may vary (use WSL recommended)
- **Fish shell**: Not officially supported (may work with manual alias setup)

**Solution:**
- Use bash or zsh for best compatibility
- On Windows, use WSL (Windows Subsystem for Linux)
- For fish shell, manually add aliases to `~/.config/fish/config.fish`

### npm audit Not Working

**Problem:** `npm audit` checks are not running or showing errors.

**Limitations:**
- `npm audit` only works when scanning directories/repositories with `package.json` + lockfile
- `npm audit` **does not work** for standalone package scans (e.g., `sentinel scan react@18.0.0`)
- Requires npm to be installed and accessible

**Solution:**
- For standalone packages, rely on OSV and GitHub Advisories providers
- For project scanning, ensure `package.json` and a lockfile exist in the directory
- If `npm audit` is causing issues, disable it: `{ "skipNpmAudit": true }` in config

### "CLI script not found" Error

**Problem:** Wrapper script can't find the CLI.

**Solution:**
```bash
# Check if installation exists
ls -la ~/.sentinel/bin/cli.mjs

# If missing, reinstall
./bin/install.sh
```

### Validation Always Fails

**Problem:** All packages are being blocked.

**Solution:**
```bash
# Check JSON file exists
ls -la ~/.sentinel/config/compromised-packages.json

# Update the JSON
cd sentinel
git pull
./bin/install.sh
```

### npm audit Takes Too Long

**Problem:** Validation is slow because npm audit is slow.

**Solution:**
Create `sentinel.config.json`:
```json
{
  "skipNpmAudit": true
}
```

Note: This disables npm audit checks but still scans against the JSON blacklist and vulnerability providers.

### Provider Errors

**Problem:** Providers (OSV, GitHub, Snyk) are failing or timing out.

**Solution:**

| Method | Command/Config | Description |
|--------|----------------|-------------|
| **CLI** | `--enableOsv=false` | Disable OSV provider |
| **CLI** | `--enableGitHub=false` | Disable GitHub provider |
| **CLI** | `--enableSnyk=false` | Disable Snyk provider |
| **Config** | `"providers": { "osv": { "enabled": false } }` | Disable via config file |

**Example:**
```bash
# Disable a problematic provider via CLI
sentinel scan package-name --enableOsv=false

# Or via config file
# Create sentinel.config.json:
{
  "providers": {
    "osv": { "enabled": false },
    "github": { "enabled": false }
  }
}
```

**Note:** Providers fail gracefully - if a provider is down, Sentinel falls back to npm audit. Installation is not blocked unless a vulnerability is actually found.

### Snyk Provider Not Working

**Problem:** Snyk provider is not checking packages.

**Solution:** See [Snyk Provider Setup](PROVIDERS.md#-3-snyk--disabled-by-default) in the Providers Guide for complete configuration instructions.

### GitHub Provider Rate Limits

**Problem:** GitHub provider is hitting rate limits.

**Solution:** See [GitHub Security Advisories](PROVIDERS.md#-2-github-security-advisories--enabled-by-default) in the Providers Guide for token setup and rate limit information.

### Permission Denied

**Problem:** Scripts are not executable.

**Solution:**
```bash
chmod +x bin/*.sh
chmod +x bin/cli.mjs
```

## Getting Help

1. Check this troubleshooting guide
2. Review [Usage Guide](USAGE.md)
3. Open an issue on GitHub