@maverick006/security-engine 1.0.2 → 1.0.4

package/src/scoring.ts

@@ -1,8 +1,6 @@
-import { NormalizedFinding, Severity } from '@maverick006/types';
+import { NormalizedFinding, Severity, ScannerCoverage, DeterministicScore, ScoreDeductions } from '@maverick006/types';
 
-export interface ScoreResult {
-  score: number;
-  grade: 'A' | 'B' | 'C' | 'D' | 'F';
+export interface ScoreResult extends DeterministicScore {
   metrics: {
     critical: number;
     high: number;
@@ -12,68 +10,147 @@ export interface ScoreResult {
 }
 
 /**
- * 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
  */
-export function calculateScore(findings: NormalizedFinding[]): ScoreResult {
+export function calculateScore(
+  findings: NormalizedFinding[],
+  coverage?: Partial<ScannerCoverage>
+): ScoreResult {
   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 Severity.CRITICAL:
+      case 'CRITICAL':
         critical++;
-        score += 100;
         break;
       case Severity.HIGH:
+      case 'HIGH':
         high++;
-        score += 20;
         break;
       case Severity.MEDIUM:
+      case 'MEDIUM':
         medium++;
-        score += 5;
         break;
       case Severity.LOW:
-      case 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: string[] = [
+    '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: ScoreResult['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';
-  } else if (score > 150) {
-    grade = 'F';
-  } else if (score > 70) {
-    grade = 'D';
-  } else if (score > 30) {
-    grade = 'C';
-  } else if (score > 10) {
+    score = Math.min(score, 49);
+    explanation.push(`Grade Override: F (1 or more Critical severity findings detected)`);
+  } else if (score >= 90) {
+    grade = 'A';
+  } else if (score >= 80) {
     grade = 'B';
+  } else if (score >= 70) {
+    grade = 'C';
+  } else if (score >= 50) {
+    grade = 'D';
+  } else {
+    grade = 'F';
   }
 
+  explanation.push(`Final deterministic score: ${score}/100 (Grade ${grade})`);
+
+  const deductions: ScoreDeductions = {
+    critical: critDeduction,
+    high: highDeduction,
+    medium: medDeduction,
+    low: lowDeduction,
+    info: 0,
+    totalDeductions
+  };
+
+  const defaultCoverage: ScannerCoverage = {
+    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
   };
 }

package/tests/deduplication.test.ts

@@ -0,0 +1,122 @@
+import { deduplicateFindings } from '../src/deduplication';
+import { NormalizedFinding, Severity } from '@maverick006/types';
+
+describe('Cross-Scanner Deduplication Engine', () => {
+  it('should remove exact duplicate findings from the same scanner', () => {
+    const findings: NormalizedFinding[] = [
+      {
+        scanner: 'Semgrep',
+        ruleId: 'sql-injection',
+        title: 'SQL Injection in Query',
+        description: 'User input concatenation',
+        severity: Severity.CRITICAL,
+        file: 'src/db.ts',
+        line: 42,
+        column: 10
+      },
+      {
+        scanner: 'Semgrep',
+        ruleId: 'sql-injection',
+        title: 'SQL Injection in Query',
+        description: 'User input concatenation',
+        severity: Severity.CRITICAL,
+        file: 'src/db.ts',
+        line: 42,
+        column: 10
+      }
+    ];
+
+    const result = deduplicateFindings(findings);
+    expect(result).toHaveLength(1);
+    expect(result[0].scanner).toBe('Semgrep');
+  });
+
+  it('should deduplicate cross-scanner findings with same CVE on same file/package', () => {
+    const findings: NormalizedFinding[] = [
+      {
+        scanner: 'npm-audit',
+        ruleId: 'CVE-2023-45133',
+        title: 'CVE-2023-45133 in @babel/traverse',
+        description: 'Arbitrary code execution via traverse',
+        severity: Severity.HIGH,
+        package: '@babel/traverse',
+        packageVersion: '7.23.0',
+        fixedVersion: '7.23.2',
+        file: 'package-lock.json'
+      },
+      {
+        scanner: 'Trivy',
+        ruleId: 'CVE-2023-45133',
+        title: 'Babel traverse code execution (CVE-2023-45133)',
+        description: 'Arbitrary code execution in babel/traverse',
+        severity: Severity.HIGH,
+        package: '@babel/traverse',
+        packageVersion: '7.23.0',
+        fixedVersion: '7.23.2',
+        file: 'package-lock.json'
+      }
+    ];
+
+    const result = deduplicateFindings(findings);
+    expect(result).toHaveLength(1);
+    expect(result[0].scanner).toContain('npm-audit');
+    expect(result[0].scanner).toContain('Trivy');
+    expect(result[0].package).toBe('@babel/traverse');
+  });
+
+  it('should deduplicate findings with nearby line shifts (+/- 3 lines)', () => {
+    const findings: NormalizedFinding[] = [
+      {
+        scanner: 'Semgrep',
+        ruleId: 'hardcoded-secret',
+        title: 'Hardcoded API Token',
+        description: 'Detected high entropy string',
+        severity: Severity.HIGH,
+        file: 'src/config.ts',
+        line: 15
+      },
+      {
+        scanner: 'Gitleaks',
+        ruleId: 'hardcoded-secret',
+        title: 'Generic API Key',
+        description: 'Detected secret key',
+        severity: Severity.HIGH,
+        file: 'src/config.ts',
+        line: 17 // within 2 lines
+      }
+    ];
+
+    const result = deduplicateFindings(findings, { lineTolerance: 3 });
+    expect(result).toHaveLength(1);
+    expect(result[0].scanner).toContain('Semgrep');
+    expect(result[0].scanner).toContain('Gitleaks');
+  });
+
+  it('should preserve distinct vulnerabilities on the same file and line', () => {
+    const findings: NormalizedFinding[] = [
+      {
+        scanner: 'Semgrep',
+        ruleId: 'sqli-rule-1',
+        title: 'SQL Injection',
+        description: 'Unescaped SQL query',
+        severity: Severity.CRITICAL,
+        file: 'src/api/user.ts',
+        line: 25
+      },
+      {
+        scanner: 'Semgrep',
+        ruleId: 'xss-rule-2',
+        title: 'Cross-Site Scripting (XSS)',
+        description: 'Unsanitized HTML rendering',
+        severity: Severity.HIGH,
+        file: 'src/api/user.ts',
+        line: 25
+      }
+    ];
+
+    const result = deduplicateFindings(findings);
+    expect(result).toHaveLength(2);
+    expect(result.map(r => r.title)).toContain('SQL Injection');
+    expect(result.map(r => r.title)).toContain('Cross-Site Scripting (XSS)');
+  });
+});

package/tests/orchestrator.test.ts

@@ -1,96 +1,120 @@
-import { Orchestrator } from '../src/orchestrator';
-import { SecurityScanner } from '../src/scanner';
-import { ScanInput, ScannerResult, Severity, NormalizedFinding } from '@maverick006/types';
-
-class MockScanner implements SecurityScanner {
-  public name: string;
-  public version = '1.0.0';
-  private findings: NormalizedFinding[];
-
-  constructor(name: string, findings: NormalizedFinding[]) {
-    this.name = name;
-    this.findings = findings;
-  }
-
-  async scan(input: ScanInput): Promise<ScannerResult> {
-    return {
-      scanner: this.name,
-      success: true,
-      findings: this.findings,
-      startTime: new Date(),
-      endTime: new Date(),
-    };
-  }
-}
-
-describe('Orchestrator', () => {
-  it('should aggregate findings from multiple scanners', async () => {
-    const finding1: NormalizedFinding = {
-      scanner: 'Mock1',
-      title: 'Finding 1',
-      description: 'Desc 1',
-      severity: Severity.HIGH,
-      ruleId: 'rule-1',
-      file: 'test.js',
-      line: 10,
-    };
-    
-    const finding2: NormalizedFinding = {
-      scanner: 'Mock2',
-      title: 'Finding 2',
-      description: 'Desc 2',
-      severity: Severity.MEDIUM,
-      ruleId: 'rule-2',
-      file: 'test2.js',
-      line: 20,
-    };
-
-    const scanner1 = new MockScanner('Mock1', [finding1]);
-    const scanner2 = new MockScanner('Mock2', [finding2]);
-
-    const orchestrator = new Orchestrator([scanner1, scanner2]);
-
-    const result = await orchestrator.runScan({
-      scanId: 'scan-1',
-      repositoryPath: '/fake/path'
-    });
-
-    expect(result.findings.length).toBe(2);
-    expect(result.findings).toEqual(expect.arrayContaining([finding1, finding2]));
-  });
-
-  it('should deduplicate findings with the same fingerprint', async () => {
-    const finding1: NormalizedFinding = {
-      scanner: 'Mock1',
-      title: 'Finding 1',
-      description: 'Desc 1',
-      severity: Severity.HIGH,
-      ruleId: 'rule-1',
-      file: 'test.js',
-      line: 10,
-    };
-    
-    const finding2: NormalizedFinding = {
-      scanner: 'Mock2',
-      title: 'Finding 1 duplicate',
-      description: 'Desc 1 duplicate',
-      severity: Severity.HIGH,
-      ruleId: 'rule-1', // Same rule
-      file: 'test.js',  // Same file
-      line: 10,         // Same line
-    };
-
-    const scanner1 = new MockScanner('Mock1', [finding1]);
-    const scanner2 = new MockScanner('Mock2', [finding2]);
-
-    const orchestrator = new Orchestrator([scanner1, scanner2]);
-
-    const result = await orchestrator.runScan({
-      scanId: 'scan-2',
-      repositoryPath: '/fake/path'
-    });
-
-    expect(result.findings.length).toBe(1);
-    expect(result.findings[0]).toEqual(finding1); // Should keep the first one
-  });
-});
+import { Orchestrator } from '../src/orchestrator';
+import { SecurityScanner } from '../src/scanner';
+import { ScanInput, ScannerResult, ScannerState, Severity } from '@maverick006/types';
+
+describe('Security Orchestrator with Bounded Concurrency', () => {
+  const mockInput: ScanInput = {
+    scanId: 'test-scan-123',
+    repositoryPath: '/mock/repo'
+  };
+
+  it('should execute scanners with bounded concurrency and aggregate findings', async () => {
+    let runningCount = 0;
+    let maxConcurrent = 0;
+
+    const createMockScanner = (name: string, delayMs: number): SecurityScanner => ({
+      name,
+      scan: async (input: ScanInput): Promise<ScannerResult> => {
+        runningCount++;
+        maxConcurrent = Math.max(maxConcurrent, runningCount);
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        runningCount--;
+
+        return {
+          scanner: name,
+          success: true,
+          state: ScannerState.SUCCESS,
+          findings: [
+            {
+              scanner: name,
+              ruleId: `${name}-rule`,
+              title: `${name} finding`,
+              description: 'sample',
+              severity: Severity.LOW,
+              file: `${name}.ts`,
+              line: 1
+            }
+          ],
+          startTime: new Date(),
+          endTime: new Date()
+        };
+      }
+    });
+
+    const scanners: SecurityScanner[] = [
+      createMockScanner('Semgrep', 30),
+      createMockScanner('Gitleaks', 30),
+      createMockScanner('Trivy', 30),
+      createMockScanner('npm-audit', 30),
+      createMockScanner('Checkov', 30)
+    ];
+
+    const orchestrator = new Orchestrator(scanners, { concurrencyLimit: 2 });
+    const result = await orchestrator.runScan(mockInput);
+
+    expect(maxConcurrent).toBeLessThanOrEqual(2);
+    expect(result.scannerResults).toHaveLength(5);
+    expect(result.findings).toHaveLength(5);
+    expect(result.coverage.code).toBe(true);
+    expect(result.coverage.secrets).toBe(true);
+  });
+
+  it('should handle timeout gracefully without crashing the whole scan', async () => {
+    const normalScanner: SecurityScanner = {
+      name: 'Semgrep',
+      scan: async () => ({
+        scanner: 'Semgrep',
+        success: true,
+        state: ScannerState.SUCCESS,
+        findings: [],
+        startTime: new Date(),
+        endTime: new Date()
+      })
+    };
+
+    const slowScanner: SecurityScanner = {
+      name: 'SlowScanner',
+      scan: async () => {
+        await new Promise(resolve => setTimeout(resolve, 200));
+        return {
+          scanner: 'SlowScanner',
+          success: true,
+          findings: [],
+          startTime: new Date(),
+          endTime: new Date()
+        };
+      }
+    };
+
+    const orchestrator = new Orchestrator([normalScanner, slowScanner], { timeoutMs: 50 });
+    const result = await orchestrator.runScan(mockInput);
+
+    expect(result.scannerResults).toHaveLength(2);
+    const slowResult = result.scannerResults.find(r => r.scanner === 'SlowScanner');
+    expect(slowResult?.state).toBe(ScannerState.TIMEOUT);
+    expect(slowResult?.success).toBe(false);
+
+    const normalResult = result.scannerResults.find(r => r.scanner === 'Semgrep');
+    expect(normalResult?.state).toBe(ScannerState.SUCCESS);
+  });
+
+  it('should detect when scanner capability detects repo is not applicable and return SKIPPED', async () => {
+    const iacScanner: SecurityScanner = {
+      name: 'Checkov',
+      capabilities: {
+        category: 'iac',
+        detectApplicability: async () => false // No IaC files
+      },
+      scan: async () => {
+        throw new Error('Should not be called when detectApplicability returns false');
+      }
+    };
+
+    const orchestrator = new Orchestrator([iacScanner]);
+    const result = await orchestrator.runScan(mockInput);
+
+    expect(result.scannerResults).toHaveLength(1);
+    expect(result.scannerResults[0].state).toBe(ScannerState.SKIPPED);
+    expect(result.scannerResults[0].findings).toHaveLength(0);
+  });
+});

package/tests/scoring.test.ts

@@ -1,62 +1,70 @@
 import { calculateScore } from '../src/scoring';
 import { NormalizedFinding, Severity } from '@maverick006/types';
 
-describe('Deterministic Scoring Engine', () => {
-  
-  const createFinding = (severity: Severity): NormalizedFinding => ({
+describe('Deterministic Scoring Engine (0-100)', () => {
+  const createFinding = (severity: Severity, title = 'test finding'): NormalizedFinding => ({
     scanner: 'test',
     ruleId: 'test-rule',
-    title: 'test finding',
+    title,
     description: 'test desc',
     severity,
     file: 'test.ts',
     line: 1
   });
 
-  it('should return grade A for perfect score (0 findings)', () => {
+  it('should return score 100 and grade A for perfect score (0 findings)', () => {
     const result = calculateScore([]);
-    expect(result.score).toBe(0);
+    expect(result.score).toBe(100);
     expect(result.grade).toBe('A');
+    expect(result.deductions.totalDeductions).toBe(0);
+    expect(result.explanation).toContain('Baseline score: 100/100');
+    expect(result.explanation.some(e => e.includes('No security findings identified'))).toBe(true);
   });
 
-  it('should return grade A for score <= 10 (e.g. 2 mediums)', () => {
+  it('should deduct 3 points per medium finding (e.g. 2 mediums = 94, Grade A)', () => {
     const findings = [
-      createFinding(Severity.MEDIUM), // 5
-      createFinding(Severity.MEDIUM), // 5
+      createFinding(Severity.MEDIUM), // -3
+      createFinding(Severity.MEDIUM), // -3
     ];
     const result = calculateScore(findings);
-    expect(result.score).toBe(10);
+    expect(result.score).toBe(94);
     expect(result.grade).toBe('A');
+    expect(result.deductions.medium).toBe(6);
+    expect(result.breakdown.medium).toBe(2);
   });
 
-  it('should return grade B for score <= 30 (e.g. 1 high, 2 lows)', () => {
+  it('should deduct 10 for high and 1 for low (e.g. 1 high, 2 lows = 88, Grade B)', () => {
     const findings = [
-      createFinding(Severity.HIGH), // 20
-      createFinding(Severity.LOW),  // 1
-      createFinding(Severity.LOW),  // 1
+      createFinding(Severity.HIGH), // -10
+      createFinding(Severity.LOW),  // -1
+      createFinding(Severity.LOW),  // -1
     ];
     const result = calculateScore(findings);
-    expect(result.score).toBe(22);
+    expect(result.score).toBe(88);
     expect(result.grade).toBe('B');
+    expect(result.deductions.high).toBe(10);
+    expect(result.deductions.low).toBe(2);
+    expect(result.deductions.totalDeductions).toBe(12);
   });
 
-  it('should immediately return grade F if any CRITICAL finding exists', () => {
+  it('should immediately force grade F and cap score to <= 49 if any CRITICAL exists', () => {
     const findings = [
-      createFinding(Severity.CRITICAL), // 100
-      createFinding(Severity.LOW),      // 1
+      createFinding(Severity.CRITICAL), // -30, and caps grade to F, score to <= 49
+      createFinding(Severity.LOW),      // -1
     ];
     const result = calculateScore(findings);
-    // Score is 101, which is normally D, but CRITICAL forces F
-    expect(result.score).toBe(101);
+    expect(result.score).toBeLessThanOrEqual(49);
     expect(result.grade).toBe('F');
+    expect(result.deductions.critical).toBe(30);
+    expect(result.breakdown.critical).toBe(1);
+    expect(result.explanation.some(e => e.includes('Grade Override: F'))).toBe(true);
   });
 
-  it('should return grade F if score > 150 without criticals', () => {
-    // 8 HIGHs = 160 score
-    const findings = Array(8).fill(createFinding(Severity.HIGH));
+  it('should clamp minimum score at 0 and return grade F for heavy deductions', () => {
+    const findings = Array(15).fill(createFinding(Severity.HIGH)); // 15 * 10 = -150
     const result = calculateScore(findings);
-    expect(result.score).toBe(160);
+    expect(result.score).toBe(0);
     expect(result.grade).toBe('F');
+    expect(result.deductions.totalDeductions).toBe(150);
   });
-
 });