coverme-security-scanner 3.7.4 → 3.7.7

package/commands/coverme.md

@@ -1,6 +1,6 @@
 # Security Assessment
 
-Run a security scan and generate a PDF report. Execute automatically without asking questions.
+Run an enterprise-grade security assessment combining 4 review types into a unified report. Execute automatically without asking questions.
 
 ## Step 1: Setup
 ```bash
@@ -8,12 +8,283 @@ mkdir -p .coverme
 ```
 
 ## Step 2: Run Security Scan
-Use ONE Task agent with subagent_type="general-purpose" to perform the full security assessment:
+Use ONE Task agent with subagent_type="general-purpose" to perform a COMPREHENSIVE assessment:
 
-prompt: "Perform a comprehensive security assessment of this codebase. Analyze: 1) Architecture and tech stack 2) API endpoints and attack surface 3) Security vulnerabilities (secrets, injection, XSS, auth issues) 4) Infrastructure (Docker, CI/CD, dependencies). When done, use the Write tool to create .coverme/scan.json with this structure: {\"project\":\"<name>\",\"date\":\"2026-02-19\",\"executiveSummary\":\"<summary>\",\"summary\":{\"critical\":0,\"high\":0,\"medium\":0,\"low\":0,\"total\":0},\"overallRiskLevel\":\"low|medium|high|critical\",\"findings\":[{\"id\":\"VULN-01\",\"title\":\"\",\"severity\":\"critical|high|medium|low\",\"file\":\"\",\"line\":0,\"issue\":\"\",\"why\":\"\",\"fix\":\"\",\"cwe\":\"\"}],\"architecture\":{\"overview\":\"\",\"components\":[]},\"positiveObservations\":[{\"title\":\"\",\"description\":\"\"}]}"
+prompt: |
+  Perform a COMPREHENSIVE security assessment combining:
+  1. Security Review (STRIDE vulnerabilities)
+  2. Threat Model (DREAD scoring)
+  3. Code Quality Review (dead code, DRY violations)
+  4. Privacy Analysis (LINDDUN)
 
-## Step 3: Wait for agent to complete
-Use AgentOutputTool to wait for the agent.
+  YOU MUST produce findings at the quality level of a professional security audit firm.
+  Target: 25-35 findings for a medium codebase, 40+ for large.
+
+  ## PHASE 1: Codebase Metrics
+
+  First, gather precise metrics:
+  ```
+  - Count total files: find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.py" \) | wc -l
+  - Count lines: find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.py" \) -exec wc -l {} + | tail -1
+  - List components (frontend/, backend/, api/, etc.)
+  - Map technology stack (React, Express, Postgres, etc.)
+  - Read .gitignore to know what's excluded
+  ```
+
+  ## PHASE 2: Architecture Analysis
+
+  Map the system:
+  - Identify all components with their technology
+  - Define trust boundaries (TB1-Browser, TB2-BFF, TB3-API, TB4-Database, TB5-External)
+  - Document entry points with auth method
+  - List critical assets (keys, tokens, PII, credentials)
+
+  ## PHASE 3: Security Vulnerabilities (STRIDE)
+
+  For EACH finding, you MUST include ALL of these:
+
+  **Required Fields:**
+  - **ID**: Use prefixes based on source:
+    - `T-FE-N`: Frontend threats
+    - `T-BE-N`: Backend threats
+    - `T-DB-N`: Database threats
+    - `T-ENC-N`: Encryption/enclave threats
+    - `CR-N`: Code review findings
+    - `SR-N`: Security review findings
+    - `QR-N`: Quality review items
+
+  - **Title**: Specific, not generic. Good: "Attestation Fallback Accepts Unverified Keys". Bad: "Security Issue"
+
+  - **File + Line Range**: Exact location with range. Example: `frontend/lib/e2e-encryption.ts:51-91`
+
+  - **Code References**: Include actual function/variable names inline:
+    - Good: "When unavailable, `fetchEnclaveInfo()` falls back and stores keys with `keysVerified: false`"
+    - Bad: "The function has a fallback"
+
+  - **DREAD Score**: Calculate each component (1-10):
+    - Damage: How bad if exploited?
+    - Reproducibility: How easy to reproduce?
+    - Exploitability: How easy to exploit?
+    - Affected Users: How many affected?
+    - Discoverability: How easy to find?
+    - Final: (D+R+E+A+D) / 5
+
+  - **Description**: 2-3 sentences explaining WHAT the code does wrong with inline `code references`
+
+  - **Recommendation**: Specific actionable fix, not generic advice
+
+  - **Status**: `open` | `partial` | `mitigated` | `accepted`
+
+  - **CWE**: Include CWE identifier (e.g., "CWE-295: Improper Certificate Validation")
+
+  - **relatedFindings**: Link to related findings when issues are connected
+
+  ### Vulnerability Categories to Check:
+
+  **Silent Fallbacks (CRITICAL priority)**:
+  - try/catch blocks that swallow errors and continue execution
+  - `||` operators providing insecure defaults (e.g., `password || 'default123'`)
+  - Authentication that defaults to "allow" on error
+  - Crypto operations falling back to weaker algorithms
+  - if/else branches that silently skip security checks
+  - Graceful degradation that removes security controls
+
+  **Hardcoded Credentials**:
+  - Default passwords in code (not just comments)
+  - API keys in source (not from env vars)
+  - Fallback credentials like `amqp://user:pass123@localhost`
+  - Secrets in Helm values, Docker configs, CI files
+
+  **Input Validation Gaps**:
+  - User input used in SQL/shell/eval without sanitization
+  - Missing regex validation on IDs, names, paths
+  - Unbounded arrays that could cause DoS
+  - Path traversal vulnerabilities
+
+  **Error Information Leaks**:
+  - `error.message` or `error.stack` returned to clients
+  - Internal hostnames/IPs in error responses
+  - Database errors exposed to users
+  - Debug info in production responses
+
+  **Authentication/Authorization**:
+  - Missing auth on sensitive endpoints
+  - Token validation issues
+  - Session management flaws
+  - Privilege escalation paths
+
+  **Cryptographic Issues**:
+  - Weak algorithms (MD5, SHA1 for security)
+  - Hardcoded IVs or keys
+  - Missing signature verification
+  - Key management flaws
+
+  ## PHASE 4: Code Quality Review
+
+  Find issues with LINE COUNTS:
+
+  **Dead Code (estimate removable lines)**:
+  - Functions defined but never called (trace call graph)
+  - Routes defined but not mounted
+  - Commented-out code blocks
+  - Example: "processMessage() - likely dead non-streaming path (~240 lines)"
+
+  **DRY Violations (estimate duplicated lines)**:
+  - Near-identical code blocks in multiple files
+  - Copy-pasted logic with minor variations
+  - Example: "CSV + Excel Handler process/prepareForStreaming nearly identical (~470 lines)"
+
+  **Deprecated Patterns**:
+  - Old API usage
+  - Legacy code paths
+  - Outdated dependencies
+
+  ## PHASE 5: Privacy Analysis (LINDDUN)
+
+  Analyze for privacy threats:
+  - **L**inkability: Can actions be linked to users?
+  - **I**dentifiability: Can users be identified?
+  - **N**on-repudiation: Can users deny actions?
+  - **D**etectability: Can user presence be detected?
+  - **D**isclosure: Is data disclosed inappropriately?
+  - **U**nawareness: Are users unaware of data collection?
+  - **N**on-compliance: Are regulations violated?
+
+  ## PHASE 6: Cross-Reference & Merge
+
+  **Merge duplicate findings**:
+  - When same issue found in multiple analyses, combine them
+  - Use format: "CR-02 / T-EKS-3: Hardcoded Tracker API Keys"
+
+  **Link related findings**:
+  - Add `relatedFindings: ["T-FE-2"]` when issues are connected
+  - Build attack chains showing how findings combine
+
+  ## PHASE 7: Identify Resolved Issues
+
+  Look for issues that WERE present but are NOW fixed:
+  - Commented code showing old vulnerable patterns
+  - Security controls that are properly implemented
+  - Previous findings that have been addressed
+
+  Document these in `resolvedIssues` with:
+  - What was the original issue
+  - How it was resolved
+  - Current security status
+
+  ## OUTPUT FORMAT
+
+  Create `.coverme/scan.json` with this EXACT structure:
+
+  ```json
+  {
+    "project": "<project-name>",
+    "date": "2026-02-19",
+    "branch": "main",
+    "scope": "<X> files, ~<Y> lines - Full platform assessment",
+    "components": ["Frontend (Next.js)", "Backend (Express)", "Database (Postgres)"],
+    "methodology": "STRIDE + DREAD-D + LINDDUN",
+    "reviewType": "Security + Threat Model + Code Quality + Privacy",
+    "author": "Claude Code",
+
+    "executiveSummary": "<3-4 paragraphs: 1) System overview 2) Security architecture 3) Key findings summary 4) Critical remaining issues>",
+    "overallRiskLevel": "low|medium|high|critical",
+
+    "summary": { "critical": 0, "high": 0, "medium": 0, "low": 0, "total": 0 },
+
+    "topPriorities": [
+      { "finding": "T-FE-1", "severity": "high", "action": "Block attestation fallback" }
+    ],
+
+    "architecture": {
+      "overview": "<1-2 sentences about system architecture>",
+      "components": [
+        {"name": "Frontend", "technology": "Next.js BFF", "description": "PKCE OAuth, session management"}
+      ],
+      "trustBoundaries": [
+        {"id": "TB1", "boundary": "Browser", "trustLevel": "untrusted", "description": "User browser environment"},
+        {"id": "TB2", "boundary": "API Gateway", "trustLevel": "semi-trusted", "description": "Holds OAuth tokens"}
+      ]
+    },
+
+    "findings": [
+      {
+        "id": "T-FE-1",
+        "title": "Attestation Fallback Accepts Unverified Keys",
+        "severity": "high",
+        "status": "open",
+        "file": "frontend/lib/e2e-encryption.ts",
+        "line": "51-91",
+        "dreadScore": 6.3,
+        "cwe": "CWE-295: Improper Certificate Validation",
+        "issue": "When the attestation bundle endpoint is unavailable, `fetchEnclaveInfo()` falls back to the legacy `/api/v1/enclave` endpoint and stores keys with `keysVerified: false`. The browser silently proceeds to encrypt messages with unverified public keys.",
+        "why": "This enables a man-in-the-middle attack by a compromised gateway. An attacker who controls the gateway can substitute their own keys and decrypt all messages.",
+        "fix": "Block the request or display a prominent security warning when attestation fails. Do not silently proceed with unverified keys. Consider: `if (!keysVerified) throw new AttestationError('Cannot proceed without verified keys')`",
+        "relatedFindings": ["T-FE-2", "CR-07"]
+      }
+    ],
+
+    "threatModel": [
+      {"id": "T-FE-1", "severity": "high", "dread": 6.3, "status": "partial", "finding": "Attestation fallback accepts unverified keys"},
+      {"id": "T-ENC-2", "severity": "low", "dread": 2.0, "status": "mitigated", "finding": "Session key zeroization implemented"}
+    ],
+
+    "qualityReview": {
+      "deadCode": [
+        {"type": "dead-code", "action": "DELETE", "file": "src/old-handler.js", "line": 1, "description": "processMessage() - likely dead non-streaming path (~240 lines)"}
+      ],
+      "dryViolations": [
+        {"type": "dry-violation", "action": "MERGE", "file": "src/handlers/csv.js", "description": "CSV + Excel Handler process/prepareForStreaming nearly identical (~470 lines)", "relatedFiles": ["src/handlers/excel.js"]}
+      ]
+    },
+
+    "positiveObservations": [
+      {"title": "Zero-Knowledge Architecture", "description": "API gateway genuinely never sees plaintext. Encrypted payloads flow through without decryption."},
+      {"title": "Atomic Credit Operations", "description": "Lua scripts for token burning prevent cross-pod race conditions."},
+      {"title": "Post-Quantum Cryptography", "description": "XWing (ML-KEM-768 + X25519) hybrid KEM with Ed25519 signing."}
+    ],
+
+    "resolvedIssues": [
+      {"id": "RES-01", "title": "SQL Injection in DuckDB", "severity": "critical", "resolution": "Resolved: enable_external_access=false sandbox mode + SQL validation blocklist."},
+      {"id": "RES-02", "title": "Admin API Fail-Open", "severity": "high", "resolution": "Resolved: Binds to 127.0.0.1 by default. Fail-closed when no ADMIN_ALLOWED_IPS configured."}
+    ],
+
+    "privacyAnalysis": [
+      {"category": "Linkability", "risk": "medium", "description": "User actions can be linked via hashed KRN in metrics", "mitigation": "SHA-256 hashing provides pseudonymization"},
+      {"category": "Identifiability", "risk": "low", "description": "KRN logged in some paths enables identification", "mitigation": "Replace with getUserHash() in all logs"}
+    ],
+
+    "remediation": {
+      "p0": [{"action": "Remove hardcoded secrets from Helm values. Move to Secrets Manager. Rotate keys.", "finding": "CR-02", "owner": "DevOps"}],
+      "p1": [{"action": "Block attestation fallback or show prominent warning", "finding": "T-FE-1", "owner": "Frontend"}],
+      "p2": [{"action": "Extract Redis metrics to shared module (~160 lines)", "finding": "QR-16", "owner": "Backend"}]
+    }
+  }
+  ```
+
+  ## QUALITY REQUIREMENTS
+
+  **Minimum Thresholds:**
+  - 25+ findings for medium codebase (5k-50k lines)
+  - 40+ findings for large codebase (50k+ lines)
+  - Every HIGH/CRITICAL finding MUST have exact file:line
+  - Every finding MUST have DREAD score
+  - Every finding MUST have CWE identifier
+  - Include at least 5 positive observations
+  - Include code quality items with line counts
+  - Cross-reference related findings
+  - Include at least 3 resolved issues (if any exist)
+  - Include LINDDUN privacy analysis
+
+  **Quality Checks:**
+  - NO generic findings like "Consider adding validation"
+  - NO findings without file locations
+  - NO DREAD scores without calculation
+  - ALL code references must use actual function/variable names from the code
+  - ALL recommendations must be actionable, not vague
+
+## Step 3: Wait for agent
+Use AgentOutputTool to wait for completion.
 
 ## Step 4: Generate PDF
 ```bash

package/dist/pdf/generator.js

@@ -402,9 +402,7 @@ export class PDFGenerator {
             this.y = this.doc.y + spacing.paragraph;
         }
         if (report.architecture?.components?.length) {
-            // Start components table on new page to keep it together
-            this.newPage();
-            this.y = spacing.page.top;
+            this.checkPageBreak(150);
             this.subTitle('Components');
             this.renderSimpleTable(['Component', 'Technology', 'Description'], report.architecture.components.map(c => [c.name, c.technology, c.description]), [100, 150, 245]);
         }
@@ -616,46 +614,78 @@ export class PDFGenerator {
         const boxPadding = 12;
         const boxInnerWidth = layout.content.width - (boxPadding * 2);
         const style = colors.severity[finding.severity];
-        // ID in severity color, title in black - allow wrapping for long titles
-        const titleText = `[${finding.id}] ${finding.title}`;
-        const titleHeight = this.doc
+        // Finding ID in accent color
+        this.doc
             .font(fonts.weights.bold)
             .fontSize(fonts.sizes.body)
-            .heightOfString(titleText, { width: layout.content.width });
+            .fillColor(colors.accent)
+            .text(finding.id, spacing.page.margin, this.y);
+        this.y += 18;
+        // Title - large and prominent
         this.doc
             .font(fonts.weights.bold)
-            .fontSize(fonts.sizes.body)
-            .fillColor(style.text)
-            .text(`[${finding.id}]`, spacing.page.margin, this.y, { continued: true })
+            .fontSize(fonts.sizes.h3)
             .fillColor(colors.text.primary)
-            .text(` ${finding.title}`, { width: layout.content.width - 60 });
-        this.y = this.doc.y + 4;
-        // Cross-references and DREAD score line
-        const hasRefs = finding.relatedFindings?.length || finding.dreadScore || finding.cwe;
-        if (hasRefs) {
-            const parts = [];
-            if (finding.dreadScore)
-                parts.push(`DREAD: ${finding.dreadScore.toFixed(1)}`);
-            if (finding.cwe)
-                parts.push(finding.cwe);
-            if (finding.relatedFindings?.length) {
-                parts.push(`Related: ${finding.relatedFindings.join(', ')}`);
-            }
+            .text(finding.title, spacing.page.margin, this.y, { width: layout.content.width });
+        this.y = this.doc.y + 6;
+        // Severity badge (small pill)
+        const badgeHeight = 16;
+        const severityText = finding.severity.toUpperCase();
+        const severityWidth = this.doc.font(fonts.weights.bold).fontSize(7).widthOfString(severityText) + 12;
+        this.doc
+            .roundedRect(spacing.page.margin, this.y, severityWidth, badgeHeight, 3)
+            .fill(style.bg);
+        this.doc
+            .font(fonts.weights.bold)
+            .fontSize(7)
+            .fillColor(style.text)
+            .text(severityText, spacing.page.margin + 6, this.y + 4);
+        let xOffset = spacing.page.margin + severityWidth + 6;
+        // Status badge (if present) - small colored text, no box
+        if (finding.status) {
+            const statusColors = {
+                open: '#DC2626',
+                partial: '#D97706',
+                mitigated: '#059669',
+                accepted: '#4F46E5',
+                resolved: '#059669',
+            };
+            const statusColor = statusColors[finding.status] || statusColors.open;
+            const statusText = finding.status.charAt(0).toUpperCase() + finding.status.slice(1);
             this.doc
-                .font(fonts.weights.normal)
-                .fontSize(fonts.sizes.small)
-                .fillColor(colors.text.muted)
-                .text(parts.join(' | '), spacing.page.margin, this.y);
-            this.y += 14;
+                .font(fonts.weights.bold)
+                .fontSize(9)
+                .fillColor(statusColor)
+                .text(statusText, xOffset, this.y + 3);
         }
-        // File reference (if present)
+        this.y += badgeHeight + 8;
+        // File reference with line numbers (if present)
         if (finding.file) {
             this.doc
                 .font(fonts.mono)
                 .fontSize(fonts.sizes.small)
                 .fillColor(colors.accent)
                 .text(`${finding.file}${finding.line ? `:${finding.line}` : ''}`, spacing.page.margin, this.y);
-            this.y += 18;
+            this.y += 16;
+        }
+        // DREAD/CVSS score and metadata line
+        const metaParts = [];
+        if (finding.dreadScore)
+            metaParts.push(`DREAD: ${finding.dreadScore.toFixed(1)}`);
+        if (finding.cvssScore)
+            metaParts.push(`CVSS: ${finding.cvssScore.toFixed(1)}`);
+        if (finding.cwe)
+            metaParts.push(finding.cwe);
+        if (finding.relatedFindings?.length) {
+            metaParts.push(`Related: ${finding.relatedFindings.join(', ')}`);
+        }
+        if (metaParts.length > 0) {
+            this.doc
+                .font(fonts.weights.normal)
+                .fontSize(fonts.sizes.small)
+                .fillColor(colors.text.muted)
+                .text(metaParts.join(' | '), spacing.page.margin, this.y);
+            this.y += 16;
         }
         // ─────────────────────────────────────────────────────────────
         // Check for structured format (issue/why/fix) vs legacy format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverme-security-scanner",
-  "version": "3.7.4",
+  "version": "3.7.7",
   "description": "AI-powered security assessment reports with beautiful PDF output",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node bin/install-command.js --global || true"
   },
   "files": [
     "dist",