SupplyChain Sentry

Scan npm dependencies for supply chain security risks — detect malicious install scripts, suspicious packages, and weak reputation signals before they compromise your project.

Why SupplyChain Sentry?

Run sentry-scan and if the report shows no Critical/High issues, your dependencies' install scripts should not perform obviously malicious actions (dynamic code execution, unexpected outbound requests, or sensitive file access).

Installation

npm install -g supplychain-sentry

Or run without installing:

npx supplychain-sentry

Quick Start

sentry-scan
sentry-scan --verbose
sentry-scan --json > report.json
sentry-scan --html sentry-report.html

Rules (16)

Ignore a rule or package

{
  "ignorePackages": ["debug"],
  "ignoreRules": ["R010"]
}

Configuration

Create .sentryrc.json or sentry.config.json:

{
  "ignorePackages": ["lodash"],
  "ignoreRules": ["R010"],
  "thresholds": {
    "reputation": 40,
    "severity": "high"
  },
  "sandbox": {
    "enabled": true,
    "timeout": 30
  },
  "output": {
    "json": false,
    "html": false
  }
}

Reputation Score (0–100)

Packages below the reputation threshold (default 30) are flagged automatically.

Exit Codes

FAQ

My package was flagged as high risk — what should I do?

1. Run sentry-scan --verbose to inspect rule evidence.
2. If it is a false positive, add the package or rule to .sentryrc.json:

{
  "ignorePackages": ["my-internal-lib"],
  "ignoreRules": ["R004"]
}

Why does SupplyChain Sentry use Docker?

Docker runs install scripts in an isolated container with --network=none and read-only mounts to observe risky behavior without affecting your host. If Docker is unavailable, sandbox analysis is skipped with a clear warning and all other checks still run.

Disable sandbox entirely with:

sentry-scan --no-sandbox

How is the reputation score calculated?

The score combines public npm metadata and lockfile-derived dependency depth. See the table above. Sub-scores are included in verbose and JSON output.

Privacy Policy

SupplyChain Sentry:

• Does not collect telemetry
• Does not upload scan results to any remote server
• Only performs outbound requests to public npm APIs for package metadata and download counts
• Stores reports locally only when you pass --json or --html

Your dependency list never leaves your machine except for public npm metadata lookups.

CI Integration

GitHub Actions

name: Supply Chain Scan
on: [push, pull_request]

jobs:
  sentry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx supplychain-sentry --json report.json
      - uses: actions/upload-artifact@v4
        with:
          name: sentry-report
          path: report.json

GitLab CI

supplychain-scan:
  image: node:20
  script:
    - npm ci
    - npx supplychain-sentry --json report.json
  artifacts:
    paths:
      - report.json

CircleCI

jobs:
  scan:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run: npm ci
      - run: npx supplychain-sentry --json report.json
      - store_artifacts:
          path: report.json

Contributing

• Report false positives via GitHub Issues with rule ID and package name
• Propose new rules in src/rules/index.ts and add tests under test/

Development

npm install
npm run build
npm test
npm run test:coverage
npm run benchmark
npm run validate:real

See BENCHMARKS.md for recorded performance data and real-project validation results.

License

MIT — see LICENSE.