npx depwarden scan .

Why

The 2025–2026 worm wave (Shai-Hulud, Mini Shai-Hulud, Miasma) changed the threat model:

• Self-propagating packages harvested secrets with bundled scanner payloads.
• Persistence moved into Claude / Cursor / VS Code / MCP configs — removing the package does not remove the backdoor.
• Install-time attacks (e.g. Phantom Gyp via binding.gyp) slip past tooling that only watches lifecycle scripts.

Enterprise firewalls exist. depwarden is the free tripwire for everyone else: local, CI-friendly, severity-ranked.

Install

npx depwarden scan .                 # one-shot, no install
npm i -D depwarden                   # pin in a project
npx depwarden init                   # drop a sample GitHub Actions workflow

What it catches

| Scanner | Detects | |---|---| | manifest-audit | Install scripts in the tree, git/http deps that bypass the registry, typosquat-suspect names, deprecated packages, versions published in the last 14 days, dangerous scripts in your own package.json | | worm-ioc | Known worm indicator files/hashes in node_modules, bundled secret-scanner markers, obfuscated payloads, remote-exec lifecycle scripts, undeclared binding.gyp | | agent-config | Suspicious commands in .cursor/, .claude/, .vscode/tasks.json, .github/workflows, Continue/Windsurf/Codex surfaces; unknown MCP binaries; untrusted MCP URLs; external hooks; auto-run tasks; known exfil domains |

IOC and agent-config rules are detection patterns only — they flag lookalikes of known campaigns, not proof of compromise.

What it doesn't catch

Honest limits: pattern- and heuristic-based. No behavioral sandboxing, no full version-diff reputation engine, no registry-wide scoring. Novel, clean-looking malware in a package you already trust will not be flagged. Use it as a tripwire layer, not a guarantee.

Flags

depwarden scan [dir] [flags]
depwarden init [dir] [--force]

| Flag | Description | Default | |---|---|---| | --format <mode> | Output: human, json, sarif, annotations | human | | --json | Alias for --format json | off | | --offline | Skip npm registry lookups | off | | --skip-node-modules | Skip the node_modules worm scan | off | | --min-severity <level> | Exit 1 at this severity: info | low | medium | high | critical | medium | | --fail-on <level> | Alias for --min-severity | medium | | --scanners <list> | Subset: manifest, worm, agent (full ids accepted) | all | | --ignore <glob> | Skip paths; repeatable / comma-separated (*, **, ?) | none | | --quiet | Hide findings below medium in human output | off | | --no-color | Disable ANSI colors (also auto when not a TTY / NO_COLOR) | auto | | --watch | Rescan when lockfiles or agent-config paths change | off | | --force | Overwrite existing files (init only) | off | | -h, --help | Show help | — | | -v, --version | Show version | — |

npx depwarden scan . --fail-on high
npx depwarden scan . --format sarif > results.sarif
npx depwarden scan . --format annotations
npx depwarden scan . --watch --offline
npx depwarden scan . --scanners manifest,worm --ignore "fixtures/**"

Exit codes

| Code | Meaning | |---|---| | 0 | No findings at or above --fail-on / --min-severity (default medium) | | 1 | At least one finding at or above the threshold | | 2 | Usage error (unknown flag/scanner/format, invalid severity) or runtime error |

Use --fail-on high in CI if you want hygiene signals (low / info) to stay visible without failing the build.

CI

Drop a workflow with:

npx depwarden init

Or copy .github/workflows/depwarden.yml:

name: depwarden

on:
  push:
    branches: [main, master]
  pull_request:

jobs:
  supply-chain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Supply-chain scan
        run: npx depwarden@1 scan . --fail-on high --format annotations

SARIF upload (optional):

- run: npx depwarden@1 scan . --fail-on high --format sarif > depwarden.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: depwarden.sarif

Pre-commit:

#!/bin/sh
npx depwarden scan . --offline --quiet || exit 1

Programmatic API

import { runScan } from 'depwarden';

const report = await runScan('./my-project', { offline: true });
console.log(report.counts, report.findings);

Docs

• Product overview
• Full usage reference
• Changelog

Severity model

critical / high — act now (known IOC hashes, exfil domains, malicious lifecycle scripts).
medium — review (typosquat suspects, unknown MCP binaries, auto-run tasks).
low / info — hygiene (fresh releases, deprecated packages, recently modified agent configs); do not fail by default.

Roadmap

• Remote IOC list updates (fetch stubbed today; ships bundled list)
• Registry version-diff heuristics
• Hosted team policies and alerting

License

MIT © John Yaghobieh