verdaccio-security-filter 1.3.12 → 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 |

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

@@ -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: {},
@@ -321,6 +332,18 @@ class SecurityFilterPlugin {
         };
     }
     filter_metadata(packageInfo) {
+        return __awaiter(this, void 0, void 0, function* () {
+            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;

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