coverme-scanner 1.1.0 → 1.3.0

package/README.md

@@ -1,127 +1,456 @@
-# CoverMe Scanner
+<div align="center">
 
-**Multi-Agent AI Code Scanner for Claude Code**
+# CoverMe
 
-One command. 7 AI agents. Complete code analysis with cross-validation.
+### The Most Comprehensive AI Security Scanner for Your Codebase
+
+**22 AI Agents | Auto-Detection | Runtime Verification | Zero Config**
+
+[![npm version](https://img.shields.io/npm/v/coverme-scanner.svg?style=flat-square)](https://www.npmjs.com/package/coverme-scanner)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+<img src="https://raw.githubusercontent.com/vibecode/coverme-scanner/main/assets/demo.gif" alt="CoverMe Demo" width="600">
+
+[Quick Start](#quick-start) | [Features](#features) | [Agents](#-21-specialized-agents) | [Reports](#-beautiful-reports) | [Custom Agents](#-custom-agents)
+
+</div>
+
+---
+
+## Why CoverMe?
+
+Traditional security scanners are **noisy** (too many false positives) and **blind** (miss context-specific issues).
+
+CoverMe is different:
+
+| Traditional Scanners | CoverMe |
+|---------------------|---------|
+| Single-pass analysis | **21 specialized AI agents** working in parallel |
+| Pattern matching | **Deep understanding** of your code's intent |
+| Generic rules | **Auto-detects** your stack and adapts |
+| 60%+ false positives | **Cross-validation** eliminates noise |
+| Requires configuration | **Zero config** - just run it |
+
+---
 
 ## Quick Start
 
 ```bash
-# Install
+# Install globally
 npm install -g coverme-scanner
 
-# Initialize in your project
+# Initialize in your project (one-time)
 coverme init
 
-# In Claude Code, run:
+# Run the scan (in Claude Code)
 /coverme
 ```
 
-That's it! The scan will analyze your codebase and generate an HTML report.
+**That's it.** Watch 22 AI agents analyze your entire codebase and generate a beautiful HTML report.
+
+---
+
+## Features
+
+### Auto-Detection
+
+CoverMe automatically detects your stack and adapts its scanning:
+
+| Category | Auto-Detected |
+|----------|---------------|
+| **Auth** | OAuth, JWT, Session, Clerk, Auth0, NextAuth, Supabase Auth, Firebase, Passport.js, API Keys |
+| **Database** | PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, Supabase, Prisma, TypeORM, Drizzle, PlanetScale, Neon, Turso |
+| **Framework** | React, Next.js, Express, Fastify, NestJS, Django, FastAPI, Flask |
+| **AI/LLM** | OpenAI, Anthropic, LangChain, Ollama, HuggingFace, Bedrock, Vertex AI |
+| **Infra** | Docker, Kubernetes, Terraform, GitHub Actions, GitLab CI |
+
+### Smart Skipping
+
+Agents that aren't relevant to your project **automatically skip**:
+- No AI code? AI Security Scanner skips.
+- No Redis? Redis Scanner skips.
+- No enclaves? Enclave Scanner skips.
+
+**Zero noise. Maximum relevance.**
+
+---
+
+## 22 Specialized Agents
+
+<details>
+<summary><b>Security Agents (Click to expand)</b></summary>
+
+| Agent | What It Finds |
+|-------|---------------|
+| **Security Core** | OWASP Top 10, SQL/NoSQL injection, XSS, Command injection, SSRF, Path traversal |
+| **Auth & Session** | OAuth flaws, JWT vulnerabilities, session fixation, cookie security, MFA bypass |
+| **API Security** | CORS misconfiguration, rate limiting, IDOR, mass assignment, webhook security |
+| **Database** | SQL injection, ORM-specific issues, connection security, RLS bypass |
+| **Redis & Cache** | KEYS command abuse, Lua injection, cache poisoning, session security |
+| **AI/LLM** | Prompt injection, content filter bypass, PII in prompts, jailbreak vectors |
+
+</details>
+
+<details>
+<summary><b>Quality & Architecture Agents (Click to expand)</b></summary>
+
+| Agent | What It Finds |
+|-------|---------------|
+| **Infrastructure** | Docker security, K8s misconfig, CI/CD secrets, IaC issues |
+| **Data & Privacy** | PII exposure, GDPR violations, encryption gaps, data retention |
+| **Performance** | N+1 queries, memory leaks, ReDoS, blocking operations |
+| **Business Logic** | Race conditions, TOCTOU, workflow bypass, pricing exploits |
+| **Code Quality** | Complexity, dead code, error handling, anti-patterns |
+| **Dead Code** | Unused dependencies, unreachable code, stale feature flags |
+
+</details>
+
+<details>
+<summary><b>Validation Agents (Click to expand)</b></summary>
+
+| Agent | What It Does |
+|-------|--------------|
+| **Design Decision Detector** | Identifies intentional patterns to prevent false positives |
+| **Context-Aware Validator** | Understands deployment context (K8s, API gateway, WAF) |
+| **Network & Architecture** | Service boundaries, trust zones, NetworkPolicy gaps |
+| **Resilience & Fallback** | Circuit breakers, retry patterns, graceful degradation |
+| **Testing & Reliability** | Test coverage gaps, missing health checks |
+| **Duplicate Scanner** | Finds existing solutions in your codebase |
+| **Executive Summary** | Generates high-level risk overview |
+| **Runtime Verification** | SSH to compare actual runtime vs code config |
+
+</details>
+
+---
+
+## Beautiful Reports
+
+CoverMe generates **professional HTML reports** with:
+
+<table>
+<tr>
+<td width="50%">
+
+**Executive Summary**
+- Risk level assessment
+- Top risks bullet points
+- Findings by owner (Dev/DevOps/Architect)
+
+**Project Overview**
+- Auto-detected stack
+- Architecture type
+- Key components
+
+</td>
+<td width="50%">
+
+**Detailed Findings**
+- Severity scoring (DREAD)
+- Code snippets with line numbers
+- Copy-paste fix recommendations
+- Claude Code prompts ready to use
+
+**Smart Filtering**
+- By severity
+- By file
+- By category
+- By owner
+
+</td>
+</tr>
+</table>
+
+### Sample Report Sections
+
+```
+Executive Summary
+-----------------
+Risk Level: HIGH
+
+Top Risks:
+- SQL injection in user search allows database access
+- Missing rate limiting enables brute force attacks
+- Admin API exposed without IP restriction
+
+Findings by Owner:
+  Developer: 5
+  DevOps: 3
+  Architect: 1
+```
+
+---
+
+## Runtime Verification (SSH)
+
+**The killer feature**: CoverMe can SSH into your servers and compare the **actual runtime** against your **code configuration**.
+
+### Why?
+
+Your Dockerfile says `USER appuser`, but the container runs as `root`. Why? Because docker-compose overrides it. **This is why vulnerabilities become exploitable.**
+
+### Setup
+
+```bash
+# Add your server (one-time)
+coverme verify setup --host deploy@production.example.com --name production
+
+# That's it! Now /coverme will automatically:
+# 1. Scan your code
+# 2. SSH to production
+# 3. Compare expected vs actual
+# 4. Report any mismatches
+```
+
+### What It Catches
+
+| Issue | Example |
+|-------|---------|
+| **User Mismatch** | Dockerfile: `USER appuser` → Runtime: `root` |
+| **Security Context Ignored** | K8s: `runAsNonRoot: true` → Pod runs as root |
+| **Ports Exposed** | Code expects 3000 → Runtime has 3000, 6379, 5432 |
+| **Permissions Wrong** | Expected: 755 → Actual: 777 |
+
+### Manage Environments
+
+```bash
+coverme verify list                    # List all configured servers
+coverme verify remove production       # Remove an environment
+```
+
+---
+
+## Custom Agents
+
+Add your own specialized agents in seconds:
+
+```bash
+# Add a custom agent
+coverme agent add "John" "Check all .env files for exposed secrets"
+coverme agent add "Sarah" "Find regex patterns vulnerable to ReDoS"
+coverme agent add "Compliance" "Check for GDPR and PCI-DSS violations"
+
+# List your agents
+coverme agent list
+
+# Remove an agent
+coverme agent remove "John"
+```
+
+Your custom agents run **alongside the 21 built-in agents** and appear in the same report.
+
+---
 
 ## How It Works
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                    COVERME ORCHESTRATOR                         │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  Phase 1: DISCOVERY (5 agents in parallel)                      │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│
-│  │ Security │ │ Quality  │ │   Arch   │ │   Deps   │ │  Perf  ││
-│  │  Agent   │ │  Agent   │ │  Agent   │ │  Agent   │ │ Agent  ││
-│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘│
-│       │            │            │            │           │      │
-│       └────────────┴────────────┴────────────┴───────────┘      │
-│                              │                                  │
-│                              ▼                                  │
-│  Phase 2: CROSS-VALIDATION (2 agents in parallel)               │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │  Cross-Validator: Challenge findings, find false positives │   │
-│  │  Deep-Dive Expert: Analyze disputed/complex issues        │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                              │                                  │
-│                              ▼                                  │
-│  Phase 3: CONSENSUS & REPORT                                    │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │  Merge findings, calculate confidence, generate report    │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## What It Finds
-
-### Security Issues
-- SQL/NoSQL Injection
-- Cross-Site Scripting (XSS)
-- Command Injection
-- Authentication/Authorization flaws
-- Hardcoded secrets
-- SSRF, Path Traversal
-
-### Code Quality
-- DRY violations
-- High complexity functions
-- Dead code
-- Anti-patterns
-- Error handling problems
-
-### Architecture Issues
-- Layer violations
-- Circular dependencies
-- Missing abstractions
-- Coupling problems
-
-### Dependency Issues
-- Known CVEs
-- Outdated packages
-- License compliance
-
-### Performance Issues
-- N+1 queries
-- Memory leaks
-- Blocking operations
-
-## Why Multi-Agent?
-
-Traditional scanners have high false positive rates. CoverMe uses a unique approach:
-
-1. **Multiple perspectives**: 5 specialized agents scan independently
-2. **Cross-validation**: 2 validators challenge the findings
-3. **Consensus**: Only high-confidence findings make the report
-
-This results in:
-- **Lower false positive rate** - Validators catch mistakes
-- **Higher coverage** - Multiple agents find different issues
-- **Confidence scores** - Know how certain each finding is
-
-## Report Output
-
-The scan produces an HTML report in `.coverme/` folder:
-
-- **Score** - A-F grade with severity breakdown
-- **Critical/High/Medium/Low Issues** - With code context and fixes
-- **Claude Code Prompts** - Copy-paste ready fix instructions
-- **Positive Observations** - Good patterns found in your code
-
-## Requirements
-
-- Claude Code CLI installed and authenticated
-- Node.js 18+
+                         COVERME ORCHESTRATOR
+    ________________________________________________________________
+   |                                                                |
+   |  PHASE 0: PROJECT DISCOVERY                                    |
+   |  [Auto-detect stack, auth, databases, frameworks]              |
+   |________________________________________________________________|
+   |                                                                |
+   |  PHASE 1: PARALLEL DISCOVERY (21 agents)                       |
+   |                                                                |
+   |  Security    Auth     API      Infra    Data     AI/LLM       |
+   |     |         |        |         |        |        |          |
+   |  Database   Redis   Quality   Logic    Perf     Dead         |
+   |     |         |        |         |        |        |          |
+   |  PII      Resil    Network   Design    CTX     Custom...     |
+   |     |         |        |         |        |        |          |
+   |     +----+----+--------+----+----+--------+----+---+          |
+   |          |                  |                  |              |
+   |          v                  v                  v              |
+   |________________________________________________________________|
+   |                                                                |
+   |  PHASE 2: CROSS-VALIDATION                                     |
+   |  [Challenge findings, find mitigations, detect false positives]|
+   |________________________________________________________________|
+   |                                                                |
+   |  PHASE 3: CONSENSUS                                            |
+   |  [Merge, dedupe, calculate confidence, generate report]        |
+   |________________________________________________________________|
+```
+
+---
+
+## Installation
+
+### Requirements
+
+- **Node.js 18+**
+- **Claude Code** CLI installed and authenticated
 - No external API keys needed (uses your Claude Code session)
 
-## Commands
+### Install
+
+```bash
+npm install -g coverme-scanner
+```
+
+### Initialize (once per project)
+
+```bash
+cd your-project
+coverme init
+```
+
+This creates:
+- `.coverme/` folder for reports
+- `.claude/commands/coverme.md` slash command
+
+### Run
+
+In Claude Code:
+```
+/coverme
+```
+
+Or with arguments:
+```
+/coverme src/
+```
+
+---
+
+## CLI Commands
 
 ```bash
-# Initialize in current project
+# Initialize CoverMe in a project
 coverme init
 
-# Generate report from JSON
+# Generate HTML report from JSON
 coverme report scan.json -f html -o report.html
+
+# Custom Agents
+coverme agent add "Name" "Task description"
+coverme agent list
+coverme agent remove "Name"
+
+# Help
+coverme --help
+```
+
+---
+
+## Configuration
+
+CoverMe works **zero-config** out of the box, but you can customize:
+
+### Custom Agents
+
+Create `.coverme/agents.json`:
+
+```json
+{
+  "agents": [
+    { "name": "Security Lead", "task": "Review all auth flows for OWASP compliance" },
+    { "name": "Performance", "task": "Find N+1 queries and memory leaks" }
+  ]
+}
+```
+
+### Ignore Patterns
+
+Add to `.coverme/config.json`:
+
+```json
+{
+  "ignore": [
+    "node_modules",
+    "dist",
+    "*.test.ts",
+    "**/__mocks__/**"
+  ]
+}
+```
+
+---
+
+## FAQ
+
+<details>
+<summary><b>How long does a scan take?</b></summary>
+
+Typically 2-5 minutes depending on codebase size. All 22 agents run in parallel.
+
+</details>
+
+<details>
+<summary><b>Does it send my code anywhere?</b></summary>
+
+CoverMe runs entirely through your local Claude Code session. Your code is processed by the same Claude API you're already using.
+
+</details>
+
+<details>
+<summary><b>Can I use it in CI/CD?</b></summary>
+
+Not yet, but it's on the roadmap. Currently CoverMe requires an interactive Claude Code session.
+
+</details>
+
+<details>
+<summary><b>What languages does it support?</b></summary>
+
+Any language Claude understands: TypeScript, JavaScript, Python, Go, Rust, Java, C#, Ruby, PHP, and more.
+
+</details>
+
+<details>
+<summary><b>How do I reduce false positives?</b></summary>
+
+CoverMe already has multiple validation agents that eliminate most false positives. For remaining cases:
+1. Add comments like `// Intentional: ...` to document design decisions
+2. Create custom agents for your specific patterns
+3. The Design Decision Detector will learn from these
+
+</details>
+
+---
+
+## Roadmap
+
+- [ ] CI/CD integration (GitHub Action)
+- [ ] VS Code extension
+- [ ] Baseline comparison (diff between scans)
+- [ ] Custom rule definitions
+- [ ] Team dashboard
+- [ ] Slack/Discord notifications
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
+
+```bash
+# Clone the repo
+git clone https://github.com/vibecode/coverme-scanner.git
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test locally
+npm link
 ```
 
+---
+
 ## License
 
-MIT
+MIT - see [LICENSE](LICENSE)
+
+---
+
+<div align="center">
+
+**Built with Claude Code**
+
+[Report Bug](https://github.com/vibecode/coverme-scanner/issues) | [Request Feature](https://github.com/vibecode/coverme-scanner/issues) | [Star on GitHub](https://github.com/vibecode/coverme-scanner)
 
+</div>

package/dist/cli/index.js

@@ -105,5 +105,115 @@ agentCmd
     (0, fs_1.writeFileSync)(agentsPath, JSON.stringify(agents, null, 2));
     console.log(`Removed agent "${removed.name}"`);
 });
+// Runtime verification commands
+const verifyCmd = program
+    .command('verify')
+    .description('Verify runtime environment matches code expectations');
+verifyCmd
+    .command('setup')
+    .description('Configure SSH access for runtime verification')
+    .option('-h, --host <host>', 'SSH host (e.g., user@server.com)')
+    .option('-p, --port <port>', 'SSH port', '22')
+    .option('-k, --key <path>', 'Path to SSH private key')
+    .option('-n, --name <name>', 'Environment name (e.g., production, staging)')
+    .action((options) => {
+    const covermeDir = (0, path_1.join)(process.cwd(), '.coverme');
+    const configPath = (0, path_1.join)(covermeDir, 'runtime.json');
+    if (!(0, fs_1.existsSync)(covermeDir)) {
+        (0, fs_1.mkdirSync)(covermeDir, { recursive: true });
+    }
+    let config = { environments: [] };
+    if ((0, fs_1.existsSync)(configPath)) {
+        config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf-8'));
+        if (!config.environments)
+            config.environments = [];
+    }
+    if (!options.host) {
+        console.log('\nRuntime Verification Setup');
+        console.log('==========================\n');
+        console.log('This feature allows CoverMe to SSH into your servers and compare');
+        console.log('the actual runtime environment against your code configuration.\n');
+        console.log('Usage:');
+        console.log('  coverme verify setup --host user@server.com --name production');
+        console.log('  coverme verify setup --host deploy@staging.example.com --key ~/.ssh/id_rsa --name staging\n');
+        console.log('Options:');
+        console.log('  -h, --host <host>  SSH host (required)');
+        console.log('  -n, --name <name>  Environment name (default: from host)');
+        console.log('  -p, --port <port>  SSH port (default: 22)');
+        console.log('  -k, --key <path>   Path to SSH private key\n');
+        if (config.environments.length > 0) {
+            console.log('Configured environments:');
+            config.environments.forEach((env, i) => {
+                console.log(`  ${i + 1}. ${env.name}: ${env.host}:${env.port}`);
+            });
+        }
+        return;
+    }
+    const envName = options.name || options.host.split('@')[1]?.split('.')[0] || 'default';
+    // Remove existing with same name
+    config.environments = config.environments.filter((e) => e.name !== envName);
+    config.environments.push({
+        name: envName,
+        host: options.host,
+        port: parseInt(options.port || '22'),
+        keyPath: options.key || null,
+        addedAt: new Date().toISOString()
+    });
+    (0, fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+    console.log(`\nAdded environment "${envName}"`);
+    console.log(`  Host: ${options.host}`);
+    console.log(`  Port: ${options.port || '22'}`);
+    if (options.key)
+        console.log(`  Key: ${options.key}`);
+    console.log('\nRun verification with:');
+    console.log(`  /coverme-verify ${envName}`);
+    console.log('\nOr in Claude Code:');
+    console.log(`  /coverme --verify ${envName}`);
+});
+verifyCmd
+    .command('list')
+    .description('List configured environments')
+    .action(() => {
+    const configPath = (0, path_1.join)(process.cwd(), '.coverme', 'runtime.json');
+    if (!(0, fs_1.existsSync)(configPath)) {
+        console.log('No environments configured.');
+        console.log('Run: coverme verify setup --host user@server.com --name production');
+        return;
+    }
+    const config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf-8'));
+    if (!config.environments || config.environments.length === 0) {
+        console.log('No environments configured.');
+        return;
+    }
+    console.log('\nConfigured Environments:\n');
+    config.environments.forEach((env, i) => {
+        console.log(`  ${i + 1}. ${env.name}`);
+        console.log(`     Host: ${env.host}:${env.port}`);
+        if (env.keyPath)
+            console.log(`     Key: ${env.keyPath}`);
+        console.log(`     Added: ${new Date(env.addedAt).toLocaleDateString()}`);
+        console.log('');
+    });
+});
+verifyCmd
+    .command('remove')
+    .description('Remove an environment')
+    .argument('<name>', 'Environment name')
+    .action((name) => {
+    const configPath = (0, path_1.join)(process.cwd(), '.coverme', 'runtime.json');
+    if (!(0, fs_1.existsSync)(configPath)) {
+        console.error('No environments configured.');
+        return;
+    }
+    const config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf-8'));
+    const idx = config.environments.findIndex((e) => e.name.toLowerCase() === name.toLowerCase());
+    if (idx === -1) {
+        console.error(`Environment "${name}" not found`);
+        return;
+    }
+    const removed = config.environments.splice(idx, 1)[0];
+    (0, fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+    console.log(`Removed environment "${removed.name}"`);
+});
 program.parse();
 //# sourceMappingURL=index.js.map