wordpress-security-validation

WordPress 安全与数据验证

版本： 1.1.0 目标： WordPress 6.7+ | PHP 8.3+ 技能水平： 中级至高级

概述

在 WordPress 开发中，安全性不是可选项，而是基础。本技能将介绍三层安全模型，通过正确的输入清理、业务逻辑验证和输出转义，防止 XSS、CSRF、SQL 注入及其他常见 Web 漏洞。

黄金法则：“输入时清理，按逻辑验证，输出时转义。”

为什么这很重要

每年，数以千计的 WordPress 网站因插件和主题中的安全漏洞而遭到入侵。这些攻击大多利用了以下三种弱点之一：

1. XSS（跨站脚本攻击）： 通过未经清理的输出注入恶意 JavaScript
2. CSRF（跨站请求伪造）： 代表已通过身份验证的用户执行未经授权的操作
3. SQL 注入： 通过未经清理的数据库查询操纵数据库

本技能提供了完整且可用于生产环境的模式，用于防范这三种攻击途径。

---

三层安全模型

WordPress 安全遵循深度防御策略，包含三个不同层次：

User Input → [1. SANITIZE] → [2. VALIDATE] → Process → [3. ESCAPE] → Output

第 1 层：清理（输入清理）

目的： 移除危险字符并规范数据格式 时机： 收到用户输入后立即处理 示例： sanitize_text_field($_POST['username'])

第 2 层：验证（逻辑检查）

目的： 确保数据符合业务要求 时机： 清理之后、处理之前 示例： if (!is_email($email)) { /* error */ }

第 3 层：转义（输出保护）

目的： 通过编码特殊字符来防止 XSS 时机： 每次向浏览器输出数据时 示例： echo esc_html($user_input);

关键区别：

• 清理会移除／转换无效数据（改变值）
• 验证会检查数据是否可接受（返回 true／false）
• 转义会让数据显示时更加安全（针对特定上下文进行编码）

---

1. Nonce：CSRF 防护

什么是 Nonce？

Nonce（一次性数字）是用于验证请求来自你的网站，而非恶意外部来源的加密令牌。它们可以防止**跨站请求伪造（CSRF）**攻击。

CSRF 攻击的运作方式：

<img src="https://yoursite.com/wp-admin/admin.php?action=delete_user&id=1">

Nonce 如何防止 CSRF：

<form action="admin.php?action=delete_user&id=1" method="POST">
    <?php wp_nonce_field('delete_user_1', 'delete_nonce'); ?>
    <button>Delete User</button>
</form>

Nonce 实现模式

模式 1：表单 Nonce（最常见）

之前（存在漏洞）：

// Vulnerable form processing
if (isset($_POST['submit'])) {
    $user_id = absint($_POST['user_id']);
    delete_user($user_id); // ⚠️ CSRF vulnerable!
}

之后（安全）：

// Generate nonce in form
<form method="post" action="">
    <?php wp_nonce_field('delete_user_action', 'delete_user_nonce'); ?>
    <input type="hidden" name="user_id" value="42">
    <button type="submit" name="submit">Delete User</button>
</form>

// Verify nonce on submission
if (isset($_POST['submit'])) {
    // Security check #1: Verify nonce
    if (!isset($_POST['delete_user_nonce']) ||
        !wp_verify_nonce($_POST['delete_user_nonce'], 'delete_user_action')) {
        wp_die('Security check failed: Invalid nonce');
    }

    // Security check #2: Capability check
    if (!current_user_can('delete_users')) {
        wp_die('You do not have permission to delete users');
    }

    // Now safe to process
    $user_id = absint($_POST['user_id']);
    wp_delete_user($user_id);
}

关键函数：

• wp_nonce_field($action, $name) - 生成隐藏的 nonce 字段
• wp_verify_nonce($nonce, $action) - 验证 nonce 是否有效

模式 2：URL Nonce

适用场景： 删除／移至回收站链接、管理操作

// Generate nonce URL
$delete_url = wp_nonce_url(
    admin_url('admin.php?action=delete_post&post_id=123'),
    'delete_post_123',  // Action (must be unique)
    'delete_nonce'      // Query parameter name
);

echo '<a href="' . esc_url($delete_url) . '">Delete Post</a>';

// Verify nonce in handler
add_action('admin_action_delete_post', 'handle_delete_post');
function handle_delete_post() {
    // Verify nonce from URL
    if (!isset($_GET['delete_nonce']) ||
        !wp_verify_nonce($_GET['delete_nonce'], 'delete_post_123')) {
        wp_die('Invalid security token');
    }

    // Verify capability
    $post_id = absint($_GET['post_id']);
    if (!current_user_can('delete_post', $post_id)) {
        wp_die('You cannot delete this post');
    }

    // Delete post
    wp_delete_post($post_id, true); // true = force delete

    // Redirect with success message
    wp_redirect(add_query_arg('message', 'deleted', wp_get_referer()));
    exit;
}

模式 3：AJAX Nonce

适用场景： 前端 AJAX 请求

之前（存在漏洞）：

// ⚠️ Vulnerable AJAX request
jQuery.post(ajaxurl, {
    action: 'update_user_meta',
    user_id: 42,
    meta_key: 'favorite_color',
    meta_value: 'blue'
}, function(response) {
    console.log(response);
});

之后（安全）：

PHP（使用 nonce 加载脚本）：

add_action('wp_enqueue_scripts', 'enqueue_ajax_script');
function enqueue_ajax_script() {
    wp_enqueue_script('my-ajax-script',
        plugin_dir_url(__FILE__) . 'js/ajax.js',
        ['jquery'],
        '1.0.0',
        true
    );

    // Pass nonce and AJAX URL to JavaScript
    wp_localize_script('my-ajax-script', 'myAjax', [
        'ajaxurl' => admin_url('admin-ajax.php'),
        'nonce' => wp_create_nonce('my_ajax_nonce'), // Generate nonce
    ]);
}

// AJAX handler with nonce verification
add_action('wp_ajax_update_user_meta', 'handle_ajax_update');
function handle_ajax_update() {
    // Verify nonce
    check_ajax_referer('my_ajax_nonce', 'nonce');

    // Verify capability
    if (!current_user_can('edit_users')) {
        wp_send_json_error(['message' => 'Permission denied']);
    }

    // Sanitize input
    $user_id = absint($_POST['user_id']);
    $meta_key = sanitize_key($_POST['meta_key']);
    $meta_value = sanitize_text_field($_POST['meta_value']);

    // Update meta
    update_user_meta($user_id, $meta_key, $meta_value);

    wp_send_json_success(['message' => 'Updated successfully']);
}

JavaScript（在 AJAX 中使用 nonce）：

jQuery(document).ready(function($) {
    $('#update-button').on('click', function() {
        $.post(myAjax.ajaxurl, {
            action: 'update_user_meta',
            nonce: myAjax.nonce,  // Include nonce
            user_id: 42,
            meta_key: 'favorite_color',
            meta_value: 'blue'
        }, function(response) {
            if (response.success) {
                console.log(response.data.message);
            } else {
                console.error(response.data.message);
            }
        });
    });
});

关键函数：

• wp_create_nonce($action) - 生成 nonce 令牌
• check_ajax_referer($action, $query_arg) - 验证 AJAX nonce（失败时终止执行）
• wp_send_json_success($data) - 发送 JSON 成功响应
• wp_send_json_error($data) - 发送 JSON 错误响应

Nonce 最佳实践

✅ 应该：

• 使用唯一的操作名称（例如 delete_post_$post_id，而不只是 delete）
• 处理任何数据之前，始终先验证 nonce
• 将 nonce 检查与能力检查结合使用
• 使用专用的 nonce 函数（AJAX 请求使用 check_ajax_referer）

❌ 不要：

• 为多个操作重复使用同一个 nonce 操作名称
• 因为操作“只读”就跳过 nonce 验证
• 仅依赖 nonce 验证（也要始终检查能力）
• 将 nonce 长期存储在 Cookie 或 URL 中（它们会过期）

Nonce 有效期： WordPress nonce 默认在 24 小时后过期（由于时间窗口机制，前后各为 12 小时）。

---

2. 清理函数参考

清理会通过移除或编码危险字符，将用户输入转换为安全格式。这是防御恶意数据的第一道防线。

核心清理函数

函数	用例	示例输入	输出
sanitize_text_field()	单行文本（用户名、标题）	"Hello <script>alert('xss')</script>"	"Hello alert('xss')"
sanitize_email()	电子邮件地址	"[email protected]<script>"	"[email protected]"
sanitize_url() / esc_url_raw()	URL（用于存储）	"javascript:alert('xss')"	""（已拦截）
sanitize_key()	数组键、元数据键	"my key!"	"my_key"
sanitize_file_name()	文件上传	"../../etc/passwd"	"..etcpasswd"
absint()	正整数	"-5"、"42abc"	5、42
intval()	任意整数	"-5"、"42.7"	-5、42
floatval()	浮点数	"3.14abc"	3.14
wp_kses_post()	HTML 内容（允许安全标签）	"<p>Safe</p><script>Bad</script>"	"<p>Safe</p>"
wp_kses()	使用自定义允许标签的 HTML	见下文	自定义过滤
sanitize_textarea_field()	多行文本	"Line 1\nLine 2<script>"	"Line 1\nLine 2"
sanitize_title()	文章别名	"Hello World!"	"hello-world"

详细示例

文本清理

// Single-line text (removes HTML, line breaks, extra whitespace)
$username = sanitize_text_field($_POST['username']);
// Input: "  John <b>Doe</b>\n"
// Output: "John Doe"

// Multi-line text (preserves line breaks, removes HTML)
$bio = sanitize_textarea_field($_POST['bio']);
// Input: "Line 1\nLine 2<script>alert('xss')</script>"
// Output: "Line 1\nLine 2alert('xss')"

// Email (validates format and removes invalid characters)
$email = sanitize_email($_POST['email']);
// Input: "[email protected] <script>"
// Output: "[email protected]"

// URL (removes dangerous protocols)
$website = esc_url_raw($_POST['website']);
// Input: "javascript:alert('xss')"
// Output: "" (blocked protocol)
// Input: "http://example.com"
// Output: "http://example.com"

数值清理

// Positive integers only (absolute value)
$post_id = absint($_POST['post_id']);
// Input: "-5", "42", "123abc"
// Output: 5, 42, 123

// Any integer (preserves negative)
$temperature = intval($_POST['temperature']);
// Input: "-5", "42.7", "99abc"
// Output: -5, 42, 99

// Floating-point numbers
$price = floatval($_POST['price']);
// Input: "19.99", "20.5abc"
// Output: 19.99, 20.5

HTML 清理

wp_kses_post() - 允许 WordPress 文章编辑器标签：

$content = wp_kses_post($_POST['content']);
// Allows: <p>, <a>, <strong>, <em>, <ul>, <ol>, <li>, <blockquote>, <img>, etc.
// Blocks: <script>, <iframe>, <object>, <embed>, <form>

// Input: "<p>Safe content</p><script>alert('xss')</script>"
// Output: "<p>Safe content</p>alert('xss')"

wp_kses() - 自定义允许标签：

// Define allowed tags and attributes
$allowed_html = [
    'a' => [
        'href' => true,
        'title' => true,
        'target' => true,
    ],
    'strong' => [],
    'em' => [],
    'br' => [],
];

$clean_html = wp_kses($_POST['content'], $allowed_html);

// Input: "<a href='#' onclick='alert(1)'>Link</a><script>Bad</script>"
// Output: "<a href='#'>Link</a>Bad" (onclick removed, script stripped)

移除所有 HTML：

$plain_text = wp_strip_all_tags($_POST['content']);
// Input: "<p>Hello <b>World</b></p>"
// Output: "Hello World"

文件上传清理

// Sanitize filename (removes path traversal, special characters)
$safe_filename = sanitize_file_name($_FILES['upload']['name']);
// Input: "../../etc/passwd", "my file!.php"
// Output: "..etcpasswd", "my-file.php"

// Complete file upload example
if (isset($_FILES['user_avatar'])) {
    // Verify nonce first!
    if (!wp_verify_nonce($_POST['upload_nonce'], 'upload_avatar')) {
        wp_die('Security check failed');
    }

    // Sanitize filename
    $filename = sanitize_file_name($_FILES['user_avatar']['name']);

    // Validate file type
    $allowed_types = ['image/jpeg', 'image/png', 'image/gif'];
    $file_type = $_FILES['user_avatar']['type'];

    if (!in_array($file_type, $allowed_types)) {
        wp_die('Invalid file type. Only JPG, PNG, GIF allowed.');
    }

    // Use WordPress upload handler (handles security)
    $upload = wp_handle_upload($_FILES['user_avatar'], [
        'test_form' => false,
        'mimes' => [
            'jpg|jpeg' => 'image/jpeg',
            'png' => 'image/png',
            'gif' => 'image/gif',
        ],
    ]);

    if (isset($upload['error'])) {
        wp_die('Upload failed: ' . $upload['error']);
    }

    // Store uploaded file URL
    $avatar_url = $upload['url'];
    update_user_meta(get_current_user_id(), 'avatar_url', $avatar_url);
}

数组清理

// Sanitize array of text fields
$tags = array_map('sanitize_text_field', $_POST['tags']);
// Input: ['tag1', '<script>tag2</script>', 'tag3']
// Output: ['tag1', 'tag2', 'tag3']

// Sanitize array of integers
$ids = array_map('absint', $_POST['post_ids']);
// Input: ['1', '2abc', '-5']
// Output: [1, 2, 5]

// Sanitize array of emails
$emails = array_map('sanitize_email', $_POST['email_list']);

自定义清理回调

// Register setting with sanitization callback
register_setting('my_plugin_options', 'my_plugin_settings', [
    'type' => 'array',
    'sanitize_callback' => 'my_plugin_sanitize_settings',
]);

function my_plugin_sanitize_settings($input) {
    $sanitized = [];

    // Sanitize API key (alphanumeric only)
    if (isset($input['api_key'])) {
        $sanitized['api_key'] = preg_replace('/[^a-zA-Z0-9]/', '', $input['api_key']);
    }

    // Sanitize boolean checkbox
    $sanitized['enable_feature'] = isset($input['enable_feature']) ? 1 : 0;

    // Sanitize color (hex format)
    if (isset($input['primary_color'])) {
        $color = sanitize_hex_color($input['primary_color']);
        $sanitized['primary_color'] = $color ? $color : '#000000';
    }

    // Sanitize select option (whitelist)
    $allowed_modes = ['mode1', 'mode2', 'mode3'];
    if (isset($input['mode']) && in_array($input['mode'], $allowed_modes)) {
        $sanitized['mode'] = $input['mode'];
    } else {
        $sanitized['mode'] = 'mode1'; // Default
    }

    return $sanitized;
}

---

3. 验证模式

验证可确保数据在清理后符合业务逻辑要求。与清理（会转换数据）不同，验证会返回 true/false。

内置验证函数

函数	用途	示例
is_email($email)	有效的电子邮件格式	is_email('[email protected]') → true
is_numeric($value)	数字字符串	is_numeric('42') → true
is_int($value)	整数类型	is_int(42) → true
is_array($value)	数组类型	is_array([1,2,3]) → true
is_user_logged_in()	用户身份验证	is_user_logged_in() → true/false
username_exists($user)	用户名是否存在	username_exists('admin') → user_id 或 null
email_exists($email)	电子邮件是否存在	email_exists('[email protected]') → user_id 或 false

验证示例

电子邮件验证

$email = sanitize_email($_POST['email']);

// Validate format
if (!is_email($email)) {
    $errors[] = 'Invalid email address format';
}

// Validate uniqueness (for registration)
if (email_exists($email)) {
    $errors[] = 'Email address already registered';
}

数值范围验证

$age = absint($_POST['age']);

// Validate range
if ($age < 18 || $age > 100) {
    $errors[] = 'Age must be between 18 and 100';
}

// Validate positive number
if ($quantity <= 0) {
    $errors[] = 'Quantity must be greater than zero';
}

字符串长度验证

$username = sanitize_text_field($_POST['username']);

// Validate minimum length
if (strlen($username) < 3) {
    $errors[] = 'Username must be at least 3 characters';
}

// Validate maximum length
if (strlen($username) > 20) {
    $errors[] = 'Username cannot exceed 20 characters';
}

必填字段验证

// Check if field exists and is not empty
if (empty($_POST['title']) || trim($_POST['title']) === '') {
    $errors[] = 'Title is required';
}

// Alternative: isset() + non-empty check
if (!isset($_POST['terms']) || $_POST['terms'] !== 'accepted') {
    $errors[] = 'You must accept the terms and conditions';
}

模式匹配（正则表达式）

$phone = sanitize_text_field($_POST['phone']);

// Validate phone format (US format: (555) 123-4567)
if (!preg_match('/^\(\d{3}\) \d{3}-\d{4}$/', $phone)) {
    $errors[] = 'Phone must be in format: (555) 123-4567';
}

// Validate alphanumeric only
$product_code = sanitize_text_field($_POST['product_code']);
if (!preg_match('/^[a-zA-Z0-9]+$/', $product_code)) {
    $errors[] = 'Product code must contain only letters and numbers';
}

多字段验证

function validate_registration_form($data) {
    $errors = [];

    // Email validation
    $email = sanitize_email($data['email']);
    if (!is_email($email)) {
        $errors['email'] = 'Invalid email address';
    } elseif (email_exists($email)) {
        $errors['email'] = 'Email already registered';
    }

    // Username validation
    $username = sanitize_text_field($data['username']);
    if (strlen($username) < 3) {
        $errors['username'] = 'Username too short (minimum 3 characters)';
    } elseif (username_exists($username)) {
        $errors['username'] = 'Username already taken';
    }

    // Password validation
    if (strlen($data['password']) < 8) {
        $errors['password'] = 'Password must be at least 8 characters'; // pragma: allowlist secret
    }

    // Password confirmation
    if ($data['password'] !== $data['password_confirm']) {
        $errors['password_confirm'] = 'Passwords do not match'; // pragma: allowlist secret
    }

    // Age validation
    $age = absint($data['age']);
    if ($age < 18) {
        $errors['age'] = 'You must be 18 or older to register';
    }

    return empty($errors) ? true : $errors;
}

// Usage
$result = validate_registration_form($_POST);
if ($result === true) {
    // Process registration
} else {
    // Display errors
    foreach ($result as $field => $error) {
        echo "<p class='error'>$error</p>";
    }
}

自定义验证规则

// Validate URL is from allowed domain
function validate_allowed_domain($url) {
    $allowed_domains = ['example.com', 'wordpress.org'];
    $host = parse_url($url, PHP_URL_HOST);

    return in_array($host, $allowed_domains);
}

// Validate date format and range
function validate_date($date_string) {
    $date = DateTime::createFromFormat('Y-m-d', $date_string);

    if (!$date) {
        return false; // Invalid format
    }

    // Check date is not in the past
    $now = new DateTime();
    if ($date < $now) {
        return false;
    }

    return true;
}

// Validate credit card (Luhn algorithm)
function validate_credit_card($number) {
    $number = preg_replace('/\D/', '', $number); // Remove non-digits

    if (strlen($number) < 13 || strlen($number) > 19) {
        return false;
    }

    $sum = 0;
    $double = false;

    for ($i = strlen($number) - 1; $i >= 0; $i--) {
        $digit = (int) $number[$i];

        if ($double) {
            $digit *= 2;
            if ($digit > 9) {
                $digit -= 9;
            }
        }

        $sum += $digit;
        $double = !$double;
    }

    return ($sum % 10) === 0;
}

---

4. 输出转义参考

转义会在输出前对特殊字符进行编码，以防止 XSS（跨站脚本攻击）。这是最后一道安全防线。

核心转义函数

函数	上下文	转义内容	示例用法
esc_html()	HTML 内容	< > & " '	echo esc_html($user_input);
esc_attr()	HTML 属性	< > & " '	<input value="<?php echo esc_attr($value); ?>">
esc_url()	HTML href/src	危险协议	<a href="<?php echo esc_url($link); ?>">
esc_js()	JavaScript 字符串	' " \ /	<script>var msg = '<?php echo esc_js($message); ?>';</script>
esc_sql()	已弃用（请使用 $wpdb->prepare()）	SQL 特殊字符	❌ 请勿使用
esc_textarea()	文本区域内容	< > &	<textarea><?php echo esc_textarea($content); ?></textarea>

详细转义示例

HTML 内容转义

// Escape HTML content (converts special characters to entities)
$user_comment = "<script>alert('XSS')</script>Hello";
echo esc_html($user_comment);
// Output: &lt;script&gt;alert('XSS')&lt;/script&gt;Hello
// Browser displays: <script>alert('XSS')</script>Hello (as text, not code)

// WRONG: No escaping
echo $user_comment; // ⚠️ Executes JavaScript!

HTML 属性转义

// Escape attribute values
$title = 'My "Awesome" Title';
?>
<input type="text"
       value="<?php echo esc_attr($title); ?>"
       placeholder="<?php echo esc_attr($placeholder); ?>">



<input value="<?php echo $title; ?>">

URL 转义

// Escape URLs (blocks dangerous protocols)
$user_url = "javascript:alert('XSS')";
echo '<a href="' . esc_url($user_url) . '">Link</a>';
// Output: <a href="">Link</a> (javascript: protocol blocked)

// Safe URL
$safe_url = "https://example.com";
echo '<a href="' . esc_url($safe_url) . '">Link</a>';
// Output: <a href="https://example.com">Link</a>

// WRONG: No escaping
echo '<a href="' . $user_url . '">Link</a>'; // ⚠️ XSS vulnerability!

JavaScript 转义

// Escape JavaScript strings
$user_message = "It's \"dangerous\" to trust user input";
?>
<script>
    var message = '<?php echo esc_js($user_message); ?>';
    alert(message);
</script>



<script>
    var message = '<?php echo $user_message; ?>'; // ⚠️ Breaks JavaScript!
</script>

Textarea 转义

// Escape textarea content
$bio = "Line 1\nLine 2 <script>alert('XSS')</script>";
?>
<textarea><?php echo esc_textarea($bio); ?></textarea>



<textarea><?php echo esc_html($bio); ?></textarea>

特定上下文中的转义

HTML 上下文

// Paragraph content
echo '<p>' . esc_html($user_content) . '</p>';

// Link text
echo '<a href="' . esc_url($url) . '">' . esc_html($link_text) . '</a>';

// Image alt text
echo '<img src="' . esc_url($image_url) . '" alt="' . esc_attr($alt_text) . '">';

属性上下文

// Data attributes
echo '<div data-user-id="' . esc_attr($user_id) . '"
           data-username="' . esc_attr($username) . '"></div>';

// Class names (use sanitize_html_class)
echo '<div class="' . esc_attr(sanitize_html_class($class)) . '"></div>';

// Style attribute (dangerous - avoid if possible)
$safe_color = sanitize_hex_color($user_color); // Validate first
echo '<div style="color: ' . esc_attr($safe_color) . ';"></div>';

JavaScript 上下文

// Inline JavaScript (avoid if possible, use wp_localize_script instead)
<script>
    var config = {
        username: '<?php echo esc_js($username); ?>',
        apiUrl: '<?php echo esc_js(admin_url('admin-ajax.php')); ?>'
    };
</script>

// BETTER: Use wp_localize_script
wp_localize_script('my-script', 'myConfig', [
    'username' => $username, // Automatically JSON-encoded
    'apiUrl' => admin_url('admin-ajax.php'),
]);

国际化与转义

// Translate and escape
echo esc_html__('Welcome User', 'my-plugin');

// Translate with variable, then escape
$message = sprintf(
    __('Hello %s, you have %d new messages', 'my-plugin'),
    esc_html($username),
    absint($message_count)
);
echo $message;

// Escape translatable attributes
<input placeholder="<?php echo esc_attr__('Enter your name', 'my-plugin'); ?>">

// Allow HTML in translations (use wp_kses_post)
$welcome_html = __('Welcome to <strong>My Plugin</strong>!', 'my-plugin');
echo wp_kses_post($welcome_html);

常见转义错误

❌ 错误：

// Double-escaping (displays HTML entities to user)
echo esc_html(esc_html($content)); // ⚠️ Displays <script>

// Wrong function for context
echo '<a href="' . esc_html($url) . '">Link</a>'; // ⚠️ Use esc_url()

// No escaping in JavaScript
echo "<script>var x = '$user_input';</script>"; // ⚠️ Use esc_js()

// Escaping before storage (store raw, escape on output)
update_option('setting', esc_html($value)); // ⚠️ Escape on output, not input

✅ 正确：

// Escape once, on output
echo esc_html($content);

// Use correct function for context
echo '<a href="' . esc_url($url) . '">' . esc_html($text) . '</a>';

// Escape JavaScript properly
wp_localize_script('script', 'data', ['value' => $user_input]);

// Store raw, escape on output
update_option('setting', $value); // Store raw
echo esc_html(get_option('setting')); // Escape on output

---

5. 能力检查（授权）

能力检查可确保用户有权执行操作。务必与 nonce 验证结合使用。

内置能力

能力	描述	默认角色
read	查看内容	所有已登录用户
edit_posts	创建／编辑自己的文章	作者、编辑、管理员
edit_published_posts	编辑已发布的文章	编辑、管理员
delete_posts	删除自己的文章	作者、编辑、管理员
manage_options	管理站点设置	仅管理员
upload_files	上传媒体文件	作者、编辑、管理员
edit_users	编辑用户账户	仅管理员
delete_users	删除用户	仅管理员
install_plugins	安装／激活插件	仅管理员
switch_themes	更换主题	仅管理员

能力检查模式

基本能力检查

// Check if user is logged in
if (!is_user_logged_in()) {
    wp_die('You must be logged in to access this page');
}

// Check if user has capability
if (!current_user_can('manage_options')) {
    wp_die('You do not have permission to manage settings');
}

// Check if user can edit specific post
$post_id = absint($_GET['post_id']);
if (!current_user_can('edit_post', $post_id)) {
    wp_die('You cannot edit this post');
}

完整的安全示例

add_action('admin_post_update_settings', 'handle_settings_update');
function handle_settings_update() {
    // 1. Check if user is logged in
    if (!is_user_logged_in()) {
        wp_die('You must be logged in');
    }

    // 2. Verify nonce
    if (!isset($_POST['settings_nonce']) ||
        !wp_verify_nonce($_POST['settings_nonce'], 'update_settings')) {
        wp_die('Security check failed');
    }

    // 3. Check user capability
    if (!current_user_can('manage_options')) {
        wp_die('You do not have permission to update settings');
    }

    // 4. Sanitize input
    $api_key = sanitize_text_field($_POST['api_key']);
    $enable_feature = isset($_POST['enable_feature']) ? 1 : 0;

    // 5. Validate data
    if (strlen($api_key) < 10) {
        wp_die('API key must be at least 10 characters');
    }

    // 6. Update options
    update_option('my_plugin_api_key', $api_key);
    update_option('my_plugin_enable_feature', $enable_feature);

    // 7. Redirect with success message
    wp_redirect(add_query_arg('message', 'updated', wp_get_referer()));
    exit;
}

针对文章的能力

// Check if user can edit specific post
$post_id = absint($_POST['post_id']);
if (!current_user_can('edit_post', $post_id)) {
    wp_send_json_error(['message' => 'You cannot edit this post']);
}

// Check if user can delete specific post
if (!current_user_can('delete_post', $post_id)) {
    wp_send_json_error(['message' => 'You cannot delete this post']);
}

// Check if user can publish posts
if (!current_user_can('publish_posts')) {
    wp_send_json_error(['message' => 'You cannot publish posts']);
}

自定义能力

// Register custom role with custom capability
add_action('init', 'register_custom_role');
function register_custom_role() {
    add_role('store_manager', 'Store Manager', [
        'read' => true,
        'edit_posts' => true,
        'manage_products' => true, // Custom capability
    ]);
}

// Add custom capability to existing role
$role = get_role('editor');
$role->add_cap('manage_products');

// Check custom capability
if (current_user_can('manage_products')) {
    // Allow product management
}

---

6. SQL 注入防护

重要： 切勿在 SQL 查询中信任用户输入。务必使用 $wpdb->prepare()。

问题：SQL 注入

之前（存在漏洞）：

global $wpdb;

// ⚠️ CRITICAL VULNERABILITY - SQL INJECTION!
$user_id = $_GET['user_id'];
$results = $wpdb->get_results(
    "SELECT * FROM {$wpdb->posts} WHERE post_author = $user_id"
);

// Attacker can inject SQL:
// ?user_id=1 OR 1=1 -- (returns all posts)
// ?user_id=1; DROP TABLE wp_posts; -- (deletes table!)

之后（安全）：

global $wpdb;

// ✅ SECURE - Using prepared statements
$user_id = absint($_GET['user_id']); // Sanitize first
$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_author = %d",
        $user_id
    )
);

预处理语句占位符

占位符	类型	示例
%s	字符串	"SELECT * FROM table WHERE name = %s"
%d	整数	"SELECT * FROM table WHERE id = %d"
%f	浮点数	"SELECT * FROM table WHERE price = %f"

完整示例

SELECT 查询

global $wpdb;

$email = sanitize_email($_POST['email']);

// Prepared statement (prevents SQL injection)
$user = $wpdb->get_row(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->users} WHERE user_email = %s",
        $email
    )
);

if ($user) {
    echo "User found: " . esc_html($user->user_login);
}

INSERT 查询

global $wpdb;

// Use wpdb->insert() (automatically prepares)
$result = $wpdb->insert(
    $wpdb->prefix . 'my_table',
    [
        'title' => sanitize_text_field($_POST['title']),
        'content' => wp_kses_post($_POST['content']),
        'user_id' => absint($_POST['user_id']),
        'price' => floatval($_POST['price']),
        'created_at' => current_time('mysql'),
    ],
    ['%s', '%s', '%d', '%f', '%s'] // Format specifiers
);

if ($result === false) {
    wp_die('Database insert failed: ' . $wpdb->last_error);
}

$inserted_id = $wpdb->insert_id;

UPDATE 查询

global $wpdb;

$wpdb->update(
    $wpdb->prefix . 'my_table',
    [
        'title' => sanitize_text_field($_POST['title']), // New values
        'updated_at' => current_time('mysql'),
    ],
    ['id' => absint($_POST['id'])], // WHERE condition
    ['%s', '%s'], // Format for new values
    ['%d']        // Format for WHERE condition
);

DELETE 查询

global $wpdb;

$wpdb->delete(
    $wpdb->prefix . 'my_table',
    ['id' => absint($_POST['id'])],
    ['%d']
);

复杂 WHERE 子句

global $wpdb;

$status = sanitize_text_field($_POST['status']);
$min_price = floatval($_POST['min_price']);

// Multiple placeholders
$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->prefix}products
         WHERE status = %s AND price >= %f
         ORDER BY created_at DESC
         LIMIT %d",
        $status,
        $min_price,
        10 // LIMIT value
    )
);

常见 SQL 注入错误

❌ 错误：

// String concatenation (vulnerable!)
$sql = "SELECT * FROM table WHERE name = '" . $_POST['name'] . "'";

// Using esc_sql() (deprecated and insufficient)
$sql = "SELECT * FROM table WHERE name = '" . esc_sql($_POST['name']) . "'";

// Not using placeholders
$wpdb->query("DELETE FROM table WHERE id = $id"); // ⚠️ Vulnerable

✅ 正确：

// Always use $wpdb->prepare()
$wpdb->get_results($wpdb->prepare(
    "SELECT * FROM table WHERE name = %s",
    $_POST['name']
));

// Use wpdb methods (insert, update, delete)
$wpdb->insert('table', ['name' => $_POST['name']], ['%s']);

---

7. 常见漏洞与攻击场景

XSS（跨站脚本攻击）

攻击场景：

// Vulnerable code
echo "Welcome, " . $_GET['username'];
// Attacker visits: ?username=<script>alert(document.cookie)</script>
// Browser executes JavaScript, stealing session cookies

防护：

// Escape output
echo "Welcome, " . esc_html($_GET['username']);
// Output: Welcome, <script>alert(document.cookie)</script>

CSRF（跨站请求伪造）

攻击场景：

<img src="https://yoursite.com/wp-admin/admin.php?action=delete_all_posts">

防护：

// Require nonce verification
if (!wp_verify_nonce($_GET['nonce'], 'delete_all_posts')) {
    wp_die('Invalid security token');
}

SQL 注入

攻击场景：

// Vulnerable code
$wpdb->query("DELETE FROM posts WHERE id = " . $_GET['id']);
// Attacker visits: ?id=1 OR 1=1
// Deletes ALL posts!

防护：

// Use prepared statements
$wpdb->query($wpdb->prepare(
    "DELETE FROM posts WHERE id = %d",
    absint($_GET['id'])
));

文件上传攻击

攻击场景：

// Vulnerable code
move_uploaded_file($_FILES['file']['tmp_name'], 'uploads/' . $_FILES['file']['name']);
// Attacker uploads: malicious.php
// Executes: https://yoursite.com/uploads/malicious.php

防护：

// Validate file type and use wp_handle_upload()
$allowed_types = ['image/jpeg', 'image/png'];
if (!in_array($_FILES['file']['type'], $allowed_types)) {
    wp_die('Invalid file type');
}

$upload = wp_handle_upload($_FILES['file'], ['test_form' => false]);

路径遍历

攻击场景：

// Vulnerable code
include($_GET['template'] . '.php');
// Attacker visits: ?template=../../../../etc/passwd

防护：

// Whitelist allowed templates
$allowed_templates = ['template1', 'template2'];
$template = sanitize_file_name($_GET['template']);

if (in_array($template, $allowed_templates)) {
    include($template . '.php');
}

---

8. 完整的安全实现示例

<?php
/**
 * Secure Form Handling Example
 * Demonstrates all security layers: nonces, sanitization, validation, escaping
 */

// 1. Display Form (with nonce)
function display_user_profile_form() {
    $user_id = get_current_user_id();
    $user_data = get_user_meta($user_id, 'profile_data', true);

    ?>
    <form method="post" action="<?php echo esc_url(admin_url('admin-post.php')); ?>">
        <input type="hidden" name="action" value="update_user_profile">
        <?php wp_nonce_field('update_profile_' . $user_id, 'profile_nonce'); ?>

        <label>
            Display Name:
            <input type="text"
                   name="display_name"
                   value="<?php echo esc_attr($user_data['display_name'] ?? ''); ?>"
                   required>
        </label>

        <label>
            Email:
            <input type="email"
                   name="email"
                   value="<?php echo esc_attr($user_data['email'] ?? ''); ?>"
                   required>
        </label>

        <label>
            Bio:
            <textarea name="bio"><?php echo esc_textarea($user_data['bio'] ?? ''); ?></textarea>
        </label>

        <label>
            Website:
            <input type="url"
                   name="website"
                   value="<?php echo esc_attr($user_data['website'] ?? ''); ?>">
        </label>

        <button type="submit">Update Profile</button>
    </form>
    <?php
}

// 2. Process Form (with full security)
add_action('admin_post_update_user_profile', 'handle_profile_update');
function handle_profile_update() {
    // SECURITY LAYER 1: Authentication
    if (!is_user_logged_in()) {
        wp_die('You must be logged in to update your profile');
    }

    $user_id = get_current_user_id();

    // SECURITY LAYER 2: Nonce Verification
    if (!isset($_POST['profile_nonce']) ||
        !wp_verify_nonce($_POST['profile_nonce'], 'update_profile_' . $user_id)) {
        wp_die('Security check failed: Invalid nonce');
    }

    // SECURITY LAYER 3: Capability Check
    if (!current_user_can('edit_user', $user_id)) {
        wp_die('You do not have permission to update this profile');
    }

    // SECURITY LAYER 4: Sanitization
    $display_name = sanitize_text_field($_POST['display_name']);
    $email = sanitize_email($_POST['email']);
    $bio = sanitize_textarea_field($_POST['bio']);
    $website = esc_url_raw($_POST['website']);

    // SECURITY LAYER 5: Validation
    $errors = [];

    if (empty($display_name) || strlen($display_name) < 3) {
        $errors[] = 'Display name must be at least 3 characters';
    }

    if (!is_email($email)) {
        $errors[] = 'Invalid email address';
    }

    if (!empty($website) && !filter_var($website, FILTER_VALIDATE_URL)) {
        $errors[] = 'Invalid website URL';
    }

    if (!empty($errors)) {
        wp_die(implode('<br>', array_map('esc_html', $errors)));
    }

    // SECURITY LAYER 6: Process Data
    $profile_data = [
        'display_name' => $display_name,
        'email' => $email,
        'bio' => $bio,
        'website' => $website,
    ];

    update_user_meta($user_id, 'profile_data', $profile_data);

    // SECURITY LAYER 7: Safe Redirect
    wp_redirect(add_query_arg('message', 'profile_updated', wp_get_referer()));
    exit;
}

// 3. Display Success Message (with escaping)
add_action('admin_notices', 'show_profile_update_notice');
function show_profile_update_notice() {
    if (isset($_GET['message']) && $_GET['message'] === 'profile_updated') {
        echo '<div class="notice notice-success is-dismissible">';
        echo '<p>' . esc_html__('Profile updated successfully!', 'my-plugin') . '</p>';
        echo '</div>';
    }
}

---

9. 安全检查清单

对你实现的每项 WordPress 功能使用此检查清单：

输入安全（表单、AJAX、API）

• 已实现 nonce 验证（wp_verify_nonce()）
• 已执行能力检查（current_user_can()）
• 已使用适当的函数对所有输入进行清理
• 已根据业务逻辑验证所有输入
• 文件上传使用 wp_handle_upload()
• 使用文件类型白名单，而非黑名单

输出安全（模板、API）

• 所有动态内容均使用 esc_html()、esc_attr() 等进行转义
• URL 使用 esc_url() 转义
• JavaScript 变量使用 wp_localize_script() 或 esc_js()
• 不使用原始的 echo $_POST 或 echo $_GET

数据库安全

• 所有查询均使用 $wpdb->prepare()
• SQL 中不进行字符串拼接
• 使用 $wpdb->insert()、$wpdb->update()、$wpdb->delete()
• 表名使用 $wpdb->prefix

会话安全

• 已检查用户身份验证（is_user_logged_in()）
• 已验证用户角色（current_user_can()）
• 敏感操作要求重新进行身份验证
• 会话数据绝不存储在 GET 参数中

代码质量

• 不使用 eval()、assert() 或 create_function()
• 不对用户输入使用 extract()
• 错误消息不会泄露系统信息
• 在生产环境中禁用调试模式（WP_DEBUG = false）
• 在生产环境中无法访问 phpinfo() / var_dump() / print_r()（防止服务器信息泄露）
• 安全相关操作中没有空的 catch 代码块——应安全地拒绝操作并记录原因
• 对用户可控输入或访问控制输入使用的每个 switch 都有安全拒绝的 default

具有安全影响的代码质量缺陷： 在生产环境中遗留 phpinfo() 会泄露服务器内部信息；空的 catch 代码块会悄无声息地吞掉签名或功能权限检查失败的情况（导致默认放行）；没有 default 的 switch 会让意外输入未得到处理而直接跳过（CWE-478）。请参阅 PHP 质量反模式，了解符合要求和不符合要求的示例。这些模式源自 CAST Highlight 代码质量指标（https://doc.casthighlight.com/）。

---

10. 测试你的安全实现

手动测试清单

1. 测试 Nonce 过期：

# Generate form with nonce, wait 25 hours, submit
# Expected: "Security check failed" error

2. 测试 CSRF 防护：

<form action="https://yoursite.com/wp-admin/admin-post.php" method="POST">
    <input name="action" value="your_action">
    <button>Submit</button>
</form>

3. 测试 XSS 防护：

Input: <script>alert('XSS')</script>
Expected Output: &lt;script&gt;alert('XSS')&lt;/script&gt; (as text)

4. 测试 SQL 注入：

Input: 1 OR 1=1
Expected: Treats as literal string, no SQL execution

5. 测试功能权限绕过：

// Log in as subscriber (low-privilege user)
// Try to access admin-only features
// Expected: "You do not have permission" error

自动化安全测试

安装安全扫描器：

# WPScan (CLI tool)
gem install wpscan
wpscan --url https://yoursite.com --enumerate vp

# Sucuri Security Plugin
wp plugin install sucuri-scanner --activate

运行 PHP Code Sniffer：

# Check for security issues
vendor/bin/phpcs --standard=WordPress-Extra,WordPress-VIP-Go

---

11. 相关技能与资源

前置要求

• PHP 基础知识 - 了解 PHP 语法、类型和函数
• WordPress 插件基础知识 - 钩子、操作、过滤器和插件结构

进阶主题

• WordPress 测试与 QA - 以安全为重点的测试策略
• WordPress REST API - API 端点安全
• WordPress 性能 - 安全的缓存策略

外部资源

• WordPress 安全手册
• 插件安全最佳实践
• OWASP Top 10
• WordPress 插件安全测试

用于测试的安全插件

• Wordfence Security - 防火墙和恶意软件扫描器
• Sucuri Security - 安全审计和监控
• iThemes Security - 安全强化和监控

---

快速参考卡

// ============================================
// NONCES (CSRF Protection)
// ============================================

// Forms
wp_nonce_field('action_name', 'nonce_field_name');
wp_verify_nonce($_POST['nonce_field_name'], 'action_name');

// URLs
wp_nonce_url($url, 'action_name', 'nonce_param');
wp_verify_nonce($_GET['nonce_param'], 'action_name');

// AJAX
wp_create_nonce('ajax_action');
check_ajax_referer('ajax_action', 'nonce');

// ============================================
// SANITIZATION (Input Cleaning)
// ============================================

sanitize_text_field()    // Single-line text
sanitize_textarea_field()// Multi-line text
sanitize_email()         // Email addresses
esc_url_raw()           // URLs (for storage)
sanitize_file_name()    // File names
absint()                // Positive integers
wp_kses_post()          // HTML content

// ============================================
// VALIDATION (Logic Checks)
// ============================================

is_email($email)        // Valid email format
is_numeric($value)      // Numeric value
strlen($str) >= 3       // Minimum length
preg_match($pattern)    // Pattern matching
in_array($value, $allowed) // Whitelist check

// ============================================
// ESCAPING (Output Protection)
// ============================================

esc_html()              // HTML content
esc_attr()              // HTML attributes
esc_url()               // URLs (output)
esc_js()                // JavaScript strings
esc_textarea()          // Textarea content

// ============================================
// CAPABILITIES (Authorization)
// ============================================

is_user_logged_in()
current_user_can('capability')
current_user_can('edit_post', $post_id)

// ============================================
// SQL INJECTION PREVENTION
// ============================================

$wpdb->prepare("SELECT * FROM table WHERE id = %d", $id);
$wpdb->insert($table, $data, $format);
$wpdb->update($table, $data, $where, $format, $where_format);

---

请记住： 安全不是一项功能，而是一项要求。每一行处理用户输入或显示数据的代码都必须遵循这些原则。如有疑问，请先清理、验证并转义数据。