verdaccio-security-filter 1.3.12 → 1.4.1

package/README.md

@@ -117,7 +117,7 @@ This plugin implements **two independent security layers** for complete protecti
 - [ ] **ML-based Anomaly Detection** - Machine learning for threat detection
 
 #### Phase 5: Developer Experience
-- [ ] **Dry Run Mode** - Test rules without actually blocking
+- [x] **Dry Run Mode** - Test rules without actually blocking (`dryRun: true`)
 - [ ] **Auto-approve Criteria** - Automatic approval based on npm stats (downloads, stars)
 - [ ] **CLI Tool** - Command-line interface for rule management
 - [ ] **Visual Studio Code Extension** - IDE integration
@@ -150,47 +150,44 @@ npm link
 
 ## 🔧 How It Works
 
-This plugin implements **two layers of protection** to block malicious packages:
+The plugin works in two layers. Configure both: the same settings go under `filters` and under `middlewares`.
 
 ### Layer 1: Metadata Filtering (`filter_metadata`)
-When a client requests package information (e.g., `npm info lodash`), the plugin:
-1. Checks if the package is allowed (whitelist mode)
-2. Validates against blocked patterns, scopes, and age requirements
-3. **Throws HTTP 404 error** for completely blocked packages (patterns, scopes, whitelist violations)
-4. Filters out specific blocked versions from the versions list for partial blocks
+Runs inside Verdaccio when package metadata is read, so it sees every version:
+1. Removes versions blocked by `blockedVersions`, `versionRangeRules` and `whitelist.versions`
+2. Removes versions rejected by the CVE, license, age and author checks
+3. Blocks the package as a whole when no version is left, or when the package itself is not allowed
 
-**Result**: Blocked packages return "404 Not Found" - as if they don't exist in the registry.
+npm then resolves ranges against the versions that are left.
 
-### Layer 2: Middleware Interception (`register_middlewares`)
-When a client tries to download a tarball file (e.g., during `npm install`), the plugin:
-1. Intercepts **all HTTP requests** early in the middleware chain
-2. Extracts package name and version from the request URL
-3. Applies all security checks (whitelist, patterns, scopes, blocked versions, range rules)
-4. Returns **403 Forbidden** for blocked packages with detailed error message
+### Layer 2: Middleware (`register_middlewares`)
+Runs first on every `GET` request:
+1. Blocks packages by name: whitelist, patterns, scopes
+2. Blocks tarball downloads of blocked versions, even if a client has stale metadata or a lockfile
+3. Turns a whole-package block from layer 1 into an HTTP error that carries the reason
 
-**Result**: Even if metadata is cached, tarball downloads are blocked at the HTTP level.
+### What a client sees
 
-### Why Both Layers?
+A removed version is simply missing from the metadata. A blocked package or tarball is answered with **403 Forbidden**, and the reason is in the `error` field, which npm prints:
 
-- **Metadata filtering (404)** - Makes blocked packages invisible to npm/yarn
-- **Middleware interception (403)** - Blocks tarball downloads even with cached metadata
-- Together, they provide **complete protection** against blocked packages being installed in any way
-
-Example flow when a blocked package is requested:
 ```
 npm install hawk
-→ GET /hawk (metadata request)
-→ [Security Filter] Blocked hawk@* - Package is not in whitelist
-→ HTTP 404 Not Found: Package blocked by security filter: Not in whitelist
-→ npm ERR! 404 Not Found - GET http://localhost:4873/hawk
-
-npm install (with hawk as dependency)
-→ GET /hawk/-/hawk-9.0.1.tgz (tarball request)
-→ [Middleware] Tarball request: hawk/hawk-9.0.1.tgz
-→ [Security Filter] Blocked hawk@9.0.1 - Package is not in whitelist
-→ HTTP 403 Forbidden: {"error": "Package blocked by security filter", "reason": "Package is not in whitelist"}
+npm error code E403
+npm error 403 403 Forbidden - GET http://localhost:4873/hawk - Package blocked by security filter: Package is not in whitelist
+```
+
+```json
+{
+  "error": "Package blocked by security filter: License 'GPL-3.0' is not in allowed list",
+  "package": "some-package",
+  "reason": "License 'GPL-3.0' is not in allowed list",
+  "security": { "blocked": true, "reason": "...", "plugin": { "name": "verdaccio-security-filter", "version": "..." } },
+  "timestamp": "2026-01-15T10:30:00.000Z"
+}
 ```
 
+The 403 for packages blocked in layer 1 (CVE, license, age, author, fail-closed errors) needs the middleware. With only `filters` configured, such a package is returned with an empty version list and npm reports "No versions available" without a reason.
+
 ## ⚙️ Configuration
 
 ### Quick Start (Middleware Only)
@@ -406,11 +403,30 @@ middlewares:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `mode` | `string` | `blacklist` | Filter mode: `blacklist` or `whitelist` |
+| `dryRun` | `boolean` | `false` | Log and record every decision, but block nothing. See [Dry-run mode](#dry-run-mode) |
 | `blockedVersions` | `string[]` | `[]` | List of `package@version` to block |
 | `blockedPatterns` | `string[]` | `[]` | Regex patterns for package names |
 | `allowedScopes` | `string[]` | `[]` | Allowed package scopes |
 | `blockedScopes` | `string[]` | `[]` | Blocked package scopes |
 
+### Dry-run mode
+
+Set `dryRun: true` to see what a rule set would do before enforcing it. Put it in both the `filters` and the `middlewares` block, like the rest of the configuration.
+
+```yaml
+dryRun: true
+```
+
+While it is on:
+
+- every check runs as usual, including CVE lookups
+- nothing is blocked: metadata is served unchanged and every tarball can be downloaded
+- each decision is logged at `warn` with a `[DRY RUN]` marker, followed by a summary such as `lodash: would remove 115 of 117 version(s)`
+- metrics events carry `"dryRun": true`
+- one warning at start-up says that dry-run is active
+
+Recommended before turning on `cveCheck.autoBlock`, a license policy or the author filter on a registry that is already in use.
+
 ### CVE Check Options
 
 | Option | Type | Default | Description |

package/build/index.d.ts

@@ -25,6 +25,7 @@ export default class SecurityFilterPlugin implements IPluginMiddleware<SecurityC
     private _removeVersions;
     private _rejectedVersions;
     filter_metadata(packageInfo: Package): Promise<Package>;
+    private _filterMetadata;
     private _versionBlockReason;
     private _checkPackageBlock;
     private _getAppliedRules;

package/build/index.js

@@ -56,7 +56,12 @@ const cve_checker_1 = require("./lib/cve-checker");
 const license_checker_1 = require("./lib/license-checker");
 const package_age_checker_1 = require("./lib/package-age-checker");
 const author_checker_1 = require("./lib/author-checker");
+const lru_cache_1 = require("./lib/lru-cache");
 const PLUGIN_VERSION = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf8')).version;
+const filterBlocks = new lru_cache_1.LRUCache(1000);
+function forbiddenBody(packageName, reason, extra = {}) {
+    return Object.assign(Object.assign({ error: `Package blocked by security filter: ${reason}`, package: packageName, reason }, extra), { timestamp: new Date().toISOString() });
+}
 class SecurityFilterPlugin {
     constructor(config, options) {
         this.config = config || {};
@@ -66,8 +71,8 @@ class SecurityFilterPlugin {
                 onCveCheckError: 'fail-open',
             };
         }
-        this.logger = new logger_1.SecurityLogger(options.logger, this.config.logger);
-        this.metrics = new metrics_1.MetricsCollector(this.config.metrics);
+        this.logger = new logger_1.SecurityLogger(options.logger, this.config.logger, !!this.config.dryRun);
+        this.metrics = new metrics_1.MetricsCollector(this.config.metrics, !!this.config.dryRun);
         this.whitelistChecker = new whitelist_checker_1.WhitelistChecker(this.config.whitelist);
         this.cveChecker = new cve_checker_1.CVEChecker(this.config.cveCheck);
         this.licenseChecker = new license_checker_1.LicenseChecker(this.config.licenses);
@@ -90,6 +95,9 @@ class SecurityFilterPlugin {
             }
         });
         this._logInitialization();
+        if (this.config.dryRun) {
+            this.logger.warn('Dry-run mode is on: decisions are logged and recorded in metrics, but nothing is blocked');
+        }
     }
     _parseVersionRangeRules(rules) {
         return rules.map((rule, index) => {
@@ -140,6 +148,8 @@ class SecurityFilterPlugin {
     _getEnabledFeatures() {
         var _a, _b, _c, _d, _e;
         const features = [];
+        if (this.config.dryRun)
+            features.push('dry-run');
         if (this.config.mode === 'whitelist')
             features.push('whitelist-mode');
         if ((_a = this.config.metrics) === null || _a === void 0 ? void 0 : _a.enabled)
@@ -225,13 +235,10 @@ class SecurityFilterPlugin {
                     if (blockResult.blocked) {
                         this.logger.warn(`[Middleware] [X] BLOCKED TARBALL: ${packageName}@${version || '*'} - ${blockResult.reason}`);
                         this.metrics.recordBlock(packageName, version || '*', blockResult.reason);
-                        res.status(403).json({
-                            error: 'Package blocked by security filter',
-                            package: packageName,
-                            version: version || 'all versions',
-                            reason: blockResult.reason,
-                            timestamp: new Date().toISOString()
-                        });
+                        if (this.config.dryRun) {
+                            return next();
+                        }
+                        res.status(403).json(forbiddenBody(packageName, blockResult.reason, { version: version || 'all versions' }));
                         return;
                     }
                     this.logger.debug(`[Middleware] [OK] ALLOWED TARBALL: ${packageName}@${version || 'unknown'}`);
@@ -241,10 +248,10 @@ class SecurityFilterPlugin {
                     const blockResult = yield this._checkPackageBlock(packageName);
                     if (blockResult.blocked) {
                         this.logger.warn(`[Middleware] [X] BLOCKED METADATA: ${packageName} - ${blockResult.reason}`);
-                        const blockedResponse = {
-                            name: packageName,
-                            versions: {},
-                            'dist-tags': {},
+                        if (this.config.dryRun) {
+                            return next();
+                        }
+                        res.status(403).json(forbiddenBody(packageName, blockResult.reason, {
                             security: {
                                 blocked: true,
                                 reason: blockResult.reason,
@@ -255,21 +262,24 @@ class SecurityFilterPlugin {
                                 },
                                 blockedAt: new Date().toISOString(),
                                 rules: this._getAppliedRules(packageName),
-                                message: `This package has been blocked by security filter: ${blockResult.reason}`,
                                 contact: 'Please contact your registry administrator for more information',
                             },
-                            _security: {
-                                blocked: true,
-                                reason: blockResult.reason,
-                                blockedBy: 'verdaccio-security-filter',
-                                blockedAt: new Date().toISOString(),
-                            }
-                        };
-                        res.status(200).json(blockedResponse);
+                        }));
                         return;
                     }
-                    else {
-                        this.logger.debug(`[Middleware] [OK] ALLOWED METADATA: ${packageName}`);
+                    this.logger.debug(`[Middleware] [OK] ALLOWED METADATA: ${packageName}`);
+                    if (!this.config.dryRun) {
+                        const startedAt = Date.now();
+                        const send = res.send.bind(res);
+                        res.send = (body) => {
+                            const block = filterBlocks.get(packageName);
+                            if (block && block.at >= startedAt && res.statusCode < 300) {
+                                res.removeHeader('ETag');
+                                res.status(403);
+                                return send(JSON.stringify(forbiddenBody(packageName, block.security.reason, { security: block.security })));
+                            }
+                            return send(body);
+                        };
                     }
                 }
                 next();
@@ -321,6 +331,25 @@ class SecurityFilterPlugin {
         };
     }
     filter_metadata(packageInfo) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const filtered = yield this._filterMetadata(packageInfo);
+            if (!this.config.dryRun) {
+                const security = filtered.security;
+                if (security === null || security === void 0 ? void 0 : security.blocked) {
+                    filterBlocks.set(packageInfo.name, { security, at: Date.now() });
+                }
+                return filtered;
+            }
+            if (filtered === packageInfo) {
+                return filtered;
+            }
+            const total = Object.keys(packageInfo.versions || {}).length;
+            const left = Object.keys(filtered.versions || {}).length;
+            this.logger.warn(`[filter_metadata] ${packageInfo.name}: would remove ${total - left} of ${total} version(s)`);
+            return packageInfo;
+        });
+    }
+    _filterMetadata(packageInfo) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e;
             let pkg = packageInfo;

package/build/lib/logger.d.ts

@@ -4,7 +4,7 @@ export declare class SecurityLogger {
     private verdaccioLogger;
     private config;
     private readonly prefix;
-    constructor(verdaccioLogger: Logger, config?: LoggerConfig);
+    constructor(verdaccioLogger: Logger, config?: LoggerConfig, dryRun?: boolean);
     private shouldLog;
     private formatMessage;
     trace(message: string, ...args: any[]): void;

package/build/lib/logger.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecurityLogger = void 0;
 class SecurityLogger {
-    constructor(verdaccioLogger, config) {
-        this.prefix = '[Security Filter]';
+    constructor(verdaccioLogger, config, dryRun = false) {
+        this.prefix = dryRun ? '[Security Filter] [DRY RUN]' : '[Security Filter]';
         this.verdaccioLogger = verdaccioLogger;
         this.config = {
             level: (config === null || config === void 0 ? void 0 : config.level) || 'info',

package/build/lib/metrics.d.ts

@@ -1,12 +1,13 @@
 import { MetricsConfig, MetricsData } from '../types';
 export declare class MetricsCollector {
+    private readonly dryRun;
     private config;
     private metricsBuffer;
     private readonly bufferSize;
     private readonly maxBufferSize;
     private readonly flushIntervalMs;
     private flushTimer;
-    constructor(config?: MetricsConfig);
+    constructor(config?: MetricsConfig, dryRun?: boolean);
     record(event: MetricsData): void;
     recordBlock(packageName: string, version: string, reason: string, metadata?: Record<string, any>): void;
     recordPublishRejected(packageName: string, version: string, reason: string): void;

package/build/lib/metrics.js

@@ -37,7 +37,8 @@ exports.MetricsCollector = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 class MetricsCollector {
-    constructor(config) {
+    constructor(config, dryRun = false) {
+        this.dryRun = dryRun;
         this.metricsBuffer = [];
         this.bufferSize = 100;
         this.maxBufferSize = 500;
@@ -60,7 +61,7 @@ class MetricsCollector {
         if (this.metricsBuffer.length >= this.maxBufferSize) {
             this.flush();
         }
-        this.metricsBuffer.push(event);
+        this.metricsBuffer.push(this.dryRun ? Object.assign(Object.assign({}, event), { dryRun: true }) : event);
         if (this.metricsBuffer.length >= this.bufferSize) {
             this.flush();
         }

package/build/types.d.ts

@@ -58,6 +58,7 @@ export interface SecurityConfig extends Config {
     blockedScopes?: string[];
     versionRangeRules?: VersionRangeRule[];
     mode?: 'blacklist' | 'whitelist';
+    dryRun?: boolean;
     whitelist?: WhitelistConfig;
     licenses?: LicenseConfig;
     cveCheck?: CVECheckConfig;
@@ -100,6 +101,7 @@ export interface MetricsData {
     version?: string;
     reason: string;
     metadata?: Record<string, any>;
+    dryRun?: boolean;
 }
 export interface AuthorInfo {
     name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verdaccio-security-filter",
-  "version": "1.3.12",
+  "version": "1.4.1",
   "description": "Advanced security filter plugin for Verdaccio with version range blocking and fallback strategies",
   "main": "build/index.js",
   "types": "build/index.d.ts",