@maverick006/security-engine 1.0.2 → 1.0.4

package/dist/scoring.js

@@ -3,69 +3,139 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateScore = calculateScore;
 const types_1 = require("@maverick006/types");
 /**
- * Calculates a deterministic security score and grade based on the volume and severity of findings.
- * Weights: CRITICAL=100, HIGH=20, MEDIUM=5, LOW=1
+ * Calculates a deterministic, reproducible security score (0 to 100) and grade
+ * based on the volume and severity of unique findings.
  *
- * Grade thresholds:
- * A: <= 10  (e.g., up to 2 mediums, or 10 lows)
- * B: <= 30  (e.g., 1 high, or several mediums)
- * C: <= 70  (e.g., 3 highs)
- * D: <= 150 (e.g., many highs, but no criticals. Or 1 critical and nothing else = 100, wait, 1 critical is auto F)
- * F: > 150 OR any CRITICAL finding.
+ * Rules:
+ * - Base score: 100
+ * - Critical: -30 points per finding (any critical forces Grade F and caps score at <= 49)
+ * - High: -10 points per finding
+ * - Medium: -3 points per finding
+ * - Low: -1 point per finding
+ * - Info: 0 points
+ *
+ * Grades:
+ * A: 90 - 100
+ * B: 80 - 89
+ * C: 70 - 79
+ * D: 50 - 69
+ * F: < 50 OR any CRITICAL finding
  */
-function calculateScore(findings) {
+function calculateScore(findings, coverage) {
     let critical = 0;
     let high = 0;
     let medium = 0;
     let low = 0;
-    let score = 0;
+    let info = 0;
     for (const finding of findings) {
-        switch (finding.severity) {
+        const sev = (finding.severity || '').toUpperCase();
+        switch (sev) {
             case types_1.Severity.CRITICAL:
+            case 'CRITICAL':
                 critical++;
-                score += 100;
                 break;
             case types_1.Severity.HIGH:
+            case 'HIGH':
                 high++;
-                score += 20;
                 break;
             case types_1.Severity.MEDIUM:
+            case 'MEDIUM':
                 medium++;
-                score += 5;
                 break;
             case types_1.Severity.LOW:
-            case types_1.Severity.INFO:
+            case 'LOW':
                 low++;
-                score += 1;
+                break;
+            default:
+                info++;
                 break;
         }
     }
+    const critDeduction = critical * 30;
+    const highDeduction = high * 10;
+    const medDeduction = medium * 3;
+    const lowDeduction = low * 1;
+    const totalDeductions = critDeduction + highDeduction + medDeduction + lowDeduction;
+    let rawScore = 100 - totalDeductions;
+    let score = Math.max(0, Math.min(100, rawScore));
+    const explanation = [
+        'Baseline score: 100/100'
+    ];
+    if (critical > 0) {
+        explanation.push(`-${critDeduction} points: ${critical} Critical severity ${critical === 1 ? 'finding' : 'findings'} (-30 pts each)`);
+    }
+    if (high > 0) {
+        explanation.push(`-${highDeduction} points: ${high} High severity ${high === 1 ? 'finding' : 'findings'} (-10 pts each)`);
+    }
+    if (medium > 0) {
+        explanation.push(`-${medDeduction} points: ${medium} Medium severity ${medium === 1 ? 'finding' : 'findings'} (-3 pts each)`);
+    }
+    if (low > 0) {
+        explanation.push(`-${lowDeduction} points: ${low} Low severity ${low === 1 ? 'finding' : 'findings'} (-1 pt each)`);
+    }
+    if (findings.length === 0) {
+        explanation.push('No security findings identified across executed scanners (+0 deductions)');
+    }
     let grade = 'A';
     if (critical > 0) {
-        // A single CRITICAL vulnerability drops the grade to F immediately.
+        // Critical vulnerability automatically caps grade to F and score to at most 49
         grade = 'F';
+        score = Math.min(score, 49);
+        explanation.push(`Grade Override: F (1 or more Critical severity findings detected)`);
     }
-    else if (score > 150) {
-        grade = 'F';
+    else if (score >= 90) {
+        grade = 'A';
     }
-    else if (score > 70) {
-        grade = 'D';
+    else if (score >= 80) {
+        grade = 'B';
     }
-    else if (score > 30) {
+    else if (score >= 70) {
         grade = 'C';
     }
-    else if (score > 10) {
-        grade = 'B';
+    else if (score >= 50) {
+        grade = 'D';
+    }
+    else {
+        grade = 'F';
     }
+    explanation.push(`Final deterministic score: ${score}/100 (Grade ${grade})`);
+    const deductions = {
+        critical: critDeduction,
+        high: highDeduction,
+        medium: medDeduction,
+        low: lowDeduction,
+        info: 0,
+        totalDeductions
+    };
+    const defaultCoverage = {
+        code: false,
+        dependencies: false,
+        secrets: false,
+        containers: false,
+        iac: false,
+        web: false,
+        cloud: false,
+        ...coverage
+    };
     return {
         score,
         grade,
-        metrics: {
+        deductions,
+        breakdown: {
             critical,
             high,
             medium,
             low,
-        }
+            info
+        },
+        metrics: {
+            critical,
+            high,
+            medium,
+            low
+        },
+        coverage: defaultCoverage,
+        explanation
     };
 }
 //# sourceMappingURL=scoring.js.map

package/dist/scoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"scoring.js","sourceRoot":"","sources":["../src/scoring.ts"],"names":[],"mappings":";;AAwBA,wCAsDC;AA9ED,8CAAiE;AAajE;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,QAA6B;IAC1D,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,QAAQ,OAAO,CAAC,QAAQ,EAAE,CAAC;YACzB,KAAK,gBAAQ,CAAC,QAAQ;gBACpB,QAAQ,EAAE,CAAC;gBACX,KAAK,IAAI,GAAG,CAAC;gBACb,MAAM;YACR,KAAK,gBAAQ,CAAC,IAAI;gBAChB,IAAI,EAAE,CAAC;gBACP,KAAK,IAAI,EAAE,CAAC;gBACZ,MAAM;YACR,KAAK,gBAAQ,CAAC,MAAM;gBAClB,MAAM,EAAE,CAAC;gBACT,KAAK,IAAI,CAAC,CAAC;gBACX,MAAM;YACR,KAAK,gBAAQ,CAAC,GAAG,CAAC;YAClB,KAAK,gBAAQ,CAAC,IAAI;gBAChB,GAAG,EAAE,CAAC;gBACN,KAAK,IAAI,CAAC,CAAC;gBACX,MAAM;QACV,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAyB,GAAG,CAAC;IAEtC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,oEAAoE;QACpE,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;SAAM,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QACvB,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;SAAM,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACtB,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;SAAM,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACtB,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;SAAM,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACtB,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;IAED,OAAO;QACL,KAAK;QACL,KAAK;QACL,OAAO,EAAE;YACP,QAAQ;YACR,IAAI;YACJ,MAAM;YACN,GAAG;SACJ;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"scoring.js","sourceRoot":"","sources":["../src/scoring.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@maverick006/security-engine",
-  "version": "1.0.2",
+  "version": "1.0.4",
+  "description": "VibeGuard Security Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -10,12 +11,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@maverick006/types": "*"
+    "@maverick006/types": "*",
+    "typescript": "^5.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
     "jest": "^29.5.0",
     "@types/jest": "^29.5.0",
     "ts-jest": "^29.1.0"
   }
-}
+}

package/src/deduplication.ts

@@ -0,0 +1,118 @@
+import { NormalizedFinding, Severity } from '@maverick006/types';
+
+/**
+ * Options for finding deduplication.
+ */
+export interface DeduplicationOptions {
+  lineTolerance?: number; // default +/- 3 lines
+}
+
+/**
+ * Normalizes a rule or CVE identifier to detect cross-scanner duplicates.
+ */
+function normalizeIdentifier(finding: NormalizedFinding): string {
+  // If CVE or CWE is present, prioritize that as universal identifier
+  const cveMatch = (finding.ruleId || finding.title || finding.description || '').match(/CVE-\d{4}-\d+/i);
+  if (cveMatch) {
+    return cveMatch[0].toUpperCase();
+  }
+
+  // If package-based vulnerability, match package + cwe/rule
+  if (finding.package) {
+    const pkg = finding.package.toLowerCase();
+    const cwe = finding.cwe ? finding.cwe.toLowerCase() : '';
+    return `pkg:${pkg}:${cwe || finding.ruleId || 'vuln'}`;
+  }
+
+  // Generic rule ID fallback
+  return (finding.ruleId || finding.title || 'unknown').toLowerCase().trim();
+}
+
+/**
+ * Normalizes file paths for reliable cross-platform comparison.
+ */
+function normalizeFilePath(filePath?: string): string {
+  if (!filePath) return '';
+  return filePath.replace(/\\/g, '/').toLowerCase().trim();
+}
+
+/**
+ * Merges two findings for the same vulnerability, retaining the highest confidence and most complete metadata.
+ */
+function mergeFindings(primary: NormalizedFinding, secondary: NormalizedFinding): NormalizedFinding {
+  return {
+    ...primary,
+    // Keep the more severe or primary severity
+    severity: primary.severity || secondary.severity,
+    confidence: primary.confidence || secondary.confidence,
+    cwe: primary.cwe || secondary.cwe,
+    owasp: primary.owasp || secondary.owasp,
+    remediation: primary.remediation || secondary.remediation,
+    codeSnippet: primary.codeSnippet || secondary.codeSnippet,
+    package: primary.package || secondary.package,
+    packageVersion: primary.packageVersion || secondary.packageVersion,
+    fixedVersion: primary.fixedVersion || secondary.fixedVersion,
+    references: Array.from(new Set([...(primary.references || []), ...(secondary.references || [])])),
+    // Note in scanner if multiple scanners detected it
+    scanner: primary.scanner.includes(secondary.scanner)
+      ? primary.scanner
+      : `${primary.scanner}, ${secondary.scanner}`
+  };
+}
+
+/**
+ * Deduplicates findings across multiple scanners:
+ * 1. Exact duplicates (same scanner, file, rule, line).
+ * 2. Cross-scanner duplicates (e.g. Trivy & npm-audit reporting the same CVE or package vuln).
+ * 3. Line shift tolerance (+/- 3 lines) to handle minor offset differences.
+ * 4. Preserves distinct vulnerabilities on the same file/line.
+ */
+export function deduplicateFindings(
+  findings: NormalizedFinding[],
+  options: DeduplicationOptions = {}
+): NormalizedFinding[] {
+  const lineTolerance = options.lineTolerance ?? 3;
+  const deduplicated: NormalizedFinding[] = [];
+
+  for (const candidate of findings) {
+    const candidateFile = normalizeFilePath(candidate.file);
+    const candidateId = normalizeIdentifier(candidate);
+    const candidateLine = candidate.line || 0;
+
+    let matchedIndex = -1;
+
+    for (let i = 0; i < deduplicated.length; i++) {
+      const existing = deduplicated[i];
+      const existingFile = normalizeFilePath(existing.file);
+      const existingId = normalizeIdentifier(existing);
+      const existingLine = existing.line || 0;
+
+      // Check for same file & same vulnerability identity
+      const isSameFile = candidateFile && existingFile ? candidateFile === existingFile : true;
+      const isSameVuln = candidateId === existingId;
+
+      if (isSameFile && isSameVuln) {
+        // If line numbers exist, check line tolerance
+        if (candidateLine > 0 && existingLine > 0) {
+          if (Math.abs(candidateLine - existingLine) <= lineTolerance) {
+            matchedIndex = i;
+            break;
+          }
+        } else {
+          // If either lacks line numbers (e.g. package/repo level), treat as match
+          matchedIndex = i;
+          break;
+        }
+      }
+    }
+
+    if (matchedIndex >= 0) {
+      // Merge with existing finding
+      deduplicated[matchedIndex] = mergeFindings(deduplicated[matchedIndex], candidate);
+    } else {
+      deduplicated.push({ ...candidate });
+    }
+  }
+
+  return deduplicated;
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './scanner';
 export * from './orchestrator';
 export * from './scoring';
+export * from './deduplication';

package/src/orchestrator.ts

@@ -1,75 +1,212 @@
-import { NormalizedFinding, ScanInput, ScannerResult } from '@maverick006/types';
+import { NormalizedFinding, ScanInput, ScannerResult, ScannerState, ScannerCoverage } from '@maverick006/types';
 import { SecurityScanner } from './scanner';
+import { deduplicateFindings } from './deduplication';
+
+export interface OrchestratorOptions {
+  concurrencyLimit?: number; // default: 3
+  timeoutMs?: number;        // default: 120,000ms (2 mins per scanner)
+}
+
+export interface OrchestratedScanResult extends ScannerResult {
+  scannerResults: ScannerResult[];
+  coverage: ScannerCoverage;
+}
+
+/**
+ * Runs tasks with a bounded concurrency pool (no unlimited Promise.all).
+ */
+async function runWithConcurrencyLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let currentIndex = 0;
+
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (currentIndex < items.length) {
+      const index = currentIndex++;
+      results[index] = await fn(items[index]);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Wraps a promise with a timeout.
+ */
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, scannerName: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const err = new Error(`Scanner ${scannerName} timed out after ${timeoutMs}ms`);
+      (err as any).code = 'ETIMEDOUT';
+      reject(err);
+    }, timeoutMs);
+
+    promise
+      .then(val => {
+        clearTimeout(timer);
+        resolve(val);
+      })
+      .catch(err => {
+        clearTimeout(timer);
+        reject(err);
+      });
+  });
+}
 
 /**
  * Orchestrates the execution of multiple security scanners and aggregates/deduplicates their findings.
  */
 export class Orchestrator {
   private scanners: SecurityScanner[] = [];
+  private options: OrchestratorOptions;
 
-  constructor(scanners: SecurityScanner[]) {
+  constructor(scanners: SecurityScanner[], options: OrchestratorOptions = {}) {
     this.scanners = scanners;
+    this.options = {
+      concurrencyLimit: options.concurrencyLimit ?? 3,
+      timeoutMs: options.timeoutMs ?? 120_000
+    };
   }
 
   /**
-   * Executes all registered scanners against the given input.
+   * Executes registered scanners using a bounded concurrency pool.
    */
-  async runScan(input: ScanInput): Promise<ScannerResult> {
+  async runScan(input: ScanInput): Promise<OrchestratedScanResult> {
     const startTime = new Date();
-    
-    // Execute all scanners concurrently
-    const scanPromises = this.scanners.map(scanner => scanner.scan(input));
-    const results = await Promise.allSettled(scanPromises);
-    
+    const concurrency = this.options.concurrencyLimit ?? 3;
+    const timeout = this.options.timeoutMs ?? 120_000;
+
+    const executeScanner = async (scanner: SecurityScanner): Promise<ScannerResult> => {
+      const scanStart = new Date();
+
+      // Check applicability if scanner provides capability detection
+      if (scanner.capabilities?.detectApplicability) {
+        try {
+          const isApplicable = await scanner.capabilities.detectApplicability(input.repositoryPath, input);
+          if (!isApplicable) {
+            const scanEnd = new Date();
+            return {
+              scanner: scanner.name,
+              success: true,
+              state: ScannerState.SKIPPED,
+              reason: `Skipped: Not applicable to repository or target`,
+              findings: [],
+              startTime: scanStart,
+              endTime: scanEnd,
+              durationMs: scanEnd.getTime() - scanStart.getTime()
+            };
+          }
+        } catch (err: any) {
+          console.warn(`Applicability check error for ${scanner.name}:`, err.message);
+        }
+      }
+
+      try {
+        const scanPromise = scanner.scan(input);
+        const result = await withTimeout(scanPromise, timeout, scanner.name);
+        const scanEnd = new Date();
+
+        return {
+          ...result,
+          state: result.state || (result.success ? ScannerState.SUCCESS : ScannerState.FAILED),
+          durationMs: scanEnd.getTime() - scanStart.getTime(),
+          endTime: scanEnd
+        };
+      } catch (err: any) {
+        const scanEnd = new Date();
+        const durationMs = scanEnd.getTime() - scanStart.getTime();
+
+        if (err.code === 'ETIMEDOUT') {
+          return {
+            scanner: scanner.name,
+            success: false,
+            state: ScannerState.TIMEOUT,
+            error: err.message,
+            reason: `Execution exceeded timeout of ${timeout}ms`,
+            findings: [],
+            startTime: scanStart,
+            endTime: scanEnd,
+            durationMs
+          };
+        }
+
+        if (err.code === 'ENOENT') {
+          return {
+            scanner: scanner.name,
+            success: false,
+            state: ScannerState.NOT_INSTALLED,
+            error: err.message,
+            reason: `Scanner executable was not found on PATH`,
+            findings: [],
+            startTime: scanStart,
+            endTime: scanEnd,
+            durationMs
+          };
+        }
+
+        return {
+          scanner: scanner.name,
+          success: false,
+          state: ScannerState.FAILED,
+          error: err.message || String(err),
+          findings: [],
+          startTime: scanStart,
+          endTime: scanEnd,
+          durationMs
+        };
+      }
+    };
+
+    // Execute through bounded concurrency worker pool
+    const scannerResults = await runWithConcurrencyLimit(this.scanners, concurrency, executeScanner);
+
     let allFindings: NormalizedFinding[] = [];
     const rawOutputs: Record<string, string> = {};
-    
-    for (let i = 0; i < results.length; i++) {
-      const result = results[i];
-      const scannerName = this.scanners[i].name;
 
-      if (result.status === 'fulfilled') {
-        const data = result.value;
+    for (const data of scannerResults) {
+      if (data.findings && data.findings.length > 0) {
         allFindings = allFindings.concat(data.findings);
-        if (data.rawOutput) {
-          rawOutputs[scannerName] = data.rawOutput;
-        }
-      } else {
-        // Log scanner failure safely (in production this would use a proper logger)
-        console.error(`Scanner ${scannerName} failed:`, result.reason);
+      }
+      if (data.rawOutput) {
+        rawOutputs[data.scanner] = data.rawOutput;
       }
     }
 
-    const deduplicatedFindings = this.deduplicateFindings(allFindings);
+    // High-precision deduplication across scanners with line tolerance
+    const deduplicatedFindings = deduplicateFindings(allFindings);
+
+    // Standardize finding IDs to VG-FIND-001, VG-FIND-002, etc.
+    deduplicatedFindings.forEach((finding, index) => {
+      finding.id = `VG-FIND-${String(index + 1).padStart(3, '0')}`;
+    });
+
+    // Compute coverage matrix based on successful scanner executions
+    const coverage: ScannerCoverage = {
+      code: scannerResults.some(r => r.scanner.toLowerCase().includes('semgrep') && r.state === ScannerState.SUCCESS),
+      dependencies: scannerResults.some(r => (r.scanner.toLowerCase().includes('npm') || r.scanner.toLowerCase().includes('audit') || r.scanner.toLowerCase().includes('trivy')) && r.state === ScannerState.SUCCESS),
+      secrets: scannerResults.some(r => r.scanner.toLowerCase().includes('gitleaks') && r.state === ScannerState.SUCCESS),
+      containers: scannerResults.some(r => r.scanner.toLowerCase().includes('trivy') && r.state === ScannerState.SUCCESS),
+      iac: scannerResults.some(r => r.scanner.toLowerCase().includes('checkov') && r.state === ScannerState.SUCCESS),
+      web: scannerResults.some(r => r.scanner.toLowerCase().includes('zap') && r.state === ScannerState.SUCCESS),
+      cloud: scannerResults.some(r => (r.scanner.toLowerCase().includes('prowler') || r.scanner.toLowerCase().includes('cspm')) && r.state === ScannerState.SUCCESS)
+    };
 
+    const endTime = new Date();
     return {
       scanner: 'VibeGuard_Orchestrator',
-      success: true,
+      success: scannerResults.some(r => r.state === ScannerState.SUCCESS),
+      state: ScannerState.SUCCESS,
+      durationMs: endTime.getTime() - startTime.getTime(),
       findings: deduplicatedFindings,
-      rawOutput: JSON.stringify(rawOutputs), // Aggregate raw outputs
+      scannerResults,
+      coverage,
+      rawOutput: JSON.stringify(rawOutputs),
       startTime,
-      endTime: new Date()
+      endTime
     };
   }
-
-  /**
-   * Deduplicates findings based on a fingerprint generated from ruleId, file, line, and column.
-   */
-  private deduplicateFindings(findings: NormalizedFinding[]): NormalizedFinding[] {
-    const unique = new Map<string, NormalizedFinding>();
-    
-    for (const finding of findings) {
-      // Create a unique fingerprint for the finding
-      const fingerprint = `${finding.ruleId}-${finding.file}-${finding.line}-${finding.column}`;
-      
-      if (!unique.has(fingerprint)) {
-        unique.set(fingerprint, finding);
-      } else {
-        // If it already exists, we might want to merge information, but for now we keep the first one
-        // Optionally, if the new one has higher confidence, we could replace it.
-      }
-    }
-
-    return Array.from(unique.values());
-  }
 }

package/src/scanner.ts

@@ -1,5 +1,11 @@
 import { ScanInput, ScannerResult } from '@maverick006/types';
 
+export interface ScannerCapability {
+  category: 'code' | 'dependencies' | 'secrets' | 'containers' | 'iac' | 'web' | 'cloud';
+  requiresCredentials?: boolean;
+  detectApplicability?: (repoPath: string, input?: ScanInput) => Promise<boolean> | boolean;
+}
+
 /**
  * Base interface that all VibeGuard scanners must implement.
  * This provides the core abstraction allowing new scanners to be added
@@ -16,6 +22,11 @@ export interface SecurityScanner {
    */
   version?: string;
 
+  /**
+   * Optional capability metadata and applicability detection.
+   */
+  capabilities?: ScannerCapability;
+
   /**
    * Executes the scanner against the given input.
    *