envprobe 1.0.0

package/src/scanners/shell.js

@@ -0,0 +1,125 @@
+/**
+ * Shell/Bash Scanner
+ * Detects environment variable references in shell script files
+ * Supports: $VAR_NAME, ${VAR_NAME}
+ * 
+ * Note: Shell scripts may produce more false positives than other languages
+ * due to the prevalence of variable usage in shell scripting.
+ */
+
+/**
+ * Regex patterns for detecting environment variable references
+ * 
+ * Pattern 1: $VAR_NAME (simple variable expansion)
+ * - Matches: $DATABASE_URL, $API_KEY
+ * - Must be followed by a non-word character or end of string to avoid partial matches
+ * - More prone to false positives (e.g., $1, $?, special vars)
+ * - We filter these out by requiring uppercase start
+ * - This pattern is checked FIRST to maintain consistent ordering in results
+ * 
+ * Pattern 2: ${VAR_NAME} (braced variable expansion)
+ * - Matches: ${DATABASE_URL}, ${API_KEY}
+ * - Also matches parameter expansion: ${VAR:-default}, ${VAR:=default}, ${VAR:?error}
+ * - This is the preferred form and less ambiguous
+ * - Captures the variable name inside the braces
+ * 
+ * Both patterns work within double quotes, which is common in shell scripts.
+ * Single quotes prevent variable expansion in shell, but we still detect them
+ * as they might indicate configuration that needs documentation.
+ */
+const PATTERNS = [
+  // Simple expansion: $VAR_NAME
+  // Uses word boundary or lookahead to ensure we capture the full variable name
+  // This pattern is checked FIRST to maintain consistent ordering in results
+  /\$([A-Z_][A-Z0-9_]*)(?=\W|$)/g,
+  
+  // Braced expansion: ${VAR_NAME} with optional parameter expansion operators
+  // Matches: ${VAR}, ${VAR:-default}, ${VAR:=default}, ${VAR:?error}, ${VAR:+value}
+  // Captures the variable name between the braces, before any colon or closing brace
+  /\$\{([A-Z_][A-Z0-9_]*)(?:[:\}])/g,
+];
+
+/**
+ * Supported file extensions for Shell/Bash scripts
+ */
+const SUPPORTED_EXTENSIONS = ['.sh', '.bash', '.zsh'];
+
+/**
+ * Scan file content for environment variable references
+ * @param {string} content - File content to scan
+ * @param {string} filePath - Path to the file being scanned
+ * @returns {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>}
+ */
+export function scan(content, filePath) {
+  const references = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    references.push(...scanLine(lines[i], filePath, i + 1));
+  }
+
+  return references;
+}
+
+export function scanLine(line, filePath, lineNumber) {
+  const references = [];
+  const seenPerLine = new Set();
+
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      const varName = match[1];
+      const matchedPattern = match[0];
+
+      if (seenPerLine.has(varName)) {
+        continue;
+      }
+
+      if (varName && isValidEnvVarName(varName)) {
+        references.push({
+          varName,
+          filePath,
+          lineNumber,
+          pattern: matchedPattern,
+        });
+
+        seenPerLine.add(varName);
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Validate environment variable name
+ * Must start with letter or underscore, contain only uppercase letters, digits, and underscores
+ * 
+ * This helps filter out shell special variables like:
+ * - Positional parameters: $1, $2, $@, $*
+ * - Special variables: $?, $!, $-
+ * - Lowercase local variables: $var, $my_var
+ * 
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean}
+ */
+function isValidEnvVarName(varName) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(varName);
+}
+
+/**
+ * Get supported file extensions
+ * @returns {string[]}
+ */
+export function getSupportedExtensions() {
+  return SUPPORTED_EXTENSIONS;
+}
+
+/**
+ * Get regex patterns used for scanning
+ * @returns {RegExp[]}
+ */
+export function getPatterns() {
+  return PATTERNS;
+}

package/src/security.js

@@ -0,0 +1,411 @@
+/**
+ * Security Utilities Module
+ * 
+ * Provides security functions for:
+ * - Path sanitization and validation
+ * - Input validation and sanitization
+ * - Pattern validation
+ * - Resource limits
+ * - Safe file operations
+ */
+
+import path from 'path';
+import { isValidEnvVarName } from './utils.js';
+
+/**
+ * Maximum file size to process (10MB)
+ */
+export const MAX_FILE_SIZE = 10 * 1024 * 1024;
+
+/**
+ * Maximum number of files to scan
+ */
+export const MAX_FILES_TO_SCAN = 100000;
+
+/**
+ * Maximum directory depth
+ */
+export const MAX_DIRECTORY_DEPTH = 100;
+
+/**
+ * Maximum pattern length
+ */
+export const MAX_PATTERN_LENGTH = 1000;
+
+/**
+ * Maximum path length
+ */
+export const MAX_PATH_LENGTH = 4096;
+
+/**
+ * Sanitize a file path to prevent directory traversal attacks
+ * 
+ * @param {string} filePath - Path to sanitize
+ * @param {string} basePath - Base directory path (optional)
+ * @returns {string} Sanitized path
+ * @throws {Error} If path is invalid or attempts traversal
+ */
+export function sanitizePath(filePath, basePath = process.cwd()) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('Invalid file path');
+  }
+
+  // Check for null bytes
+  if (filePath.includes('\x00')) {
+    throw new Error('Path contains null bytes');
+  }
+
+  // Check path length
+  if (filePath.length > MAX_PATH_LENGTH) {
+    throw new Error(`Path too long (max ${MAX_PATH_LENGTH} characters)`);
+  }
+
+  // Resolve to absolute path
+  const resolvedPath = path.resolve(basePath, filePath);
+  const resolvedBase = path.resolve(basePath);
+
+  // Ensure path is within base directory
+  if (!resolvedPath.startsWith(resolvedBase)) {
+    throw new Error('Path traversal detected');
+  }
+
+  return resolvedPath;
+}
+
+/**
+ * Validate and sanitize a glob pattern
+ * 
+ * @param {string} pattern - Glob pattern to validate
+ * @returns {string} Sanitized pattern
+ * @throws {Error} If pattern is invalid or malicious
+ */
+export function sanitizePattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') {
+    throw new Error('Invalid pattern');
+  }
+
+  // Check pattern length
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`Pattern too long (max ${MAX_PATTERN_LENGTH} characters)`);
+  }
+
+  // Check for null bytes
+  if (pattern.includes('\x00')) {
+    throw new Error('Pattern contains null bytes');
+  }
+
+  // Check for shell metacharacters that could cause command injection
+  const dangerousChars = /[;&|`$()]/;
+  if (dangerousChars.test(pattern)) {
+    throw new Error('Pattern contains dangerous characters');
+  }
+
+  // Check for ReDoS patterns (basic check)
+  const redosPatterns = [
+    /(\(.*\+\))+/,  // (a+)+
+    /(\(.*\*\))+/,  // (a*)*
+    /(\(.*\|\))+/   // (a|b)+
+  ];
+
+  for (const redosPattern of redosPatterns) {
+    if (redosPattern.test(pattern)) {
+      throw new Error('Pattern may cause ReDoS');
+    }
+  }
+
+  return pattern;
+}
+
+/**
+ * Sanitize command-line argument
+ * 
+ * @param {string} arg - Argument to sanitize
+ * @returns {string} Sanitized argument
+ * @throws {Error} If argument is invalid or malicious
+ */
+export function sanitizeArgument(arg) {
+  if (typeof arg !== 'string') {
+    throw new Error('Invalid argument type');
+  }
+
+  // Check for null bytes
+  if (arg.includes('\x00')) {
+    throw new Error('Argument contains null bytes');
+  }
+
+  // Check for shell metacharacters
+  const shellMetachars = /[;&|`$()<>]/;
+  if (shellMetachars.test(arg)) {
+    throw new Error('Argument contains shell metacharacters');
+  }
+
+  // Check for newlines (command injection)
+  if (arg.includes('\n') || arg.includes('\r')) {
+    throw new Error('Argument contains newline characters');
+  }
+
+  return arg;
+}
+
+/**
+ * Validate environment variable name
+ * 
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean} True if valid
+ */
+export function validateEnvVarName(varName) {
+  if (!varName || typeof varName !== 'string') {
+    return false;
+  }
+
+  // Check length
+  if (varName.length > 255) {
+    return false;
+  }
+
+  // Use existing validation
+  return isValidEnvVarName(varName);
+}
+
+/**
+ * Sanitize error message to prevent information leakage
+ * 
+ * @param {Error} error - Error object
+ * @param {boolean} verbose - Include more details
+ * @returns {string} Sanitized error message
+ */
+export function sanitizeErrorMessage(error, verbose = false) {
+  if (!error) {
+    return 'Unknown error';
+  }
+
+  let message = error.message || 'Unknown error';
+
+  if (!verbose) {
+    // Remove absolute paths
+    message = message.replace(/\/[^\s]+/g, '[path]');
+    message = message.replace(/[A-Z]:\\[^\s]+/g, '[path]');
+
+    // Remove potential secrets (anything that looks like a key/token)
+    message = message.replace(/[a-zA-Z0-9_-]{32,}/g, '[redacted]');
+
+    // Limit message length
+    if (message.length > 200) {
+      message = message.substring(0, 200) + '...';
+    }
+  }
+
+  return message;
+}
+
+/**
+ * Check if file size is within limits
+ * 
+ * @param {number} size - File size in bytes
+ * @returns {boolean} True if within limits
+ */
+export function isFileSizeValid(size) {
+  return typeof size === 'number' && size >= 0 && size <= MAX_FILE_SIZE;
+}
+
+/**
+ * Check if directory depth is within limits
+ * 
+ * @param {string} filePath - File path to check
+ * @param {string} basePath - Base directory path
+ * @returns {boolean} True if within limits
+ */
+export function isDepthValid(filePath, basePath = process.cwd()) {
+  const relativePath = path.relative(basePath, filePath);
+  const depth = relativePath.split(path.sep).length;
+  return depth <= MAX_DIRECTORY_DEPTH;
+}
+
+/**
+ * Rate limiter for file operations
+ */
+export class RateLimiter {
+  constructor(maxOperations = 1000, windowMs = 1000) {
+    this.maxOperations = maxOperations;
+    this.windowMs = windowMs;
+    this.operations = [];
+  }
+
+  /**
+   * Check if operation is allowed
+   * @returns {boolean} True if allowed
+   */
+  allowOperation() {
+    const now = Date.now();
+    
+    // Remove old operations outside window
+    this.operations = this.operations.filter(
+      time => now - time < this.windowMs
+    );
+
+    // Check if under limit
+    if (this.operations.length >= this.maxOperations) {
+      return false;
+    }
+
+    // Record operation
+    this.operations.push(now);
+    return true;
+  }
+
+  /**
+   * Reset rate limiter
+   */
+  reset() {
+    this.operations = [];
+  }
+}
+
+/**
+ * Timeout wrapper for async operations
+ * 
+ * @param {Promise} promise - Promise to wrap
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise} Promise that rejects on timeout
+ */
+export function withTimeout(promise, timeoutMs = 30000) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Operation timed out')), timeoutMs)
+    )
+  ]);
+}
+
+/**
+ * Validate configuration object
+ * 
+ * @param {Object} config - Configuration to validate
+ * @returns {Object} Validated configuration
+ * @throws {Error} If configuration is invalid
+ */
+export function validateConfiguration(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('Invalid configuration');
+  }
+
+  // Check for prototype pollution - but allow 'path' property
+  const dangerousProps = ['__proto__', 'constructor', 'prototype'];
+  for (const prop of dangerousProps) {
+    if (prop in config) {
+      throw new Error('Configuration contains dangerous properties');
+    }
+  }
+
+  // Validate each property
+  const validated = {};
+
+  if (config.path !== undefined) {
+    if (typeof config.path !== 'string') {
+      throw new Error('Invalid path in configuration');
+    }
+    validated.path = config.path;
+  }
+
+  if (config.envFile !== undefined) {
+    if (typeof config.envFile !== 'string') {
+      throw new Error('Invalid envFile in configuration');
+    }
+    validated.envFile = config.envFile;
+  }
+
+  if (config.format !== undefined) {
+    if (!['text', 'json', 'github'].includes(config.format)) {
+      throw new Error('Invalid format in configuration');
+    }
+    validated.format = config.format;
+  }
+
+  if (config.failOn !== undefined) {
+    if (!['missing', 'unused', 'undocumented', 'all', 'none'].includes(config.failOn)) {
+      throw new Error('Invalid failOn in configuration');
+    }
+    validated.failOn = config.failOn;
+  }
+
+  if (config.ignore !== undefined) {
+    if (!Array.isArray(config.ignore)) {
+      throw new Error('Invalid ignore in configuration');
+    }
+    validated.ignore = config.ignore.filter(p => typeof p === 'string');
+  }
+
+  if (config.noColor !== undefined) {
+    validated.noColor = Boolean(config.noColor);
+  }
+
+  if (config.quiet !== undefined) {
+    validated.quiet = Boolean(config.quiet);
+  }
+
+  if (config.watch !== undefined) {
+    validated.watch = Boolean(config.watch);
+  }
+
+  if (config.suggestions !== undefined) {
+    validated.suggestions = Boolean(config.suggestions);
+  }
+
+  if (config.progress !== undefined) {
+    validated.progress = Boolean(config.progress);
+  }
+
+  if (config.fix !== undefined) {
+    validated.fix = Boolean(config.fix);
+  }
+
+  return validated;
+}
+
+/**
+ * Escape special characters for safe display
+ * 
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+export function escapeForDisplay(str) {
+  if (typeof str !== 'string') {
+    return '';
+  }
+
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;')
+    .replace(/\//g, '&#x2F;');
+}
+
+/**
+ * Check if path is safe to access
+ * 
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if safe
+ */
+export function isSafePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    return false;
+  }
+
+  // Check for dangerous patterns
+  const dangerousPatterns = [
+    /\.\./,           // Parent directory
+    /^\/etc\//,       // System files
+    /^\/root\//,      // Root home
+    /^\/sys\//,       // System files
+    /^\/proc\//,      // Process files
+    /^C:\\Windows/i,  // Windows system
+    /^C:\\Program/i,  // Program files
+    /\.ssh/,          // SSH keys
+    /\.aws/,          // AWS credentials
+    /\.env$/          // Actual env files (not .env.example)
+  ];
+
+  return !dangerousPatterns.some(pattern => pattern.test(filePath));
+}

package/src/suggestions.js

@@ -0,0 +1,154 @@
+/**
+ * Intelligent suggestions and fixes for common issues
+ */
+
+/**
+ * Analyze issues and provide actionable suggestions
+ */
+export function generateSuggestions(result) {
+  const suggestions = [];
+
+  // Missing variables suggestions
+  if (result.missing.length > 0) {
+    suggestions.push({
+      type: 'missing',
+      severity: 'error',
+      message: `Found ${result.missing.length} missing environment variable(s)`,
+      action: 'Add these variables to your .env.example file:',
+      items: result.missing.map(m => ({
+        variable: m.varName,
+        locations: m.locations.map(l => `${l.filePath}:${l.lineNumber}`),
+        suggestion: `${m.varName}=`,
+      })),
+    });
+  }
+
+  // Unused variables suggestions
+  if (result.unused.length > 0) {
+    suggestions.push({
+      type: 'unused',
+      severity: 'warning',
+      message: `Found ${result.unused.length} unused environment variable(s)`,
+      action: 'Consider removing these from .env.example or use them in your code:',
+      items: result.unused.map(u => ({
+        variable: u.varName,
+        suggestion: `Remove ${u.varName} from .env.example or add usage in code`,
+      })),
+    });
+  }
+
+  // Undocumented variables suggestions
+  if (result.undocumented.length > 0) {
+    suggestions.push({
+      type: 'undocumented',
+      severity: 'info',
+      message: `Found ${result.undocumented.length} undocumented environment variable(s)`,
+      action: 'Add comments to document these variables:',
+      items: result.undocumented.map(u => ({
+        variable: u.varName,
+        suggestion: `# Description of ${u.varName}\n${u.varName}=`,
+      })),
+    });
+  }
+
+  return suggestions;
+}
+
+/**
+ * Generate auto-fix content for .env.example
+ */
+export function generateEnvExampleFix(result, existingContent = '') {
+  const lines = existingContent.split('\n');
+  const additions = [];
+
+  // Add missing variables
+  for (const missing of result.missing) {
+    const example = inferExampleValue(missing.varName);
+    additions.push(`# ${missing.varName} - Add description here`);
+    additions.push(`${missing.varName}=${example}`);
+    additions.push('');
+  }
+
+  return [...lines, '', '# Auto-generated additions', ...additions].join('\n');
+}
+
+/**
+ * Infer example value based on variable name
+ */
+function inferExampleValue(varName) {
+  const patterns = {
+    PORT: '3000',
+    HOST: 'localhost',
+    URL: 'https://example.com',
+    API_KEY: 'your_api_key_here',
+    SECRET: 'your_secret_here',
+    TOKEN: 'your_token_here',
+    PASSWORD: 'your_password_here',
+    DATABASE: 'postgres://localhost:5432/dbname',
+    REDIS: 'redis://localhost:6379',
+    EMAIL: 'user@example.com',
+    DEBUG: 'false',
+    NODE_ENV: 'development',
+  };
+
+  for (const [pattern, value] of Object.entries(patterns)) {
+    if (varName.toUpperCase().includes(pattern)) {
+      return value;
+    }
+  }
+
+  return 'your_value_here';
+}
+
+/**
+ * Suggest similar variable names (typo detection)
+ */
+export function findSimilarVariables(varName, definedVars) {
+  const similar = [];
+
+  for (const defined of definedVars) {
+    const distance = levenshteinDistance(varName.toLowerCase(), defined.toLowerCase());
+    const maxLength = Math.max(varName.length, defined.length);
+    const similarity = 1 - distance / maxLength;
+
+    if (similarity > 0.7 && similarity < 1) {
+      similar.push({
+        name: defined,
+        similarity: Math.round(similarity * 100),
+      });
+    }
+  }
+
+  return similar.sort((a, b) => b.similarity - a.similarity);
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(str1, str2) {
+  const matrix = [];
+
+  for (let i = 0; i <= str2.length; i++) {
+    matrix[i] = [i];
+  }
+
+  for (let j = 0; j <= str1.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= str2.length; i++) {
+    for (let j = 1; j <= str1.length; j++) {
+      if (str2.charAt(i - 1) === str1.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1,
+          matrix[i][j - 1] + 1,
+          matrix[i - 1][j] + 1
+        );
+      }
+    }
+  }
+
+  return matrix[str2.length][str1.length];
+}