RIO Audit Filter

Filters npm audit --json output using project-local exclusions from package.json.

Usage

Install this package as a development dependency:

npm install --save-dev --save-exact @rio-cloud/audit-filter

Add an audit script to the consuming project where you feed the JSON output of your npm audit call to the filter. You can fine-tune which parts end up in the audit report, e.g. with --omit=dev if you don't want to see vulnerabilities in your devDependencies. You can (and should) also pass in your desired

// in your package.json:
{
  // ...
  "scripts": {
    // ...
    "audit": "npm audit --registry https://registry.npmjs.org --json | rio-audit-filter --audit-level=moderate"
  }
}

rio-audit-filter exits with:

• 0 when no vulnerabilities at or above the configured audit level remain after filtering
• 1 when vulnerabilities at or above the configured audit level remain
• 2 when stdin, CLI options, or package.json exclusions are invalid

Informational messages about used or unused exclusions are written to stdout. Warnings about detected vulnerabilities and outdated exclusions are written to stderr. When --json is given and vulnerabilities remain, the filtered audit JSON is also written to stderr.

Exclusions

Exclusions live in the consuming project's package.json under rioAuditFilterExclusions.

Each entry needs a package value, a non-empty description value, and a suppressedOn value. Such vulnerabilities are only hidden while suppressedOn is within the grace period. By default, that grace period is 14 days.

{
  // ... in your package.json
  "rioAuditFilterExclusions": [
    {
      // Vulnerabilities from npm package should be ignored.
      "package": "brace-expansion",

      // Describe WHY this exclusion exists.
      "description": "The vulnerability is not affecting us because we do not allow arbitrary input to reach it. brace-expansion is a bundled dependency which we cannot control.",

      // RFC 9557 date string, i.e. YYY-MM-DD. Excluded vulnerabilities re-surface after a grace period.
      "suppressedOn": "2026-05-30"
    }
  ]
}

Use ISO calendar dates in YYYY-MM-DD format. The value must not be more than one day in the future.

CLI Options

rio-audit-filter --help
rio-audit-filter --audit-level high
rio-audit-filter --grace-period-days 7
rio-audit-filter --json

The --audit-level option accepts info, low, moderate, high, and critical. The default is moderate.

The --grace-period-days option accepts only positive integers. The default is 14.

The --json option writes the filtered audit report to stderr when vulnerabilities remain.