coverme-security-scanner 3.0.0 → 3.1.0

package/README.md

@@ -1,96 +1,86 @@
-# CoverMe Scanner v3
+# coverme-cli
 
-AI-powered security assessment tool for Claude Code.
-
-## Overview
-
-CoverMe is a slash command for Claude Code that performs comprehensive security assessments and generates professional PDF reports. It uses Claude's intelligence to analyze code like a senior security consultant.
+AI-powered security assessment reports with beautiful PDF output.
 
 ## Installation
 
 ```bash
-cd coverme-v3
-npm install
-npm run build
-npm link  # Makes 'coverme' command available globally
+npm install -g coverme-cli
 ```
 
 ## Usage
 
-### 1. Run Security Scan (in Claude Code)
-
-Navigate to your project and run:
-```
-/coverme
-```
-
-Claude will:
-1. Discover and read relevant source files
-2. Analyze security patterns and vulnerabilities
-3. Generate a threat model (STRIDE + DREAD)
-4. Create quality recommendations
-5. Save results to `coverme-report.json`
+### With Claude Code (Recommended)
 
-### 2. Generate PDF Report
+1. Install the slash command:
 
 ```bash
-coverme report coverme-report.json
-coverme report coverme-report.json --output my-report.pdf
-coverme report coverme-report.json --open  # Opens PDF after generation
+coverme-install --global
 ```
 
-### 3. Validate JSON
+2. Open Claude Code in your project:
 
 ```bash
-coverme validate coverme-report.json
+cd your-project
+claude
 ```
 
-## Output Format
+3. Run the security assessment:
 
-The scan produces a JSON file with:
-
-- **projectName**: Project identifier
-- **scanDate**: ISO timestamp
-- **executiveSummary**: Architecture overview and security posture
-- **findings**: Array of security findings with DREAD scores
-- **threatModel**: STRIDE-based threat analysis
-- **qualityReview**: Delete/Merge/Simplify recommendations
-- **positiveObservations**: Good security practices found
-- **previouslyResolved**: Fixed issues from prior scans
+```
+/coverme
+```
 
-## Finding Quality Standard
+Claude will:
+- Launch 6 parallel security agents
+- Analyze your entire codebase
+- Generate a JSON report
+- Create a professional PDF
 
-Each finding includes:
-- **Severity**: critical / high / medium / low / info
-- **DPI Priority**: "Today" / "This Sprint" / "Next Sprint" / "Backlog"
-- **DREAD Score**: Damage, Reproducibility, Exploitability, Affected Users, Discoverability
-- **Specific Location**: File path and line numbers
-- **Evidence**: Actual code snippets
-- **Remediation**: Concrete fix with code example
+### Manual Usage
 
-## Project Structure
+Generate PDF from a JSON report:
 
+```bash
+coverme report.json output.pdf
 ```
-coverme-v3/
-├── .claude/
-│   └── commands/
-│       └── coverme.md          # The main prompt (~350 lines)
-├── src/
-│   ├── index.ts                # CLI entry (~120 lines)
-│   ├── types.ts                # Type definitions (~200 lines)
-│   └── pdf-generator.ts        # PDF generation (~700 lines)
-├── package.json
-├── tsconfig.json
-└── README.md
+
+## Report Schema
+
+```typescript
+interface SecurityReport {
+  project: string;
+  date: string;
+  branch?: string;
+  scope?: string;
+
+  summary: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    total: number;
+  };
+
+  overallRiskLevel: 'critical' | 'high' | 'medium' | 'low';
+  executiveSummary: string;
+
+  findings: Finding[];
+  threatModel?: ThreatModelEntry[];
+  positiveObservations?: { title: string; description: string }[];
+  remediation?: { p0?: Item[]; p1?: Item[]; p2?: Item[]; p3?: Item[] };
+}
 ```
 
-Total: ~1,350 lines (vs previous ~5,000 lines)
+See `src/pdf/types.ts` for the complete schema.
 
-## Requirements
+## Design
 
-- Node.js 20+
-- Claude Code CLI
-- PDFKit (installed via npm)
+Minimal, elegant styling inspired by Stripe, Notion, and Airtable:
+- Soft, muted severity colors
+- Clean typography
+- Professional table layouts
+- Subtle borders and spacing
 
 ## License
 

package/bin/coverme.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { generatePDF } from '../dist/index.js';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+  console.log(`
+coverme - Generate beautiful security assessment PDFs
+
+Usage:
+  coverme <input.json> [output.pdf]
+
+Options:
+  -h, --help     Show this help message
+
+Example:
+  coverme report.json security-assessment.pdf
+
+The input JSON should follow the SecurityReport schema.
+See https://github.com/your-org/coverme-cli for documentation.
+`);
+  process.exit(0);
+}
+
+const inputPath = resolve(process.cwd(), args[0]);
+const outputPath = args[1]
+  ? resolve(process.cwd(), args[1])
+  : inputPath.replace(/\.json$/, '.pdf');
+
+try {
+  const data = JSON.parse(readFileSync(inputPath, 'utf-8'));
+
+  console.log(`Generating PDF from ${inputPath}...`);
+
+  await generatePDF(data, outputPath);
+
+  console.log(`PDF generated: ${outputPath}`);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}

package/bin/install-command.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { mkdirSync, copyFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Determine target directory
+const targetDir = process.argv[2] === '--global'
+  ? join(homedir(), '.claude', 'commands')
+  : join(process.cwd(), '.claude', 'commands');
+
+// Source file
+const sourceFile = join(__dirname, '..', 'commands', 'coverme.md');
+
+// Create directory if needed
+if (!existsSync(targetDir)) {
+  mkdirSync(targetDir, { recursive: true });
+  console.log(`Created directory: ${targetDir}`);
+}
+
+// Copy the command file
+const targetFile = join(targetDir, 'coverme.md');
+copyFileSync(sourceFile, targetFile);
+
+console.log(`
+Installed /coverme command to: ${targetFile}
+
+Usage:
+  Open Claude Code in your project directory and run:
+  /coverme
+
+This will run a comprehensive security assessment and generate a PDF report.
+`);

package/commands/coverme.md

@@ -0,0 +1,326 @@
+# Security Assessment Generator v2
+
+Run a comprehensive security assessment on this codebase and generate a professional PDF report with deep analysis.
+
+## Instructions
+
+You are a senior security architect and penetration tester performing a pre-production security audit. Run 7 parallel security agents to analyze this codebase comprehensively.
+
+### Step 1: Launch Parallel Agents
+
+Launch these 7 agents simultaneously using the Task tool:
+
+1. **Executive Summary Agent** (subagent_type: Explore)
+   - Understand what the system does
+   - Identify the tech stack and architecture
+   - Map trust boundaries and critical assets
+   - Determine overall risk level
+   - Identify the crown jewels (most valuable assets)
+
+2. **Attack Surface Agent** (subagent_type: Explore)
+   - Map all entry points (APIs, webhooks, file uploads, CLI args)
+   - Identify unauthenticated endpoints
+   - Find admin/debug interfaces
+   - Check for exposed internal services
+   - Document external dependencies and their trust level
+
+3. **Vulnerability Hunter Agent** (subagent_type: Explore)
+   - OWASP Top 10 deep dive with CODE EVIDENCE
+   - For each finding: extract the EXACT vulnerable code snippet
+   - Authentication/authorization bypass paths
+   - Injection vulnerabilities (SQL, command, XSS, SSTI)
+   - Secrets in code, hardcoded credentials (show exact lines)
+   - Insecure deserialization, SSRF, XXE
+   - Rate limiting gaps, brute force opportunities
+
+4. **Attack Chain Analyst Agent** (subagent_type: Explore)
+   - Identify how vulnerabilities COMBINE for greater impact
+   - Map realistic attack scenarios (entry -> pivot -> objective)
+   - Calculate blast radius for each chain
+   - Example: "Unauthenticated API + hardcoded secret = full DB access"
+   - Prioritize chains by likelihood and impact
+
+5. **Business Logic Agent** (subagent_type: Explore)
+   - Race conditions in critical flows (payments, credits, locks)
+   - Workflow bypass opportunities (skip steps, replay)
+   - Credit/billing manipulation vectors
+   - Data validation gaps at business boundaries
+   - PII handling and data residency violations
+   - Privilege escalation paths
+
+6. **Infrastructure Agent** (subagent_type: Explore)
+   - Docker/Kubernetes security (securityContext, network policies)
+   - CI/CD pipeline security gates (or lack thereof)
+   - Secrets management (env vars, mounted secrets, hardcoded)
+   - Cloud configuration (IAM, S3 buckets, security groups)
+   - Database security (encryption, access controls)
+   - Dependency vulnerabilities (npm audit, CVEs)
+
+7. **Compliance & Impact Agent** (subagent_type: Explore)
+   - Map findings to compliance frameworks (SOC2, PCI-DSS, GDPR, HIPAA)
+   - Calculate business impact for each critical finding
+   - Estimate financial exposure ranges
+   - Identify SLA/availability risks
+   - Determine data breach notification requirements
+
+### Step 2: Deep Dive on Findings
+
+For EVERY critical and high finding, ensure you have:
+
+1. **Code Evidence** - The EXACT vulnerable code snippet:
+   ```
+   "codeEvidence": [{
+     "file": "src/auth/login.js",
+     "startLine": 45,
+     "endLine": 52,
+     "code": "const user = await db.query(`SELECT * FROM users WHERE id = ${req.params.id}`);",
+     "annotation": "User input directly interpolated into SQL query"
+   }]
+   ```
+
+2. **Exploitability Assessment**:
+   ```
+   "exploitability": {
+     "skillLevel": "novice",           // novice/intermediate/expert
+     "accessRequired": "network",       // network/adjacent/local/physical
+     "authRequired": "none",            // none/low/high
+     "userInteraction": "none",         // none/required
+     "hasPublicExploit": true,          // Known PoC exists?
+     "exploitMaturity": "weaponized",   // theoretical/poc/weaponized
+     "automatable": true                // Can be mass-exploited?
+   }
+   ```
+
+3. **Blast Radius**:
+   ```
+   "blastRadius": {
+     "affectedUsers": "all",            // none/single/subset/all
+     "affectedData": ["PII", "credentials", "financial"],
+     "affectedServices": ["auth", "payments"],
+     "cascadeRisk": true,               // Leads to further compromise?
+     "containment": "system"            // isolated/component/system/infrastructure
+   }
+   ```
+
+4. **Business Impact**:
+   ```
+   "businessImpact": {
+     "confidentiality": "high",
+     "integrity": "high",
+     "availability": "low",
+     "financialExposure": "$100k-$1M potential fraud",
+     "complianceViolations": ["PCI-DSS 6.5.1", "SOC2 CC6.1"],
+     "reputationalRisk": "high",
+     "slaImpact": "99.9% SLA at risk"
+   }
+   ```
+
+5. **Proof of Concept** (safe, non-destructive):
+   ```
+   "proofOfConcept": "curl -X POST /api/admin/users -H 'X-Admin: true' -d '{\"role\":\"admin\"}'"
+   ```
+
+### Step 3: Build Attack Chains
+
+Identify 2-5 realistic attack chains that combine multiple vulnerabilities:
+
+```json
+"attackChains": [
+  {
+    "id": "AC-01",
+    "name": "Credential Theft to Full Infrastructure Compromise",
+    "description": "Attacker chains unauthenticated endpoint access with hardcoded secrets to gain full system control",
+    "likelihood": "high",
+    "impact": "critical",
+    "steps": [
+      { "order": 1, "findingId": "HIGH-02", "action": "Access unauthenticated /enclave/register endpoint", "outcome": "Register malicious enclave with attacker-controlled keys" },
+      { "order": 2, "findingId": "HIGH-01", "action": "Use leaked tracker API key from Helm values", "outcome": "Gain access to usage analytics and user activity" },
+      { "order": 3, "findingId": "CRIT-01", "action": "Pivot using AWS credentials from .env", "outcome": "Full AWS account access, S3 data exfiltration" }
+    ],
+    "mitigationStrategy": "Breaking any link stops the chain. Priority: rotate AWS credentials immediately."
+  }
+]
+```
+
+### Step 4: Compile Results
+
+After all agents complete, compile their findings into a JSON file with this enhanced schema:
+
+```json
+{
+  "project": "Project Name",
+  "date": "YYYY-MM-DD",
+  "branch": "branch-name",
+  "scope": "X files, ~Y lines",
+  "methodology": "7 parallel security agents with attack chain analysis",
+
+  "summary": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0,
+    "total": 0
+  },
+
+  "overallRiskLevel": "critical|high|medium|low",
+  "executiveSummary": "2-3 paragraphs: what the system does, key findings, recommended actions...",
+
+  "topPriorities": [
+    { "finding": "Description", "severity": "critical", "action": "Immediate action required" }
+  ],
+
+  "attackChains": [
+    {
+      "id": "AC-01",
+      "name": "Chain name",
+      "description": "How vulnerabilities combine",
+      "likelihood": "high",
+      "impact": "critical",
+      "steps": [
+        { "order": 1, "findingId": "CRIT-01", "action": "What attacker does", "outcome": "What they achieve" }
+      ],
+      "mitigationStrategy": "How to break the chain"
+    }
+  ],
+
+  "riskMatrix": [
+    { "category": "Authentication", "currentRisk": "high", "residualRisk": "low", "trend": "stable" },
+    { "category": "Data Protection", "currentRisk": "medium", "residualRisk": "low", "trend": "improving" }
+  ],
+
+  "architecture": {
+    "overview": "System description...",
+    "components": [
+      { "name": "Component", "technology": "Tech", "description": "Purpose" }
+    ],
+    "trustBoundaries": [
+      { "id": "TB-01", "boundary": "Internet/DMZ", "trustLevel": "untrusted", "description": "Public API surface" }
+    ]
+  },
+
+  "network": {
+    "diagram": "ASCII diagram...",
+    "ports": [
+      { "port": 443, "protocol": "HTTPS", "component": "API", "binding": "0.0.0.0", "purpose": "Public API" }
+    ],
+    "externalDeps": [
+      { "service": "Stripe", "endpoint": "api.stripe.com", "auth": "API key", "risk": "PCI scope" }
+    ]
+  },
+
+  "findings": [
+    {
+      "id": "CRIT-01",
+      "title": "Finding title",
+      "severity": "critical",
+      "file": "path/to/file.js",
+      "line": 123,
+      "issue": "What we found...",
+      "why": "Why it matters...",
+      "fix": "How to fix...",
+      "status": "open",
+      "dreadScore": 8.5,
+      "cwe": "CWE-89",
+      "cvssScore": 9.1,
+      "cvssVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N",
+      "codeEvidence": [
+        {
+          "file": "src/db/query.js",
+          "startLine": 45,
+          "endLine": 48,
+          "code": "db.query(`SELECT * FROM users WHERE id = ${userId}`)",
+          "annotation": "Unsanitized user input in SQL query"
+        }
+      ],
+      "exploitability": {
+        "skillLevel": "novice",
+        "accessRequired": "network",
+        "authRequired": "none",
+        "userInteraction": "none",
+        "hasPublicExploit": true,
+        "exploitMaturity": "weaponized",
+        "automatable": true
+      },
+      "blastRadius": {
+        "affectedUsers": "all",
+        "affectedData": ["PII", "credentials"],
+        "affectedServices": ["database", "auth"],
+        "cascadeRisk": true,
+        "containment": "system"
+      },
+      "businessImpact": {
+        "confidentiality": "high",
+        "integrity": "high",
+        "availability": "none",
+        "financialExposure": "$500k-$5M breach costs",
+        "complianceViolations": ["GDPR Art 32", "SOC2 CC6.1"],
+        "reputationalRisk": "high"
+      },
+      "proofOfConcept": "curl '/api/users/1 OR 1=1--'",
+      "relatedFindings": ["HIGH-02", "HIGH-03"],
+      "attackChainPosition": "entry",
+      "references": ["https://owasp.org/Top10/A03_2021-Injection/"]
+    }
+  ],
+
+  "threatModel": [
+    {
+      "id": "T-01",
+      "severity": "high",
+      "dread": 6.5,
+      "status": "open",
+      "finding": "STRIDE threat description"
+    }
+  ],
+
+  "positiveObservations": [
+    { "title": "Good Practice", "description": "What they did right..." }
+  ],
+
+  "complianceMapping": [
+    {
+      "framework": "SOC2",
+      "controls": [
+        { "controlId": "CC6.1", "name": "Logical Access", "status": "partial", "relatedFindings": ["HIGH-02"] }
+      ]
+    }
+  ],
+
+  "remediation": {
+    "p0": [{ "action": "Do this NOW", "finding": "CRIT-01", "owner": "Security" }],
+    "p1": [{ "action": "Do this week", "finding": "HIGH-01", "owner": "Backend" }],
+    "p2": [],
+    "p3": []
+  }
+}
+```
+
+### Step 5: Generate PDF
+
+Save the JSON to `security-report.json` in the project root, then run:
+
+```bash
+npx coverme-cli security-report.json security-assessment-$(date +%Y-%m-%d).pdf
+```
+
+### Quality Checklist
+
+Before generating the PDF, verify:
+- [ ] Every CRITICAL/HIGH finding has codeEvidence with actual code
+- [ ] Every CRITICAL/HIGH finding has exploitability assessment
+- [ ] Every CRITICAL/HIGH finding has blastRadius defined
+- [ ] At least 2 attack chains are documented
+- [ ] Top priorities match the most impactful attack chains
+- [ ] Proof of concepts are safe and non-destructive
+- [ ] CWE IDs are accurate for vulnerability types
+- [ ] Compliance violations are specific (e.g., "PCI-DSS 6.5.1" not just "PCI-DSS")
+
+### Output
+
+The final deliverable is:
+1. `security-report.json` - Enhanced findings data with attack chains
+2. `security-assessment-YYYY-MM-DD.pdf` - Professional PDF report
+
+---
+
+Now begin the security assessment. Launch all 7 agents in parallel.

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=index.d.ts.map
+export { generatePDF, PDFGenerator } from './pdf/generator.js';
+export type { SecurityReport, Finding, Severity } from './pdf/types.js';
+export { colors, fonts, spacing, layout } from './pdf/styles.js';