coverme-scanner 1.0.25 → 1.2.0

package/.claude/commands/coverme.md

@@ -1,6 +1,6 @@
 # CoverMe - Ultimate AI Security Scanner
 
-The most comprehensive AI-powered code scanner. 10 specialized agents + 3 validators + deep analysis.
+The most comprehensive AI-powered code scanner. 15 specialized agents + 3 validators + deep analysis.
 
 $ARGUMENTS
 
@@ -10,7 +10,7 @@ $ARGUMENTS
 2. **DO NOT STOP FOR CONFIRMATION** - Just keep going through all phases
 3. **DO NOT ASK ABOUT FILE CHANGES** - Automatically update/overwrite scan.json
 4. **DO NOT ASK TO OPEN REPORT** - Just open it automatically at the end
-5. **COMPLETE EVERYTHING IN ONE GO** - All 5 phases without interruption
+5. **COMPLETE EVERYTHING IN ONE GO** - All 6 phases without interruption
 6. **RUN AGENTS IN BACKGROUND** - Use `run_in_background: true` for all Task tool calls
 7. **RUN BASH IN BACKGROUND** - Use `run_in_background: true` for long Bash commands
 
@@ -18,9 +18,27 @@ Execute ALL phases automatically. Do NOT stop until the HTML report is open.
 
 ---
 
-## Phase 0: Load Custom Agents (if exists)
+## Phase 0: Project Discovery & Load Custom Agents
 
-**FIRST**, check if `.coverme/agents.json` exists:
+### Step 1: Understand the Project
+Before scanning, understand what you're scanning. Run these commands:
+```bash
+# Get project info
+cat package.json 2>/dev/null | head -20
+cat README.md 2>/dev/null | head -50
+ls -la
+```
+
+Create a mental model of:
+- **Project type**: Backend API, Frontend SPA, Full-stack, CLI tool, Library, etc.
+- **Tech stack**: Node.js, Python, React, Next.js, etc.
+- **Main purpose**: What does this project do? (1-2 sentences)
+- **Architecture**: Monolith, microservices, serverless, etc.
+
+This context will be included in the final report.
+
+### Step 2: Load Custom Agents (if exists)
+Check if `.coverme/agents.json` exists:
 ```bash
 cat .coverme/agents.json 2>/dev/null || echo "NO_CUSTOM_AGENTS"
 ```

package/README.md

@@ -1,127 +1,416 @@
-# 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
+
+**21 AI Agents | Auto-Detection | Zero Config | One Command**
+
+[![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 21 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.**
+
+---
+
+## 21 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 |
+
+</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
+```
+
+---
+
+## 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 21 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>