mpx-scan 1.0.0

package/src/reporters/terminal.js

@@ -0,0 +1,140 @@
+/**
+ * Terminal Reporter
+ * 
+ * Beautiful colored output for CLI with chalk
+ */
+
+const chalk = require('chalk');
+
+const STATUS_ICONS = {
+  pass: '✓',
+  warn: '⚠',
+  fail: '✗',
+  error: '⚠',
+  info: 'ℹ'
+};
+
+const STATUS_COLORS = {
+  pass: 'green',
+  warn: 'yellow',
+  fail: 'red',
+  error: 'red',
+  info: 'blue'
+};
+
+const GRADE_COLORS = {
+  'A+': 'greenBright',
+  'A': 'green',
+  'B': 'cyan',
+  'C': 'yellow',
+  'D': 'magenta',
+  'F': 'red'
+};
+
+function formatReport(results, options = {}) {
+  const lines = [];
+  
+  // Header
+  lines.push('');
+  lines.push(chalk.bold.cyan('┌─────────────────────────────────────────────────────────────┐'));
+  lines.push(chalk.bold.cyan('│') + chalk.bold('         mpx-scan — Website Security Report          ') + chalk.bold.cyan('│'));
+  lines.push(chalk.bold.cyan('└─────────────────────────────────────────────────────────────┘'));
+  lines.push('');
+  
+  // URL and basic info
+  lines.push(chalk.bold('Target:     ') + chalk.cyan(results.url));
+  lines.push(chalk.bold('Scanned:    ') + chalk.gray(new Date(results.scannedAt).toLocaleString()));
+  lines.push(chalk.bold('Duration:   ') + chalk.gray(`${results.scanDuration}ms`));
+  lines.push('');
+  
+  // Overall score
+  const gradeColor = GRADE_COLORS[results.grade] || 'gray';
+  const percentage = Math.round((results.score / results.maxScore) * 100);
+  const barLength = 40;
+  const filledLength = Math.round((percentage / 100) * barLength);
+  const bar = '█'.repeat(filledLength) + '░'.repeat(barLength - filledLength);
+  
+  lines.push(chalk.bold('Overall Score:'));
+  lines.push('  ' + chalk[gradeColor](bar));
+  lines.push('  ' + chalk.bold[gradeColor](`${results.grade}`) + chalk.gray(` (${percentage}/100)`));
+  lines.push('');
+  
+  // Summary
+  lines.push(chalk.bold('Summary:'));
+  lines.push('  ' + chalk.green(`${STATUS_ICONS.pass} ${results.summary.passed} passed`) + 
+             chalk.gray(' │ ') +
+             chalk.yellow(`${STATUS_ICONS.warn} ${results.summary.warnings} warnings`) +
+             chalk.gray(' │ ') +
+             chalk.red(`${STATUS_ICONS.fail} ${results.summary.failed} failed`));
+  lines.push('');
+  
+  // Sections
+  const sections = Object.entries(results.sections);
+  
+  for (const [name, section] of sections) {
+    const sectionGrade = section.grade;
+    const sectionColor = GRADE_COLORS[sectionGrade] || 'gray';
+    const sectionPercentage = Math.round((section.score / section.maxScore) * 100);
+    
+    lines.push(chalk.bold.underline(`\n${capitalize(name)}`));
+    lines.push(chalk.gray(`  Score: ${section.score}/${section.maxScore} (${sectionPercentage}%) — Grade: `) + chalk.bold[sectionColor](sectionGrade));
+    lines.push('');
+    
+    for (const check of section.checks) {
+      const icon = STATUS_ICONS[check.status] || '•';
+      const color = STATUS_COLORS[check.status] || 'white';
+      
+      lines.push('  ' + chalk[color](`${icon} ${check.name}`));
+      
+      if (check.message) {
+        lines.push('    ' + chalk.gray(check.message));
+      }
+      
+      if (check.value && !options.brief) {
+        const value = String(check.value).length > 100 
+          ? String(check.value).substring(0, 100) + '...'
+          : check.value;
+        lines.push('    ' + chalk.dim(`→ ${value}`));
+      }
+      
+      if (check.recommendation && !options.brief) {
+        lines.push('    ' + chalk.cyan(`💡 ${check.recommendation}`));
+      }
+    }
+  }
+  
+  // Free tier upgrade message
+  if (results.tier === 'free') {
+    lines.push('');
+    lines.push(chalk.yellow('─'.repeat(63)));
+    lines.push(chalk.yellow.bold('🔓 Upgrade to Pro for:'));
+    lines.push(chalk.yellow('  • Unlimited scans (free tier: 3/day)'));
+    lines.push(chalk.yellow('  • All security checks (DNS, cookies, SRI, exposed files)'));
+    lines.push(chalk.yellow('  • JSON/CSV export for CI/CD integration'));
+    lines.push(chalk.yellow('  • Batch scanning'));
+    lines.push('');
+    lines.push(chalk.blue('Learn more: https://mesaplex.com/mpx-scan'));
+    lines.push(chalk.yellow('─'.repeat(63)));
+  }
+  
+  lines.push('');
+  
+  return lines.join('\n');
+}
+
+function formatBrief(results) {
+  const gradeColor = GRADE_COLORS[results.grade] || 'gray';
+  const percentage = Math.round((results.score / results.maxScore) * 100);
+  
+  return `${results.url} — ${chalk.bold[gradeColor](results.grade)} (${percentage}/100) — ` +
+         `${chalk.green(results.summary.passed + ' ✓')} ${chalk.yellow(results.summary.warnings + ' ⚠')} ${chalk.red(results.summary.failed + ' ✗')}`;
+}
+
+function capitalize(str) {
+  return str
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, s => s.toUpperCase())
+    .trim();
+}
+
+module.exports = { formatReport, formatBrief };

package/src/scanners/cookies.js

@@ -0,0 +1,122 @@
+/**
+ * Cookie Security Scanner
+ * 
+ * Checks Set-Cookie headers for security flags:
+ * - Secure flag (HTTPS only)
+ * - HttpOnly flag (no JS access)
+ * - SameSite attribute
+ * - Path scope
+ * - Expiration
+ */
+
+const https = require('https');
+const http = require('http');
+
+async function scanCookies(parsedUrl, options = {}) {
+  const checks = [];
+  let score = 0;
+  let maxScore = 0;
+
+  const cookies = await fetchCookies(parsedUrl, options);
+
+  if (cookies.length === 0) {
+    checks.push({ name: 'Cookies', status: 'info', message: 'No cookies set on initial page load' });
+    return { score: 1, maxScore: 1, checks };
+  }
+
+  checks.push({ name: 'Cookie Count', status: 'info', message: `${cookies.length} cookie(s) found`, value: cookies.length.toString() });
+
+  for (const cookie of cookies) {
+    const name = cookie.name || 'unnamed';
+    const isSession = /session|sid|token|auth|jwt|csrf/i.test(name);
+    const weight = isSession ? 2 : 1;
+
+    // --- Secure flag ---
+    maxScore += weight;
+    if (cookie.secure) {
+      checks.push({ name: `${name}: Secure`, status: 'pass', message: 'Cookie sent only over HTTPS' });
+      score += weight;
+    } else if (parsedUrl.protocol === 'https:') {
+      checks.push({ name: `${name}: Secure`, status: isSession ? 'fail' : 'warn', message: 'Missing Secure flag — cookie can be sent over HTTP', recommendation: 'Add Secure flag to Set-Cookie header' });
+      if (!isSession) score += weight * 0.5;
+    }
+
+    // --- HttpOnly flag ---
+    maxScore += weight;
+    if (cookie.httpOnly) {
+      checks.push({ name: `${name}: HttpOnly`, status: 'pass', message: 'Cookie inaccessible to JavaScript' });
+      score += weight;
+    } else {
+      checks.push({ name: `${name}: HttpOnly`, status: isSession ? 'fail' : 'warn', message: 'Missing HttpOnly — cookie accessible via document.cookie (XSS risk)', recommendation: 'Add HttpOnly flag to prevent JavaScript access' });
+      if (!isSession) score += weight * 0.25;
+    }
+
+    // --- SameSite ---
+    maxScore += weight * 0.5;
+    if (cookie.sameSite) {
+      const val = cookie.sameSite.toLowerCase();
+      if (val === 'strict' || val === 'lax') {
+        checks.push({ name: `${name}: SameSite`, status: 'pass', message: `SameSite=${cookie.sameSite}`, value: cookie.sameSite });
+        score += weight * 0.5;
+      } else if (val === 'none') {
+        checks.push({ name: `${name}: SameSite`, status: 'warn', message: 'SameSite=None — cookie sent on all cross-site requests' });
+        score += weight * 0.25;
+      }
+    } else {
+      checks.push({ name: `${name}: SameSite`, status: 'warn', message: 'Missing SameSite attribute', recommendation: 'Add SameSite=Lax or SameSite=Strict' });
+    }
+  }
+
+  return { score, maxScore, checks };
+}
+
+function fetchCookies(parsedUrl, options = {}) {
+  return new Promise((resolve, reject) => {
+    const timeout = options.timeout || 10000;
+    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+    
+    const req = protocol.request(parsedUrl.href, {
+      method: 'GET',
+      timeout,
+      headers: { 'User-Agent': 'SiteGuard/0.1 Security Scanner' },
+      rejectUnauthorized: false,
+    }, (res) => {
+      // Consume body
+      res.on('data', () => {});
+      res.on('end', () => {});
+
+      const setCookies = res.headers['set-cookie'] || [];
+      const parsed = setCookies.map(parseCookie);
+      resolve(parsed);
+    });
+
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Timeout')); });
+    req.end();
+  });
+}
+
+function parseCookie(setCookieStr) {
+  const parts = setCookieStr.split(';').map(p => p.trim());
+  const [nameValue, ...attrs] = parts;
+  const eqIndex = nameValue.indexOf('=');
+  const name = eqIndex > -1 ? nameValue.substring(0, eqIndex) : nameValue;
+  
+  const cookie = { name, raw: setCookieStr };
+  
+  for (const attr of attrs) {
+    const [key, val] = attr.split('=').map(s => s.trim());
+    const lower = key.toLowerCase();
+    if (lower === 'secure') cookie.secure = true;
+    else if (lower === 'httponly') cookie.httpOnly = true;
+    else if (lower === 'samesite') cookie.sameSite = val || 'Lax';
+    else if (lower === 'path') cookie.path = val;
+    else if (lower === 'domain') cookie.domain = val;
+    else if (lower === 'expires') cookie.expires = val;
+    else if (lower === 'max-age') cookie.maxAge = parseInt(val);
+  }
+  
+  return cookie;
+}
+
+module.exports = { scanCookies };

package/src/scanners/dns.js

@@ -0,0 +1,113 @@
+/**
+ * DNS Security Scanner
+ * 
+ * Checks DNS configuration for security features:
+ * - SPF records (email spoofing protection)
+ * - DMARC records (email authentication)
+ * - DKIM (if discoverable)
+ * - DNSSEC (via DO flag)
+ * - CAA records (certificate authority authorization)
+ * - MX records (mail configuration)
+ */
+
+const dns = require('dns');
+const { Resolver } = dns.promises;
+
+async function scanDNS(parsedUrl, options = {}) {
+  const checks = [];
+  let score = 0;
+  let maxScore = 0;
+  
+  const hostname = parsedUrl.hostname;
+  // Get root domain for DNS checks
+  const parts = hostname.split('.');
+  const rootDomain = parts.length > 2 ? parts.slice(-2).join('.') : hostname;
+  
+  const resolver = new Resolver();
+  resolver.setServers(['8.8.8.8', '1.1.1.1']); // Use public DNS
+
+  // --- SPF Record ---
+  maxScore += 1;
+  try {
+    const txtRecords = await resolver.resolveTxt(rootDomain);
+    const spf = txtRecords.flat().find(r => r.startsWith('v=spf1'));
+    if (spf) {
+      const hasAll = /[-~?+]all/.test(spf);
+      const isStrict = /-all/.test(spf);
+      if (isStrict) {
+        checks.push({ name: 'SPF Record', status: 'pass', message: 'Strict SPF (-all) — rejects unauthorized senders', value: spf.substring(0, 150) });
+        score += 1;
+      } else if (hasAll) {
+        checks.push({ name: 'SPF Record', status: 'warn', message: 'SPF present but uses soft fail (~all). Consider -all', value: spf.substring(0, 150) });
+        score += 0.5;
+      } else {
+        checks.push({ name: 'SPF Record', status: 'warn', message: 'SPF present but may not reject unauthorized senders', value: spf.substring(0, 150) });
+        score += 0.5;
+      }
+    } else {
+      checks.push({ name: 'SPF Record', status: 'fail', message: 'No SPF record found. Domain vulnerable to email spoofing.', recommendation: 'Add TXT record: v=spf1 include:_spf.google.com -all (adjust for your email provider)' });
+    }
+  } catch (err) {
+    checks.push({ name: 'SPF Record', status: 'info', message: `Could not query TXT records: ${err.code || err.message}` });
+  }
+
+  // --- DMARC Record ---
+  maxScore += 1;
+  try {
+    const dmarcRecords = await resolver.resolveTxt(`_dmarc.${rootDomain}`);
+    const dmarc = dmarcRecords.flat().find(r => r.startsWith('v=DMARC1'));
+    if (dmarc) {
+      const policy = (dmarc.match(/p=(\w+)/) || [])[1] || 'none';
+      if (policy === 'reject') {
+        checks.push({ name: 'DMARC Record', status: 'pass', message: 'DMARC policy=reject — strongest protection', value: dmarc.substring(0, 150) });
+        score += 1;
+      } else if (policy === 'quarantine') {
+        checks.push({ name: 'DMARC Record', status: 'pass', message: 'DMARC policy=quarantine — good protection', value: dmarc.substring(0, 150) });
+        score += 0.75;
+      } else {
+        checks.push({ name: 'DMARC Record', status: 'warn', message: `DMARC policy=${policy} — monitoring only, not enforcing`, value: dmarc.substring(0, 150) });
+        score += 0.25;
+      }
+    } else {
+      checks.push({ name: 'DMARC Record', status: 'fail', message: 'No DMARC record. Email spoofing protection incomplete.', recommendation: 'Add TXT record at _dmarc.yourdomain.com: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com' });
+    }
+  } catch (err) {
+    if (err.code === 'ENOTFOUND' || err.code === 'ENODATA') {
+      checks.push({ name: 'DMARC Record', status: 'fail', message: 'No DMARC record found', recommendation: 'Add DMARC TXT record at _dmarc.yourdomain.com' });
+    } else {
+      checks.push({ name: 'DMARC Record', status: 'info', message: `Could not query DMARC: ${err.code || err.message}` });
+    }
+  }
+
+  // --- CAA Records ---
+  maxScore += 0.5;
+  try {
+    const caaRecords = await resolver.resolveCaa(rootDomain);
+    if (caaRecords && caaRecords.length > 0) {
+      const issuers = caaRecords.filter(r => r.tag === 'issue').map(r => r.value);
+      checks.push({ name: 'CAA Records', status: 'pass', message: `Restricts certificate issuance to: ${issuers.join(', ')}`, value: issuers.join(', ') });
+      score += 0.5;
+    } else {
+      checks.push({ name: 'CAA Records', status: 'warn', message: 'No CAA records. Any CA can issue certificates for this domain.', recommendation: 'Add CAA records to restrict which CAs can issue certificates' });
+    }
+  } catch (err) {
+    if (err.code === 'ENODATA' || err.code === 'ENOTFOUND') {
+      checks.push({ name: 'CAA Records', status: 'warn', message: 'No CAA records found' });
+    } else {
+      checks.push({ name: 'CAA Records', status: 'info', message: `Could not query CAA: ${err.code || err.message}` });
+    }
+  }
+
+  // --- MX Records (informational) ---
+  try {
+    const mxRecords = await resolver.resolveMx(rootDomain);
+    if (mxRecords && mxRecords.length > 0) {
+      const mxList = mxRecords.sort((a, b) => a.priority - b.priority).map(r => `${r.exchange} (${r.priority})`);
+      checks.push({ name: 'MX Records', status: 'info', message: `Mail servers: ${mxList.join(', ')}`, value: mxList.join(', ') });
+    }
+  } catch { /* MX is informational only */ }
+
+  return { score, maxScore, checks };
+}
+
+module.exports = { scanDNS };

package/src/scanners/exposed-files.js

@@ -0,0 +1,231 @@
+/**
+ * Exposed Files Scanner
+ * 
+ * Checks for files/paths that should not be publicly accessible:
+ * - .env, .git, .htaccess
+ * - wp-admin, phpinfo
+ * - Backup files, config files
+ * - Directory listings
+ */
+
+const https = require('https');
+const http = require('http');
+
+const SENSITIVE_PATHS = [
+  { path: '/.env', name: '.env file', severity: 'critical', description: 'Environment variables (may contain secrets, API keys, passwords)' },
+  { path: '/.git/HEAD', name: '.git directory', severity: 'critical', description: 'Git repository exposed — full source code and history accessible' },
+  { path: '/.git/config', name: '.git config', severity: 'critical', description: 'Git configuration with potential remote URLs and credentials' },
+  { path: '/.svn/entries', name: '.svn directory', severity: 'high', description: 'Subversion repository exposed' },
+  { path: '/.htaccess', name: '.htaccess', severity: 'medium', description: 'Apache configuration file — reveals server setup' },
+  { path: '/wp-admin/', name: 'WordPress Admin', severity: 'medium', description: 'WordPress admin panel exposed' },
+  { path: '/wp-login.php', name: 'WordPress Login', severity: 'low', description: 'WordPress login page' },
+  { path: '/phpinfo.php', name: 'PHP Info', severity: 'high', description: 'PHP configuration disclosure' },
+  { path: '/server-status', name: 'Server Status', severity: 'high', description: 'Apache server status page' },
+  { path: '/elmah.axd', name: 'ELMAH Log', severity: 'high', description: '.NET error log viewer' },
+  { path: '/backup.sql', name: 'SQL Backup', severity: 'critical', description: 'Database backup file' },
+  { path: '/dump.sql', name: 'SQL Dump', severity: 'critical', description: 'Database dump file' },
+  { path: '/db.sql', name: 'Database File', severity: 'critical', description: 'Database file' },
+  { path: '/.DS_Store', name: '.DS_Store', severity: 'low', description: 'macOS directory metadata — reveals file/folder names' },
+  { path: '/crossdomain.xml', name: 'crossdomain.xml', severity: 'low', description: 'Flash cross-domain policy (may be overly permissive)' },
+  { path: '/composer.json', name: 'composer.json', severity: 'high', description: 'PHP dependency manifest — reveals packages and versions' },
+  { path: '/package.json', name: 'package.json', severity: 'medium', description: 'Node.js dependency manifest — reveals packages and versions' },
+  { path: '/Gruntfile.js', name: 'Gruntfile.js', severity: 'medium', description: 'Build tool configuration exposed' },
+  { path: '/Dockerfile', name: 'Dockerfile', severity: 'high', description: 'Docker configuration — reveals infrastructure details' },
+  { path: '/docker-compose.yml', name: 'docker-compose.yml', severity: 'critical', description: 'Docker Compose — may contain service passwords and configs' },
+  { path: '/.dockerenv', name: '.dockerenv', severity: 'medium', description: 'Running inside Docker container' },
+  { path: '/web.config', name: 'web.config', severity: 'high', description: 'IIS configuration — reveals server setup and potential credentials' },
+  { path: '/config.php', name: 'config.php', severity: 'critical', description: 'PHP configuration file — likely contains database credentials' },
+  { path: '/wp-config.php.bak', name: 'wp-config.php.bak', severity: 'critical', description: 'WordPress config backup — contains database credentials in plaintext' },
+  { path: '/.npmrc', name: '.npmrc', severity: 'critical', description: 'npm config — may contain auth tokens' },
+  { path: '/.aws/credentials', name: 'AWS credentials', severity: 'critical', description: 'AWS credential file exposed' },
+  { path: '/debug.log', name: 'debug.log', severity: 'high', description: 'Debug log — may contain stack traces and sensitive data' },
+  { path: '/error.log', name: 'error.log', severity: 'high', description: 'Error log — may contain stack traces and paths' },
+  { path: '/access.log', name: 'access.log', severity: 'medium', description: 'Access log — reveals visitor IPs and paths' },
+  { path: '/.vscode/settings.json', name: 'VS Code settings', severity: 'low', description: 'IDE settings exposed — reveals development environment' },
+  { path: '/adminer.php', name: 'Adminer', severity: 'critical', description: 'Database admin tool exposed to the internet' },
+  { path: '/phpmyadmin/', name: 'phpMyAdmin', severity: 'critical', description: 'Database admin panel exposed to the internet' },
+  { path: '/.well-known/security.txt', name: 'security.txt', severity: 'info', description: 'Security contact information' },
+  { path: '/robots.txt', name: 'robots.txt', severity: 'info', description: 'Robots exclusion — may reveal hidden paths' },
+  { path: '/sitemap.xml', name: 'sitemap.xml', severity: 'info', description: 'Site map — reveals site structure' },
+  { path: '/humans.txt', name: 'humans.txt', severity: 'info', description: 'Team information file' },
+];
+
+async function scanExposedFiles(parsedUrl, options = {}) {
+  const checks = [];
+  let score = 0;
+  let maxScore = 0;
+
+  // Score critical, high, and medium severity paths (not low/info)
+  const scoredPaths = SENSITIVE_PATHS.filter(p => ['critical', 'high', 'medium'].includes(p.severity));
+  maxScore = scoredPaths.length;
+  // Note: low severity items are reported but NOT scored
+
+  // Check paths concurrently (in batches to be polite)
+  const batchSize = options.concurrency || 5;
+  const results = [];
+  
+  for (let i = 0; i < SENSITIVE_PATHS.length; i += batchSize) {
+    const batch = SENSITIVE_PATHS.slice(i, i + batchSize);
+    const batchResults = await Promise.all(
+      batch.map(async (entry) => {
+        try {
+          const status = await checkPath(parsedUrl, entry.path, options);
+          return { ...entry, status };
+        } catch {
+          return { ...entry, status: 0 };
+        }
+      })
+    );
+    results.push(...batchResults);
+  }
+
+  let exposedCritical = 0;
+  let exposedHigh = 0;
+
+  // Track connection failures to detect unreachable hosts
+  let connectionFailures = 0;
+  
+  for (const result of results) {
+    // Only 200-299 is truly exposed. 3xx redirects are NOT exposures.
+    // Status 0 = connection failed
+    const isExposed = result.status >= 200 && result.status < 300;
+    if (result.status === 0) connectionFailures++;
+    
+    if (result.severity === 'info') {
+      if (isExposed) {
+        checks.push({ name: result.name, status: 'info', message: `Found (${result.status}) — ${result.description}`, value: result.path });
+      }
+      continue;
+    }
+
+    if (result.severity === 'low') {
+      // Low severity: report if found, but don't affect score
+      if (isExposed) {
+        checks.push({ name: result.name, status: 'info', message: `Found (${result.status}) — ${result.description}`, value: result.path });
+      }
+      continue;
+    }
+
+    if (isExposed) {
+      if (result.severity === 'critical') {
+        checks.push({ name: result.name, status: 'fail', message: `🚨 EXPOSED (${result.status}) — ${result.description}`, value: result.path });
+        exposedCritical++;
+      } else if (result.severity === 'high') {
+        checks.push({ name: result.name, status: 'fail', message: `⚠️ EXPOSED (${result.status}) — ${result.description}`, value: result.path });
+        exposedHigh++;
+      } else if (result.severity === 'medium') {
+        checks.push({ name: result.name, status: 'warn', message: `Accessible (${result.status}) — ${result.description}`, value: result.path });
+        score += 0.5;
+      }
+    } else if (result.status > 0) {
+      score += 1;
+    }
+  }
+  
+  // If most checks failed to connect, report as error
+  const totalScored = results.filter(r => !['info'].includes(r.severity)).length;
+  if (connectionFailures > totalScored * 0.8) {
+    checks.unshift({ name: 'Exposed Files', status: 'error', message: 'Most path checks failed to connect — results may be unreliable' });
+  }
+
+  if (exposedCritical === 0 && exposedHigh === 0) {
+    checks.unshift({ name: 'Sensitive Files', status: 'pass', message: 'No critical or high-severity files exposed' });
+  } else {
+    checks.unshift({ name: 'Sensitive Files', status: 'fail', message: `${exposedCritical} critical, ${exposedHigh} high-severity files exposed!` });
+  }
+
+  return { score, maxScore, checks };
+}
+
+function checkPath(parsedUrl, pathStr, options = {}) {
+  return new Promise((resolve) => {
+    const timeout = options.timeout || 5000;
+    const url = new URL(pathStr, parsedUrl.href);
+    const protocol = url.protocol === 'https:' ? https : http;
+    let resolved = false;
+    const done = (val) => { if (!resolved) { resolved = true; resolve(val); } };
+    
+    // Hard timeout fallback
+    const timer = setTimeout(() => done(0), timeout + 2000);
+    
+    const req = protocol.request(url.href, {
+      method: 'GET',
+      timeout,
+      headers: { 'User-Agent': 'SiteGuard/0.1 Security Scanner' },
+      rejectUnauthorized: false,
+    }, (res) => {
+      let body = '';
+      res.setEncoding('utf-8');
+      res.on('data', (chunk) => {
+        body += chunk;
+        if (body.length > 2000) {
+          res.destroy();
+          clearTimeout(timer);
+          done(validateResponse(res.statusCode, body, pathStr));
+        }
+      });
+      res.on('end', () => {
+        clearTimeout(timer);
+        done(validateResponse(res.statusCode, body, pathStr));
+      });
+      res.on('error', () => { clearTimeout(timer); done(0); });
+      res.on('close', () => { clearTimeout(timer); done(res.statusCode); });
+    });
+
+    req.on('error', () => { clearTimeout(timer); done(0); });
+    req.on('timeout', () => { clearTimeout(timer); req.destroy(); done(0); });
+    req.end();
+  });
+}
+
+/**
+ * Validate if a response is actually the sensitive file or a generic page.
+ * Returns the effective status code (404 for false positives).
+ */
+function validateResponse(statusCode, body, pathStr) {
+  if (statusCode < 200 || statusCode >= 300) return statusCode;
+  if (!body || body.length < 5) return 404; // Empty response
+  
+  // Soft 404 detection — generic error pages
+  if (/<title>.*(?:404|not found|page not found|error|oops|doesn't exist).*<\/title>/i.test(body)) return 404;
+  if (/<h1>.*(?:404|not found|page not found).*<\/h1>/i.test(body)) return 404;
+  
+  // If the body is HTML but the file shouldn't be HTML, it's likely a catch-all route
+  const isHtmlResponse = /<(!DOCTYPE|html|head|body)/i.test(body);
+  const nonHtmlFiles = ['/.env', '/.git/HEAD', '/.git/config', '/.htaccess', '/backup.sql', 
+    '/dump.sql', '/db.sql', '/.DS_Store', '/composer.json', '/package.json', '/Gruntfile.js',
+    '/Dockerfile', '/docker-compose.yml', '/.dockerenv', '/config.php', '/wp-config.php.bak',
+    '/.npmrc', '/.aws/credentials', '/debug.log', '/error.log', '/access.log',
+    '/.vscode/settings.json'];
+  
+  if (isHtmlResponse && nonHtmlFiles.includes(pathStr)) {
+    // HTML response for a non-HTML file = probably a catch-all/SPA router
+    return 404;
+  }
+  
+  // For admin panel paths that return HTML, check if it's actually the admin panel
+  // or just a generic page / catch-all route
+  const adminPaths = ['/wp-admin/', '/wp-login.php', '/phpmyadmin/', '/adminer.php', '/server-status', '/elmah.axd'];
+  if (isHtmlResponse && adminPaths.includes(pathStr)) {
+    // Check for actual admin panel indicators
+    if (pathStr.includes('wp-admin') && !/wp-login|wordpress/i.test(body)) return 404;
+    if (pathStr.includes('wp-login') && !/<form[^>]*wp-login/i.test(body)) return 404;
+    if (pathStr.includes('phpmyadmin') && !/phpMyAdmin|pma_/i.test(body)) return 404;
+    if (pathStr.includes('adminer') && !/adminer/i.test(body)) return 404;
+    if (pathStr.includes('server-status') && !/Server Version|Apache/i.test(body)) return 404;
+    if (pathStr.includes('elmah') && !/ELMAH|Error Log/i.test(body)) return 404;
+  }
+  
+  // Content validation for specific files
+  if (pathStr === '/.env' && !/[A-Z_]+=/.test(body)) return 404;
+  if (pathStr === '/.git/HEAD' && !/ref:/.test(body)) return 404;
+  if (pathStr === '/.git/config' && !/\[core\]|\[remote/.test(body)) return 404;
+  if (pathStr === '/composer.json' && !/"require"/.test(body)) return 404;
+  if (pathStr === '/package.json' && !/"name"|"version"/.test(body)) return 404;
+  if (pathStr === '/Dockerfile' && !/FROM |RUN |CMD /i.test(body)) return 404;
+  if (pathStr === '/docker-compose.yml' && !/services:|version:/i.test(body)) return 404;
+  
+  return statusCode;
+}
+
+module.exports = { scanExposedFiles };