ioc-checker

Supply-chain IoC (indicator of compromise) scanner for npm projects. It checks whether your project pulled in a known-malicious package by matching a curated list of package@version indicators against your dependency tree and lockfiles.

It distinguishes the two ways packages get weaponized:

• Typosquats / worms — obscure packages where any installed version is malicious.
• Hijacked popular packages — legitimate packages (e.g. chalk, debug) where only specific compromised versions are malicious. ioc-checker matches the exact version, so it won't false-positive on the safe releases you actually use.

Usage

Run it in any npm project directory. No install required:

# directly from GitHub
npx github:matrica-code/ioc-checker

# once published to npm
npx @matrica-code/ioc-checker

Options

-d, --dir <path>     project directory to scan (default: current directory)
-j, --json           machine-readable JSON output (good for CI)
    --iocs <path>    use a custom IoC definition file instead of the bundled one
-h, --help           show help

Exit codes

| Code | Meaning | |------|---------| | 0 | clean — no IoCs detected | | 1 | at least one IoC matched (review the output) | | 2 | usage / load error |

This makes it usable as a CI gate:

# .github/workflows/supply-chain.yml
- run: npx github:matrica-code/ioc-checker

What it scans

1. Installed dependency tree via npm ls --all --json (full transitive tree).
2. package-lock.json — exact versions (lockfile v1, v2, and v3).
3. yarn.lock / pnpm-lock.yaml — best-effort text scan if present.

Updating the IoC list

Indicators live in data/iocs.json, grouped by campaign with an advisory link. Each entry is:

{
  "name": "chalk",
  "versions": ["5.6.1"]
}

• "versions": "*" — any installed version is malicious (typosquat/worm).
• "versions": ["1.2.3", "2.0.0"] — only these exact versions are malicious.

To add a new incident, append a campaign group with its packages and the advisory URL. The version strings are sourced from public advisories — verify against the linked advisory before acting on a hit.

Releasing

CI runs the test suite on every push and PR (ci.yml).

Publishing is automated (publish.yml) and triggers when a GitHub Release is published. It uses the NPM_TOKEN org secret. To cut a release:

1. Bump the version: npm version patch (or minor / major), then git push --follow-tags.
2. Create a GitHub Release for that tag.

The workflow runs the tests and then npm publish --access public. It can also be triggered manually via Actions → Publish to npm → Run workflow.

License

MIT