eslint-plugin-secure-coding 2.3.3 → 2.4.0

package/src/rules/detect-non-literal-fs-filename/index.ts

@@ -1,551 +0,0 @@
-/**
- * ESLint Rule: detect-non-literal-fs-filename
- * Detects variable in filename argument of fs calls, which might allow an attacker to access anything on your system
- * LLM-optimized with comprehensive path traversal prevention guidance
- *
- * @see https://owasp.org/www-community/attacks/Path_Traversal
- * @see https://cwe.mitre.org/data/definitions/22.html
- */
-import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
-import { AST_NODE_TYPES, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
-import { createRule } from '@interlace/eslint-devkit';
-
-type MessageIds =
-  | 'fsPathTraversal'
-  | 'usePathResolve'
-  | 'validatePath'
-  | 'useBasename'
-  | 'createSafeDir'
-  | 'whitelistExtensions';
-
-export interface Options {
-  /** Allow literal strings. Default: false (stricter) */
-  allowLiterals?: boolean;
-  
-  /** Additional fs methods to check */
-  additionalMethods?: string[];
-}
-
-type RuleOptions = [Options?];
-
-/**
- * File system operations and their security implications
- */
-interface FSOperation {
-  method: string;
-  dangerous: boolean;
-  vulnerability: 'path-traversal' | 'directory-traversal' | 'file-access';
-  safePattern: string;
-  example: { bad: string; good: string };
-  effort: string;
-}
-
-const FS_OPERATIONS: FSOperation[] = [
-  {
-    method: 'readFile',
-    dangerous: true,
-    vulnerability: 'file-access',
-    safePattern: 'path.resolve(SAFE_DIR, path.basename(userInput))',
-    example: {
-      bad: 'fs.readFile(userPath, callback)',
-      good: 'const safePath = path.join(SAFE_UPLOADS_DIR, path.basename(userPath)); fs.readFile(safePath, callback)'
-    },
-    effort: '10-15 minutes'
-  },
-  {
-    method: 'writeFile',
-    dangerous: true,
-    vulnerability: 'file-access',
-    safePattern: 'path.resolve(SAFE_DIR, path.basename(userInput))',
-    example: {
-      bad: 'fs.writeFile(userPath, data, callback)',
-      good: 'const safePath = path.join(SAFE_WRITES_DIR, path.basename(userPath)); fs.writeFile(safePath, data, callback)'
-    },
-    effort: '10-15 minutes'
-  },
-  {
-    method: 'stat',
-    dangerous: true,
-    vulnerability: 'path-traversal',
-    safePattern: 'path.resolve(baseDir, userInput) with validation',
-    example: {
-      bad: 'fs.stat(userPath, callback)',
-      good: 'const resolvedPath = path.resolve(SAFE_DIR, userPath);\nif (!resolvedPath.startsWith(SAFE_DIR)) return;\nfs.stat(resolvedPath, callback)'
-    },
-    effort: '15-20 minutes'
-  },
-  {
-    method: 'readdir',
-    dangerous: true,
-    vulnerability: 'directory-traversal',
-    safePattern: 'Validate directory is within allowed paths',
-    example: {
-      bad: 'fs.readdir(userDir, callback)',
-      good: 'const resolvedDir = path.resolve(ALLOWED_DIRS, userDir);\nif (!resolvedDir.startsWith(ALLOWED_DIRS)) return;\nfs.readdir(resolvedDir, callback)'
-    },
-    effort: '15-20 minutes'
-  }
-];
-
-export const detectNonLiteralFsFilename = createRule<RuleOptions, MessageIds>({
-  name: 'detect-non-literal-fs-filename',
-  meta: {
-    type: 'problem',
-    docs: {
-      description: 'Detects variable in filename argument of fs calls, which might allow an attacker to access anything on your system',
-    },
-    messages: {
-      // 🎯 Token optimization: 39% reduction (49→30 tokens) - template variables still work
-      fsPathTraversal: formatLLMMessage({
-        icon: '🔑',
-        issueName: 'Path traversal',
-        cwe: 'CWE-22',
-        description: 'Path traversal vulnerability',
-        severity: '{{riskLevel}}',
-        fix: '{{safePattern}}',
-        documentationLink: 'https://owasp.org/www-community/attacks/Path_Traversal',
-      }),
-      usePathResolve: formatLLMMessage({
-        icon: MessageIcons.INFO,
-        issueName: 'Use path.resolve',
-        description: 'Use path.resolve() to normalize paths',
-        severity: 'LOW',
-        fix: 'path.resolve(SAFE_DIR, userInput)',
-        documentationLink: 'https://nodejs.org/api/path.html#pathresolvepaths',
-      }),
-      validatePath: formatLLMMessage({
-        icon: MessageIcons.INFO,
-        issueName: 'Validate Path',
-        description: 'Validate resolved path starts with allowed base',
-        severity: 'LOW',
-        fix: 'if (!resolved.startsWith(SAFE_DIR)) throw new Error()',
-        documentationLink: 'https://owasp.org/www-community/attacks/Path_Traversal',
-      }),
-      useBasename: formatLLMMessage({
-        icon: MessageIcons.INFO,
-        issueName: 'Use path.basename',
-        description: 'Use path.basename() to strip directory components',
-        severity: 'LOW',
-        fix: 'path.basename(userInput)',
-        documentationLink: 'https://nodejs.org/api/path.html#pathbasenamepath-suffix',
-      }),
-      createSafeDir: formatLLMMessage({
-        icon: MessageIcons.INFO,
-        issueName: 'Define Safe Directory',
-        description: 'Define SAFE_DIR constant',
-        severity: 'LOW',
-        fix: 'const SAFE_DIR = path.resolve(__dirname, "uploads")',
-        documentationLink: 'https://owasp.org/www-community/attacks/Path_Traversal',
-      }),
-      whitelistExtensions: formatLLMMessage({
-        icon: MessageIcons.INFO,
-        issueName: 'Whitelist Extensions',
-        description: 'Whitelist allowed file extensions',
-        severity: 'LOW',
-        fix: 'const ALLOWED_EXT = [".txt", ".pdf"]; if (!ALLOWED_EXT.includes(ext)) throw',
-        documentationLink: 'https://owasp.org/www-community/attacks/Path_Traversal',
-      })
-    },
-    schema: [
-      {
-        type: 'object',
-        properties: {
-          allowLiterals: {
-            type: 'boolean',
-            default: false,
-            description: 'Allow literal string paths'
-          },
-          additionalMethods: {
-            type: 'array',
-            items: { type: 'string' },
-            default: [],
-            description: 'Additional fs methods to check'
-          },
-          allowedExtensions: {
-            type: 'array',
-            items: { type: 'string' },
-            default: [],
-            description: 'Allowed file extensions (e.g., [".txt", ".json"])'
-          }
-        },
-        additionalProperties: false,
-      },
-    ],
-  },
-  defaultOptions: [
-    {
-      allowLiterals: false,
-      additionalMethods: []
-    },
-  ],
-  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
-    const options = context.options[0] || {};
-    const {
-allowLiterals = false,
-      additionalMethods = []
-    
-}: Options = options || {};
-
-    /**
-     * File system methods that can be dangerous with user input
-     */
-    const dangerousMethods = [
-      'readFile', 'readFileSync',
-      'writeFile', 'writeFileSync',
-      'appendFile', 'appendFileSync',
-      'stat', 'statSync',
-      'lstat', 'lstatSync',
-      'readdir', 'readdirSync',
-      'unlink', 'unlinkSync',
-      'mkdir', 'mkdirSync',
-      'rmdir', 'rmdirSync',
-      'access', 'accessSync',
-      'createReadStream', 'createWriteStream',
-      ...additionalMethods
-    ];
-
-    /**
-     * Check if a node is a literal string (safe)
-     */
-    const isLiteralString = (node: TSESTree.Node): boolean => {
-      return node.type === 'Literal' && typeof node.value === 'string';
-    };
-
-    /**
-     * Check if path has dangerous patterns like ../ or ..\
-     */
-    const hasTraversalPatterns = (pathStr: string): boolean => {
-      return /\.\.[/\\]/.test(pathStr) || /^\.\.[/\\]/.test(pathStr);
-    };
-
-    /**
-     * Extract path argument from fs call
-     */
-    const extractPathArgument = (node: TSESTree.CallExpression): {
-      path: string;
-      pathNode: TSESTree.Node | null;
-      method: string;
-      operation: FSOperation | null;
-    } => {
-      const method = node.callee.type === AST_NODE_TYPES.MemberExpression &&
-                    node.callee.property.type === AST_NODE_TYPES.Identifier
-                      ? node.callee.property.name
-                      : 'unknown';
-
-      const operation = FS_OPERATIONS.find(op => op.method === method) || null;
-
-      // First argument is usually the path
-      const pathNode = node.arguments.length > 0 ? node.arguments[0] : null;
-      const sourceCode = context.sourceCode || context.sourceCode;
-      const path = pathNode ? sourceCode.getText(pathNode) : '';
-
-      return { path, pathNode, method, operation };
-    };
-
-    /**
-     * Determine if the path argument is potentially dangerous
-     */
-    const isDangerousPath = (pathNode: TSESTree.Node | null, pathStr: string): boolean => {
-      // Allow literals if configured
-      if (allowLiterals && pathNode && isLiteralString(pathNode)) {
-        return false;
-      }
-
-      // Check for obvious traversal patterns in literals
-      if (pathNode && isLiteralString(pathNode) && hasTraversalPatterns(pathStr)) {
-        return true;
-      }
-
-      // SAFE: path.join(__dirname, 'literal', 'path') with all literal args
-      if (pathNode && isSafePathConstruction(pathNode)) {
-        return false;
-      }
-
-      // SAFE: Path variable inside validated if-block with startsWith check
-      if (pathNode && hasPathValidation(pathNode)) {
-        return false;
-      }
-
-      // Any non-literal is dangerous
-      return !pathNode || !isLiteralString(pathNode);
-    };
-
-    /**
-     * Check if path is constructed safely using path.join/__dirname with literal args
-     * 
-     * Safe patterns:
-     * - path.join(__dirname, 'data', 'file.json')
-     * - path.resolve(__dirname, 'uploads')
-     */
-    const isSafePathConstruction = (pathNode: TSESTree.Node): boolean => {
-      if (pathNode.type !== AST_NODE_TYPES.CallExpression) {
-        return false;
-      }
-      
-      const callee = pathNode.callee;
-      if (callee.type !== AST_NODE_TYPES.MemberExpression ||
-          callee.object.type !== AST_NODE_TYPES.Identifier ||
-          callee.object.name !== 'path' ||
-          callee.property.type !== AST_NODE_TYPES.Identifier) {
-        return false;
-      }
-      
-      const method = callee.property.name;
-      if (!['join', 'resolve'].includes(method)) {
-        return false;
-      }
-      
-      const args = pathNode.arguments;
-      if (args.length === 0) {
-        return false;
-      }
-      
-      // First arg should be __dirname or a literal
-      const firstArg = args[0];
-      const isFirstArgSafe = 
-        (firstArg.type === AST_NODE_TYPES.Identifier && firstArg.name === '__dirname') ||
-        (firstArg.type === AST_NODE_TYPES.Literal && typeof firstArg.value === 'string');
-      
-      if (!isFirstArgSafe) {
-        return false;
-      }
-      
-      // All remaining args should be literals
-      for (let i = 1; i < args.length; i++) {
-        const arg = args[i];
-        if (arg.type !== AST_NODE_TYPES.Literal || typeof arg.value !== 'string') {
-          return false;
-        }
-        // Also check for traversal patterns in literals
-        if (hasTraversalPatterns(String(arg.value))) {
-          return false;
-        }
-      }
-      
-      return true;
-    };
-
-    /**
-     * Check if the path variable has been validated with startsWith()
-     * 
-     * Safe patterns:
-     * 1. Inside if-block: if (safePath.startsWith(SAFE_DIR)) { fs.readFileSync(safePath); }
-     * 2. After guard clause: if (!safePath.startsWith(SAFE_DIR)) { throw }; fs.readFileSync(safePath);
-     */
-    const hasPathValidation = (pathNode: TSESTree.Node): boolean => {
-      if (pathNode.type !== AST_NODE_TYPES.Identifier) {
-        return false;
-      }
-      
-      const varName = pathNode.name;
-      
-      // AST-based validation detection (faster than getText + regex)
-      const isStartsWithOrIncludesCall = (testNode: TSESTree.Node): boolean => {
-        // Handle negation: !path.startsWith(...)
-        if (testNode.type === AST_NODE_TYPES.UnaryExpression && 
-            testNode.operator === '!' &&
-            testNode.argument.type === AST_NODE_TYPES.CallExpression) {
-          testNode = testNode.argument;
-        }
-        
-        // Pattern: varName.startsWith(...) or varName.includes(...)
-        if (testNode.type === AST_NODE_TYPES.CallExpression &&
-            testNode.callee.type === AST_NODE_TYPES.MemberExpression &&
-            testNode.callee.object.type === AST_NODE_TYPES.Identifier &&
-            testNode.callee.object.name === varName &&
-            testNode.callee.property.type === AST_NODE_TYPES.Identifier &&
-            (testNode.callee.property.name === 'startsWith' || 
-             testNode.callee.property.name === 'includes')) {
-          return true;
-        }
-        return false;
-      };
-
-      const hasEarlyExit = (consequent: TSESTree.Statement): boolean => {
-        if (consequent.type === AST_NODE_TYPES.BlockStatement) {
-          return consequent.body.some(stmt => 
-            stmt.type === AST_NODE_TYPES.ThrowStatement ||
-            stmt.type === AST_NODE_TYPES.ReturnStatement
-          );
-        }
-        return consequent.type === AST_NODE_TYPES.ThrowStatement ||
-               consequent.type === AST_NODE_TYPES.ReturnStatement;
-      };
-      
-      // Walk up to find enclosing IfStatement or BlockStatement
-      let current: TSESTree.Node | undefined = pathNode.parent;
-      let foundFunctionBody = false;
-      
-      while (current && !foundFunctionBody) {
-        // Check 1: Inside an if-block with validation
-        if (current.type === AST_NODE_TYPES.IfStatement) {
-          if (isStartsWithOrIncludesCall(current.test)) {
-            return true;
-          }
-        }
-        
-        // Check 2: In a function body, look for preceding sibling if-statements with guard clause
-        if (current.type === AST_NODE_TYPES.BlockStatement && current.parent && (
-            current.parent.type === AST_NODE_TYPES.FunctionDeclaration ||
-            current.parent.type === AST_NODE_TYPES.FunctionExpression ||
-            current.parent.type === AST_NODE_TYPES.ArrowFunctionExpression)) {
-          
-          foundFunctionBody = true;
-          const blockBody = current.body;
-          const nodeIndex = blockBody.findIndex((stmt: TSESTree.Statement) => {
-            let check: TSESTree.Node | undefined = pathNode;
-            while (check) {
-              if (check === stmt) return true;
-              check = check.parent;
-            }
-            return false;
-          });
-          
-          // Look at preceding statements for validation patterns with early exit
-          for (let i = 0; i < nodeIndex; i++) {
-            const stmt = blockBody[i];
-            if (stmt.type === AST_NODE_TYPES.IfStatement &&
-                isStartsWithOrIncludesCall(stmt.test) &&
-                hasEarlyExit(stmt.consequent)) {
-              return true;
-            }
-          }
-        }
-        
-        current = current.parent;
-      }
-      
-      return false;
-    };
-
-    /**
-     * Generate refactoring steps based on the operation
-     */
-    const generateRefactoringSteps = (operation: FSOperation): string => {
-      switch (operation.method) {
-        case 'readFile':
-        case 'writeFile':
-          return [
-            '   1. Define a SAFE_DIR constant for allowed operations',
-            '   2. Use path.basename() to strip directory components',
-            '   3. Combine with SAFE_DIR: path.join(SAFE_DIR, path.basename(userPath))',
-            '   4. Optionally validate file extensions',
-            '   5. Add error handling for invalid paths'
-          ].join('\n');
-
-        case 'stat':
-          return [
-            '   1. Use path.resolve() to normalize the path',
-            '   2. Check if resolved path starts with allowed base directory',
-            '   3. Reject requests that escape the allowed directory',
-            '   4. Use path.relative() for additional validation',
-            '   5. Log security events for monitoring'
-          ].join('\n');
-
-        case 'readdir':
-          return [
-            '   1. Resolve the directory path: path.resolve(ALLOWED_DIRS, userDir)',
-            '   2. Validate resolved path starts with ALLOWED_DIRS',
-            '   3. Check directory exists and is readable',
-            '   4. Consider whitelisting allowed directories',
-            '   5. Add rate limiting to prevent enumeration attacks'
-          ].join('\n');
-
-        default:
-          return [
-            '   1. Identify the specific file operation needed',
-            '   2. Define safe base directories for operations',
-            '   3. Use path.resolve() and validate containment',
-            '   4. Sanitize user input (basename, extension validation)',
-            '   5. Add comprehensive error handling'
-          ].join('\n');
-      }
-    };
-
-    /**
-     * Determine risk level based on the operation and path
-     */
-    const determineRiskLevel = (operation: FSOperation, pathStr: string): string => {
-      if (hasTraversalPatterns(pathStr)) {
-        return 'CRITICAL';
-      }
-
-      if (operation.dangerous) {
-        return 'HIGH';
-      }
-
-      return 'MEDIUM';
-    };
-
-    /**
-     * Check fs method calls for path traversal vulnerabilities
-     */
-    const checkFsCall = (node: TSESTree.CallExpression) => {
-      // Check if it's an fs method call
-      if (node.callee.type !== 'MemberExpression' ||
-          node.callee.object.type !== 'Identifier' ||
-          node.callee.object.name !== 'fs' ||
-          node.callee.property.type !== 'Identifier') {
-        return;
-      }
-
-      const methodName = node.callee.property.name;
-
-      // Skip if not a dangerous method
-      if (!dangerousMethods.includes(methodName)) {
-        return;
-      }
-
-      const { path, pathNode, method, operation } = extractPathArgument(node);
-
-      // Check if the path argument is dangerous
-      if (!isDangerousPath(pathNode, path)) {
-        return;
-      }
-
-      const riskLevel = determineRiskLevel(operation || FS_OPERATIONS[0], path);
-      const steps = operation ? generateRefactoringSteps(operation) : 'Review file system access patterns';
-      const safePattern = operation?.safePattern || 'Use path.resolve() with validation';
-
-      context.report({
-        node,
-        messageId: 'fsPathTraversal',
-        data: {
-          method,
-          path,
-          riskLevel,
-          vulnerability: operation?.vulnerability || 'path traversal',
-          safePattern,
-          steps,
-          effort: operation?.effort || '15-20 minutes'
-        },
-        suggest: [
-          {
-            messageId: 'usePathResolve',
-            fix: () => null
-          },
-          {
-            messageId: 'validatePath',
-            fix: () => null
-          },
-          {
-            messageId: 'useBasename',
-            fix: () => null
-          },
-          {
-            messageId: 'createSafeDir',
-            fix: () => null
-          },
-          {
-            messageId: 'whitelistExtensions',
-            fix: () => null
-          }
-        ]
-      });
-    };
-
-    return {
-      CallExpression: checkFsCall
-    };
-  },
-});