guardrail-security 1.0.1 → 2.0.0

package/dist/supply-chain/vulnerability-db.d.ts

@@ -1,16 +1,30 @@
 /**
  * Vulnerability Database Integration
  *
- * Integrates with multiple vulnerability databases:
- * - OSV (Open Source Vulnerabilities)
- * - GitHub Security Advisories
- * - NVD (National Vulnerability Database)
+ * Real-time OSV (Open Source Vulnerabilities) integration with:
+ * - Multi-ecosystem support (npm, PyPI, RubyGems, Go)
+ * - Persistent caching with 24h TTL
+ * - Batch request optimization
+ * - CVSS scoring and vectors
+ * - Remediation path analysis
+ * - Optional NVD enrichment for CVE details
+ * - Retry logic with exponential backoff
+ * - Configurable timeouts
  */
+export interface VulnerabilityDbOptions {
+    noCache?: boolean;
+    nvdEnrichment?: boolean;
+    timeout?: number;
+    retries?: number;
+    cacheDir?: string;
+}
+export type Ecosystem = 'npm' | 'PyPI' | 'RubyGems' | 'Go';
 export interface Vulnerability {
     id: string;
     source: 'osv' | 'github' | 'nvd' | 'npm';
     severity: 'low' | 'medium' | 'high' | 'critical';
     cvssScore?: number;
+    cvssVector?: string;
     title: string;
     description: string;
     affectedVersions: string[];
@@ -19,6 +33,7 @@ export interface Vulnerability {
     publishedAt: Date;
     updatedAt: Date;
     cwe?: string[];
+    aliases?: string[];
 }
 export interface VulnerabilityCheckResult {
     package: string;
@@ -27,6 +42,13 @@ export interface VulnerabilityCheckResult {
     isVulnerable: boolean;
     highestSeverity: 'none' | 'low' | 'medium' | 'high' | 'critical';
     recommendedVersion?: string;
+    isDirect: boolean;
+    remediationPath?: {
+        action: 'upgrade' | 'replace' | 'remove';
+        targetVersion?: string;
+        breakingChange: boolean;
+        description: string;
+    };
 }
 export interface VulnerabilityReport {
     projectPath: string;
@@ -40,37 +62,77 @@ export interface VulnerabilityReport {
         medium: number;
         low: number;
     };
+    ecosystem: Ecosystem;
+    directVulnerabilities: number;
+    transitiveVulnerabilities: number;
+    cacheHitRate?: number;
 }
 export declare class VulnerabilityDatabase {
     private osvApiUrl;
-    private npmAuditUrl;
+    private cacheDir;
+    private cachePath;
+    private memoryCache;
+    private cacheHits;
+    private cacheMisses;
+    private options;
+    constructor(cacheDirOrOptions?: string | VulnerabilityDbOptions);
+    /**
+     * Update options at runtime
+     */
+    setOptions(options: Partial<VulnerabilityDbOptions>): void;
+    /**
+     * Load cache from disk
+     */
+    private loadDiskCache;
+    /**
+     * Save cache to disk
+     */
+    private saveDiskCache;
     /**
      * Check a single package for vulnerabilities
      */
-    checkPackage(name: string, version: string): Promise<VulnerabilityCheckResult>;
+    checkPackage(name: string, version: string, ecosystem?: Ecosystem, isDirect?: boolean): Promise<VulnerabilityCheckResult>;
     /**
-     * Check multiple packages in bulk
+     * Check multiple packages in bulk with batching
      */
     checkPackages(packages: {
         name: string;
         version: string;
+        ecosystem?: Ecosystem;
+        isDirect?: boolean;
     }[]): Promise<VulnerabilityCheckResult[]>;
+    /**
+     * Query OSV with retry logic and exponential backoff
+     */
+    private queryOSVWithRetry;
     /**
      * Query OSV (Open Source Vulnerabilities) API
      */
     private queryOSV;
     /**
-     * Parse OSV API response
+     * Enrich vulnerabilities with NVD data (CVSS scores)
      */
-    private parseOSVResponse;
+    private enrichWithNVD;
     /**
-     * Query npm audit API
+     * Query NVD API for CVE details
      */
-    private queryNpmAudit;
+    private queryNVD;
     /**
-     * Parse npm audit response
+     * Map CVSS score to severity level
      */
-    private parseNpmAuditResponse;
+    private mapCVSSSeverity;
+    /**
+     * Delay helper for retry backoff
+     */
+    private delay;
+    /**
+     * Parse OSV API response
+     */
+    private parseOSVResponse;
+    /**
+     * Check if a version is affected by vulnerability ranges
+     */
+    private isVersionAffected;
     /**
      * Map OSV severity to standard levels
      */
@@ -84,9 +146,9 @@ export declare class VulnerabilityDatabase {
      */
     private extractPatchedVersions;
     /**
-     * Deduplicate vulnerabilities by ID
+     * Calculate remediation path for a vulnerability
      */
-    private deduplicateVulnerabilities;
+    private calculateRemediationPath;
     /**
      * Build result object
      */
@@ -97,17 +159,28 @@ export declare class VulnerabilityDatabase {
     generateReport(projectPath: string, packages: {
         name: string;
         version: string;
-    }[]): Promise<VulnerabilityReport>;
+        ecosystem?: Ecosystem;
+        isDirect?: boolean;
+    }[], ecosystem?: Ecosystem): Promise<VulnerabilityReport>;
     /**
      * Clear vulnerability cache
      */
     clearCache(): void;
+    /**
+     * Clear entire cache directory
+     */
+    static clearCacheDirectory(cacheDir?: string): {
+        success: boolean;
+        path: string;
+        error?: string;
+    };
     /**
      * Get cache statistics
      */
     getCacheStats(): {
         size: number;
         oldestEntry: Date | null;
+        hitRate: number;
     };
 }
 export declare const vulnerabilityDatabase: VulnerabilityDatabase;

package/dist/supply-chain/vulnerability-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vulnerability-db.d.ts","sourceRoot":"","sources":["../../src/supply-chain/vulnerability-db.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;IACzC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,IAAI,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,IAAI,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH;AAKD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,WAAW,CAAkE;IAIrF;;OAEG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAoCpF;;OAEG;IACG,aAAa,CAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAevG;;OAEG;YACW,QAAQ;IA6BtB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;OAEG;YACW,aAAa;IAyB3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAsB9B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAWlC;;OAEG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA4BtH;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE;CAY5D;AAGD,eAAO,MAAM,qBAAqB,uBAA8B,CAAC"}
+{"version":3,"file":"vulnerability-db.d.ts","sourceRoot":"","sources":["../../src/supply-chain/vulnerability-db.ts"],"names":[],"mappings":"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"}