mpx-scan 1.2.1 → 1.3.1

package/bin/cli.js

@@ -12,6 +12,7 @@ const chalk = require('chalk');
 const { scan } = require('../src/index');
 const { formatReport, formatBrief } = require('../src/reporters/terminal');
 const { formatJSON } = require('../src/reporters/json');
+const { generatePDF, getDefaultPDFFilename } = require('../src/reporters/pdf');
 const { generateFixes, PLATFORMS } = require('../src/generators/fixes');
 const { getSchema } = require('../src/schema');
 const { 
@@ -25,13 +26,13 @@ const {
 
 const pkg = require('../package.json');
 
-// Exit codes per AI-native spec
+// Exit codes
 const EXIT = {
   SUCCESS: 0,           // Success, no issues found
-  ISSUES_FOUND: 1,      // Success, issues found
-  BAD_ARGS: 2,          // Invalid arguments
-  CONFIG_ERROR: 3,      // Configuration error
-  NETWORK_ERROR: 4      // Network/connectivity error
+  ISSUES_FOUND: 1,      // Issues found or error occurred
+  BAD_ARGS: 2,          // Invalid arguments / bad usage
+  CONFIG_ERROR: 1,      // Configuration error
+  NETWORK_ERROR: 1      // Network/connectivity error
 };
 
 // Auto-detect non-interactive mode
@@ -39,6 +40,12 @@ const isInteractive = process.stdout.isTTY && !process.env.CI;
 
 const program = new Command();
 
+// Error handling — set before any command/option registration
+program.exitOverride();
+program.configureOutput({
+  writeErr: () => {} // Suppress Commander's own error output; we handle it in the catch below
+});
+
 program
   .name('mpx-scan')
   .description('Professional website security scanner — check headers, SSL, DNS, and more')
@@ -47,14 +54,15 @@ program
   .option('--full', 'Run all checks (Pro only)')
   .option('--json', 'Output as JSON (machine-readable)')
   .option('--brief', 'Brief output (one-line summary)')
-  .option('--quiet, -q', 'Minimal output (results only, no banners)')
+  .option('-q, --quiet', 'Minimal output (results only, no banners)')
   .option('--no-color', 'Disable colored output')
   .option('--batch', 'Batch mode: read URLs from stdin (one per line)')
   .option('--schema', 'Output JSON schema describing all commands and flags')
   .option('--fix <platform>', `Generate fix config for platform (${PLATFORMS.join(', ')})`)
+  .option('--pdf [filename]', 'Export results as a PDF report')
   .option('--timeout <seconds>', 'Connection timeout', '10')
   .option('--ci', 'CI/CD mode: exit 1 if score below threshold')
-  .option('--min-score <score>', 'Minimum score for CI mode (default: 70)', '70')
+  .option('--min-score <score>', 'Minimum score for CI mode', '70')
   .action(async (url, options) => {
     // Handle --schema flag
     if (options.schema) {
@@ -71,7 +79,8 @@ program
 
     // Show help if no URL provided
     if (!url) {
-      program.help();
+      program.outputHelp();
+      process.exit(EXIT.BAD_ARGS);
       return;
     }
     
@@ -89,6 +98,31 @@ async function runSingleScan(url, options) {
   }
 
   try {
+    // BUG-03: Validate --fix platform BEFORE scanning (exits 2 for invalid platforms)
+    if (options.fix) {
+      if (!PLATFORMS.includes(options.fix)) {
+        if (jsonMode) {
+          console.log(JSON.stringify({ error: `Invalid platform: "${options.fix}". Valid platforms: ${PLATFORMS.join(', ')}`, code: 'ERR_BAD_ARGS' }, null, 2));
+        } else {
+          console.error(chalk.red(`Error: Invalid platform: "${options.fix}"`));
+          console.error(chalk.yellow(`Valid platforms: ${PLATFORMS.join(', ')}`));
+          console.error('');
+        }
+        return EXIT.BAD_ARGS;
+      }
+    }
+
+    // Validate timeout
+    const timeoutVal = parseInt(options.timeout);
+    if (isNaN(timeoutVal) || timeoutVal < 0) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ error: 'Invalid --timeout value. Must be a non-negative number.', code: 'ERR_BAD_ARGS' }, null, 2));
+      } else {
+        console.error(chalk.red('Error: Invalid --timeout value. Must be a non-negative number.'));
+      }
+      return EXIT.BAD_ARGS;
+    }
+    
     // Check license and rate limits
     const license = getLicense();
     const rateLimit = checkRateLimit();
@@ -104,7 +138,7 @@ async function runSingleScan(url, options) {
           upgrade: 'https://mesaplex.com/mpx-scan'
         }, null, 2));
       } else {
-        console.error(chalk.red.bold('\n❌ Daily scan limit reached'));
+        console.error(chalk.red('Error: Daily scan limit reached'));
         console.error(chalk.yellow(`Free tier: ${FREE_DAILY_LIMIT} scans/day`));
         console.error(chalk.gray(`Resets: ${new Date(rateLimit.resetsAt).toLocaleString()}\n`));
         console.error(chalk.blue('Upgrade to Pro for unlimited scans:'));
@@ -122,7 +156,7 @@ async function runSingleScan(url, options) {
           upgrade: 'https://mesaplex.com/mpx-scan'
         }, null, 2));
       } else {
-        console.error(chalk.red.bold('\n❌ --full flag requires Pro license'));
+        console.error(chalk.red('Error: --full flag requires Pro license'));
         console.error(chalk.yellow('Free tier includes: headers, SSL, server checks'));
         console.error(chalk.yellow('Pro includes: all checks (DNS, cookies, SRI, exposed files, etc.)\n'));
         console.error(chalk.blue('Upgrade: https://mesaplex.com/mpx-scan\n'));
@@ -159,9 +193,48 @@ async function runSingleScan(url, options) {
       console.log(formatReport(results, { ...options, quiet: quietMode }));
     }
     
+    // Generate PDF if requested
+    if (options.pdf !== undefined) {
+      const pdfPath = (typeof options.pdf === 'string' && options.pdf)
+        ? options.pdf
+        : getDefaultPDFFilename(results.hostname);
+      try {
+        await generatePDF(results, pdfPath);
+        if (!jsonMode && !options.brief) {
+          console.error(chalk.green(`📄 PDF report saved: ${pdfPath}`));
+        }
+      } catch (pdfErr) {
+        if (jsonMode) {
+          console.error(JSON.stringify({ warning: `PDF generation failed: ${pdfErr.message}` }));
+        } else {
+          console.error(chalk.yellow(`Warning: PDF generation failed: ${pdfErr.message}`));
+        }
+      }
+    }
+
+    // Check if core scanners errored with network issues (DNS failure, connection refused, etc.)
+    const coreScanners = ['headers', 'ssl'];
+    const coreErrored = coreScanners.every(name => {
+      const section = results.sections[name];
+      if (!section) return false;
+      return section.checks.some(c => c.status === 'error' && 
+        /ENOTFOUND|ECONNREFUSED|ETIMEDOUT|ECONNRESET|network/i.test(c.message || ''));
+    });
+    if (coreErrored) {
+      return EXIT.NETWORK_ERROR;
+    }
+    
     // Determine exit code based on findings
     if (options.ci) {
       const minScore = parseInt(options.minScore);
+      if (isNaN(minScore)) {
+        if (jsonMode) {
+          console.log(JSON.stringify({ error: 'Invalid --min-score value', code: 'ERR_BAD_ARGS' }, null, 2));
+        } else {
+          console.error(chalk.red('Error: Invalid --min-score value. Must be a number.'));
+        }
+        return EXIT.BAD_ARGS;
+      }
       const percentage = Math.round((results.score / results.maxScore) * 100);
       if (percentage < minScore) {
         if (!jsonMode && !options.brief && !quietMode) {
@@ -169,6 +242,7 @@ async function runSingleScan(url, options) {
         }
         return EXIT.ISSUES_FOUND;
       }
+      return EXIT.SUCCESS;
     }
     
     // Exit 1 if there are failures, 0 if clean
@@ -182,7 +256,7 @@ async function runSingleScan(url, options) {
       const code = isNetworkError(err) ? 'ERR_NETWORK' : 'ERR_SCAN';
       console.log(JSON.stringify({ error: err.message, code }, null, 2));
     } else {
-      console.error(chalk.red.bold('\n❌ Error:'), err.message);
+      console.error(chalk.red('Error:'), err.message);
       console.error('');
     }
     return isNetworkError(err) ? EXIT.NETWORK_ERROR : EXIT.ISSUES_FOUND;
@@ -198,7 +272,7 @@ async function runBatchMode(options) {
     if (jsonMode) {
       console.log(JSON.stringify({ error: 'No URLs provided on stdin', code: 'ERR_NO_INPUT' }, null, 2));
     } else {
-      console.error(chalk.red('No URLs provided. Pipe URLs via stdin:'));
+      console.error(chalk.red('Error: No URLs provided. Pipe URLs via stdin:'));
       console.error(chalk.gray('  cat urls.txt | mpx-scan --batch --json'));
     }
     process.exit(EXIT.BAD_ARGS);
@@ -211,7 +285,7 @@ async function runBatchMode(options) {
     if (jsonMode) {
       console.log(JSON.stringify({ error: 'No valid URLs found in input', code: 'ERR_NO_INPUT' }, null, 2));
     } else {
-      console.error(chalk.red('No valid URLs found in input.'));
+      console.error(chalk.red('Error: No valid URLs found in input.'));
     }
     process.exit(EXIT.BAD_ARGS);
     return;
@@ -345,7 +419,7 @@ program
       console.log(chalk.gray('  • Batch scanning'));
       console.log('');
     } catch (err) {
-      console.error(chalk.red.bold('\n❌ Activation failed:'), err.message);
+      console.error(chalk.red('Error:'), err.message);
       console.error('');
       process.exit(EXIT.CONFIG_ERROR);
     }
@@ -362,6 +436,79 @@ program
     console.log('');
   });
 
+// Update subcommand
+program
+  .command('update')
+  .description('Check for updates and optionally install the latest version')
+  .option('--check', 'Only check for updates (do not install)')
+  .option('--json', 'Machine-readable JSON output')
+  .action(async (options, cmd) => {
+    const { checkForUpdate, performUpdate } = require('../src/update');
+    const jsonMode = options.json || cmd.parent?.opts()?.json;
+
+    try {
+      const info = checkForUpdate();
+
+      if (jsonMode) {
+        const output = {
+          current: info.current,
+          latest: info.latest,
+          updateAvailable: info.updateAvailable,
+          isGlobal: info.isGlobal
+        };
+
+        if (!options.check && info.updateAvailable) {
+          try {
+            const result = performUpdate(info.isGlobal);
+            output.updated = true;
+            output.newVersion = result.version;
+          } catch (err) {
+            output.updated = false;
+            output.error = err.message;
+          }
+        }
+
+        console.log(JSON.stringify(output, null, 2));
+        process.exit(EXIT.SUCCESS);
+        return;
+      }
+
+      // Human-readable output
+      if (!info.updateAvailable) {
+        console.log('');
+        console.log(chalk.green.bold(`✓ mpx-scan v${info.current} is up to date`));
+        console.log('');
+        process.exit(EXIT.SUCCESS);
+        return;
+      }
+
+      console.log('');
+      console.log(chalk.yellow.bold(`⬆ Update available: v${info.current} → v${info.latest}`));
+
+      if (options.check) {
+        console.log(chalk.gray(`Run ${chalk.cyan('mpx-scan update')} to install`));
+        console.log('');
+        process.exit(EXIT.SUCCESS);
+        return;
+      }
+
+      console.log(chalk.gray(`Installing v${info.latest}${info.isGlobal ? ' (global)' : ''}...`));
+
+      const result = performUpdate(info.isGlobal);
+      console.log(chalk.green.bold(`✓ Updated to v${result.version}`));
+      console.log('');
+      process.exit(EXIT.SUCCESS);
+    } catch (err) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ error: err.message, code: 'ERR_UPDATE' }, null, 2));
+      } else {
+        console.error(chalk.red('Error:'), err.message);
+        console.error('');
+      }
+      process.exit(EXIT.NETWORK_ERROR);
+    }
+  });
+
 // MCP subcommand
 program
   .command('mcp')
@@ -384,6 +531,8 @@ ${chalk.bold('Examples:')}
   ${chalk.cyan('mpx-scan example.com --json')}            JSON output
   ${chalk.cyan('mpx-scan example.com --fix nginx')}       Generate nginx config
   ${chalk.cyan('mpx-scan example.com --brief')}           One-line summary
+  ${chalk.cyan('mpx-scan example.com --pdf')}             Export PDF report
+  ${chalk.cyan('mpx-scan example.com --pdf report.pdf')}  Export PDF to specific file
   ${chalk.cyan('mpx-scan --schema')}                      Show tool schema (JSON)
   ${chalk.cyan('cat urls.txt | mpx-scan --batch --json')} Batch scan from stdin
   ${chalk.cyan('mpx-scan mcp')}                           Start MCP server
@@ -391,10 +540,8 @@ ${chalk.bold('Examples:')}
 
 ${chalk.bold('Exit Codes:')}
   0  Success, no issues found
-  1  Success, issues found
-  2  Invalid arguments
-  3  Configuration error (license, rate limit)
-  4  Network/connectivity error
+  1  Error or issues found
+  2  Invalid usage or bad arguments
 
 ${chalk.bold('Free vs Pro:')}
   ${chalk.yellow('Free:')}  3 scans/day, basic checks (headers, SSL, server)
@@ -403,4 +550,15 @@ ${chalk.bold('Free vs Pro:')}
   ${chalk.blue('Upgrade: https://mesaplex.com/mpx-scan')}
 `);
 
-program.parse();
+try {
+  program.parse();
+} catch (err) {
+  if (err.code === 'commander.version') {
+    process.exit(0);
+  }
+  if (err.code !== 'commander.help' && err.code !== 'commander.helpDisplayed') {
+    const msg = err.message.startsWith('error:') ? `Error: ${err.message.slice(7)}` : `Error: ${err.message}`;
+    console.error(chalk.red(msg));
+    process.exit(EXIT.BAD_ARGS);
+  }
+}

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "mpx-scan",
-  "version": "1.2.1",
-  "description": "Professional website security scanner CLI. Check headers, SSL, cookies, DNS, and get actionable fix suggestions. Part of the Mesaplex developer toolchain.",
+  "version": "1.3.1",
+  "description": "Website security scanner CLI. Headers, SSL, cookies, and DNS auditing. AI-native with JSON output and MCP server.",
   "main": "src/index.js",
   "bin": {
     "mpx-scan": "bin/cli.js"
   },
   "scripts": {
-    "test": "node test/run.js",
-    "start": "node bin/cli.js"
+    "test": "node test/run.js"
   },
+  "funding": "https://mesaplex.com/pricing",
   "keywords": [
+    "cli",
+    "devtools",
+    "mesaplex",
+    "ai-native",
+    "mcp",
+    "model-context-protocol",
+    "automation",
+    "json-output",
     "security",
     "scanner",
     "headers",
@@ -20,16 +28,10 @@
     "owasp",
     "devops",
     "ci-cd",
-    "mesaplex",
-    "devtools",
     "security-headers",
     "ssl-check",
     "dns-security",
-    "cors",
-    "mcp",
-    "ai-native",
-    "model-context-protocol",
-    "automation"
+    "cors"
   ],
   "author": "Mesaplex <support@mesaplex.com>",
   "license": "SEE LICENSE IN LICENSE",
@@ -38,20 +40,22 @@
     "url": "git+https://github.com/mesaplexdev/mpx-scan.git"
   },
   "homepage": "https://github.com/mesaplexdev/mpx-scan#readme",
-  "bugs": "https://github.com/mesaplexdev/mpx-scan/issues",
+  "bugs": {
+    "url": "https://github.com/mesaplexdev/mpx-scan/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^4.1.2",
-    "commander": "^12.0.0"
+    "commander": "^12.0.0",
+    "pdfkit": "^0.17.2"
   },
   "files": [
     "src/",
     "bin/",
     "README.md",
-    "LICENSE",
-    "package.json"
+    "LICENSE"
   ]
 }

package/src/index.js

@@ -7,6 +7,8 @@
  * Zero external dependencies for scanning (only chalk/commander for CLI)
  */
 
+const https = require('https');
+const http = require('http');
 const { scanHeaders } = require('./scanners/headers');
 const { scanSSL } = require('./scanners/ssl');
 const { scanCookies } = require('./scanners/cookies');
@@ -30,8 +32,58 @@ const SCANNER_TIERS = {
  * @param {object} options - Scan options
  * @returns {object} Structured scan report
  */
+/**
+ * Quick connectivity check — throws a network error if the host is unreachable.
+ * Used to provide exit code 4 (NETWORK_ERROR) early instead of silently returning error checks.
+ */
+function checkConnectivity(parsedUrl, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+    const timer = setTimeout(() => {
+      req && req.destroy();
+      const err = new Error(`ETIMEDOUT: Connection to ${parsedUrl.hostname} timed out`);
+      err.code = 'ETIMEDOUT';
+      reject(err);
+    }, timeoutMs);
+
+    const req = protocol.request({
+      hostname: parsedUrl.hostname,
+      port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+      path: parsedUrl.pathname || '/',
+      method: 'HEAD',
+      timeout: timeoutMs,
+      headers: { 'User-Agent': 'mpx-scan/1.3.0 Security Scanner' },
+      rejectUnauthorized: false,
+    }, (res) => {
+      clearTimeout(timer);
+      res.resume();
+      resolve();
+    });
+
+    req.on('error', (err) => {
+      clearTimeout(timer);
+      if (err.code === 'ENOTFOUND' || err.code === 'EAI_AGAIN' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET') {
+        reject(err);
+      } else {
+        resolve(); // Other errors (like SSL) are fine — host is reachable
+      }
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      clearTimeout(timer);
+      const err = new Error(`ETIMEDOUT: Connection to ${parsedUrl.hostname} timed out`);
+      err.code = 'ETIMEDOUT';
+      reject(err);
+    });
+
+    req.end();
+  });
+}
+
 async function scan(url, options = {}) {
   const startTime = Date.now();
+  const timeoutMs = options.timeout || 10000;
   
   // Normalize URL
   if (!url.startsWith('http://') && !url.startsWith('https://')) {
@@ -39,6 +91,9 @@ async function scan(url, options = {}) {
   }
   
   const parsedUrl = new URL(url);
+  
+  // BUG-02: Pre-scan connectivity check — throws network error → CLI maps to exit 4
+  await checkConnectivity(parsedUrl, Math.min(timeoutMs, 10000));
   const results = {
     url: parsedUrl.href,
     hostname: parsedUrl.hostname,
@@ -75,10 +130,21 @@ async function scan(url, options = {}) {
   
   const enabledScanners = allScanners.filter(s => allowedScanners.includes(s.name));
 
+  // BUG-05: Wrap each scanner in a timeout race to prevent hanging on closed ports
+  const scannerTimeout = timeoutMs + 5000; // Give scanners a bit extra beyond the connect timeout
+
   // Run scanners concurrently
   const scanPromises = enabledScanners.map(async (scanner) => {
     try {
-      const result = await scanner.fn(parsedUrl, options);
+      // BUG-05: Race scanner against timeout to prevent indefinite hang on closed ports
+      const timeoutPromise = new Promise((_, reject) => {
+        const t = setTimeout(() => {
+          reject(new Error(`Scanner timed out after ${scannerTimeout}ms`));
+        }, scannerTimeout);
+        // Allow process to exit even if timer is pending
+        if (t.unref) t.unref();
+      });
+      const result = await Promise.race([scanner.fn(parsedUrl, options), timeoutPromise]);
       return { name: scanner.name, weight: scanner.weight, result };
     } catch (err) {
       return { 

package/src/reporters/json.js

@@ -4,10 +4,12 @@
  * Machine-readable output for CI/CD pipelines
  */
 
+const pkg = require('../../package.json');
+
 function formatJSON(results, pretty = false) {
   const output = {
     mpxScan: {
-      version: '1.0.0',
+      version: pkg.version,
       scannedAt: results.scannedAt,
       scanDuration: results.scanDuration
     },