{"id":17484,"library":"verdaccio-audit","title":"Verdaccio Audit Middleware","description":"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.","status":"active","version":"10.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/verdaccio/monorepo","tags":["javascript","verdaccio","plugin","middleware","audit","typescript"],"install":[{"cmd":"npm install verdaccio-audit","lang":"bash","label":"npm"},{"cmd":"yarn add verdaccio-audit","lang":"bash","label":"yarn"},{"cmd":"pnpm add verdaccio-audit","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"verdaccio-audit functions as a plugin for Verdaccio and requires the core Verdaccio registry to operate. It is a peer dependency.","package":"verdaccio","optional":false},{"reason":"Provides core TypeScript types and interfaces used in Verdaccio plugins for consistent development. Often an implicit dependency.","package":"@verdaccio/types","optional":true}],"imports":[{"note":"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.","wrong":"const Audit = require('verdaccio-audit');","symbol":"Verdaccio Audit Plugin (Configuration)","correct":"# In your Verdaccio config.yaml:\nmiddleware:\n  audit:\n    enabled: true\n    # ... other configuration options"},{"note":"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.","wrong":"import { AuditMiddleware } from 'verdaccio-audit';","symbol":"AuditMiddleware (Programmatic Import)","correct":"import AuditMiddleware from 'verdaccio-audit';"},{"note":"TypeScript users who need to define or extend the plugin's configuration interface might import specific types, typically from a build output path.","symbol":"AuditPluginConfig (Type)","correct":"import type { AuditPluginConfig } from 'verdaccio-audit/build/types';"}],"quickstart":{"code":"yarn add verdaccio-audit\n# OR npm install verdaccio-audit\n\n# --- In your Verdaccio config.yaml (example path: ~/.verdaccio/config.yaml) ---\n\n# Existing Verdaccio configurations...\n\n# Example of auth settings (required for Verdaccio operation)\nauth:\n  htpasswd:\n    file: ./htpasswd\n    # Other htpasswd options\n\n# Enable and configure the audit middleware plugin\nmiddleware:\n  audit:\n    enabled: true\n    # Set to 'false' to completely block external npmjs.com audit calls.\n    # When set to 'false', Verdaccio will not proxy audit requests to npmjs.com.\n    allow_external_audit: false\n    # Optionally, provide a custom message shown when audit requests are blocked.\n    message: \"npm audit requests are managed internally or disabled by policy.\"\n    # Set the logging level for the plugin (e.g., info, warn, error, debug)\n    log_level: info\n\n# Remaining Verdaccio configurations...\n","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=10.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=10.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=10.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","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`.","error":"ERROR: Plugin 'verdaccio-audit' not found"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'audit')"},{"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.","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.","error":"ERROR: The plugin 'verdaccio-audit' has an incompatible Node.js version. Required: >=16, Current: 14.x.x"}],"ecosystem":"npm","meta_description":null}