eslint-plugin-secure-coding 2.3.2 → 2.3.3

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

@@ -0,0 +1,551 @@
+/**
+ * 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
+    };
+  },
+});