@raj-dev/guardrail

A lightweight, offline-first security scanner for npm projects.
Run dependency checks, SAST, secrets detection, and SBOM generation from your terminal—no cloud, no telemetry.

Table of contents

• Why guardrail?
• What it does
• What it does not do
• Quick start
• Installation
• Usage
• CLI reference
• Example output
• HTML report
• Features in detail
• Configuration
• Exit codes
• Security disclaimer
• Roadmap
• Support
• License

Why guardrail?

• Offline-first — Everything runs on your machine. No uploads, no SaaS, no account.
• Zero telemetry — We don’t collect or send any data.
• Single command — One CLI to run npm audit, SAST, secrets checks, and optional SBOM.
• CI-friendly — JSON output and configurable fail level for pipelines.

What it does

All scanning is local only. No frameworks required; just Node.js and your project.

What it does not do

• No network upload of results or SBOM.
• No CI/CD config generation (you plug it into your own pipeline).
• No guarantee that every finding is a true positive—manual review is still required.
• Not a full SAST suite — it focuses on a small set of high-value checks, not exhaustive analysis.

Quick start

From your project root (where package.json lives). Install globally once (npm install -g @raj-dev/guardrail), or use npx:

npx @raj-dev/guardrail scan

To also generate an SBOM and use pretty output:

npx @raj-dev/guardrail scan --level high --format pretty --sbom

Installation

Because guardrail is a CLI, the usual way to install it is globally with -g. Then you can run guardrail from any project directory:

npm install -g @raj-dev/guardrail

Then from any project root:

guardrail scan
guardrail scan --sbom --format json

Other options:

Run without installing (uses latest from npm each time):

npx @raj-dev/guardrail scan

As a dev dependency (lock to a version; good for CI or team consistency):

npm install --save-dev @raj-dev/guardrail

Then in your scripts (in package.json):

{
  "scripts": {
    "security": "guardrail scan --level high",
    "security:full": "guardrail scan --level high --sbom --format json"
  }
}

Usage

The main command is scan. Run it from your project directory (the one with package.json).

guardrail scan [options]

Common examples

CLI reference

Examples:

# Strict: fail on any finding from low up
guardrail scan --level low

# Relaxed: only fail on critical
guardrail scan --level critical

# JSON for piping or CI
guardrail scan --format json > report.json

Example output

With --format pretty (default), you’ll see progress and a summary like this:

🔍 Starting security scan...
━━━━━━━━━━━━━━━━━━━━━━━━━━

📦 Scanning npm dependencies
⏳ Running npm audit...
✅ Dependency scan completed

🧠 Running static code analysis
📁 Scanning JavaScript files...
⚠️  Found 3 potential issues

🔐 Checking for hardcoded secrets
🔎 Searching for API keys & tokens...
✅ No secrets found

📦 Generating SBOM (CycloneDX)
📄 sbom.json created

📊 Final Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Critical : 1
⚠️  High     : 2
🟡 Medium   : 3
🟢 Low      : 1

With --format json, the output is a single JSON object with summary and issues, suitable for CI or custom tooling.

HTML report

Use --format html to only generate a report file, or --report to generate a report in addition to your usual output:

guardrail scan --format html
# Writes report.html; open in a browser.

guardrail scan --report
# Pretty output in terminal + report.html generated.

The report is written to report.html in your project root. Open it in any browser to view:

• Summary cards — Critical, High, Medium, Low counts at a glance
• Issues by source — Grouped by npm-audit, SAST, secrets, SBOM
• Severity badges — Color-coded for quick scanning
• Print-friendly — Works well when printed or saved as PDF

No server or network required; the report is a single self-contained HTML file.

Features in detail

Dependency scanning (npm audit)

Guardrail runs npm audit --json and parses the result. It maps npm’s severity levels to a normalized summary and issue list. If npm audit fails (e.g. no package-lock.json) or returns non-zero, that’s reported as a low-severity issue so the rest of the scan still runs.

SAST v1 (string-based)

Scans .js files (excluding node_modules) for literal patterns:

• eval(
• new Function(
• child_process.exec / child_process.execSync

Useful for a fast first pass; can have false positives (e.g. in comments or strings).

SAST v2 (ESLint-based)

Runs ESLint programmatically with custom rules—no project .eslintrc needed. The same risky constructs are flagged using the AST, which cuts down false positives. Rules included:

Secrets detection

Regex-based scan over .js files (again excluding node_modules) for:

• AWS-style access key patterns (e.g. AKIA...)
• token=..., secret=..., apiKey=...-style assignments

Designed to catch obvious leaks; not a replacement for a dedicated secrets manager or pre-commit hooks.

SBOM (CycloneDX)

With --sbom, guardrail uses @cyclonedx/cyclonedx-npm to generate a CycloneDX SBOM and writes it to sbom.json in the current working directory. Useful for supply-chain visibility and compliance. The file is created only on your machine; nothing is sent to any server.

Configuration

You can set defaults in your project’s package.json under a guardrail key. CLI flags override these.

{
  "guardrail": {
    "failLevel": "high",
    "exclude": ["dist", "coverage"],
    "includeGlob": ["**/*.js"]
  }
}

Exit codes

Use --level and the exit code in CI to gate on security findings.

Security disclaimer

Guardrail is intended to help you spot common issues. It is not a full security audit. Findings can be false positives or false negatives. Use it alongside code review, dependency review, and other tools—not as the only security gate.

Roadmap

• More SAST rules (e.g. unsafe deserialization, dangerous redirects).
• Configurable secret patterns and exclude list.
• Optional SARIF output for CI integration.
• Support for lockfile-only SBOM when node_modules is not present.

Support

If this tool is useful to you, consider supporting the author:

• Buy Me a Coffee — One-time or monthly support
• GitHub Sponsors — Sponsor open source work

Publishing

To publish this package to npm:

1. Update package.json
   Set repository, bugs, and homepage URLs to your actual repo (e.g. https://github.com/YourUser/guardrail).

2. Login to npm (if needed):

   npm login

3. Dry-run (see what would be published):

   npm pack --dry-run

4. Publish (scoped packages are public when publishConfig.access is "public"):

   npm publish

Before publishing, prepublishOnly runs node --check src/cli.js to catch syntax errors. No scan is run.

License

MIT. See LICENSE for details.