@sun-asterisk/sunlint 1.3.18 → 1.3.20

package/rules/security/S045_brute_force_protection/README.md

@@ -0,0 +1,345 @@
+# S045 - Brute-force Protection
+
+## Overview
+
+This rule enforces protection against brute-force attacks on authentication endpoints. It detects missing rate limiting, account lockout mechanisms, and other brute-force protection measures in authentication flows to prevent unauthorized access attempts.
+
+## Description
+
+Brute-force protection is a critical security measure that helps prevent:
+
+- **Brute-force attacks** on login and authentication endpoints
+- **Credential stuffing** attacks using stolen credentials
+- **Automated attacks** that attempt to guess passwords
+- **Account takeover** through systematic password attempts
+- **System overload** from excessive authentication requests
+
+## Rule Details
+
+**Rule ID**: S045  
+**Category**: Security  
+**Severity**: Error  
+**Type**: Hybrid Analysis (Symbol-based + Regex-based)
+
+## Examples
+
+### ❌ Violations
+
+```typescript
+// NestJS - Login endpoint without rate limiting
+@Post('login')
+async login(@Body() loginDto: LoginDto) {
+  return this.authService.validateUser(loginDto);
+}
+
+// Express.js - Authentication without rate limiting
+app.post('/auth/login', (req, res) => {
+  const { username, password } = req.body;
+  // No rate limiting or lockout mechanism
+  authenticateUser(username, password);
+});
+
+// Password reset without protection
+@Post('reset-password')
+async resetPassword(@Body() resetDto: ResetPasswordDto) {
+  // No rate limiting or captcha
+  return this.authService.resetPassword(resetDto);
+}
+
+// Sign-in endpoint without throttling
+app.post('/signin', async (req, res) => {
+  const { email, password } = req.body;
+  // Missing brute-force protection
+  const user = await User.findOne({ email });
+  if (user && await bcrypt.compare(password, user.password)) {
+    res.json({ token: generateToken(user) });
+  }
+});
+
+// Authentication handler without lockout
+function authenticateUser(username, password) {
+  // No attempt counting or lockout mechanism
+  return validateCredentials(username, password);
+}
+
+// Forgot password without protection
+@Post('forgot-password')
+async forgotPassword(@Body() body: { email: string }) {
+  // No rate limiting for password reset requests
+  return this.authService.sendResetEmail(body.email);
+}
+```
+
+### ✅ Correct Usage
+
+```typescript
+// NestJS - Login with rate limiting
+@Post('login')
+@Throttle(5, 60) // 5 attempts per minute
+async login(@Body() loginDto: LoginDto) {
+  return this.authService.validateUser(loginDto);
+}
+
+// Express.js - Authentication with rate limiting middleware
+const rateLimit = require('express-rate-limit');
+
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // limit each IP to 5 requests per windowMs
+  message: 'Too many login attempts, please try again later'
+});
+
+app.post('/auth/login', loginLimiter, (req, res) => {
+  const { username, password } = req.body;
+  authenticateUser(username, password);
+});
+
+// NestJS with ThrottlerModule configuration
+@Module({
+  imports: [
+    ThrottlerModule.forRoot([{
+      ttl: 60000, // 1 minute
+      limit: 5,   // 5 requests per minute
+    }]),
+  ],
+})
+export class AuthModule {}
+
+// Express with rate-limiter-flexible
+const { RateLimiterMemory } = require('rate-limiter-flexible');
+
+const rateLimiter = new RateLimiterMemory({
+  points: 5, // Number of attempts
+  duration: 900, // Per 15 minutes
+});
+
+app.post('/login', async (req, res) => {
+  try {
+    await rateLimiter.consume(req.ip);
+    // Process login
+  } catch (rejRes) {
+    res.status(429).send('Too Many Requests');
+  }
+});
+
+// Password reset with rate limiting and captcha
+@Post('reset-password')
+@Throttle(3, 3600) // 3 attempts per hour
+async resetPassword(
+  @Body() resetDto: ResetPasswordDto,
+  @Body('captcha') captcha: string
+) {
+  // Verify captcha first
+  await this.captchaService.verify(captcha);
+  return this.authService.resetPassword(resetDto);
+}
+
+// Account lockout implementation
+const accountLockout = new Map();
+
+app.post('/login', async (req, res) => {
+  const { username, password } = req.body;
+  const attempts = accountLockout.get(username) || 0;
+  
+  if (attempts >= 5) {
+    return res.status(423).json({ 
+      error: 'Account locked due to too many failed attempts' 
+    });
+  }
+  
+  const isValid = await validateCredentials(username, password);
+  if (!isValid) {
+    accountLockout.set(username, attempts + 1);
+    return res.status(401).json({ error: 'Invalid credentials' });
+  }
+  
+  // Reset attempts on successful login
+  accountLockout.delete(username);
+  res.json({ token: generateToken(username) });
+});
+
+// Express Brute for progressive delays
+const ExpressBrute = require('express-brute');
+const store = new ExpressBrute.MemoryStore();
+
+const bruteforce = new ExpressBrute(store, {
+  freeRetries: 3,
+  minWait: 5 * 60 * 1000, // 5 minutes
+  maxWait: 60 * 60 * 1000, // 1 hour
+});
+
+app.post('/auth/login', bruteforce.prevent, (req, res) => {
+  // Login logic with brute-force protection
+});
+```
+
+## Configuration
+
+### Detected Patterns
+
+This rule detects brute-force protection issues in multiple scenarios:
+
+### Authentication Endpoints
+
+- `login`, `signin`, `authenticate`, `auth` endpoints without protection
+- `password`, `reset`, `forgot` endpoints without rate limiting
+- Authentication handlers without throttling mechanisms
+
+### Rate Limiting Libraries
+
+**Supported Libraries:**
+- `express-rate-limit`
+- `express-slow-down`
+- `@nestjs/throttler`
+- `rate-limiter-flexible`
+- `bottleneck`
+- `limiter`
+
+### Account Lockout Libraries
+
+**Supported Libraries:**
+- `express-slow-down`
+- `rate-limiter-flexible`
+- `express-brute`
+- `express-brute-mongo`
+
+### CAPTCHA Libraries
+
+**Supported Libraries:**
+- `recaptcha`
+- `hcaptcha`
+- `turnstile`
+- `captcha`
+
+### Protection Patterns
+
+**Required Protection Indicators:**
+- Rate limiting: `rate.*limit`, `throttle`, `@Throttle()`
+- Account lockout: `lockout`, `max.*attempts`, `brute.*force.*protection`
+- Progressive delays: `cooldown`, `progressive.*delay`
+- CAPTCHA verification: `captcha`, `recaptcha`, `hcaptcha`
+
+### Vulnerable Patterns
+
+**Detected Anti-patterns:**
+- Authentication endpoints without rate limiting
+- Login handlers without throttling
+- Password reset without protection
+- Sign-in without attempt limits
+
+## Security Benefits
+
+1. **Attack Prevention**: Blocks automated brute-force attacks
+2. **Resource Protection**: Prevents system overload from excessive requests
+3. **Account Security**: Protects user accounts from unauthorized access
+4. **Service Availability**: Maintains service availability under attack
+5. **Compliance**: Meets security standards and regulations
+
+## Analysis Approach
+
+### Symbol-based Analysis (Primary)
+
+- Uses TypeScript AST for semantic analysis
+- Detects authentication endpoints and decorators
+- Analyzes middleware usage and rate limiting
+- Provides precise line/column positions
+
+### Regex-based Analysis (Fallback)
+
+- Pattern-based detection for complex cases
+- Handles string-based endpoint definitions
+- Covers edge cases missed by AST analysis
+- Maintains line number accuracy
+
+## Best Practices
+
+1. **Implement rate limiting** on all authentication endpoints
+2. **Use progressive delays** for repeated failed attempts
+3. **Enable account lockout** after multiple failed attempts
+4. **Add CAPTCHA verification** for sensitive operations
+5. **Monitor and log** authentication attempts
+6. **Use IP-based rate limiting** to prevent distributed attacks
+7. **Implement proper error messages** that don't reveal user existence
+8. **Set appropriate time windows** for rate limiting (15-60 minutes)
+9. **Configure reasonable attempt limits** (3-5 attempts before lockout)
+10. **Use established libraries** rather than custom implementations
+
+## Configuration Options
+
+### Default Settings
+
+- **Max Attempts Threshold**: 5 attempts
+- **Time Window**: 15 minutes
+- **Enable Rate Limit Detection**: true
+- **Enable Account Lockout Detection**: true
+- **Enable CAPTCHA Detection**: true
+
+### Customizable Parameters
+
+```json
+{
+  "maxAttemptsThreshold": 5,
+  "timeWindowMinutes": 15,
+  "checkAuthenticationEndpoints": [
+    "login", "signin", "authenticate", "auth",
+    "password", "reset", "forgot"
+  ]
+}
+```
+
+## Testing
+
+Run the rule on test fixtures:
+
+```bash
+# Test violations
+node cli.js --rule=S045 --input=examples/rule-test-fixtures/rules/S045_brute_force_protection/violations --engine=heuristic
+
+# Test clean examples
+node cli.js --rule=S045 --input=examples/rule-test-fixtures/rules/S045_brute_force_protection/clean --engine=heuristic
+
+# Test all examples
+node cli.js --rule=S045 --input=examples/rule-test-fixtures/rules/S045_brute_force_protection --engine=heuristic
+
+# Framework-specific testing
+# Test with ESLint engine (fast)
+node cli.js --rule=S045 --input=path/to/your/files
+
+# Test with heuristic engine (comprehensive)
+node cli.js --rule=S045 --input=path/to/your/files --engine=heuristic
+```
+
+## Framework Compatibility
+
+- **Node.js**: All versions
+- **Frameworks**: Express.js, NestJS, Fastify, Koa
+- **Languages**: JavaScript, TypeScript
+- **Analysis Engines**: ESLint (fast), Heuristic (comprehensive)
+
+## Related Rules
+
+- **S031**: Set Secure flag for Session Cookies
+- **S032**: Set HttpOnly attribute for Session Cookies
+- **S041**: Session Tokens must be invalidated after logout or expiration
+- **S044**: Re-authentication Required for Sensitive Operations
+- **S048**: No Current Password in Password Reset
+
+Together, these rules provide comprehensive authentication security.
+
+## OWASP References
+
+- [OWASP Brute Force Attack](https://owasp.org/www-community/attacks/Brute_force_attack)
+- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+- [OWASP Blocking Brute Force Attacks](https://owasp.org/www-community/controls/Blocking_Brute_Force_Attacks)
+- [PortSwigger Web Security - Brute Force](https://portswigger.net/web-security/authentication/password-based/brute-force)
+
+## Implementation Notes
+
+This rule uses a hybrid analysis approach:
+
+1. **Symbol-based analysis** detects decorator usage (`@Throttle()`) and middleware patterns
+2. **Regex-based analysis** catches string-based configurations and complex patterns
+3. **Library detection** identifies known rate limiting and protection libraries
+4. **Context awareness** distinguishes between authentication and other endpoints
+
+The rule maintains high accuracy while minimizing false positives through careful pattern matching and context analysis.

package/rules/security/S045_brute_force_protection/analyzer.js

@@ -0,0 +1,336 @@
+/**
+ * S045 Main Analyzer - Brute-force Protection
+ * Primary: Symbol-based analysis (when available)
+ * Fallback: Regex-based for all other cases
+ * Command: node cli.js --rule=S045 --input=examples/rule-test-fixtures/rules/S045_brute_force_protection --engine=heuristic
+ */
+
+const S045SymbolBasedAnalyzer = require("./symbol-based-analyzer.js");
+
+class S045Analyzer {
+  constructor(options = {}) {
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(`🔧 [S045] Constructor called with options:`, !!options);
+      console.log(
+        `🔧 [S045] Options type:`,
+        typeof options,
+        Object.keys(options || {})
+      );
+    }
+
+    this.ruleId = "S045";
+    this.ruleName = "Brute-force Protection";
+    this.description =
+      "Implement protection against brute-force attacks on authentication endpoints. This rule detects missing rate limiting, account lockout mechanisms, and other brute-force protection measures in authentication flows.";
+    this.semanticEngine = options.semanticEngine || null;
+    this.verbose = options.verbose || false;
+
+    // Configuration
+    this.config = {
+      useSymbolBased: true, // Primary approach
+      fallbackToRegex: true, // Secondary approach
+      regexBasedOnly: false, // Can be set to true for pure mode
+    };
+
+    // Initialize analyzers
+    try {
+      this.symbolAnalyzer = new S045SymbolBasedAnalyzer(this.semanticEngine);
+      if (process.env.SUNLINT_DEBUG) {
+        console.log(`🔧 [S045] Symbol analyzer created successfully`);
+      }
+    } catch (error) {
+      console.error(`🔧 [S045] Error creating symbol analyzer:`, error);
+    }
+  }
+
+  /**
+   * Initialize analyzer with semantic engine
+   */
+  async initialize(semanticEngine) {
+    this.semanticEngine = semanticEngine;
+
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(`🔧 [S045] Main analyzer initializing...`);
+    }
+
+    // Initialize symbol analyzer
+    if (this.symbolAnalyzer) {
+      await this.symbolAnalyzer.initialize?.(semanticEngine);
+    }
+
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(`🔧 [S045] Main analyzer initialized successfully`);
+    }
+  }
+
+  /**
+   * Single file analysis method for testing
+   */
+  analyzeSingle(filePath, options = {}) {
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(`📊 [S045] analyzeSingle() called for: ${filePath}`);
+    }
+
+    // Return result using same format as analyze method
+    return this.analyze([filePath], "typescript", options);
+  }
+
+  async analyze(files, language, options = {}) {
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(
+        `🔧 [S045] analyze() method called with ${files.length} files, language: ${language}`
+      );
+    }
+
+    const violations = [];
+
+    for (const filePath of files) {
+      try {
+        if (process.env.SUNLINT_DEBUG) {
+          console.log(`🔧 [S045] Processing file: ${filePath}`);
+        }
+
+        const fileViolations = await this.analyzeFile(filePath, options);
+        violations.push(...fileViolations);
+
+        if (process.env.SUNLINT_DEBUG) {
+          console.log(
+            `🔧 [S045] File ${filePath}: Found ${fileViolations.length} violations`
+          );
+        }
+      } catch (error) {
+        console.warn(
+          `⚠ [S045] Analysis failed for ${filePath}:`,
+          error.message
+        );
+      }
+    }
+
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(`🔧 [S045] Total violations found: ${violations.length}`);
+    }
+
+    return violations;
+  }
+
+  async analyzeFile(filePath, options = {}) {
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(`🔍 [S045] analyzeFile() called for: ${filePath}`);
+    }
+
+    // Create a Map to track unique violations and prevent duplicates
+    const violationMap = new Map();
+
+    // 1. Try Symbol-based analysis first (primary)
+    if (
+      this.config.useSymbolBased &&
+      this.semanticEngine?.project &&
+      this.semanticEngine?.initialized
+    ) {
+      try {
+        if (process.env.SUNLINT_DEBUG) {
+          console.log(`🔧 [S045] Trying symbol-based analysis...`);
+        }
+        const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
+        if (sourceFile) {
+          if (process.env.SUNLINT_DEBUG) {
+            console.log(`🔧 [S045] Source file found, analyzing...`);
+          }
+          const symbolViolations = await this.symbolAnalyzer.analyze(
+            sourceFile,
+            filePath
+          );
+
+          // Add to violation map with deduplication
+          symbolViolations.forEach((violation) => {
+            const key = `${violation.line}:${violation.column}:${violation.message}`;
+            if (!violationMap.has(key)) {
+              violationMap.set(key, violation);
+            }
+          });
+
+          if (process.env.SUNLINT_DEBUG) {
+            console.log(
+              `🔧 [S045] Symbol analysis completed: ${symbolViolations.length} violations`
+            );
+          }
+        } else {
+          if (process.env.SUNLINT_DEBUG) {
+            console.log(`🔧 [S045] Source file not found, falling back...`);
+          }
+        }
+      } catch (error) {
+        console.warn(`⚠ [S045] Symbol analysis failed:`, error.message);
+      }
+    }
+
+    // 2. Fallback to regex-based analysis if needed
+    if (this.config.fallbackToRegex || this.config.regexBasedOnly) {
+      try {
+        if (process.env.SUNLINT_DEBUG) {
+          console.log(`🔧 [S045] Trying regex-based analysis...`);
+        }
+        const regexViolations = await this.analyzeWithRegex(filePath);
+
+        // Add to violation map with deduplication
+        regexViolations.forEach((violation) => {
+          const key = `${violation.line}:${violation.column}:${violation.message}`;
+          if (!violationMap.has(key)) {
+            violationMap.set(key, violation);
+          }
+        });
+
+        if (process.env.SUNLINT_DEBUG) {
+          console.log(
+            `🔧 [S045] Regex analysis completed: ${regexViolations.length} violations`
+          );
+        }
+      } catch (error) {
+        console.warn(`⚠ [S045] Regex analysis failed:`, error.message);
+      }
+    }
+
+    // Convert Map values to array and add filePath to each violation
+    const finalViolations = Array.from(violationMap.values()).map(
+      (violation) => ({
+        ...violation,
+        filePath: filePath,
+        file: filePath, // Also add 'file' for compatibility
+      })
+    );
+
+    if (process.env.SUNLINT_DEBUG) {
+      console.log(
+        `🔧 [S045] File analysis completed: ${finalViolations.length} unique violations`
+      );
+    }
+
+    return finalViolations;
+  }
+
+  async analyzeWithRegex(filePath) {
+    const fs = require('fs');
+    const violations = [];
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const lines = content.split('\n');
+
+      // Authentication endpoint patterns - simplified and more specific
+      const authEndpointPatterns = [
+        { pattern: /@Post\(['"`](.*login.*)['"`]\)/gi, type: 'nestjs' },
+        { pattern: /@Post\(['"`](.*signin.*)['"`]\)/gi, type: 'nestjs' },
+        { pattern: /@Post\(['"`](.*auth.*)['"`]\)/gi, type: 'nestjs' },
+        { pattern: /@Post\(['"`](.*password.*)['"`]\)/gi, type: 'nestjs' },
+        { pattern: /@Post\(['"`](.*reset.*)['"`]\)/gi, type: 'nestjs' },
+        { pattern: /@Post\(['"`](.*signup.*)['"`]\)/gi, type: 'nestjs' },
+        { pattern: /app\.post\(['"`](.*login.*)['"`]/gi, type: 'express' },
+        { pattern: /app\.post\(['"`](.*signin.*)['"`]/gi, type: 'express' },
+        { pattern: /app\.post\(['"`](.*auth.*)['"`]/gi, type: 'express' },
+        { pattern: /app\.post\(['"`](.*password.*)['"`]/gi, type: 'express' },
+        { pattern: /app\.post\(['"`](.*reset.*)['"`]/gi, type: 'express' },
+        { pattern: /app\.post\(['"`](.*signup.*)['"`]/gi, type: 'express' },
+        { pattern: /router\.post\(['"`](.*login.*)['"`]/gi, type: 'express' },
+        { pattern: /router\.post\(['"`](.*signin.*)['"`]/gi, type: 'express' },
+        { pattern: /router\.post\(['"`](.*auth.*)['"`]/gi, type: 'express' },
+        { pattern: /router\.post\(['"`](.*password.*)['"`]/gi, type: 'express' },
+        { pattern: /router\.post\(['"`](.*reset.*)['"`]/gi, type: 'express' },
+        { pattern: /router\.post\(['"`](.*signup.*)['"`]/gi, type: 'express' }
+      ];
+
+      // Protection patterns - more comprehensive
+      const protectionPatterns = [
+        /@Throttle/gi,
+        /@RateLimit/gi,
+        /@UseGuards.*ThrottlerGuard/gi,
+        /rateLimit/gi,
+        /throttle/gi,
+        /express-rate-limit/gi,
+        /@nestjs\/throttler/gi,
+        /lockout/gi,
+        /maxAttempts/gi,
+        /cooldown/gi,
+        /brute.*force.*protection/gi,
+        /windowMs/gi,
+        /max.*requests/gi,
+        /express-slow-down/gi,
+        /rate-limiter-flexible/gi,
+        /Limiter/gi,
+        /limiter/gi,
+        /RateLimit/gi,
+        /Throttle/gi
+      ];
+
+      // Check if file has any protection mechanisms at all
+      const hasGlobalProtection = protectionPatterns.some(pattern => {
+        pattern.lastIndex = 0;
+        return pattern.test(content);
+      });
+      
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNumber = i + 1;
+
+        // Check for authentication endpoints
+        for (const { pattern, type } of authEndpointPatterns) {
+          // Reset regex lastIndex to avoid issues with global flag
+          pattern.lastIndex = 0;
+          const match = pattern.exec(line);
+          if (match) {
+            // Check if this specific endpoint has protection
+            const hasProtection = this.checkProtectionInContext(lines, i, protectionPatterns);
+            
+            // Always flag violations if no protection is found
+            if (!hasProtection) {
+              violations.push({
+                rule: this.ruleId,
+                source: filePath,
+                category: "security",
+                line: lineNumber,
+                column: 1,
+                message: `Authentication endpoint '${match[1]}' lacks brute-force protection (rate limiting, account lockout, or CAPTCHA)`,
+                severity: "error",
+              });
+            }
+          }
+        }
+      }
+
+      return violations;
+    } catch (error) {
+      if (this.verbose) {
+        console.log(`🔍 [${this.ruleId}] Regex analysis error:`, error.message);
+      }
+      return [];
+    }
+  }
+
+  checkProtectionInContext(lines, currentLineIndex, protectionPatterns) {
+    // Check current line and surrounding context (10 lines before and after)
+    const start = Math.max(0, currentLineIndex - 10);
+    const end = Math.min(lines.length, currentLineIndex + 11);
+    
+    for (let i = start; i < end; i++) {
+      const line = lines[i];
+      for (const pattern of protectionPatterns) {
+        pattern.lastIndex = 0;
+        if (pattern.test(line)) {
+          return true;
+        }
+      }
+    }
+    
+    return false;
+  }
+
+  /**
+   * Clean up resources
+   */
+  cleanup() {
+    if (this.symbolAnalyzer?.cleanup) {
+      this.symbolAnalyzer.cleanup();
+    }
+  }
+}
+
+module.exports = S045Analyzer;