@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/php/S051-password-length.md

@@ -0,0 +1,59 @@
+---
+title: Support 12-64 Character Passwords
+impact: MEDIUM
+impactDescription: promotes the use of secure passphrases over complex but short passwords
+tags: password, length, passphrase, security, php
+---
+
+## Support 12-64 Character Passwords
+
+Modern security standards (NIST) prioritize longer passwords (passphrases) over short passwords with complex character requirements. Do not impose overly restrictive maximum length limits (like 16 or 20 characters), as this prevents users from using secure passphrases or generated secrets.
+
+**Incorrect (too restrictive or too short):**
+
+```php
+// Insecure: minimum length is too short
+$request->validate(['password' => 'min:6']);
+
+// Restrictive: prevents long secure passphrases
+$request->validate(['password' => 'min:8|max:16']); 
+```
+
+**Correct (promoting secure passphrases):**
+
+```php
+// 1. Recommended Validation (Laravel)
+$request->validate([
+    'password' => [
+        'required',
+        'string',
+        'min:12', // Minimum 12 characters recommended
+        'max:64', // Support at least 64+ characters
+    ]
+]);
+
+// 2. Using Complexity only for shorter passwords (NIST principle)
+use Illuminate\Validation\Rules\Password;
+
+$request->validate([
+    'password' => [
+        'required',
+        Password::min(12)
+            ->letters()
+            ->numbers()
+            ->symbols()
+            ->uncompromised(), // Checks against HaveIBeenPwned API
+    ]
+]);
+```
+
+**Security Guidelines:**
+- **Minimum 8 characters** (Internal use) or **12+ characters** (Public internet).
+- **Maximum 64-128 characters** should be supported.
+- **Do not use "complexity"** (Must include special chars) as a hard requirement if the password is long (e.g., > 16 characters).
+- **Allow all characters**, including spaces and Unicode.
+
+**Why 64 characters?**
+Many hashing algorithms (like BCRYPT) have an internal limit around 72 characters. Support for 64-128 characters is usually sufficient for nearly all users and password managers.
+
+**Tools:** Laravel `Rules\Password`, OWASP Password Policy, Zxcvbn (password strength estimator)

package/skill-assets/sunlint-code-quality/rules/php/S052-otp-entropy.md

@@ -0,0 +1,45 @@
+---
+title: OTPs Must Have 20-bit Entropy Minimum
+impact: MEDIUM
+impactDescription: prevents guessing and brute-force attacks on One-Time Passwords
+tags: otp, entropy, authentication, 2fa, security, php
+---
+
+## OTPs Must Have 20-bit Entropy Minimum
+
+One-Time Passwords (OTPs) with low entropy, such as 4-digit codes, are susceptible to brute-force attacks. A 6-digit numeric OTP provides roughly 20 bits of entropy (1,000,000 combinations), which is the industry standard when combined with rate limiting.
+
+**Incorrect (low entropy or predictable OTPs):**
+
+```php
+// 1. Weak - 4 digits (only 10,000 combinations)
+$otp = rand(1000, 9999);
+
+// 2. Predictable - using non-CS PRNG
+$otp = substr(mt_rand(), 0, 6);
+
+// 3. Very Weak - based on time
+$otp = substr(time(), -6);
+```
+
+**Correct (CSPRNG generated numeric OTPs):**
+
+```php
+// 1. 6-digit OTP (Recommended minimum)
+$otp = (string)random_int(100000, 999999);
+
+// 2. 8-digit OTP (Extra security)
+$otp = (string)random_int(10000000, 99999999);
+
+// 3. Ensuring Leading Zeros (if needed)
+$otp = str_pad(random_int(0, 999999), 6, '0', STR_PAD_LEFT);
+```
+
+**Requirements for Secure OTPs:**
+- **Generation**: Always use **`random_int()`**; never use `rand()` or `mt_rand()`.
+- **Length**: Minimum **6 digits** for general use.
+- **Single Use**: The code must be invalidated immediately after the first use (success or failure).
+- **Rate Limiting**: Strictly limit the number of verification attempts (e.g., 3-5 attempts) before destroying the code (see rule **S045**).
+- **Expiry**: Codes should expire within **5-10 minutes**.
+
+**Tools:** PHP Internal `random_int()`, Laravel RateLimiter, Security Audit

package/skill-assets/sunlint-code-quality/rules/php/S053-generic-error-messages.md

@@ -0,0 +1,59 @@
+---
+title: Return Generic Error Messages
+impact: HIGH
+impactDescription: prevents information disclosure and user enumeration
+tags: error-messages, information-disclosure, security, php
+---
+
+## Return Generic Error Messages
+
+Detailed error messages (e.g., database stack traces, file paths, or specific missing user notifications) provide attackers with valuable information about your system's architecture and user accounts. While detailed logs are great for developers, they must never be shown to the end-user in production.
+
+**Incorrect (detailed or revealing errors):**
+
+```php
+try {
+    $db->execute("SELECT * FROM users WHERE id = ?", [$id]);
+} catch (\Exception $e) {
+    // VULNERABLE: Exposes SQL structure, file paths, and potential credentials
+    die("Database Error: " . $e->getMessage() . " at " . $e->getFile());
+}
+
+// User Enumeration Vulnerability
+if (!$userExists) {
+    return response()->json(['error' => 'Email not found'], 404);
+}
+if (!$passwordMatches) {
+    return response()->json(['error' => 'Incorrect password'], 401);
+}
+```
+
+**Correct (generic messages for users):**
+
+```php
+try {
+    $db->execute("SELECT * FROM users WHERE id = ?", [$id]);
+} catch (\Exception $e) {
+    // 1. Log the full details for developers
+    Log::error("Database query failed", ['exception' => $e]);
+
+    // 2. Return a generic message to the user
+    return response()->json([
+        'error' => 'A system error occurred. Please contact support.',
+        'request_id' => $requestId // Provide a reference for support
+    ], 500);
+}
+
+// 3. Prevent User Enumeration (Auth)
+// Use the same message and timing for both cases
+if (!$userExists || !$passwordMatches) {
+    return response()->json(['error' => 'Invalid email or password'], 401);
+}
+```
+
+**Global Configuration:**
+- **`display_errors`**: Ensure this is set to `Off` in your production `php.ini`.
+- **Laravel**: Ensure `APP_DEBUG` is set to `false` in production. This automatically swaps detailed "Whoops" pages for a generic "500 | Server Error" page.
+- **Custom Exceptions**: Use custom exceptions and map them to generic messages in a central handler (e.g., `App\Exceptions\Handler`).
+
+**Tools:** PHP `php.ini` settings, Laravel Exception Handler, OWASP ZAP (to check for information leakage)

package/skill-assets/sunlint-code-quality/rules/php/S054-no-default-admin.md

@@ -0,0 +1,62 @@
+---
+title: Avoid Default Admin/Root Accounts
+impact: HIGH
+impactDescription: prevents attackers from gaining initial administrative access via known credentials
+tags: admin, default-accounts, credentials, security, php
+---
+
+## Avoid Default Admin/Root Accounts
+
+Systems that ship with default administrative accounts (e.g., `admin@example.com` / `password`) are easily compromised. Attackers use automated tools to scan for these common credentials across the web.
+
+**Incorrect (hardcoded or weak default admin):**
+
+```php
+// UserSeeder.php
+User::create([
+    'email' => 'admin@company.com',
+    'password' => Hash::make('admin123'), // DEFAULT!
+    'is_admin' => true,
+]);
+
+// Production code with "test" roles
+if ($user->email === 'admin@test.com') {
+    // Grant full access
+}
+```
+
+**Correct (secure initial setup):**
+
+```php
+// 1. Using Environment Variables for first run
+User::create([
+    'name' => 'System Admin',
+    'email' => env('INITIAL_ADMIN_EMAIL', 'admin@example.com'),
+    'password' => Hash::make(env('INITIAL_ADMIN_PASSWORD')), // Must be set in .env
+    'is_admin' => true,
+]);
+
+// 2. Ensuring the password is not a default in Production
+if (App::environment('production')) {
+    $password = env('INITIAL_ADMIN_PASSWORD');
+    if ($password === 'admin' || $password === 'password' || strlen($password) < 12) {
+        throw new \RuntimeException("A strong, non-default INITIAL_ADMIN_PASSWORD must be configured.");
+    }
+}
+
+// 3. One-time Setup Screen
+public function installAdmin(Request $request) {
+    if (User::where('is_admin', true)->exists()) {
+        abort(403, "Admin already exists.");
+    }
+    
+    // Validate and create admin...
+}
+```
+
+**Best Practices:**
+- **Dynamic Selection**: Do not hardcode "admin" as the username or email. Require the user to define it during installation.
+- **Force Reset**: If you must generate a default password, force the user to change it upon their first login.
+- **Notification**: Log and alert administrators when an administrative account is created or its password is changed.
+
+**Tools:** Laravel Seeders, Environment Validation, Security Audit

package/skill-assets/sunlint-code-quality/rules/php/S055-content-type-validation.md

@@ -0,0 +1,58 @@
+---
+title: Validate Content-Type In REST Services
+impact: MEDIUM
+impactDescription: prevents content-type confusion attacks and ensures predictable parsing
+tags: rest, content-type, validation, api, security, php
+---
+
+## Validate Content-Type In REST Services
+
+Accepting unexpected content types (e.g., XML when you expect JSON) can lead to parsing vulnerabilities like External Entity (XXE) attacks or bypass security filters that only check for specific formats. Strict `Content-Type` validation ensures your application only processes data in the formats it was designed to handle.
+
+**Incorrect (accepting any content type):**
+
+```php
+// No content-type check: logic might try to parse different formats
+public function store(Request $request) {
+    // If the client sends XML but the code expects JSON, this might crash or behave unexpectedly
+    $data = $request->all();
+    $this->service->process($data);
+}
+```
+
+**Correct (enforcing Content-Type via Middleware):**
+
+```php
+// 1. Plain PHP Validation
+$contentType = $_SERVER['CONTENT_TYPE'] ?? '';
+if (strpos(strtolower($contentType), 'application/json') === false) {
+    header('HTTP/1.1 415 Unsupported Media Type');
+    die("Only application/json is supported.");
+}
+
+// 2. Laravel Middleware (Recommended)
+public function handle($request, Closure $next, ...$allowedTypes)
+{
+    $contentType = $request->header('Content-Type');
+
+    if (!$contentType || !Str::contains(strtolower($contentType), $allowedTypes)) {
+        return response()->json([
+            'error' => 'Unsupported Media Type',
+            'allowed' => $allowedTypes
+        ], 415);
+    }
+
+    return $next($request);
+}
+
+// Route Usage:
+Route::post('/api/data', [DataController::class, 'store'])
+    ->middleware('validate.content:application/json');
+```
+
+**Why it matters?**
+- **XXE Prevention**: If you only expect JSON but a user sends XML with a malicious DOCTYPE, your server might be vulnerable to Local File Read or SSRF if an XML parser is automatically triggered.
+- **Strict Parsing**: Ensures that your data validation rules are applied to the correct format.
+- **API Standards**: Returning a `415 Unsupported Media Type` is the correct RESTful way to communicate protocol mismatches.
+
+**Tools:** Laravel Middleware, Symfony Request Matcher, OWASP ZAP, Postman (testing)

package/skill-assets/sunlint-code-quality/rules/php/S056-log-injection.md

@@ -0,0 +1,48 @@
+---
+title: Protect Against Log Injection
+impact: HIGH
+impactDescription: prevents log forging and exploitation
+tags: logging, injection, sanitization, security, php
+---
+
+## Protect Against Log Injection
+
+Log injection occurs when an application includes untrusted data in its logs without proper sanitization. Attackers can use this to forge log entries, hide malicious activities, or inject content that could exploit log-viewing tools.
+
+**Incorrect (unsanitized logging):**
+
+```php
+// Log injection vulnerability
+$username = $_POST['username'];
+error_log("User logged in: " . $username);
+// Attacker input: "admin\n[ERROR] Database wiped by: victim"
+```
+
+**Correct (sanitized structured logging):**
+
+```php
+// Sanitize input before logging
+function sanitizeForLog($input) {
+    if (!is_string($input)) return $input;
+    // Remove newlines and carriage returns
+    return str_replace(["\r", "\n", "\t"], ' ', $input);
+}
+
+$username = $_POST['username'];
+error_log("User logged in: " . sanitizeForLog($username));
+
+// Using structured logging (e.g., Monolog in Laravel)
+// Structured logging handles most injection issues as the data is kept separate from the message
+Log::info('User logged in', [
+    'username' => $username, // Still good practice to sanitize or use a secure formatter
+    'ip' => $_SERVER['REMOTE_ADDR']
+]);
+```
+
+**Best Practices:**
+1. Avoid multi-line log entries.
+2. Neutralize newlines and tab characters in user-controlled input before logging.
+3. Use structured logging (JSON) instead of plain text strings.
+4. Limit the length of data included in logs to prevent log-overflow or denial of service on log management systems.
+
+**Tools:** PHPStan, Psalm, SonarQube, Monolog Safe Formatters

package/skill-assets/sunlint-code-quality/rules/php/S057-synchronized-time.md

@@ -0,0 +1,52 @@
+---
+title: Use Synchronized Time (UTC) In Logs
+impact: MEDIUM
+impactDescription: enables accurate incident correlation across distributed systems
+tags: logging, time, utc, synchronization, security, php
+---
+
+## Use Synchronized Time (UTC) In Logs
+
+Inconsistent or incorrect timestamps across multiple servers make it extremely difficult to correlate events during an incident investigation. You must use a synchronized time source (NTP) and log all events in UTC using the ISO 8601 format.
+
+**Incorrect (local time or inconsistent formats):**
+
+```php
+// Local timezone - varies by server config
+Log::info("User logged in at " . date("Y-m-d H:i:s"));
+
+// Non-standard formats
+Log::info("[" . time() . "] Action performed");
+```
+
+**Correct (UTC and ISO 8601):**
+
+```php
+// 1. Explicitly sets UTC (Recommended for all backend apps)
+date_default_timezone_set('UTC');
+
+// 2. Using ISO 8601 format (DateTimeInterface::ATOM)
+$now = (new DateTime('now', new DateTimeZone('UTC')))->format(DateTimeInterface::ATOM);
+Log::info('Order processed', [
+    'timestamp' => $now, // Example: 2024-05-10T15:20:00+00:00
+    'order_id' => 123
+]);
+
+// 3. In Laravel (config/app.php)
+'timezone' => 'UTC',
+
+// 4. Using Carbon (Laravel/Symfony)
+Log::info('Event', [
+    'timestamp' => now()->toIso8601String()
+]);
+```
+
+**Synchronization Strategy:**
+- **Server Clock**: Use NTP (Network Time Protocol) to ensure all application and database servers are synchronized to the millisecond.
+- **Internal Storage**: Store all timestamps in the database as UTC. Convert to local time only when displaying to the end-user.
+- **Log Format**: Prefer structured JSON logs where the timestamp is a top-level field in ISO 8601 format.
+
+**Why ISO 8601?**
+It is unambiguous, machine-readable, and includes timezone offset information (usually `Z` or `+00:00`), making it the gold standard for log aggregation tools like Elasticsearch or Graylog.
+
+**Tools:** NTP, Monolog (with UTC formatter), Carbon, `date_default_timezone_set()`

package/skill-assets/sunlint-code-quality/rules/php/S058-ssrf-protection.md

@@ -0,0 +1,65 @@
+---
+title: Protect Against SSRF Attacks
+impact: MEDIUM
+impactDescription: prevents attackers from making requests from your server to internal services
+tags: ssrf, url, network, internal, security, php
+---
+
+## Protect Against SSRF Attacks
+
+Server-Side Request Forgery (SSRF) allows an attacker to force your server to make requests to internal services, local files, or cloud metadata endpoints (e.g., AWS metadata). This often happens when the application takes a URL from a user and fetches its content.
+
+**Incorrect (accepting user URLs without validation):**
+
+```php
+// SSRF vulnerability using file_get_contents
+$url = $_GET['url'];
+echo file_get_contents($url); // Attacker: ?url=http://169.254.169.254/latest/meta-data/
+
+// SSRF via cURL
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_URL, $_GET['url']);
+curl_exec($ch);
+```
+
+**Correct (strict validation and blocklists):**
+
+```php
+$userUrl = $_GET['url'];
+$parsed = parse_url($userUrl);
+
+// 1. Force protocol (Whitelist)
+$allowedProtocols = ['http', 'https'];
+if (!in_array($parsed['scheme'], $allowedProtocols)) {
+    die("Only HTTP/HTTPS allowed");
+}
+
+// 2. Host Whitelist (Most Secure)
+$allowedHosts = ['api.trusted.com', 'images.trusted.com'];
+if (!in_array($parsed['host'], $allowedHosts)) {
+    die("Untrusted host");
+}
+
+// 3. Block Private/Internal IP Ranges (If dynamic hosts are required)
+$ip = gethostbyname($parsed['host']);
+$privateRanges = [
+    '127.0.0.0/8', '10.0.0.0/8', '172.16.0.0/12', 
+    '192.168.0.0/16', '169.254.169.254' // AWS Metadata
+];
+// Use a library like `spatie/ip-range-check` to verify $ip against $privateRanges
+
+// 4. Safe cURL usage
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_URL, $userUrl);
+curl_setopt($ch, CURLOPT_PROTOCOLS, CURLPROTO_HTTP | CURLPROTO_HTTPS); // Restrict protocols
+curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false); // Disable redirects to prevent bypass
+curl_exec($ch);
+```
+
+**Prevention Checklist:**
+- **Whitelisting**: Only allow requests to specific, trusted domains.
+- **Protocol Restriction**: Only allow `http` or `https`. Disable `file://`, `gopher://`, `dict://`, etc.
+- **Network Isolation**: Ensure your web server cannot reach internal databases or management interfaces directly.
+- **Authentication**: Require identification for any proxying service.
+
+**Tools:** PHP `parse_url()`, cURL security options, SonarQube, Manual Security Review

package/skill-assets/sunlint-code-quality/rules/python/C006-verb-noun-functions.md

@@ -0,0 +1,30 @@
+---
+title: Use Verb-Noun Pattern for Functions
+impact: MEDIUM
+impactDescription: improves readability and intent discovery
+tags: naming, functions, readability, quality, python
+---
+
+## Use Verb-Noun Pattern for Functions
+
+Function names should clearly state what they do. Using a verb-noun pattern makes the code self-documenting.
+
+**Incorrect (ambiguous naming):**
+```python
+def data(): ...
+def process(): ...
+def my_function(): ...
+```
+
+**Correct (verb-noun naming):**
+```python
+def get_user_data(): ...
+def process_order_status(): ...
+def validate_email_address(): ...
+```
+
+**Spark Context:**
+```python
+def clean_null_values(df): ...
+def aggregate_daily_sales(df): ...
+```

package/skill-assets/sunlint-code-quality/rules/python/C013-no-dead-code.md

@@ -0,0 +1,24 @@
+---
+title: Do Not Commit Dead Code
+impact: MEDIUM
+impactDescription: reduces noise and maintenance burden
+tags: clean-code, maintenance, quality, python
+---
+
+## Do Not Commit Dead Code
+
+Dead code (commented-out code or unreachable code) clutters the codebase and leads to confusion.
+
+**Incorrect:**
+```python
+def calculate_tax(amount):
+    # Old logic:
+    # return amount * 0.05
+    return amount * 0.08
+```
+
+**Correct:**
+```python
+def calculate_tax(amount):
+    return amount * 0.08
+```

package/skill-assets/sunlint-code-quality/rules/python/C014-dependency-injection.md

@@ -0,0 +1,68 @@
+---
+title: Use Dependency Injection
+impact: HIGH
+impactDescription: enables testability and loose coupling
+tags: dependency-injection, testing, coupling, architecture, quality, python, pyspark
+---
+
+## Use Dependency Injection
+
+Direct instantiation creates tight coupling, making testing difficult and changes risky. DI enables mockability, replaceability, and testability. In Python, this is often done using constructor injection or DI frameworks.
+
+**Incorrect (hardcoded dependencies):**
+
+```python
+class OrderService:
+    def __init__(self):
+        self.db = DatabaseConnection() # Hardcoded dependency
+        self.mailer = EmailService()   # Hardcoded dependency
+
+    def create_order(self, data):
+        order = self.db.insert('orders', data)
+        self.mailer.send(data['email'], 'Order created')
+        return order
+```
+
+**Correct (injected dependencies):**
+
+```python
+class OrderService:
+    def __init__(self, db, mailer):
+        self.db = db
+        self.mailer = mailer
+
+    def create_order(self, data):
+        order = self.db.insert('orders', data)
+        self.mailer.send(data['email'], 'Order created')
+        return order
+
+# Usage
+service = OrderService(
+    db=PostgresDatabase(conn_string),
+    mailer=SendGridMailer(api_key)
+)
+
+# Testing with pytest/unittest.mock
+from unittest.mock import MagicMock
+mock_db = MagicMock()
+mock_mailer = MagicMock()
+test_service = OrderService(db=mock_db, mailer=mock_mailer)
+```
+
+**PySpark Context:**
+In Spark, dependencies like `SparkSession` should be passed to processing functions or classes rather than using globals like `SparkSession.builder.getOrCreate()` everywhere.
+
+```python
+def process_data(spark: SparkSession, input_path: String):
+    df = spark.read.load(input_path)
+    # ... process
+    return df
+```
+
+**Benefits:**
+- Easy mocking for unit tests
+- Swappable implementations (e.g., local vs cloud storage)
+- Clear dependencies visible in constructor
+- Supports interface-based design (using Protocols or ABCs)
+
+**Tools:** Static analyzer, PR review, dependency-injector (library)

package/skill-assets/sunlint-code-quality/rules/python/C017-no-constructor-logic.md

@@ -0,0 +1,30 @@
+---
+title: No Business Logic in Constructors
+impact: MEDIUM
+impactDescription: keeps instantiation simple and testable
+tags: quality, construction, clean-code, python
+---
+
+## No Business Logic in Constructors
+
+Constructors should only assign dependencies and state. Complex logic, I/O, or remote calls make testing and inheritance difficult.
+
+**Incorrect:**
+```python
+class SparkJob:
+    def __init__(self, path):
+        self.path = path
+        # ❌ I/O in constructor makes it hard to unit test
+        self.spark = SparkSession.builder.getOrCreate()
+        self.df = self.spark.read.load(path)
+```
+
+**Correct:**
+```python
+class SparkJob:
+    def __init__(self, spark_session):
+        self.spark = spark_session
+
+    def load_data(self, path):
+        return self.spark.read.load(path)
+```

package/skill-assets/sunlint-code-quality/rules/python/C018-generic-errors.md

@@ -0,0 +1,25 @@
+---
+title: Do Not Throw Generic Errors
+impact: MEDIUM
+impactDescription: prevents ambiguous error handling
+tags: error-handling, quality, python
+---
+
+## Do Not Throw Generic Errors
+
+Raising generic `Exception` or `RuntimeError` makes it impossible for callers to catch specific issues.
+
+**Incorrect:**
+```python
+if not user:
+    raise Exception("User not found")
+```
+
+**Correct:**
+```python
+class UserNotFoundError(Exception):
+    pass
+
+if not user:
+    raise UserNotFoundError("User ID 123 not found")
+```

package/skill-assets/sunlint-code-quality/rules/python/C019-error-log-level.md

@@ -0,0 +1,26 @@
+---
+title: Do Not Use Error Log Level for Non-Critical Issues
+impact: LOW
+impactDescription: prevents alert fatigue
+tags: logging, observability, quality, python
+---
+
+## Do Not Use Error Log Level for Non-Critical Issues
+
+Reserve `ERROR` level for things that require immediate attention (e.g., job failure). Use `WARNING` or `INFO` for expected deviations.
+
+**Incorrect:**
+```python
+try:
+    data = fetch_optional_data()
+except Exception:
+    logger.error("Optional data not found") # Not really an error
+```
+
+**Correct:**
+```python
+try:
+    data = fetch_optional_data()
+except Exception:
+    logger.warning("Optional data not found, continuing with defaults")
+```