coverme-scanner 1.2.0 → 1.3.0

package/dist/prompts/runtime-verify.md

@@ -0,0 +1,353 @@
+# CoverMe Runtime Verification Agent
+
+Compare your **actual runtime environment** against **code configuration** to find dangerous mismatches.
+
+## Arguments
+
+$ARGUMENTS - Environment name (from `coverme verify list`)
+
+---
+
+## CRITICAL: This agent requires SSH access
+
+Before running, ensure:
+1. SSH environment is configured: `coverme verify setup --host user@server --name production`
+2. You have SSH key or password ready
+3. The environment name is passed as argument
+
+---
+
+## PHASE 1: Load Environment Configuration
+
+```bash
+cat .coverme/runtime.json 2>/dev/null || echo "NO_RUNTIME_CONFIG"
+```
+
+If no config found, output:
+```
+ERROR: No runtime environments configured.
+
+To set up runtime verification:
+  coverme verify setup --host user@server.com --name production
+
+Then run:
+  /coverme-verify production
+```
+
+Extract the environment details:
+- `host`: SSH host (user@server)
+- `port`: SSH port
+- `keyPath`: Optional SSH key path
+
+---
+
+## PHASE 2: Gather Code Expectations
+
+Before SSH, analyze the codebase to understand EXPECTED runtime configuration:
+
+### Check Dockerfile/Docker Compose
+```bash
+cat Dockerfile 2>/dev/null
+cat docker-compose*.yml 2>/dev/null
+```
+
+Look for:
+- `USER` directive (what user should container run as?)
+- `EXPOSE` ports
+- Environment variables
+- Volume mounts
+
+### Check Kubernetes/Helm
+```bash
+cat k8s/*.yaml helm/**/values.yaml 2>/dev/null
+```
+
+Look for:
+- `securityContext.runAsUser`
+- `securityContext.runAsNonRoot`
+- `securityContext.readOnlyRootFilesystem`
+- Resource limits
+- Service accounts
+
+### Check PM2/Process Manager
+```bash
+cat ecosystem.config.js pm2.config.js 2>/dev/null
+```
+
+Look for:
+- `user` field
+- `cwd` working directory
+- Environment variables
+
+### Check Systemd
+```bash
+cat *.service 2>/dev/null
+```
+
+Look for:
+- `User=` directive
+- `Group=` directive
+- `WorkingDirectory=`
+
+### Build Expected State Object
+```json
+{
+  "expected": {
+    "user": "appuser",
+    "uid": 1000,
+    "workDir": "/app",
+    "ports": [3000, 8080],
+    "env": ["NODE_ENV=production"],
+    "readOnlyFs": true,
+    "source": "Dockerfile line 15: USER appuser"
+  }
+}
+```
+
+---
+
+## PHASE 3: SSH and Gather Runtime State
+
+**IMPORTANT**: Use the Bash tool with SSH commands. The user has pre-configured SSH access.
+
+Build SSH command prefix:
+```
+SSH_CMD="ssh -o StrictHostKeyChecking=no -p {port} {keyPath ? '-i ' + keyPath : ''} {host}"
+```
+
+### Check Running Processes
+
+```bash
+# Find Node.js/Python/Java processes
+$SSH_CMD "ps aux | grep -E 'node|python|java|pm2' | grep -v grep"
+
+# Get current user
+$SSH_CMD "whoami"
+
+# Get user running the app
+$SSH_CMD "ps -eo user,pid,cmd | grep -E 'node|python|java' | head -5"
+```
+
+### Check Docker Containers (if Docker)
+
+```bash
+# List running containers
+$SSH_CMD "docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}'"
+
+# Get user inside container
+$SSH_CMD "docker exec {container_name} whoami"
+
+# Get container user ID
+$SSH_CMD "docker exec {container_name} id"
+
+# Check container security
+$SSH_CMD "docker inspect {container_name} --format '{{.Config.User}} {{.HostConfig.ReadonlyRootfs}} {{.HostConfig.Privileged}}'"
+```
+
+### Check Kubernetes Pods (if K8s)
+
+```bash
+# Get pods
+$SSH_CMD "kubectl get pods -o wide"
+
+# Get security context
+$SSH_CMD "kubectl get pod {pod_name} -o jsonpath='{.spec.securityContext}'"
+
+# Get container user
+$SSH_CMD "kubectl exec {pod_name} -- id"
+```
+
+### Check PM2 Processes
+
+```bash
+# PM2 status
+$SSH_CMD "pm2 list"
+
+# PM2 process details
+$SSH_CMD "pm2 show 0 | grep -E 'user|uid|gid|cwd'"
+```
+
+### Check System Permissions
+
+```bash
+# Check file permissions on app directory
+$SSH_CMD "ls -la /app/ 2>/dev/null || ls -la /home/*/app/ 2>/dev/null"
+
+# Check who owns the app files
+$SSH_CMD "stat -c '%U:%G %a %n' /app/* 2>/dev/null | head -10"
+
+# Check sensitive files
+$SSH_CMD "ls -la /app/.env* /app/config/*.json 2>/dev/null"
+```
+
+### Check Network
+
+```bash
+# Check listening ports
+$SSH_CMD "netstat -tlnp 2>/dev/null || ss -tlnp"
+
+# Check firewall rules
+$SSH_CMD "iptables -L -n 2>/dev/null || ufw status 2>/dev/null"
+```
+
+### Build Actual State Object
+```json
+{
+  "actual": {
+    "user": "root",
+    "uid": 0,
+    "workDir": "/app",
+    "ports": [3000, 8080, 6379],
+    "env": ["NODE_ENV=production"],
+    "readOnlyFs": false,
+    "privileged": false,
+    "containerUser": "root",
+    "processUser": "root"
+  }
+}
+```
+
+---
+
+## PHASE 4: Compare and Generate Findings
+
+Compare expected vs actual for EACH field:
+
+### Critical Mismatches (RUNTIME prefix)
+
+| Finding | Severity | When to Report |
+|---------|----------|----------------|
+| RUNTIME-001 | CRITICAL | Code says `USER appuser`, runtime runs as `root` |
+| RUNTIME-002 | CRITICAL | Dockerfile has `USER`, but container runs as root |
+| RUNTIME-003 | HIGH | `runAsNonRoot: true` in K8s, but pod runs as root |
+| RUNTIME-004 | HIGH | ReadOnlyRootFilesystem expected, but writable |
+| RUNTIME-005 | HIGH | Privileged container not expected |
+| RUNTIME-006 | MEDIUM | Port exposed that shouldn't be (e.g., Redis 6379) |
+| RUNTIME-007 | MEDIUM | Environment variables missing or different |
+| RUNTIME-008 | MEDIUM | File permissions too open (777, world-writable) |
+| RUNTIME-009 | LOW | Working directory mismatch |
+| RUNTIME-010 | INFO | Extra processes running not in config |
+
+### Output Format
+
+```json
+{
+  "id": "RUNTIME-001",
+  "title": "Container running as root despite USER directive",
+  "severity": "critical",
+  "category": "runtime-mismatch",
+  "fixOwner": "devops",
+  "fixType": "infrastructure",
+
+  "expected": {
+    "value": "appuser (uid 1000)",
+    "source": "Dockerfile:15 - USER appuser",
+    "code": "USER appuser"
+  },
+
+  "actual": {
+    "value": "root (uid 0)",
+    "source": "docker exec container_name id",
+    "evidence": "uid=0(root) gid=0(root) groups=0(root)"
+  },
+
+  "description": "The Dockerfile specifies USER appuser, but the container is actually running as root. This happened because the docker run command included --user root or the orchestration layer overrode the USER directive.",
+
+  "impact": "Running as root inside the container means any code execution vulnerability (like the DuckDB file read issue) can access ALL files on the system, not just application files. Attackers can read /etc/shadow, modify system configs, and potentially escape the container.",
+
+  "recommendation": "1. Check docker-compose.yml for user: root override\n2. Check K8s deployment for securityContext.runAsUser: 0\n3. Ensure no --user root in docker run commands\n4. Add securityContext.runAsNonRoot: true to K8s",
+
+  "commands": {
+    "verify": "docker exec container_name id",
+    "fix_docker": "docker run --user 1000:1000 ...",
+    "fix_k8s": "kubectl patch deployment app -p '{\"spec\":{\"template\":{\"spec\":{\"securityContext\":{\"runAsNonRoot\":true}}}}}'"
+  }
+}
+```
+
+---
+
+## PHASE 5: Generate Verification Report
+
+Save to `.coverme/runtime-verify.json`:
+
+```json
+{
+  "environment": "production",
+  "host": "user@server.com",
+  "verifiedAt": "2024-01-15T10:30:00Z",
+
+  "summary": {
+    "total": 5,
+    "critical": 1,
+    "high": 2,
+    "medium": 1,
+    "low": 1,
+    "matches": 8
+  },
+
+  "mismatches": [
+    { "...finding objects..." }
+  ],
+
+  "matches": [
+    {
+      "check": "NODE_ENV",
+      "expected": "production",
+      "actual": "production",
+      "status": "match"
+    }
+  ],
+
+  "rawData": {
+    "expected": { "...from code analysis..." },
+    "actual": { "...from SSH commands..." }
+  }
+}
+```
+
+---
+
+## PHASE 6: Display Results
+
+Print summary:
+
+```
+Runtime Verification: production (user@server.com)
+=================================================
+
+CRITICAL MISMATCH: Container running as root!
+
+  Expected: USER appuser (from Dockerfile:15)
+  Actual:   root (uid=0)
+
+  This is why your DuckDB file read vulnerability was exploitable!
+  The code assumed it would run as appuser with limited permissions,
+  but in production it runs as root with access to everything.
+
+  Fix: Add to your deployment:
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 1000
+
+--------------------------------------------------
+
+Summary:
+  Matches:    8 configurations match
+  Mismatches: 5 found
+    - 1 CRITICAL (user mismatch)
+    - 2 HIGH (permissions)
+    - 1 MEDIUM (ports)
+    - 1 LOW (working directory)
+
+Full report: .coverme/runtime-verify.json
+```
+
+---
+
+## Security Notes
+
+- SSH credentials are NOT stored by CoverMe
+- Commands are read-only (no modifications to remote system)
+- All SSH output is included in the report for audit
+- Consider using a dedicated read-only SSH user for verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverme-scanner",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI-powered code scanner with multi-agent verification for Claude Code. One command scans everything.",
   "main": "dist/index.js",
   "bin": {

package/src/cli/index.ts

@@ -121,4 +121,131 @@ agentCmd
     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: { host?: string; port?: string; key?: string; name?: string }) => {
+    const covermeDir = join(process.cwd(), '.coverme');
+    const configPath = join(covermeDir, 'runtime.json');
+
+    if (!existsSync(covermeDir)) {
+      mkdirSync(covermeDir, { recursive: true });
+    }
+
+    let config: any = { environments: [] };
+    if (existsSync(configPath)) {
+      config = JSON.parse(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: any, i: number) => {
+          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: any) => e.name !== envName);
+
+    config.environments.push({
+      name: envName,
+      host: options.host,
+      port: parseInt(options.port || '22'),
+      keyPath: options.key || null,
+      addedAt: new Date().toISOString()
+    });
+
+    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 = join(process.cwd(), '.coverme', 'runtime.json');
+
+    if (!existsSync(configPath)) {
+      console.log('No environments configured.');
+      console.log('Run: coverme verify setup --host user@server.com --name production');
+      return;
+    }
+
+    const config = JSON.parse(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: any, i: number) => {
+      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: string) => {
+    const configPath = join(process.cwd(), '.coverme', 'runtime.json');
+
+    if (!existsSync(configPath)) {
+      console.error('No environments configured.');
+      return;
+    }
+
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const idx = config.environments.findIndex((e: any) => e.name.toLowerCase() === name.toLowerCase());
+
+    if (idx === -1) {
+      console.error(`Environment "${name}" not found`);
+      return;
+    }
+
+    const removed = config.environments.splice(idx, 1)[0];
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log(`Removed environment "${removed.name}"`);
+  });
+
 program.parse();

package/src/cli/init.ts

@@ -609,6 +609,7 @@ export async function init(options: InitOptions): Promise<void> {
         "Bash(git ls-files:*)",
         "Bash(git log:*)",
         "Bash(grep:*)",
+        "Bash(ssh:*)",
         "Read(.coverme/*)",
         "Write(.coverme/*)",
         "Edit(.coverme/*)"
@@ -649,7 +650,7 @@ export async function init(options: InitOptions): Promise<void> {
 Usage:
   1. Open Claude Code in your project
   2. Type /coverme and press Enter
-  3. Wait for the scan to complete
+  3. Wait for the scan to complete (22 AI agents!)
   4. Report opens automatically in your browser
 
 Reports saved to: .coverme/
@@ -657,13 +658,18 @@ Reports saved to: .coverme/
   - scan_YYYY-MM-DD_HH-MM-SS.json
 
 Custom Agents:
-  Add your own experts to the scan:
-
   coverme agent add "John" "Check all .env files for exposed secrets"
-  coverme agent add "Sarah" "Find regex patterns vulnerable to ReDoS"
+  coverme agent list
+  coverme agent remove "John"
+
+Runtime Verification (Optional):
+  Compare your actual runtime environment against code configuration.
+  Catches issues like "Dockerfile says USER appuser but container runs as root"
+
+  coverme verify setup --host user@server.com --name production
+  coverme verify list
 
-  List agents: coverme agent list
-  Remove agent: coverme agent remove "John"
+  Once configured, /coverme will automatically SSH and verify runtime.
 
 The .coverme/ folder is automatically added to .gitignore