@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/php/S037-anti-cache-headers.md

@@ -0,0 +1,56 @@
+---
+title: Set Anti-cache Headers
+impact: MEDIUM
+impactDescription: prevents sensitive data from being cached in browsers or intermediate proxies
+tags: headers, cache, sensitive-data, security, php
+---
+
+## Set Anti-cache Headers
+
+Pages containing sensitive user information (like bank statements, personal details, or private messages) should not be cached by browsers or intermediate proxy servers (CDNs). If cached, this information might be accessible to subsequent users of the same device or shared network.
+
+**Incorrect (no cache control for sensitive data):**
+
+```php
+// Sensitive data returned without cache instructions
+$balance = getBalance($userId);
+echo json_encode(['balance' => $balance]);
+```
+
+**Correct (anti-cache headers):**
+
+```php
+// 1. Plain PHP
+header('Cache-Control: no-store, no-cache, must-revalidate, private');
+header('Pragma: no-cache');
+header('Expires: 0');
+
+echo json_encode($sensitiveData);
+
+// 2. In Laravel Middleware
+public function handle($request, Closure $next) {
+    $response = $next($request);
+    
+    // Check if the response is for an authenticated user
+    if (auth()->check()) {
+        $response->headers->set('Cache-Control', 'no-store, no-cache, must-revalidate, private');
+        $response->headers->set('Pragma', 'no-cache');
+        $response->headers->set('Expires', '0');
+    }
+    
+    return $response;
+}
+```
+
+**When to use anti-cache:**
+- User profile pages.
+- Financial transactions and history.
+- Admin dashboard pages.
+- Any API endpoint returning non-public, authenticated data.
+
+**Key Header Meanings:**
+- `no-store`: Do not store any part of this response on disk (most important for security).
+- `no-cache`: Must re-validate with the server before using a cached copy.
+- `private`: Only intended for the single user, do not store in shared caches (proxies).
+
+**Tools:** Header Audit Tools, Browser Developer Tools (Network Tab), SonarQube

package/skill-assets/sunlint-code-quality/rules/php/S039-tls-certificate-validation.md

@@ -0,0 +1,54 @@
+---
+title: TLS Clients Must Validate Server Certificates
+impact: CRITICAL
+impactDescription: prevents Man-in-the-Middle (MITM) attacks by ensuring the server identity is authentic
+tags: tls, certificates, validation, mitm, security, php
+---
+
+## TLS Clients Must Validate Server Certificates
+
+Disabling certificate validation (often done to "skip" errors in development) completely negates the security of TLS. It allows an attacker to intercept, read, and modify your traffic by simply presenting any certificate, including a self-signed one.
+
+**Incorrect (disabled validation):**
+
+```php
+// 1. cURL - DANGEROUS
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_URL, "https://api.example.com");
+curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // VULNERABLE
+curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);     // VULNERABLE
+
+// 2. Stream Context - DANGEROUS
+$context = stream_context_create([
+    'ssl' => [
+        'verify_peer' => false, // VULNERABLE
+        'verify_peer_name' => false, // VULNERABLE
+    ]
+]);
+file_get_contents("https://api.example.com", false, $context);
+
+// 3. Guzzle - DANGEROUS
+$client->get('https://api.example.com', ['verify' => false]);
+```
+
+**Correct (enforced validation):**
+
+```php
+// 1. cURL - Enabled by default (Ensure CA bundle is present)
+curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
+curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
+
+// 2. Using an Internal CA for private services
+curl_setopt($ch, CURLOPT_CAINFO, "/path/to/internal-ca.pem");
+
+// 3. Guzzle (Recommended)
+$client->get('https://api.example.com', [
+    'verify' => '/path/to/ca-bundle.crt' // Or true to use system default
+]);
+```
+
+**Common Pitfalls:**
+- "Fixing" local development errors by setting `verify => false`. Instead, download the latest [cacert.pem](https://curl.se/docs/caextract.html) and update your `php.ini` (`curl.cainfo` and `openssl.cafile`).
+- Using outdated OS images that have expired Root CAs.
+
+**Tools:** `curl_error()`, `openssl_get_cert_locations()`, `SSLyze`, `OWASP ZAP`

package/skill-assets/sunlint-code-quality/rules/php/S041-logout-invalidation.md

@@ -0,0 +1,63 @@
+---
+title: Invalidate Session On Logout
+impact: MEDIUM
+impactDescription: ensures logout actually terminates access
+tags: session, logout, invalidation, security, php
+---
+
+## Invalidate Session On Logout
+
+If sessions or tokens are not explicitly invalidated on the server during logout, an attacker who has stolen a session cookie or token can still access the application even after the user has "logged out".
+
+**Incorrect (client-only or partial logout):**
+
+```php
+// Server-side: Just redirecting without destroying session
+header("Location: /login.php");
+exit;
+
+// Frontend-only logout (session cookie still valid on server!)
+// localStorage.removeItem('token'); 
+```
+
+**Correct (server-side invalidation):**
+
+```php
+// Standard PHP Session Invalidation
+session_start();
+
+// 1. Unset all session variables
+$_SESSION = [];
+
+// 2. Delete the session cookie
+if (ini_get("session.use_cookies")) {
+    $params = session_get_cookie_params();
+    setcookie(session_name(), '', time() - 42000,
+        $params["path"], $params["domain"],
+        $params["secure"], $params["httponly"]
+    );
+}
+
+// 3. Destroy the session on server
+session_destroy();
+
+header("Location: /login.php");
+exit;
+
+// In Laravel (Recommended)
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\Session;
+
+Auth::logout();
+Session::invalidate();
+Session::regenerateToken(); // To prevent CSRF fixation
+```
+
+**Important Steps:**
+1. Clear all session data (`$_SESSION = []`).
+2. Expire the session cookie in the user's browser.
+3. Call `session_destroy()` to remove server-side storage.
+4. If using JWT, add the token to a blacklist until its natural expiration.
+5. Redirect the user and set `Cache-Control: no-store` to prevent the browser from showing sensitive pages via the "Back" button.
+
+**Tools:** OWASP ZAP, Manual Session Testing, Burp Suite, SonarQube

package/skill-assets/sunlint-code-quality/rules/php/S042-long-lived-sessions.md

@@ -0,0 +1,57 @@
+---
+title: Re-authenticate For Long-lived Sessions
+impact: MEDIUM
+impactDescription: ensures continuous identity verification for extended sessions
+tags: session, authentication, timeout, reauthentication, security, php
+---
+
+## Re-authenticate For Long-lived Sessions
+
+User sessions that remain active for days or weeks (e.g., using "Remember Me" features) are more susceptible to hijack if a device is left unattended or stolen. You should implement a system that requires users to perform a full re-authentication periodically or before performing sensitive actions.
+
+**Incorrect (sessions never expire or never require re-auth):**
+
+```php
+// PHP session with no clear expiry logic
+session_start();
+// User stays logged in as long as the cookie exists
+```
+
+**Correct (enforcing session lifetime and re-auth):**
+
+```php
+// 1. Set reasonable idle session lifetime (php.ini)
+// session.gc_maxlifetime = 1440 // 24 minutes default - increase to e.g. 14400 (4 hours)
+
+// 2. track authentication time in session
+session_start();
+
+if (isset($_SESSION['user_id'])) {
+    $lastAuth = $_SESSION['last_auth_time'] ?? 0;
+    $maxAge = 4 * 60 * 60; // Require re-auth every 4 hours
+
+    if (time() - $lastAuth > $maxAge) {
+        $_SESSION['reauth_required'] = true;
+    }
+}
+
+// 3. Sensitive Action Middleware (Laravel example)
+public function handle($request, Closure $next)
+{
+    // Check if the user has authenticated within the last hour for sensitive actions
+    $lastAuthAt = $request->session()->get('auth.last_confirmed_at');
+    
+    if (!$lastAuthAt || (time() - $lastAuthAt > 3600)) {
+        return redirect()->route('password.confirm');
+    }
+
+    return $next($request);
+}
+```
+
+**Implementation Strategy:**
+- **Idle Timeout**: Automatically destroy the session after a period of user inactivity (e.g., 2 hours).
+- **Absolute Lifetime**: Force a full logout or re-auth after a total duration (e.g., 24 hours), regardless of activity.
+- **Sensitive Operations**: Require password entry before changing emails, passwords, or processing payments (see rule **S044**).
+
+**Tools:** Laravel `password.confirm`, `session.gc_maxlifetime`, Custom PHP Middleware

package/skill-assets/sunlint-code-quality/rules/php/S044-critical-changes-reauth.md

@@ -0,0 +1,71 @@
+---
+title: Re-authenticate Before Critical Changes
+impact: MEDIUM
+impactDescription: prevents unauthorized critical operations in case of session hijacking
+tags: authentication, critical, reauthentication, security, php
+---
+
+## Re-authenticate Before Critical Changes
+
+For critical operations such as changing passwords, updating contact emails, or deleting an account, a valid session alone is not enough. You must require the user to provide their current password or a 2FA code to confirm the action.
+
+**Incorrect (no confirmation for critical actions):**
+
+```php
+// VULNERABLE: Direct deletion without confirming identity
+public function deleteAccount(Request $request) {
+    $user = Auth::user();
+    $user->delete();
+    return response()->json(['status' => 'success']);
+}
+```
+
+**Correct (requiring password confirmation):**
+
+```php
+public function deleteAccount(Request $request) {
+    $request->validate([
+        'current_password' => 'required',
+    ]);
+
+    $user = Auth::user();
+
+    // 1. Manually verify the current password
+    if (!Hash::check($request->current_password, $user->password)) {
+        throw ValidationException::withMessages([
+            'current_password' => ['The provided password does not match our records.'],
+        ]);
+    }
+
+    // 2. Perform the critical action
+    $user->delete();
+
+    // 3. Log security event
+    Log::warning("User account deleted: {$user->email}");
+
+    return response()->json(['status' => 'success']);
+}
+
+// 2FA Verification example
+public function updateEmail(Request $request) {
+    $request->validate(['email' => 'required|email', 'otp' => 'required']);
+    
+    if (!TwoFactor::verify($request->otp)) {
+        return back()->withError('Invalid 2FA code.');
+    }
+    
+    // ...
+}
+```
+
+**Critical actions that MUST require re-authentication:**
+- Changing the account password.
+- Updating the primary email address.
+- Deleting the account.
+- Disabling 2FA or changing security settings.
+- Managing high-value payment methods or withdrawal addresses.
+
+**Why is this necessary?**
+If a user leaves their computer unlocked or their session cookie is stolen, the attacker can hijack the session. Requiring the password for critical changes creates a vital final barrier that prevents the attacker from locking out the real user or causing permanent data loss.
+
+**Tools:** Laravel `password.confirm`, `Hash::check`, manual code review

package/skill-assets/sunlint-code-quality/rules/php/S045-brute-force-protection.md

@@ -0,0 +1,67 @@
+---
+title: Implement Brute-force Protection
+impact: MEDIUM
+impactDescription: prevents password guessing and credential stuffing attacks
+tags: brute-force, rate-limiting, authentication, security, php
+---
+
+## Implement Brute-force Protection
+
+Without brute-force protection, attackers can use automated scripts to try millions of password combinations against your login endpoints. You must implement rate limiting or progressive delays for sensitive actions like authentication, password resets, and MFA verification.
+
+**Incorrect (no protection):**
+
+```php
+// Standard login without limits
+public function login(Request $request) {
+    if (Auth::attempt($request->only('email', 'password'))) {
+        return redirect()->intended('dashboard');
+    }
+    return back()->withErrors(['email' => 'Invalid credentials']);
+}
+```
+
+**Correct (rate limiting and locking):**
+
+```php
+// 1. Using Laravel's built-in Rate Limiter (Recommended)
+use Illuminate\Support\Facades\RateLimiter;
+
+public function login(Request $request) {
+    $throttleKey = Str::lower($request->input('email')) . '|' . $request->ip();
+
+    if (RateLimiter::tooManyAttempts($throttleKey, 5)) {
+        $seconds = RateLimiter::availableIn($throttleKey);
+        return back()->withErrors([
+            'email' => "Too many attempts. Retry in {$seconds} seconds."
+        ]);
+    }
+
+    if (Auth::attempt($request->only('email', 'password'))) {
+        RateLimiter::clear($throttleKey);
+        return redirect()->intended('dashboard');
+    }
+
+    RateLimiter::hit($throttleKey, 60); // 1 minute window
+    return back()->withErrors(['email' => 'Invalid credentials']);
+}
+
+// 2. Progressive Delay (Plain PHP)
+if ($loginFailed) {
+    $attempts = $_SESSION['login_attempts'] ?? 0;
+    $_SESSION['login_attempts'] = $attempts + 1;
+    
+    // Slow down attackers
+    if ($attempts > 3) {
+        sleep(pow(2, $attempts - 3)); // Exponential backoff
+    }
+}
+```
+
+**Best Practices:**
+1. **IP + Account Limiting**: Track attempts by both IP address and the targeted account (email/username).
+2. **CAPTCHA**: Trigger a CAPTCHA (e.g., reCAPTCHA v3) after a certain number of failed attempts.
+3. **Lockout Policy**: Temporarily disable an account after X failed attempts (e.g., lock for 30 minutes after 10 failures).
+4. **Monitoring**: Log multiple failures from a single IP to trigger WAF (Web Application Firewall) blocks.
+
+**Tools:** Laravel RateLimiter, Symfony Rate Limiter component, AWS WAF, Cloudflare Rate Limiting

package/skill-assets/sunlint-code-quality/rules/php/S047-oauth-csrf-protection.md

@@ -0,0 +1,72 @@
+---
+title: Protect OAuth Code Flow Vs CSRF
+impact: HIGH
+impactDescription: prevents attackers from tricking users into linking malicious accounts via OAuth CSRF
+tags: oauth, csrf, state, authorization, security, php
+---
+
+## Protect OAuth Code Flow Vs CSRF
+
+During the OAuth 2.0 authorization code flow, an attacker could initiate an auth request and trick a logged-in user into clicking the callback URL. Without a `state` parameter, your application might link the attacker's account (e.g., GitHub/Google) to the victim's local session.
+
+**Incorrect (no state parameter):**
+
+```php
+// Initiating OAuth without state
+public function redirectToProvider() {
+    $url = "https://provider.com/oauth/authorize?" . http_build_query([
+        'client_id' => 'CLIENT_ID',
+        'redirect_uri' => 'CALLBACK_URL',
+        'response_type' => 'code',
+        'scope' => 'user:email',
+    ]);
+    return redirect($url);
+}
+
+// Callback without state validation
+public function handleCallback(Request $request) {
+    $code = $request->input('code');
+    // Dangerous: missing state validation!
+}
+```
+
+**Correct (state parameter validation):**
+
+```php
+// 1. Manually initiating with state
+public function redirectToProvider() {
+    $state = bin2hex(random_bytes(16));
+    session(['oauth_state' => $state]); // Store in session
+
+    $url = "https://provider.com/oauth/authorize?" . http_build_query([
+        'client_id' => 'CLIENT_ID',
+        'redirect_uri' => 'CALLBACK_URL',
+        'response_type' => 'code',
+        'state' => $state,
+    ]);
+    return redirect($url);
+}
+
+// 2. Validating in callback
+public function handleCallback(Request $request) {
+    $state = $request->input('state');
+    $storedState = session()->pull('oauth_state');
+
+    if (empty($state) || $state !== $storedState) {
+        abort(403, 'Invalid OAuth state.');
+    }
+
+    // Proceed to exchange code for token
+}
+
+/**
+ * 3. Using Laravel Socialite (Recommended)
+ * Socialite handles the state parameter automatically.
+ */
+return Socialite::driver('github')->redirect();
+```
+
+**Why it matters?**
+The `state` parameter acts as a secret token that links the initial request from your site to the final callback from the provider. If the `state` doesn't match, it means the auth flow was not initiated by the user on your application, signaling a potential CSRF attack.
+
+**Tools:** Laravel Socialite, League OAuth2 Client, PHP `random_bytes()`, Manual Security Review

package/skill-assets/sunlint-code-quality/rules/php/S048-oauth-redirect-validation.md

@@ -0,0 +1,54 @@
+---
+title: Validate OAuth Redirect URIs Exactly
+impact: CRITICAL
+impactDescription: prevents authorization code theft via malicious redirection
+tags: oauth, redirect, uri, validation, security, php
+---
+
+## Validate OAuth Redirect URIs Exactly
+
+If you are building an OAuth 2.0 Identity Provider (IdP) or an internal auth service, you must validate the `redirect_uri` parameter against an exact match of pre-registered URIs. Loose validation (like substring or prefix matching) can be bypassed to leak authorization codes to an attacker-controlled site.
+
+**Incorrect (loose or partial validation):**
+
+```php
+// VULNERABLE: Substring matching
+if (strpos($redirectUri, "example.com") !== false) {
+    // Allows attacker.com/?leak=example.com
+}
+
+// VULNERABLE: Prefix matching without trailing slash
+if (strpos($redirectUri, "https://app.example.com") === 0) {
+    // Allows https://app.example.com.attacker.com
+}
+```
+
+**Correct (exact matching against whitelist):**
+
+```php
+$registeredUris = [
+    'https://app.example.com/callback',
+    'https://staging.example.com/callback'
+];
+
+$requestedUri = $_GET['redirect_uri'];
+
+// 1. Exact string comparison (Recommended)
+if (!in_array($requestedUri, $registeredUris, true)) {
+    die("Error: Invalid redirect_uri provided.");
+}
+
+// 2. Using Laravel Passport/Socialite
+// These libraries handle exact validation if configured correctly in the client table.
+```
+
+**Security Best Practices:**
+- **No Wildcards**: Do not allow `*.example.com`. Modern OAuth standards discourage any form of pattern matching.
+- **Pre-Registration**: Every client must register their exact callback URLs during the app registration phase.
+- **HTTPS Only**: Only allow `https://` schemes for production redirect URIs.
+- **Exact Path**: The entire path must match, not just the domain.
+
+**Why it matters?**
+If an attacker can redirect the OAuth flow to their own domain, they will receive the `?code=` parameter. They can then use this code to impersonate the user or link the user's account to their own, leading to a full account takeover.
+
+**Tools:** Laravel Passport, OpenID Connect specifications, Manual Security Audit

package/skill-assets/sunlint-code-quality/rules/php/S049-auth-code-expiry.md

@@ -0,0 +1,71 @@
+---
+title: Authentication Codes Must Expire Quickly
+impact: MEDIUM
+impactDescription: reduces the opportunity for an attacker to use intercepted codes
+tags: authentication, codes, expiry, otp, security, php
+---
+
+## Authentication Codes Must Expire Quickly
+
+Any temporary authentication identifiers—such as MFA codes, password reset tokens, or email verification links—must have a strict and limited lifespan. The longer a code is valid, the more time an attacker has to guess or intercept it.
+
+**Incorrect (codes last too long or never expire):**
+
+```php
+// Verification code without expiry
+$user->verification_code = '123456';
+$user->save(); // Stays valid forever!
+
+// Reset link valid for 7 days
+$resetUrl = generateResetLink($user, 7 * 24 * 60 * 60);
+```
+
+**Correct (short lifespan and single-use logic):**
+
+```php
+// 1. Using Redis for TTL (Recommended for OTPs)
+$otp = (string)random_int(100000, 999999);
+$cacheKey = "auth_otp:{$user->id}";
+
+// Store with 5-minute expiry (300 seconds)
+Redis::setex($cacheKey, 300, json_encode([
+    'code' => $otp,
+    'attempts' => 0
+]));
+
+// 2. Verified and Single Use
+public function verify(string $input) {
+    $data = json_decode(Redis::get($cacheKey), true);
+    
+    if (!$data) return false;
+
+    // Check attempts to prevent brute-force
+    if ($data['attempts'] > 3) {
+        Redis::del($cacheKey);
+        throw new Exception("Too many attempts.");
+    }
+
+    if ($input === $data['code']) {
+        Redis::del($cacheKey); // DELETE IMMEDIATELY AFTER USE
+        return true;
+    }
+    
+    // Increment attempts
+    $data['attempts']++;
+    Redis::setex($cacheKey, 300, json_encode($data));
+    return false;
+}
+```
+
+**Recommended Expiry Times:**
+- **2FA/OTP (Short code)**: 5 - 10 minutes.
+- **Magic Links**: 15 minutes.
+- **Password Reset (Long token)**: 60 minutes.
+- **Email Verification**: 24 hours.
+
+**Best Practices:**
+- **Single Use**: Invalidating the code immediately after a successful *or* too many failed attempts is mandatory.
+- **Secure Generation**: Use `random_int()` or `random_bytes()` for generation (see rule **S010**).
+- **Rate Limiting**: Limit how many times a code can be requested per user/IP.
+
+**Tools:** Laravel `signed` routes, Redis `SETEX`, PHPUnit (for expiry tests)

package/skill-assets/sunlint-code-quality/rules/php/S050-token-entropy.md

@@ -0,0 +1,58 @@
+---
+title: Reference Tokens 128-bit Entropy CSPRNG
+impact: HIGH
+impactDescription: prevents token prediction and brute-force attacks
+tags: tokens, entropy, csprng, session, security, php
+---
+
+## Reference Tokens 128-bit Entropy CSPRNG
+
+Predictable or low-entropy tokens (API keys, session IDs, reset tokens) can be guessed or brute-forced. Using a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) with at least 128 bits of entropy makes such attacks computationally infeasible.
+
+**Incorrect (predictable or low-entropy tokens):**
+
+```php
+// 1. Predictable - using non-CS PRNG
+$token = uniqid(); // Based on microtime, highly predictable
+
+// 2. Predictable - Sequential or timestamp based
+$token = "session_" . time() . "_" . $userId;
+
+// 3. Low Entropy
+$token = bin2hex(random_bytes(4)); // Only 32 bits of entropy
+```
+
+**Correct (high-entropy CSPRNG tokens):**
+
+```php
+// 1. Minimum 128 bits (16 bytes = 128 bits)
+$sessionToken = bin2hex(random_bytes(16));
+
+// 2. Recommended 256 bits (32 bytes)
+$apiKey = 'sk_' . bin2hex(random_bytes(32));
+
+// 3. Using Base64 (URL safe) for better efficiency
+$token = str_replace(['+', '/', '='], ['-', '_', ''], base64_encode(random_bytes(32)));
+
+/**
+ * 4. Using Laravel Helpers (Powered by random_bytes)
+ */
+use Illuminate\Support\Str;
+
+$token = Str::random(40); // Generates a random alphanumeric string
+```
+
+**Entropy Guide:**
+
+| Bytes | Bits | Use Case |
+|-------|------|----------|
+| 8 | 64 | **Weak** (Guessable in small datasets) |
+| 16 | 128 | **Minimum** for session IDs |
+| 32 | 256 | **Recommended** for API keys & Refresh Tokens |
+
+**Key Rules:**
+- **Always use `random_bytes()`** or `random_int()` in PHP.
+- **Never use `rand()`**, `mt_rand()`, or `uniqid()` for security tokens.
+- **Encode securely**: Use `bin2hex` or URL-safe Base64 for token representation.
+
+**Tools:** PHP Internal `random_bytes()`, SonarQube, Manual Security Review