AI Security Audit for WordPress Plugins and Themes (SQLi, Nonce, XSS)

<?php
declare(strict_types=1);

/**
* Author: Artur Yusupov (Fullstack Agentic Lab)
* Package: @agentic-lab/security-auditor
* Standard: WordPress 6.8+ / PHP 8.4 Strict
*/

namespace AgenticLab\SecurityAudit;

use wpdb;
use WP_Error;

final readonly class SecurityAuditorEngine
{
  public function __construct(
      private wpdb $db,
      private string $securityLogGroup = 'agentic-audit'
  ) {}

  /**
   * Пример уязвимого кода (До аудита):
   * 
   * public function legacy_delete_customer(): void {
   *     $id = $_POST['customer_id'];
   *     $this->db->query("DELETE FROM {$this->db->prefix}customers WHERE id = " . $id);
   * }
   */

  /**
   * Эталонный безопасный обработчик, сформированный AI-агентом после аудита.
   *
   * @param array<string, mixed> $requestData Массив входных данных ($_POST)
   * @return true|WP_Error Результат операции
   */
  public function secureDeleteCustomer(array $requestData): true|WP_Error
  {
      // 1. Проверка авторизации и матрицы прав (Capabilities)
      if (!current_user_can('manage_options')) {
          $this->logSecurityViolation('unauthorized_deletion_attempt', 'User lacks manage_options capability');
          return new WP_Error(
              'rest_forbidden',
              __('Недостаточно привилегий для выполнения операции.', 'agentic-lab'),
              ['status' => 403]
          );
      }

      // 2. Валидация криптографического токена Nonce (Защита от CSRF)
      $nonce = isset($requestData['_wpnonce']) && is_string($requestData['_wpnonce']) 
          ? sanitize_text_field(wp_unslash($requestData['_wpnonce'])) 
          : '';

      if ($nonce === '' || !wp_verify_nonce($nonce, 'agentic_delete_customer_action')) {
          $this->logSecurityViolation('csrf_detected', 'Invalid or missing CSRF nonce');
          return new WP_Error(
              'rest_invalid_nonce',
              __('Сессия истекла или запрос не прошел проверку безопасности.', 'agentic-lab'),
              ['status' => 403]
          );
      }

      // 3. Строгая санитизация и приведение типов (Type Casting)
      $rawId = $requestData['customer_id'] ?? null;
      $customerId = filter_var($rawId, FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);

      if ($customerId === false) {
          return new WP_Error(
              'rest_invalid_param',
              __('Идентификатор клиента должен быть натуральным числом.', 'agentic-lab'),
              ['status' => 400]
          );
      }

      // 4. Подготовленное выражение $wpdb->prepare() (Защита от SQL-инъекций)
      $table = $this->db->prefix . 'agentic_customers';
      
      // Внимание: имя таблицы экранируется валидацией структуры, литерал параметризуется %d
      $preparedSql = $this->db->prepare(
          "DELETE FROM {$table} WHERE id = %d AND status != %s",
          $customerId,
          'protected'
      );

      if ($preparedSql === null) {
          return new WP_Error('db_prepare_failed', __('Сбой подготовки SQL запроса.', 'agentic-lab'), ['status' => 500]);
      }

      $result = $this->db->query($preparedSql);

      if ($result === false) {
          return new WP_Error('db_query_error', __('Ошибка при удалении записи из БД.', 'agentic-lab'), ['status' => 500]);
      }

      return true;
  }

  /**
   * Безопасный рендеринг пользовательского контента с принципом Late Escaping.
   */
  public function renderCustomerProfile(int $customerId, string $rawBio, string $homepageUrl): string
  {
      // Позднее экранирование строго по контексту HTML-атрибутов и тегов
      $safeId       = esc_attr((string) $customerId);
      $safeUrl      = esc_url($homepageUrl);
      $safeBioText  = wp_kses_post($rawBio); // Разрешает безопасный HTML контента

      return sprintf(
          '<div class="customer-card" data-customer-id="%s">' .
              '<p class="customer-bio">%s</p>' .
              '<a href="%s" class="customer-site" target="_blank" rel="noopener noreferrer">%s</a>' .
          '</div>',
          $safeId,
          $safeBioText,
          $safeUrl,
          esc_html__('Перейти на сайт', 'agentic-lab')
      );
  }

  private function logSecurityViolation(string $eventType, string $description): void
  {
      error_log(sprintf(
          '[%s] [SECURITY ALERT] Type: %s | Details: %s | IP: %s | UserID: %d',
          $this->securityLogGroup,
          $eventType,
          $description,
          sanitize_text_field($_SERVER['REMOTE_ADDR'] ?? '0.0.0.0'),
          get_current_user_id()
      ));
  }
}