supply-chain-guardrail 1.0.0

package/.github/workflows/guardrail.yml

@@ -0,0 +1,37 @@
+name: guardrail
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  guardrail:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      security-events: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install dependencies and build GuardRail
+        run: npm ci && npm run build
+
+      - name: Run GuardRail scan
+        run: node dist/src/index.js scan --fail-fast --sarif guardrail.sarif
+
+      - name: Upload GuardRail SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: guardrail.sarif

package/INSTALL.md

@@ -0,0 +1,265 @@
+# GuardRail installation and rollout
+
+This is the shortest path from download to a working first scan.
+
+## Prerequisites
+
+- Node.js 20 or newer
+- npm 10 or newer
+- internet access for `verify` and `monitor`
+- a GitHub token only if you want `incident` to read GitHub Actions logs
+
+## Path 1: developer machine
+
+### 1. Get the code
+
+Clone the repository or unpack the release archive.
+
+```bash
+git clone https://github.com/guardrail-security/guardrail.git
+cd guardrail
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+### 3. Build the CLI
+
+```bash
+npm run build
+```
+
+### 4. Create or review config
+
+Copy the example file if you want a clean starting point.
+
+```bash
+cp guardrail.config.json your-project/guardrail.config.json
+```
+
+At minimum, adjust:
+
+- `scan.trustedPackages`
+- `tokenPolicy.staleAfterDays`
+- `github.owner`, `github.repo`, and `github.tokenEnvVar` if you plan to use `incident`
+- notification settings if you want live alerts
+
+### 5. Run the first scan against a real Node project
+
+```bash
+cd /path/to/your-node-project
+npx /path/to/guardrail/dist/src/index.js scan --fail-fast --sarif guardrail.sarif
+```
+
+If you installed GuardRail globally instead:
+
+```bash
+guardrail scan --fail-fast --sarif guardrail.sarif
+```
+
+### 6. Review the first-run baseline
+
+The first scan writes a signed baseline under `.guardrail/` by default.
+
+Files created there:
+
+- `.guardrail/baseline.json`
+- `.guardrail/baseline-private.pem`
+- `.guardrail/baseline-public.pem`
+
+Commit the baseline file if you want the project baseline to travel with the repository. Do **not** commit the private key unless you intentionally want a shared signing identity. In most teams, keep the private key in CI or a secure developer secret store.
+
+### 7. Add local pre-commit protection
+
+```bash
+guardrail scan --install-pre-commit
+```
+
+That writes `.git/hooks/pre-commit` so risky dependency changes fail before commit.
+
+## Path 2: use GuardRail without global install
+
+From any Node project:
+
+```bash
+npx guardrail-security scan
+npx guardrail-security audit-tokens
+npx guardrail-security verify axios@1.14.0
+```
+
+## Path 3: GitHub Actions rollout
+
+### 1. Add the workflow file
+
+Copy `.github/workflows/guardrail.yml` into the target repository.
+
+Or generate it from GuardRail itself:
+
+```bash
+guardrail scan --generate-workflow
+```
+
+### 2. Make sure the workflow can upload SARIF
+
+The generated workflow already includes these permissions:
+
+- `contents: read`
+- `actions: read`
+- `security-events: write`
+- `id-token: write`
+
+### 3. Keep dependency installation script-safe in CI
+
+The workflow intentionally installs project dependencies with:
+
+```bash
+npm ci --ignore-scripts
+```
+
+That lets GuardRail inspect lifecycle hooks before the hooks execute.
+
+### 4. Decide whether GuardRail should fail the build
+
+Default fail-fast usage:
+
+```bash
+guardrail scan --fail-fast --sarif guardrail.sarif
+```
+
+Tune the policy in `guardrail.config.json`:
+
+```jsonc
+{
+  "scan": {
+    "riskThreshold": 70,
+    "failOnSeverity": "high"
+  }
+}
+```
+
+### 5. Add GitHub token support for incident response
+
+If you want `guardrail incident` to inspect workflow logs, add a token with Actions read access.
+
+Example repository secret setup:
+
+```bash
+gh secret set GITHUB_TOKEN < ./github-token.txt
+```
+
+Then set in config:
+
+```jsonc
+{
+  "github": {
+    "owner": "your-org",
+    "repo": "your-repo",
+    "tokenEnvVar": "GITHUB_TOKEN"
+  }
+}
+```
+
+## Optional: live monitoring
+
+### Slack webhook
+
+```jsonc
+{
+  "monitor": {
+    "packages": ["axios", "react"],
+    "slackWebhook": "https://hooks.slack.com/services/..."
+  }
+}
+```
+
+Run:
+
+```bash
+guardrail monitor
+```
+
+### Generic webhook
+
+```jsonc
+{
+  "monitor": {
+    "packages": ["axios"],
+    "webhook": "https://your-webhook.example/guardrail"
+  }
+}
+```
+
+### Email via SMTP
+
+```jsonc
+{
+  "monitor": {
+    "packages": ["axios"],
+    "email": {
+      "host": "smtp.example.com",
+      "port": 587,
+      "secure": false,
+      "username": "smtp-user",
+      "password": "smtp-password",
+      "from": "guardrail@example.com",
+      "to": ["secops@example.com"]
+    }
+  }
+}
+```
+
+## Recommended rollout order
+
+1. run `guardrail scan` on a clean branch
+2. review and commit the baseline policy files
+3. add `guardrail audit-tokens` to maintainer and CI environments
+4. enable the GitHub Actions workflow
+5. turn on `--fail-fast`
+6. enable live monitoring for the packages you trust most
+7. use `guardrail incident` for every supply chain advisory that overlaps your dependency tree
+
+## Five-minute first scan
+
+Assuming GuardRail is already downloaded:
+
+```bash
+cd /path/to/guardrail
+npm install
+npm run build
+cd /path/to/your-node-project
+cp /path/to/guardrail/guardrail.config.json .
+node /path/to/guardrail/dist/src/index.js scan --fail-fast --sarif guardrail.sarif
+```
+
+That gets you:
+
+- a signed baseline
+- dependency mutation analysis
+- ghost dependency checks
+- lifecycle script inventory and scoring
+- a SARIF file for GitHub code scanning
+
+## Troubleshooting
+
+### No lockfile found
+
+GuardRail can still scan installed packages from `node_modules`, but it gets stronger when a lockfile exists.
+
+### `verify` says `fetch failed`
+
+The command needs network access to the npm registry and usually the source host.
+
+### GitHub log scan says skipped
+
+Set `github.owner`, `github.repo`, and a token through `github.tokenEnvVar` or `--github-token`.
+
+### SMTP alerts fail
+
+Check host, port, auth mode, firewall, and whether the SMTP server accepts `AUTH PLAIN`.
+
+### False positives on generated build artifacts
+
+This usually affects `verify`, not `scan`. Generated tarball files that are intentionally not committed to source will produce `partial` instead of `verified`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GuardRail Security Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# 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
+
+```bash
+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
+
+```bash
+guardrail ioc list
+```
+
+Shows both built-in and custom IOC entries with their reasons and advisory links.
+
+### Add a custom IOC
+
+```bash
+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
+
+```bash
+guardrail ioc check suspicious-package
+```
+
+Checks whether a package name matches any built-in or custom IOC entry.
+
+### Remove a custom IOC
+
+```bash
+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).
+
+```jsonc
+{
+  "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 |
+

package/dist/src/commands/audit-tokens.js

@@ -0,0 +1,111 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditTokens = runAuditTokens;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const token_scanner_1 = require("../core/token-scanner");
+const baseline_1 = require("../core/baseline");
+async function runAuditTokens(options, config) {
+    const rootDir = path.resolve(options.rootDir);
+    const result = await (0, token_scanner_1.scanTokenExposure)(rootDir, config);
+    let revoked = [];
+    if (options.revokeStale) {
+        revoked = (0, token_scanner_1.revokeSuggestedTokens)(result.findings, options.staleAfterDays ?? config.tokenPolicy?.staleAfterDays ?? 30);
+    }
+    if (options.output) {
+        fs.writeFileSync(path.resolve(rootDir, options.output), `${JSON.stringify({ ...result, revoked }, null, 2)}\n`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ...result, revoked }, null, 2));
+    }
+    else {
+        printHumanReadable(result, revoked);
+    }
+    const highest = result.issues.reduce((max, issue) => Math.max(max, (0, baseline_1.severityToNumber)(issue.severity)), 1);
+    return highest >= (0, baseline_1.severityToNumber)('high') ? 1 : 0;
+}
+function printHumanReadable(result, revoked) {
+    console.log('GuardRail token audit');
+    console.log(`root: ${result.rootDir}`);
+    console.log(`oidc trusted publishing detected: ${result.oidcTrustedPublishingDetected ? 'yes' : 'no'}`);
+    console.log(`self-hosted runners detected: ${result.selfHostedRunnerDetected ? 'yes' : 'no'}`);
+    console.log(`static publish tokens found: ${result.staticPublishTokensFound ? 'yes' : 'no'}`);
+    console.log(`mixed mode risk: ${result.mixedModeRisk ? 'yes' : 'no'}`);
+    console.log('');
+    console.log('Discovered credentials:');
+    if (result.findings.length === 0) {
+        console.log('- none');
+    }
+    else {
+        for (const finding of result.findings) {
+            console.log(`- ${finding.sourceType} ${finding.sourcePath ?? finding.envVar ?? 'unknown'} -> ${finding.tokenKind} ${finding.tokenPreview}`);
+            if (finding.note) {
+                console.log(`  note: ${finding.note}`);
+            }
+            if (finding.expiresAt) {
+                console.log(`  expires: ${finding.expiresAt}`);
+            }
+            if (finding.id) {
+                console.log(`  revoke: npm token revoke ${finding.id}`);
+            }
+        }
+    }
+    console.log('');
+    console.log('Findings:');
+    if (result.issues.length === 0) {
+        console.log('- no token hygiene issues detected');
+    }
+    else {
+        for (const issue of result.issues) {
+            console.log(`- [${issue.severity}] ${issue.code}: ${issue.title}`);
+            console.log(`  ${issue.description}`);
+            if (issue.recommendation) {
+                console.log(`  action: ${issue.recommendation}`);
+            }
+        }
+    }
+    if (result.suggestedRevocations.length > 0) {
+        console.log('');
+        console.log('Suggested revocations:');
+        for (const command of result.suggestedRevocations) {
+            console.log(`- ${command}`);
+        }
+    }
+    if (revoked.length > 0) {
+        console.log('');
+        console.log(`Revoked tokens: ${revoked.join(', ')}`);
+    }
+}