verdaccio-security-filter 1.3.11 → 1.4.0

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
@@ -406,11 +406,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 |
@@ -422,7 +441,7 @@ middlewares:
 | `cveCheck.updateInterval` | `number` | `24` | How long a package's vulnerability data is cached (hours) |
 | `cveCheck.cacheDir` | `string` | `./.security-cache` | Cache directory path |
 
-> **Note on `autoBlock` and dist-tags:** only the vulnerable versions are removed; unaffected versions stay installable. Any dist-tag (including `latest`) that points to a removed version is dropped and **not** re-pointed to another version. If `latest` is vulnerable, `npm install <pkg>` without a version or range will fail - install an explicit safe version or range instead (e.g. `npm install <pkg>@^1.2.0`).
+> **Note on removed versions and dist-tags:** whenever a check removes versions (CVE `autoBlock`, license, author, age, version rules, `whitelist.versions`), the other versions stay installable. The plugin drops every dist-tag that points to a removed version. Verdaccio then points `latest` at the highest version that is left (verified with Verdaccio 6.2), so `npm install <pkg>` keeps working. Other dist-tags that pointed to a removed version are gone.
 
 > **When OSV is unreachable:** a lookup gets one retry with a 5 second timeout each. After a failure the same package is not looked up again for 60 seconds. Previously cached data, even if older than `updateInterval`, keeps being used. With no cached data, `errorHandling.onCveCheckError` decides: `fail-open` serves the package unchecked, `fail-closed` blocks it.
 
@@ -432,7 +451,9 @@ middlewares:
 |--------|------|---------|-------------|
 | `licenses.allowed` | `string[]` | `[]` | Allowed license list |
 | `licenses.blocked` | `string[]` | `[]` | Blocked license list |
-| `licenses.requireLicense` | `boolean` | `false` | Require license field |
+| `licenses.requireLicense` | `boolean` | `true` | Reject versions without a license field |
+
+The license check runs when `licenses.allowed` is not empty. Every version is checked: versions with a rejected license are removed from the metadata, and the package is blocked as a whole only when no version is left.
 
 ### Whitelist Options
 
@@ -481,6 +502,8 @@ middlewares:
 | `authorFilter.requireVerifiedEmail` | `boolean` | `false` | Require author email information |
 | `authorFilter.warnOnly` | `boolean` | `false` | Only warn, don't block |
 
+Every version is checked against the author rules: versions published by a blocked author are removed from the metadata, and the package is blocked as a whole only when no version is left.
+
 ### Error Handling Options
 
 | Option | Type | Default | Description |

package/build/index.d.ts

@@ -23,7 +23,9 @@ export default class SecurityFilterPlugin implements IPluginMiddleware<SecurityC
     register_middlewares(app: Application, _auth: IBasicAuth<SecurityConfig>, _storage: IStorageManager<SecurityConfig>): void;
     private _blockedPackage;
     private _removeVersions;
+    private _rejectedVersions;
     filter_metadata(packageInfo: Package): Promise<Package>;
+    private _filterMetadata;
     private _versionBlockReason;
     private _checkPackageBlock;
     private _getAppliedRules;

package/build/index.js

@@ -66,8 +66,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 +90,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 +143,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,6 +230,9 @@ class SecurityFilterPlugin {
                     if (blockResult.blocked) {
                         this.logger.warn(`[Middleware] [X] BLOCKED TARBALL: ${packageName}@${version || '*'} - ${blockResult.reason}`);
                         this.metrics.recordBlock(packageName, version || '*', blockResult.reason);
+                        if (this.config.dryRun) {
+                            return next();
+                        }
                         res.status(403).json({
                             error: 'Package blocked by security filter',
                             package: packageName,
@@ -241,6 +249,9 @@ class SecurityFilterPlugin {
                     const blockResult = yield this._checkPackageBlock(packageName);
                     if (blockResult.blocked) {
                         this.logger.warn(`[Middleware] [X] BLOCKED METADATA: ${packageName} - ${blockResult.reason}`);
+                        if (this.config.dryRun) {
+                            return next();
+                        }
                         const blockedResponse = {
                             name: packageName,
                             versions: {},
@@ -306,9 +317,35 @@ class SecurityFilterPlugin {
         }
         return Object.assign(Object.assign({}, pkg), { versions, 'dist-tags': distTags });
     }
+    _rejectedVersions(pkg, check) {
+        var _a;
+        const all = Object.entries(pkg.versions || {});
+        const results = all
+            .map(([version, data]) => [version, check(data)])
+            .filter(([, result]) => !result.allowed);
+        const latest = results.find(([version]) => { var _a; return version === ((_a = pkg['dist-tags']) === null || _a === void 0 ? void 0 : _a.latest); });
+        return {
+            results,
+            versions: results.map(([version]) => version),
+            first: (_a = (latest || results[0])) === null || _a === void 0 ? void 0 : _a[1],
+            all: all.length > 0 && results.length === all.length,
+        };
+    }
     filter_metadata(packageInfo) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            const filtered = yield this._filterMetadata(packageInfo);
+            if (!this.config.dryRun || 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;
             const packageName = pkg.name;
             this.logger.debug(`[filter_metadata] --> Processing: ${packageName}`);
@@ -361,19 +398,22 @@ class SecurityFilterPlugin {
                     }
                 }
                 if (this.config.licenses && this.config.licenses.allowed && this.config.licenses.allowed.length > 0) {
-                    const latestVersion = (_c = pkg['dist-tags']) === null || _c === void 0 ? void 0 : _c.latest;
-                    if (latestVersion && ((_d = pkg.versions) === null || _d === void 0 ? void 0 : _d[latestVersion])) {
-                        const versionData = pkg.versions[latestVersion];
-                        const licenseResult = this.licenseChecker.checkLicense(versionData);
-                        if (!licenseResult.allowed) {
-                            const reason = licenseResult.reason || 'License not allowed';
-                            this.logger.warn(`[filter_metadata] LICENSE BLOCKED: ${packageName} - ${reason}`);
-                            this.metrics.recordBlock(packageName, '*', reason);
-                            return this._blockedPackage(pkg, reason, { license: licenseResult.license });
+                    const rejected = this._rejectedVersions(pkg, data => this.licenseChecker.checkLicense(data));
+                    if (rejected.all) {
+                        const reason = rejected.first.reason || 'License not allowed';
+                        this.logger.warn(`[filter_metadata] LICENSE BLOCKED: ${packageName} - ${reason}`);
+                        this.metrics.recordBlock(packageName, '*', reason);
+                        return this._blockedPackage(pkg, reason, { license: rejected.first.license });
+                    }
+                    if (rejected.versions.length > 0) {
+                        this.logger.warn(`[filter_metadata] LICENSE FILTERED: ${packageName}: ${rejected.versions.join(', ')}`);
+                        for (const [version, result] of rejected.results) {
+                            this.metrics.recordBlock(packageName, version, result.reason || 'License not allowed');
                         }
+                        pkg = this._removeVersions(pkg, rejected.versions);
                     }
                 }
-                if ((_e = this.config.packageAge) === null || _e === void 0 ? void 0 : _e.enabled) {
+                if ((_c = this.config.packageAge) === null || _c === void 0 ? void 0 : _c.enabled) {
                     const ageResult = this.packageAgeChecker.checkPackageAge(pkg);
                     if (!ageResult.allowed && !ageResult.warnOnly) {
                         const reason = ageResult.reason || 'Package too new';
@@ -400,33 +440,38 @@ class SecurityFilterPlugin {
                         pkg = this._removeVersions(pkg, removedVersions);
                     }
                 }
-                if ((_f = this.config.authorFilter) === null || _f === void 0 ? void 0 : _f.enabled) {
-                    const latestVersion = (_g = pkg['dist-tags']) === null || _g === void 0 ? void 0 : _g.latest;
-                    if (latestVersion && ((_h = pkg.versions) === null || _h === void 0 ? void 0 : _h[latestVersion])) {
-                        const versionData = pkg.versions[latestVersion];
-                        const authorResult = this.authorChecker.checkAuthor(versionData);
-                        if (!authorResult.allowed && !this.config.authorFilter.warnOnly) {
-                            const reason = authorResult.reason || 'Author not allowed';
-                            this.logger.warn(`[filter_metadata] AUTHOR BLOCKED: ${packageName} - ${reason}`);
+                if ((_d = this.config.authorFilter) === null || _d === void 0 ? void 0 : _d.enabled) {
+                    const rejected = this._rejectedVersions(pkg, data => this.authorChecker.checkAuthor(data));
+                    if (rejected.versions.length > 0 && this.config.authorFilter.warnOnly) {
+                        this.logger.warn(`[filter_metadata] AUTHOR WARNING: ${packageName}: ${rejected.versions.join(', ')} - ${rejected.first.reason} (warn-only mode)`);
+                    }
+                    else if (rejected.versions.length > 0) {
+                        for (const [version, result] of rejected.results) {
                             this.metrics.record({
                                 timestamp: new Date().toISOString(),
                                 event: 'author_blocked',
                                 packageName,
-                                version: latestVersion,
-                                reason,
+                                version: rejected.all ? '*' : version,
+                                reason: result.reason || 'Author not allowed',
                                 metadata: {
-                                    blockedBy: authorResult.blockedBy,
-                                    authorInfo: authorResult.authorInfo,
+                                    blockedBy: result.blockedBy,
+                                    authorInfo: result.authorInfo,
                                 },
                             });
+                            if (rejected.all) {
+                                break;
+                            }
+                        }
+                        if (rejected.all) {
+                            const reason = rejected.first.reason || 'Author not allowed';
+                            this.logger.warn(`[filter_metadata] AUTHOR BLOCKED: ${packageName} - ${reason}`);
                             return this._blockedPackage(pkg, reason, {
-                                blockedBy: authorResult.blockedBy,
-                                authorInfo: authorResult.authorInfo,
+                                blockedBy: rejected.first.blockedBy,
+                                authorInfo: rejected.first.authorInfo,
                             });
                         }
-                        else if (!authorResult.allowed && this.config.authorFilter.warnOnly) {
-                            this.logger.warn(`[filter_metadata] AUTHOR WARNING: ${packageName} - ${authorResult.reason} (warn-only mode)`);
-                        }
+                        this.logger.warn(`[filter_metadata] AUTHOR FILTERED: ${packageName}: ${rejected.versions.join(', ')}`);
+                        pkg = this._removeVersions(pkg, rejected.versions);
                     }
                 }
                 this.logger.debug(`[filter_metadata] [OK] ALLOWED: ${packageName}`);
@@ -434,7 +479,7 @@ class SecurityFilterPlugin {
             }
             catch (error) {
                 this.logger.error(`[filter_metadata] Error processing ${packageName}: ${error.message}`);
-                const errorStrategy = ((_j = this.config.errorHandling) === null || _j === void 0 ? void 0 : _j.onFilterError) || 'fail-open';
+                const errorStrategy = ((_e = this.config.errorHandling) === null || _e === void 0 ? void 0 : _e.onFilterError) || 'fail-open';
                 if (errorStrategy === 'fail-closed') {
                     this.logger.warn(`[filter_metadata] Error handling: fail-closed - BLOCKING ${packageName}`);
                     this.metrics.recordBlock(packageName, '*', `Error during processing: ${error.message}`);

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.11",
+  "version": "1.4.0",
   "description": "Advanced security filter plugin for Verdaccio with version range blocking and fallback strategies",
   "main": "build/index.js",
   "types": "build/index.d.ts",