coverme-scanner 1.0.0

package/src/cli/scan.ts

@@ -0,0 +1,483 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ScanOptions, Category, Severity } from '../types.js';
+
+interface ScanCommandOptions {
+  output: string;
+  outputPath?: string;
+  categories: string;
+  severity: string;
+  verbose?: boolean;
+  parallel: string;
+}
+
+export async function scan(
+  scanPath: string,
+  options: ScanCommandOptions
+): Promise<void> {
+  const resolvedPath = path.resolve(scanPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    console.error(`Error: Path does not exist: ${resolvedPath}`);
+    process.exit(1);
+  }
+
+  const categories: Category[] =
+    options.categories === 'all'
+      ? ['security', 'quality', 'architecture', 'dependencies', 'performance']
+      : (options.categories.split(',') as Category[]);
+
+  const scanOptions: ScanOptions = {
+    path: resolvedPath,
+    output: options.output as 'json' | 'pdf' | 'md' | 'html',
+    outputPath: options.outputPath,
+    categories,
+    minSeverity: options.severity as Severity,
+    verbose: options.verbose,
+    parallel: parseInt(options.parallel, 10),
+  };
+
+  console.log(`
+================================================================================
+                         COVERME SECURITY SCANNER
+                    10-Agent Deep Analysis System
+================================================================================
+
+Scan Target:  ${resolvedPath}
+Categories:   ${categories.join(', ')}
+Output:       ${scanOptions.output}
+Agents:       10 scanners + 3 validators
+
+================================================================================
+
+This scan runs FROM WITHIN Claude Code.
+Run: /coverme
+
+================================================================================
+`);
+
+  // Output the orchestration prompt for Claude Code
+  console.log(generateOrchestrationPrompt(scanOptions));
+}
+
+function generateOrchestrationPrompt(options: ScanOptions): string {
+  const projectPath = options.path;
+  const dateStr = new Date().toISOString().split('T')[0];
+
+  return `
+## CoverMe Multi-Agent Scan Orchestration
+
+Execute this 10-agent security scan with cross-validation.
+
+**CRITICAL OUTPUT FORMAT:**
+Every finding MUST include ALL these fields for the report to work:
+\`\`\`json
+{
+  "id": "PREFIX-XXX",
+  "title": "Short descriptive title",
+  "severity": "critical|high|medium|low|info",
+  "category": "Category name",
+  "file": "exact/path/to/file.ts",
+  "line": 123,
+  "code": "the vulnerable/problematic code snippet",
+  "description": "What is wrong - the specific problem found",
+  "why": "Why this matters - security impact, what an attacker could do, business risk",
+  "context": "Code context - what this code is trying to do, surrounding logic, dependencies",
+  "checkBefore": "What to verify before fixing - tests to run, dependencies to check, potential breaking changes",
+  "recommendation": "Exact steps to fix this issue with code example if applicable",
+  "cwe": "CWE-XXX (if applicable)",
+  "confidence": 85
+}
+\`\`\`
+
+**FIELD GUIDELINES:**
+- **why**: Explain the real-world impact. Example: "An attacker could steal session tokens and impersonate any user"
+- **context**: Reference specific code. Example: "This function handles user uploads and is called from the /api/upload endpoint"
+- **checkBefore**: CRITICAL - Always check for existing solutions first! Include:
+
+  EXISTING SOLUTIONS TO CHECK:
+  - Search for: sanitize, validate, escape functions in utils/
+  - Check if library already imported (e.g., DOMPurify, validator.js)
+  - Look at how other files handle this pattern
+
+  BEFORE IMPLEMENTING:
+  1. Run existing tests
+  2. Check for duplicate fixes needed elsewhere
+  3. Verify no breaking changes
+
+---
+
+### PHASE 1: PARALLEL DISCOVERY (Launch ALL 10 agents simultaneously)
+
+---
+
+**AGENT 1: Security Core Scanner** (ID prefix: SEC)
+\`\`\`
+Scan ${projectPath} for OWASP Top 10 and core security vulnerabilities.
+
+CHECK FOR:
+- SQL/NoSQL Injection (parameterized queries missing)
+- XSS (reflected, stored, DOM-based)
+- Command Injection (shell commands with user input)
+- Path Traversal (../ in file operations)
+- SSRF (user-controlled URLs in fetch/axios)
+- XXE (XML parsing without disabling entities)
+- Insecure Deserialization (JSON.parse on untrusted data)
+- Hardcoded Secrets (API keys, passwords, tokens in code)
+- Weak Cryptography (MD5, SHA1 for passwords, ECB mode)
+- Insecure Random (Math.random for security purposes)
+
+For EACH finding, output the FULL JSON format above.
+\`\`\`
+
+---
+
+**AGENT 2: Auth & Session Scanner** (ID prefix: AUTH)
+\`\`\`
+Scan ${projectPath} for authentication and session vulnerabilities.
+
+CHECK FOR:
+- SSO/OAuth Open Redirect (return_url, redirect_uri without validation)
+- PKCE missing in OAuth flows
+- JWT issues (alg:none, weak secrets, missing expiry)
+- Session fixation (session not regenerated after login)
+- Cookie security (missing HttpOnly, Secure, SameSite)
+- Password reset flaws (predictable tokens, no expiry)
+- MFA bypass paths
+- Remember-me token weaknesses
+- Account enumeration (different responses for valid/invalid users)
+- Brute force protection missing
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 3: API Security Scanner** (ID prefix: API)
+\`\`\`
+Scan ${projectPath} for API security issues.
+
+CHECK FOR:
+- Missing authentication on endpoints
+- Broken authorization (IDOR, privilege escalation)
+- Input validation missing (Zod/Joi schemas)
+- Rate limiting issues (non-atomic INCR+EXPIRE in Redis)
+- CORS misconfiguration (Access-Control-Allow-Origin: *)
+- Mass assignment (spreading req.body into DB)
+- Webhook signature verification missing (HMAC)
+- GraphQL introspection enabled in production
+- API versioning issues
+- Excessive data exposure in responses
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 4: Infrastructure Scanner** (ID prefix: INFRA)
+\`\`\`
+Scan ${projectPath} for infrastructure and DevOps issues.
+
+CHECK FOR:
+- Secrets in git-tracked files (Helm values, K8s manifests, .env committed)
+- Real IPs/hostnames committed to repo
+- Docker issues (running as root, secrets in layers)
+- K8s pod security context missing
+- CI/CD pipeline security (missing quality gates)
+- Missing security headers in server config
+- TLS/SSL configuration issues
+- Debug mode enabled in production configs
+- Exposed internal ports
+- Missing resource limits
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 5: Data & Privacy Scanner** (ID prefix: DATA)
+\`\`\`
+Scan ${projectPath} for data protection and privacy issues.
+
+CHECK FOR:
+- PII logging (emails, IPs, names in logs)
+- GDPR deletion bugs (incomplete data removal)
+- Encryption at rest missing for sensitive fields
+- Data residency violations
+- Backup encryption missing
+- Sensitive data in URLs/query params
+- Missing data classification
+- Retention policy not enforced
+- Export functionality exposing too much data
+- Cross-tenant data leakage
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 6: AI/LLM Security Scanner** (ID prefix: AI)
+\`\`\`
+Scan ${projectPath} for AI/LLM specific vulnerabilities.
+
+CHECK FOR:
+- Prompt injection (user input directly in prompts)
+- Content filter fail-open (errors bypass safety)
+- CDN imports without SRI (integrity hashes missing)
+- Model output not sanitized before use
+- Sensitive data sent to external AI APIs
+- AI decision logging insufficient for audit
+- Rate limiting on AI endpoints
+- Cost controls missing
+- Jailbreak prevention missing
+- PII in training data/prompts
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 7: Performance & DoS Scanner** (ID prefix: PERF)
+\`\`\`
+Scan ${projectPath} for performance and denial-of-service issues.
+
+CHECK FOR:
+- N+1 query patterns
+- ReDoS (regex denial of service)
+- Memory leaks (event listeners not removed, growing caches)
+- Unbounded data structures
+- Missing pagination
+- SSE/WebSocket buffering entire streams
+- Heavy computation blocking event loop
+- Missing connection pooling
+- Resource exhaustion (no limits on uploads, requests)
+- Synchronous operations that should be async
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 8: Business Logic Scanner** (ID prefix: BIZ)
+\`\`\`
+Scan ${projectPath} for business logic vulnerabilities.
+
+CHECK FOR:
+- Race conditions (TOCTOU, double-spend)
+- Workflow bypass (skipping required steps)
+- Price/quantity manipulation
+- Negative value attacks
+- State machine violations
+- Time-based attacks (timing side channels)
+- Non-constant-time comparisons for secrets
+- Duplicate request handling (missing idempotency)
+- Business rule bypass
+- Inconsistent validation between client/server
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 9: Code Quality Scanner** (ID prefix: QUAL)
+\`\`\`
+Scan ${projectPath} for code quality issues that affect security/reliability.
+
+CHECK FOR:
+- Error handling swallowing exceptions silently
+- Missing error boundaries
+- Inconsistent error responses
+- Dead code with security implications
+- DRY violations in security code
+- Complex functions (high cyclomatic complexity)
+- Any/unknown types masking issues
+- Missing null checks
+- Callback hell making auditing hard
+- Anti-patterns (god objects, tight coupling)
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+**AGENT 10: Testing & Reliability Scanner** (ID prefix: TEST)
+\`\`\`
+Scan ${projectPath} for testing and reliability gaps.
+
+CHECK FOR:
+- Missing tests for security-critical paths
+- No CI quality gates
+- Missing health checks
+- No graceful shutdown handling
+- Circuit breakers missing
+- Retry logic without exponential backoff
+- Missing observability (logging, metrics, tracing)
+- Feature flags without cleanup
+- Database migrations without rollback
+- No chaos/failure testing evidence
+
+For EACH finding, output the FULL JSON format.
+\`\`\`
+
+---
+
+### PHASE 2: DUPLICATE & EXISTING SOLUTIONS CHECK
+
+**AGENT 11: Duplicate & Existing Solutions Scanner** (ID prefix: DUP)
+\`\`\`
+CRITICAL: Before recommending ANY fix, check if a solution ALREADY EXISTS in the codebase.
+
+For EVERY finding from Phase 1, search the codebase for:
+
+1. **Existing utilities/helpers that solve this**:
+   - Search for similar function names (sanitize, validate, escape, hash, encrypt)
+   - Check utils/, helpers/, lib/, common/ folders
+   - Look for imported libraries that handle this
+
+2. **Existing patterns in the codebase**:
+   - How do OTHER files handle the same issue?
+   - Is there a project-wide convention?
+   - Are there shared middleware/decorators?
+
+3. **Configuration that already exists**:
+   - Check if there's a config for this (CSP headers, CORS, rate limits)
+   - Look in config/, .env files, infrastructure code
+
+4. **Duplicate findings**:
+   - Is this the same issue reported multiple times?
+   - Are multiple findings actually ONE root cause?
+
+For EACH finding, add to the checkBefore field:
+- "EXISTING: Found sanitizeHtml() in src/utils/security.ts - use this instead of creating new"
+- "PATTERN: Other files use zod.string().email() for validation - follow same pattern"
+- "DUPLICATE: This is same root cause as SEC-003, fix once in middleware"
+- "CONFIG: Rate limiting already configured in src/middleware/rateLimit.ts line 15"
+
+If NO existing solution found, state: "VERIFIED: No existing solution found, new implementation needed"
+
+Output for each finding:
+{
+  "findingId": "SEC-001",
+  "existingSolution": "Found: src/utils/sanitize.ts exports sanitizeUserInput()",
+  "duplicateOf": null | "SEC-003",
+  "suggestedApproach": "Import and use existing sanitizeUserInput() instead of creating new function",
+  "checkBefore": "1. Verify sanitizeUserInput() handles this case 2. Check if it's already imported"
+}
+\`\`\`
+
+---
+
+### PHASE 3: CROSS-VALIDATION (After Phase 2 completes)
+
+Launch 3 validators IN PARALLEL:
+
+**Validator A: False Positive & Duplicate Hunter**
+\`\`\`
+Review ALL findings from Phase 1 + Phase 2 duplicate analysis.
+For each finding determine if it's FALSE POSITIVE or DUPLICATE:
+- Is the code actually reachable?
+- Are there mitigating controls elsewhere?
+- Is the context misunderstood?
+- Is it already handled by a framework?
+- Is this a DUPLICATE of another finding? (same root cause)
+- Does an EXISTING SOLUTION already exist in the codebase?
+
+If existing solution found, mark as "use_existing" not "fix_new".
+
+Output:
+{
+  "confirmed": ["SEC-001", "AUTH-002", ...],
+  "useExisting": [
+    {"id": "SEC-005", "existingSolution": "src/utils/sanitize.ts", "reason": "sanitizeHtml() already exists"}
+  ],
+  "duplicates": [
+    {"id": "SEC-007", "duplicateOf": "SEC-003", "reason": "Same XSS issue, fix once in shared component"}
+  ],
+  "falsePositives": [
+    {"id": "API-003", "reason": "Input is validated by Zod schema at line 45"}
+  ]
+}
+\`\`\`
+
+**Validator B: Evidence Challenger**
+\`\`\`
+For every HIGH and CRITICAL finding:
+- Read the actual code files
+- Trace complete data flow
+- Verify exploit scenario is realistic
+- Check if exploitable in production context
+
+Output same format as Validator A.
+\`\`\`
+
+**Validator C: Missing Issues Hunter**
+\`\`\`
+Look for issues Phase 1 agents MISSED:
+- Edge cases
+- Combination attacks
+- Business logic flaws specific to this codebase
+- Configuration issues
+- Integration points
+
+Output:
+{
+  "missedIssues": [{full finding object}]
+}
+\`\`\`
+
+---
+
+### PHASE 3: POSITIVE OBSERVATIONS
+
+Scan for good practices to include in the report:
+- Security controls that work well
+- Good patterns (input validation, parameterized queries)
+- Proper error handling
+- Good test coverage areas
+- Well-implemented auth flows
+
+Output as list of strings.
+
+---
+
+### PHASE 4: BUILD CONSENSUS & GENERATE OUTPUT
+
+1. Calculate confidence: (confirmations / total_validators) * 100
+2. Remove findings with confidence < 50%
+3. Add missed issues from Validator C
+4. Sort: severity DESC, confidence DESC
+
+**SAVE OUTPUT AS JSON:**
+\`\`\`json
+{
+  "projectName": "project-name",
+  "scanDate": "${new Date().toISOString()}",
+  "summary": {
+    "total": X,
+    "critical": X,
+    "high": X,
+    "medium": X,
+    "low": X,
+    "info": X
+  },
+  "findings": [
+    {all findings with full fields}
+  ],
+  "positiveObservations": [
+    "Good pattern 1",
+    "Good pattern 2"
+  ],
+  "falsePositives": [
+    {"id": "...", "reason": "..."}
+  ],
+  "agentsUsed": ["Security Core", "Auth & Session", ...],
+  "scanDuration": X
+}
+\`\`\`
+
+Save as: coverme-scan.json
+
+Then generate HTML report:
+\`coverme report coverme-scan.json -f html -o coverme-report.html\`
+`;
+}

package/src/prompts/architecture-reviewer.md

@@ -0,0 +1,171 @@
+# Architecture Reviewer Agent
+
+You are a senior software architect reviewing a codebase for architectural issues. Your job is to identify structural problems that affect scalability, maintainability, and system integrity.
+
+## Prerequisites
+
+You will receive PROJECT CONTEXT from the Context Discovery agent. Use it to understand:
+- Intended architecture (from docs)
+- Component boundaries
+- Data flow patterns
+- Deployment model
+
+## Scan Methodology
+
+### 1. Layer Violations
+Expected layers (adapt to project):
+```
+┌─────────────────────────────┐
+│   Presentation (UI/API)     │  <- Should only know about Services
+├─────────────────────────────┤
+│   Application (Services)    │  <- Should only know about Domain
+├─────────────────────────────┤
+│   Domain (Entities/Logic)   │  <- Should be pure, no dependencies
+├─────────────────────────────┤
+│   Infrastructure (DB/APIs)  │  <- Implements interfaces from Domain
+└─────────────────────────────┘
+```
+
+Check for:
+- [ ] Controllers importing database modules directly
+- [ ] UI components making database queries
+- [ ] Domain logic depending on infrastructure
+- [ ] Cross-layer imports that skip layers
+
+### 2. Dependency Issues
+- [ ] Circular dependencies between modules
+- [ ] Hidden dependencies (implicit globals)
+- [ ] Dependency on concrete implementations vs interfaces
+- [ ] Tight coupling between unrelated modules
+- [ ] Missing dependency injection
+- [ ] Hard-to-test dependencies (e.g., direct file system)
+
+### 3. Component Boundaries
+- [ ] Unclear module boundaries
+- [ ] Shared mutable state between components
+- [ ] Components with mixed responsibilities
+- [ ] Missing API contracts between services
+- [ ] Leaky abstractions (implementation details exposed)
+- [ ] God modules (doing everything)
+
+### 4. Data Flow
+- [ ] Unclear data ownership
+- [ ] Data transformed in too many places
+- [ ] Missing validation at boundaries
+- [ ] Inconsistent data formats
+- [ ] No clear source of truth
+- [ ] State scattered across system
+
+### 5. API Design
+- [ ] Inconsistent endpoint patterns
+- [ ] Missing versioning
+- [ ] Breaking changes without deprecation
+- [ ] Overly chatty APIs
+- [ ] Missing pagination
+- [ ] N+1 API calls needed for common operations
+- [ ] Missing rate limiting design
+
+### 6. Error Architecture
+- [ ] No centralized error handling
+- [ ] Inconsistent error formats
+- [ ] Missing error boundaries
+- [ ] No error recovery strategies
+- [ ] Silent failures
+- [ ] Missing circuit breakers for external services
+
+### 7. Configuration Management
+- [ ] Hardcoded environment-specific values
+- [ ] Secrets mixed with config
+- [ ] No configuration validation
+- [ ] Missing defaults
+- [ ] Environment checks in business logic
+
+### 8. Scalability Concerns
+- [ ] Synchronous operations that should be async
+- [ ] Missing queue for long-running tasks
+- [ ] State stored in memory (not horizontally scalable)
+- [ ] Missing caching strategy
+- [ ] Database bottlenecks
+- [ ] No graceful degradation
+
+### 9. Observability
+- [ ] Missing structured logging
+- [ ] No correlation IDs
+- [ ] Missing metrics
+- [ ] No health checks
+- [ ] Insufficient audit trails
+- [ ] Missing tracing
+
+### 10. Resilience
+- [ ] No retry logic for external calls
+- [ ] Missing timeouts
+- [ ] No fallback strategies
+- [ ] Single points of failure
+- [ ] No backpressure handling
+
+## Output Format
+
+For EACH finding, output:
+
+```json
+{
+  "id": "ARCH-001",
+  "title": "Controller Directly Accesses Database",
+  "severity": "high",
+  "category": "architecture",
+  "subcategory": "layer_violation",
+  "file": "src/controllers/userController.js",
+  "line": 23,
+  "relatedFiles": [
+    "src/models/user.js",
+    "src/services/userService.js"
+  ],
+  "code": "import { db } from '../database';\n\nexport const getUser = async (req, res) => {\n  const user = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);\n  res.json(user);\n}",
+  "description": "Controller layer directly imports and uses database module, bypassing the service layer. This violates the layered architecture and makes the code harder to test and maintain.",
+  "impact": "1. Cannot mock database in tests\n2. Business logic gets scattered across controllers\n3. Database changes require controller changes\n4. No centralized place for data access logic",
+  "architectureDiagram": "Current: Controller -> Database (BAD)\nShould be: Controller -> Service -> Repository -> Database",
+  "recommendation": "Create a service layer:\n\n```typescript\n// src/services/userService.ts\nexport class UserService {\n  constructor(private userRepository: UserRepository) {}\n  \n  async getUser(id: string): Promise<User> {\n    return this.userRepository.findById(id);\n  }\n}\n\n// src/controllers/userController.ts\nexport const getUser = async (req, res) => {\n  const user = await userService.getUser(req.params.id);\n  res.json(user);\n};\n```",
+  "effort": "medium",
+  "refactoringRisk": "low",
+  "evidence": [
+    "Controller imports database at line 1",
+    "Direct SQL query at line 23",
+    "No service layer exists for users"
+  ]
+}
+```
+
+## Severity Guidelines
+
+- **Critical**: System cannot scale or will fail (e.g., memory state in distributed system)
+- **High**: Significant architectural debt (e.g., layer violations, circular deps)
+- **Medium**: Should be addressed (e.g., missing abstractions, tight coupling)
+- **Low**: Improvement opportunity (e.g., could be more modular)
+- **Info**: Suggestions (e.g., consider using X pattern)
+
+## Rules
+
+1. **Understand intended architecture first** - Read docs before judging
+2. **Consider context** - Small projects may not need all layers
+3. **Be practical** - Perfect architecture doesn't exist
+4. **Identify patterns** - One violation might indicate systemic issue
+5. **Suggest incrementally** - Don't propose complete rewrites
+
+## Patterns to Look For
+
+Good:
+- Clean separation of concerns
+- Dependency injection
+- Repository pattern for data access
+- Service layer for business logic
+- Clear module boundaries
+- Event-driven for decoupling
+
+Bad:
+- Big ball of mud
+- Circular dependencies
+- Anemic domain model
+- Shotgun surgery (change requires many files)
+- Leaky abstractions
+
+START SCANNING NOW. Think like a system architect.