trawly

A dependency risk gate for JavaScript projects and SBOMs. Reads exact installed versions from npm, pnpm, and Yarn lockfiles, or from SPDX/CycloneDX Package URLs, and queries the OSV advisory database for known vulnerabilities. It also flags supply-chain risk signals such as install scripts, deprecated packages, unexpected registries, and unusually new packages.

Limitation: trawly reports known advisories and heuristic signals. It cannot prove a package is safe : absence of findings is not absence of risk.

Install

npm install --save-dev trawly
# or run ad-hoc:
npx trawly scan

Requires Node.js >= 20.

Quickstart

# log-only run (always exits 0) : best for interactive inspection
npx trawly inspect

# gating run : exits non-zero when findings meet --fail-on (default: high). Use this in CI.
npx trawly scan

# create trawly.toml and a baseline for existing findings
npx trawly init

# scan specific lockfiles or SBOMs
npx trawly scan --lockfile path/to/package-lock.json
npx trawly scan --lockfile pnpm-lock.yaml --lockfile yarn.lock
npx trawly scan --sbom bom.cdx.json --sbom bom.spdx.json

# machine-readable output
npx trawly scan --format json > trawly-report.json
npx trawly scan --format sarif --output trawly.sarif
npx trawly scan --format markdown --output trawly.md

# include committed .env-file checks
npx trawly scan --env

# use built-in policy presets
npx trawly scan --policy strict
npx trawly scan --policy library

# fail only on findings absent from a saved baseline
npx trawly scan --baseline trawly-baseline.json
npx trawly inspect --write-baseline trawly-baseline.json

# explain where a package appears in the lockfile
npx trawly why lodash

# only production deps
npx trawly scan --prod

# show every advisory instead of grouping by package
npx trawly scan --details

Two ways to run

trawly intentionally separates the gating and reporting concerns:

Command	Exit code on findings	When to use
trawly scan	non-zero (--fail-on, default high)	CI, pre-commit, anywhere a build should fail
trawly inspect	always 0 unless an operational error occurs	local exploration, dashboards, "just show me"

Both produce identical output. Only the exit behaviour differs.

CLI

trawly scan [path]      Gating run. Exits non-zero when --fail-on is met.
trawly inspect [path]   Log-only run. Always exits 0 on findings.
trawly init [path]      Write trawly.toml and an initial baseline.
trawly why <pkg> [path] Explain where a package appears in lockfiles.

Common options (both commands):

  --lockfile <path>          Explicit lockfile path; may be repeated
  --sbom <path>              Explicit SPDX/CycloneDX SBOM path; may be repeated
  --format table|json|markdown|sarif
                             Output format (default: table)
  --output <path>            Write report output to a file
  --config <path>            Path to trawly.toml
  --policy ci|strict|library|app
                             Apply built-in scan defaults
  --baseline <path>          Mark existing findings and fail only on new ones
  --write-baseline <path>    Write the current active findings baseline
  --risk / --no-risk         Override risk signals (default: config, otherwise on)
  --env / --no-env           Override committed .env scanning (CLI default: off)
  --prod                     Skip dev dependencies
  --include-dev              Include dev dependencies (default)
  -v, --details              Show one row per advisory instead of grouping
  -q, --summary              Print only the one-line severity summary

scan-only:
  --fail-on <level>          Severity gate
                             (critical|high|moderate|low|none, default: high)

Policy presets

Policy presets are conservative defaults that can be overridden by explicit CLI flags or trawly.toml.

Policy	Fail on	Risk signals	Env scan	Dev deps	Best for
ci	high	on	off	included	Default CI gate
strict	moderate	on	on	included	Security-sensitive repos
library	moderate	on	off	excluded	Published packages
app	high	on	on	included	Deployed applications

Exit codes

Code	Meaning
0	inspect: any outcome with no operational error. scan: no finding at or above --fail-on.
1	scan only: at least one finding at or above --fail-on.
2	Operational error (e.g. lockfile read failed, OSV unreachable).
3	Invalid CLI input.

Library API

import { scanProject, scanLockfile } from "trawly";

const result = await scanProject({ cwd: process.cwd() });
for (const finding of result.findings) {
  console.log(finding.packageName, finding.severity, finding.id);
}

The result follows this shape:

{
  "scannedAt": "2026-05-03T12:34:56.000Z",
  "packagesScanned": 412,
  "findings": [
    {
      "id": "GHSA-...",
      "source": "osv",
      "type": "vulnerability",
      "severity": "high",
      "ecosystem": "npm",
      "packageName": "lodash",
      "installedVersion": "4.17.20",
      "summary": "Prototype pollution in lodash",
      "url": "https://github.com/advisories/GHSA-...",
      "fixedVersions": ["4.17.21"],
      "affectedPaths": ["node_modules/lodash"],
      "fingerprint": "sha256...",
      "aliases": ["CVE-..."],
    },
  ],
  "ignoredFindings": [],
  "summary": {
    "critical": 0,
    "high": 1,
    "moderate": 0,
    "low": 0,
    "unknown": 0,
  },
  "errors": [],
  "warnings": [],
}

Config

trawly auto-discovers trawly.toml in the scanned project, or you can pass --config.

failOn = "high"
policy = "ci"
risk = true
env = false
allowedRegistries = ["https://registry.npmjs.org", "https://registry.yarnpkg.com"]

[[ignore]]
id = "GHSA-example"
package = "lodash"
ecosystem = "npm"
expires = "2026-06-30"
reason = "Not reachable in our app"

Every ignore entry must include an expiry date.

CI example (GitHub Actions)

name: trawly
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v6
      # Pin to the reviewed release commit SHA instead of a mutable branch.
      - uses: Arindam200/trawly@<full-length-commit-sha>
        with:
          fail-on: high
          upload-sarif: "true"
          env-scan: "true"
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: trawly-report
          path: |
            trawly.sarif
            trawly.md

Testing

npm test
npm run typecheck
npm run build

# Extra parser dialect corpus and generated invariant checks.
npm run test:corpus

# Live differential checks against npm, pnpm, Yarn classic, and Yarn Berry.
npm run test:differential

# Larger generated graphs and OSV reliability behavior.
npm run test:stress

The optional trawly-reliability workflow can run the corpus, package-manager differential, and stress layers on demand in GitHub Actions.

Roadmap

Implemented in this branch:

• pnpm and Yarn lockfile support
• SARIF + Markdown reporters and a GitHub Action
• Config file with ignore entries (with required expiry)
• Baseline mode (fail only on new findings)
• init onboarding command
• Policy presets: ci, strict, library, app
• why lockfile locator command
• Risk signals: install scripts, deprecated packages, unexpected registries, package age
• Multi-ecosystem scanning via SBOM (SPDX, CycloneDX)