Verdaccio Audit Middleware

10.2.4 · active · verified Wed Apr 22

verdaccio-audit is a middleware plugin for Verdaccio, a lightweight private npm proxy registry. Its primary function is to bypass, modify, or control the default npm audit behavior when packages are retrieved through the Verdaccio instance. This empowers organizations to manage vulnerability scanning, enabling integration with internal security tools, ignoring specific advisories, or completely disabling external audit calls to `npmjs.com` for enhanced performance or privacy. The package is currently at version 10.2.4 and is an active component within the Verdaccio monorepo, which typically undergoes regular patch and minor updates across its various packages. A key differentiator of verdaccio-audit is its capability to provide granular control over the audit process directly within a private registry environment, offering a flexible alternative to relying solely on external `npm audit` services.

Common errors

```
ERROR: Plugin 'verdaccio-audit' not found
```
cause The `verdaccio-audit` package is either not installed in a location Verdaccio can discover, or there is a typographical error in the plugin's name within the `config.yaml`.

fix Install the package using `npm install verdaccio-audit` or `yarn add verdaccio-audit` in your Verdaccio storage path or a globally accessible location. Double-check that 'audit' is correctly specified under the `middleware` section in `config.yaml`.
```
TypeError: Cannot read properties of undefined (reading 'audit')
```
cause This error typically indicates that the `middleware` section, or the `audit` sub-section within `middleware`, is missing or malformed in `config.yaml`, preventing Verdaccio from correctly parsing the plugin's configuration.

fix Ensure that `middleware:` is correctly defined at the top level of `config.yaml` and that `audit:` is an appropriately indented child of `middleware:`, followed by its configuration options.
```
ERROR: The plugin 'verdaccio-audit' has an incompatible Node.js version. Required: >=16, Current: 14.x.x
```
cause The installed Node.js version on your system does not meet the minimum requirements for the `verdaccio-audit` plugin or the `verdaccio` core instance it is running on.

fix Upgrade your Node.js runtime to a version compatible with your Verdaccio core and the `verdaccio-audit` plugin. For recent Verdaccio versions, this typically means Node.js 16 or 18.

Warnings

gotcha Node.js Compatibility: While `verdaccio-audit`'s `package.json` specifies `engines.node: >=8`, current major versions of Verdaccio (e.g., v6.x) typically require Node.js >= 16 for stable operation. Running the plugin with an outdated Node.js environment or an incompatible Verdaccio core version will likely lead to startup failures or unexpected behavior.
Fix: Ensure your Node.js version meets the minimum requirements of your Verdaccio core installation (e.g., Node.js 16 or 18 for Verdaccio v6.x) and that the `verdaccio-audit` version is compatible with your Verdaccio core.
breaking Verdaccio Core Major Version Compatibility: As `verdaccio-audit` is part of the Verdaccio monorepo, its major version (v10) is typically aligned with specific major versions of the `verdaccio` core. Upgrading your `verdaccio` core to a new major version (e.g., from v5 to v6) may necessitate a corresponding upgrade of `verdaccio-audit` and potential configuration changes due to API shifts in the core registry.
Fix: Always consult the Verdaccio monorepo release notes and migration guides when performing major version upgrades of Verdaccio or its plugins to ensure compatibility and apply any required configuration adjustments.
gotcha Configuration Syntax Sensitivity: Verdaccio plugins are heavily reliant on correct configuration in `config.yaml`. Incorrect indentation, invalid keys, or misspelled options for `verdaccio-audit` will prevent the plugin from loading or functioning as intended, often without highly descriptive error messages. YAML structure must be precise.
Fix: Thoroughly review the `verdaccio-audit` documentation for the exact configuration syntax. Utilize a YAML linter or validator to confirm the correctness of your `config.yaml` before initiating Verdaccio.

Install

npm install verdaccio-audit npm
yarn add verdaccio-audit yarn
pnpm add verdaccio-audit pnpm

Imports

Verdaccio Audit Plugin (Configuration)
wrong:
```
const Audit = require('verdaccio-audit');
```
correct:
```
# In your Verdaccio config.yaml:
middleware:
  audit:
    enabled: true
    # ... other configuration options
```
Verdaccio plugins are primarily loaded and configured via the `config.yaml` file by referencing their package name under the appropriate section (e.g., `middleware`). Direct programmatic import by end-users is uncommon.
AuditMiddleware (Programmatic Import)
wrong:
```
import { AuditMiddleware } from 'verdaccio-audit';
```
correct:
```
import AuditMiddleware from 'verdaccio-audit';
```
For advanced use cases like testing or extending the plugin programmatically, `verdaccio-audit` typically provides a default export. However, this is not standard usage for integrating the plugin with Verdaccio.
AuditPluginConfig (Type)
```
import type { AuditPluginConfig } from 'verdaccio-audit/build/types';
```
TypeScript users who need to define or extend the plugin's configuration interface might import specific types, typically from a build output path.

Quickstart

Demonstrates how to install the `verdaccio-audit` package and configure it within Verdaccio's `config.yaml` to disable external npmjs.com audit requests, providing a custom message.

yarn add verdaccio-audit
# OR npm install verdaccio-audit

# --- In your Verdaccio config.yaml (example path: ~/.verdaccio/config.yaml) ---

# Existing Verdaccio configurations...

# Example of auth settings (required for Verdaccio operation)
auth:
  htpasswd:
    file: ./htpasswd
    # Other htpasswd options

# Enable and configure the audit middleware plugin
middleware:
  audit:
    enabled: true
    # Set to 'false' to completely block external npmjs.com audit calls.
    # When set to 'false', Verdaccio will not proxy audit requests to npmjs.com.
    allow_external_audit: false
    # Optionally, provide a custom message shown when audit requests are blocked.
    message: "npm audit requests are managed internally or disabled by policy."
    # Set the logging level for the plugin (e.g., info, warn, error, debug)
    log_level: info

# Remaining Verdaccio configurations...

view raw JSON →