GuardRail

GuardRail is a zero-dependency npm supply chain security tool that detects attacks before any advisory exists. It was built in response to the March 2026 axios supply chain compromise (GHSA-fw8c-xr5c-95f9), where a trusted package silently added a malicious dependency that ran a postinstall hook to deploy a RAT. No CVE existed at the time of the attack. Traditional audit tools were blind to it. GuardRail catches this class of attack -- and others like it -- by analyzing behavioral signals rather than waiting for someone to file an advisory.

The core insight: no existing tool catches "ghost dependencies" -- packages added to package.json that are never imported in source code. These packages exist solely to run their postinstall hooks. GuardRail cross-references every declared dependency against the actual import graph of the package source, and flags any dependency that is declared but never used. Combined with behavioral scoring of install scripts, baseline drift detection, and IOC matching, GuardRail provides defense-in-depth for any npm project.

Quick Start

npm install -g supply-chain-guardrail
cd your-project
guardrail scan
guardrail ioc list
guardrail audit-tokens

How Detection Works

Ghost Dependency Detection

GuardRail builds an import map by statically analyzing all source files in a package (.js, .ts, .mjs, .cjs, and related extensions). It extracts every require() call and import statement, then cross-references those against the dependencies declared in package.json. If a dependency is declared but never imported by any source file, it is flagged as a ghost dependency. This is the single most reliable signal for postinstall dropper attacks, because the malicious package does not need to be imported -- it only needs to be installed.

Script Behavioral Scoring

Every lifecycle script (preinstall, install, postinstall, prepare, prepublish) across the full dependency tree is analyzed against a weighted multi-rule system. Each rule detects a specific behavioral pattern: network calls, process spawning, file writes, base64/hex payloads, eval usage, self-delete behavior, persistence paths, and shell launchers. Individual rule matches produce a base score, and compound bonuses are added when multiple dangerous patterns appear together (for example, a script that both fetches from a URL and spawns a child process scores higher than either signal alone). The final score is compared against a configurable threshold to determine severity.

Axios Blind Spot (OIDC + Token Coexistence)

The axios attack succeeded in part because the compromised maintainer account still had static npm publish tokens alongside OIDC trusted publishing. GuardRail scans for this exact configuration: if a project uses OIDC trusted publishing but static publish tokens also exist (in .npmrc, environment variables, or CI workflow files), it flags the mixed-mode setup as a critical risk. An attacker who compromises a static token can publish releases that bypass the trusted-publisher pipeline entirely.

Baseline Drift

GuardRail creates an Ed25519-signed snapshot of every package's dependency set, lifecycle scripts, and manifest contents. On subsequent scans, it compares the current state against the signed baseline. Any change -- new dependencies, modified scripts, altered metadata -- is detected and reported. Because the baseline is cryptographically signed, an attacker cannot silently modify it. The --update-baseline flag lets you intentionally advance the baseline after reviewing changes.

Advisory-Independent

GuardRail does not depend on CVE databases or advisory feeds. All detection is based on behavioral analysis and structural comparison. This means GuardRail catches zero-day supply chain attacks the moment they appear in a package release, not days or weeks later when an advisory is published. The built-in IOC database provides an additional layer for known threats, but the core detection engine works without it.

CLI Reference

| Command | Description | |---------|-------------| | guardrail scan | Full project scan: ghost dependencies, script scoring, baseline drift, IOC matching | | guardrail monitor | Watch the npm change feed for new releases of your dependencies | | guardrail audit-tokens | Find static publish tokens and mixed-mode publishing risk | | guardrail verify <package@version> | Verify a specific package version against registry metadata and provenance signals | | guardrail incident <package@version> --from ISO --to ISO | Build an incident checklist and optionally scan GitHub Actions logs | | guardrail ioc list\|add\|remove\|check | Manage the local IOC (Indicators of Compromise) database |

scan

guardrail scan [options]

| Flag | Description | |------|-------------| | --root-dir <path> | Project root directory (default: current directory) | | --fail-fast | Exit with non-zero status on first high-severity finding | | --threshold <number> | Script risk score threshold (default: from config or 70) | | --sarif <path> | Write findings in SARIF format for GitHub Code Scanning | | --update-baseline | Update the signed baseline after scan | | --generate-workflow | Generate a GitHub Actions workflow file | | --install-pre-commit | Install a Git pre-commit hook that runs GuardRail | | --output <path> | Write scan results to a file | | --json | Output results as JSON | | --quiet | Suppress non-essential output |

monitor

guardrail monitor [options]

| Flag | Description | |------|-------------| | --root-dir <path> | Project root directory | | --interval-ms <ms> | Poll interval in milliseconds | | --slack-webhook <url> | Slack webhook URL for alerts | | --webhook <url> | Generic webhook URL for alerts | | --once | Run one check and exit instead of continuous monitoring |

audit-tokens

guardrail audit-tokens [options]

| Flag | Description | |------|-------------| | --root-dir <path> | Project root directory | | --revoke-stale | Suggest revocation of stale tokens | | --stale-after-days <days> | Number of days after which a token is considered stale |

verify

guardrail verify <package@version> [options]

| Flag | Description | |------|-------------| | --root-dir <path> | Project root directory | | --fail-fast | Exit with non-zero status on verification failure |

incident

guardrail incident <package@version> --from <ISO> --to <ISO> [options]

| Flag | Description | |------|-------------| | --from <ISO> | Start of the incident time window (required) | | --to <ISO> | End of the incident time window (required) | | --github-owner <owner> | GitHub repository owner for Actions log scanning | | --github-repo <repo> | GitHub repository name | | --github-token <token> | GitHub personal access token |

ioc

guardrail ioc <list|add|remove|check> [options]

| Flag | Description | |------|-------------| | --reason <text> | Reason for adding an IOC entry | | --advisory <id> | Advisory identifier (GHSA, CVE) |

IOC Database

GuardRail maintains a database of known malicious packages (Indicators of Compromise). The database has two layers: built-in entries that ship with GuardRail, and custom entries that you manage per-project via guardrail.config.json.

List all IOCs

guardrail ioc list

Shows both built-in and custom IOC entries with their reasons and advisory links.

Add a custom IOC

guardrail ioc add evil-package --reason "Exfiltrates env vars via postinstall" --advisory "GHSA-xxxx-xxxx-xxxx"

Adds a package to the custom IOC list in your project config. Future scans will flag this package if it appears in any dependency tree.

Check a specific package

guardrail ioc check suspicious-package

Checks whether a package name matches any built-in or custom IOC entry.

Remove a custom IOC

guardrail ioc remove evil-package

Removes a package from the custom IOC list. Built-in IOCs cannot be removed.

Contributing IOCs

The community can contribute new malicious package entries to the built-in IOC database. To submit a new IOC:

1. Open a GitHub issue using the "New IOC Submission" template.
2. Provide the package name, affected versions, advisory link (GHSA or CVE), and a description of the malicious behavior.
3. Alternatively, submit a pull request that adds the entry directly to the BUILTIN_IOCS array in src/commands/ioc.ts and the builtinIocs object in src/commands/scan.ts.

All submissions require evidence: a published advisory or a reproducible technical analysis demonstrating malicious behavior.

CI/CD Integration

GuardRail integrates into your CI/CD pipeline in three ways:

• GitHub Actions workflow: Run guardrail scan --generate-workflow to create a .github/workflows/guardrail.yml file that runs on every push and pull request.
• SARIF output: Run guardrail scan --sarif guardrail.sarif to produce SARIF output compatible with GitHub Code Scanning. Upload the SARIF file using the github/codeql-action/upload-sarif action to see GuardRail findings directly in the Security tab.
• Pre-commit hook: Run guardrail scan --install-pre-commit to install a Git hook that runs GuardRail before every commit, blocking commits that introduce high-severity findings.

Configuration

GuardRail reads guardrail.config.json from the project root. The file supports JSON-with-comments (lines starting with // and /* ... */ blocks are stripped before parsing).

{
  "scan": {
    "riskThreshold": 70,
    "failOnSeverity": "high",
    "trustedPackages": ["axios"]
  },
  "tokenPolicy": {
    "staleAfterDays": 30,
    "mixedModeAllowed": false
  },
  "github": {
    "owner": "your-org",
    "repo": "your-repo",
    "tokenEnvVar": "GITHUB_TOKEN"
  }
}

Key configuration fields:

| Field | Description | |-------|-------------| | baseline.directory | Directory for baseline data and signing keys | | baseline.path | Signed baseline file path | | baseline.privateKeyPath | Ed25519 private signing key path | | baseline.publicKeyPath | Ed25519 public verification key path | | scan.riskThreshold | Script risk score threshold for blocking | | scan.failOnSeverity | Minimum severity that fails CI in --fail-fast mode | | scan.trustedPackages | Packages whose mutations are treated as especially sensitive | | scan.ignoreDirs | Directories to skip when building import graphs | | scan.maxScriptFileBytes | Maximum script file size to analyze | | tokenPolicy.staleAfterDays | Days after which a token is considered stale | | tokenPolicy.mixedModeAllowed | Allow OIDC + static token coexistence | | monitor.packages | Explicit package watch list | | monitor.pollIntervalMs | npm change feed poll interval | | monitor.slackWebhook | Default Slack webhook for alerts | | monitor.webhook | Generic webhook for alerts | | github.owner / github.repo / github.tokenEnvVar | Defaults for incident log scanning |