101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# WP Guard — Security Reference
|
|
|
|
## Contents
|
|
|
|
- Escaping: context → function
|
|
- Sanitization: input type → function
|
|
- The unslash-then-sanitize order
|
|
- Nonce + capability lifecycle
|
|
- REST API permissions
|
|
- $wpdb->prepare details
|
|
- File uploads
|
|
- Common AI-generated violations
|
|
|
|
## Escaping: context → function
|
|
|
|
Escape at the moment of output, with the function matching the destination context:
|
|
|
|
| Output context | Function |
|
|
|---|---|
|
|
| HTML body text | `esc_html()` |
|
|
| HTML attribute | `esc_attr()` |
|
|
| URL (href/src/action) | `esc_url()` (display) / `esc_url_raw()` (storage/redirects) |
|
|
| Data for inline JS | `wp_json_encode()` + `wp_add_inline_script()`; `esc_js()` is legacy — single-quoted strings in inline attributes only |
|
|
| Textarea content | `esc_textarea()` |
|
|
| Rich/user HTML | `wp_kses_post()` or `wp_kses()` with an explicit allowlist |
|
|
| Translation + output | `esc_html__()`, `esc_html_e()`, `esc_attr__()` — escape and translate in one call |
|
|
|
|
Trust nothing at output time — not even your own stored options; another plugin or a compromised import may have written them. "Escaped on save" is not a defense.
|
|
|
|
## Sanitization: input type → function
|
|
|
|
| Expected input | Function |
|
|
|---|---|
|
|
| Plain text line | `sanitize_text_field()` |
|
|
| Multiline text | `sanitize_textarea_field()` |
|
|
| Integer / ID | `absint()` or `intval()` |
|
|
| Slug/key | `sanitize_key()` / `sanitize_title()` |
|
|
| Email | `sanitize_email()` + `is_email()` check |
|
|
| URL | `esc_url_raw()` |
|
|
| HTML payload | `wp_kses_post()` / `wp_kses()` |
|
|
| File name | `sanitize_file_name()` |
|
|
| Anything enumerable | strict allowlist comparison (`in_array( $v, $allowed, true )`) |
|
|
|
|
## The unslash-then-sanitize order
|
|
|
|
WordPress adds slashes to superglobals. The correct pipeline is always:
|
|
|
|
```php
|
|
$status = sanitize_key( wp_unslash( $_POST['ncs_status'] ?? '' ) );
|
|
```
|
|
|
|
`wp_unslash()` first, sanitizer second. Sanitizing slashed data corrupts legitimate input and hides bugs.
|
|
|
|
## Nonce + capability lifecycle
|
|
|
|
Both checks, always, for any state change. They answer different questions:
|
|
|
|
- `current_user_can( 'manage_options' )` — is this user *allowed* to do this? (authorization)
|
|
- `check_admin_referer( 'ncs_save_settings' )` / `check_ajax_referer( 'ncs_action', 'nonce' )` — did this request *intend* this action? (CSRF protection)
|
|
|
|
A nonce without a capability check lets any logged-in subscriber fire admin actions. A capability check without a nonce leaves CSRF open. AI-generated handlers routinely have one, the other, or neither — verify both exist on every `admin_post_*`, `wp_ajax_*`, and form handler.
|
|
|
|
Generate nonces with `wp_nonce_field()` (forms) or `wp_create_nonce()` (AJAX/REST payloads). Nonces are per-user and time-limited; do not cache pages containing them.
|
|
|
|
## REST API permissions
|
|
|
|
- Every route registers a real `permission_callback`. `__return_true` is acceptable only for genuinely public read-only data — never for writes.
|
|
- Validate and sanitize via the route's `args` schema (`validate_callback`, `sanitize_callback`) instead of manual checks inside the handler.
|
|
- Cookie-authenticated REST requests require the `X-WP-Nonce` header (`wp_rest` nonce); custom auth schemes must fail closed.
|
|
|
|
## $wpdb->prepare details
|
|
|
|
```php
|
|
$row = $wpdb->get_row(
|
|
$wpdb->prepare(
|
|
"SELECT * FROM {$wpdb->prefix}ncs_log WHERE user_id = %d AND event = %s",
|
|
$user_id,
|
|
$event
|
|
)
|
|
);
|
|
```
|
|
|
|
- Placeholders: `%s`, `%d`, `%f`; `%i` for table/column identifiers (WP ≥ 6.2).
|
|
- `IN ( … )` lists: build placeholders dynamically — `implode( ',', array_fill( 0, count( $ids ), '%d' ) )` — then prepare with the spread array.
|
|
- LIKE queries: `$wpdb->esc_like()` the term *before* passing it as a `%s` parameter.
|
|
- Never interpolate `$_REQUEST` data anywhere near SQL, even "validated" data.
|
|
- Prefer `WP_Query`, `get_posts()`, meta/term/option APIs when they can express the query — they bring caching for free.
|
|
|
|
## File uploads
|
|
|
|
Use `wp_handle_upload()` / media APIs — never move `$_FILES` manually. Validate type with `wp_check_filetype_and_ext()` against an allowlist; never trust the client MIME. Store outside executable paths; WordPress handles this when you use its APIs.
|
|
|
|
## Common AI-generated violations
|
|
|
|
1. `echo '<div>' . $title . '</div>';` — unescaped output (Rule 1). Published research: XSS appears in 86% of AI generations tested on XSS-prone tasks (see [sources.md](sources.md)).
|
|
2. `wp_ajax_` handler with neither `check_ajax_referer()` nor `current_user_can()` (Rule 3).
|
|
3. `"SELECT * FROM {$wpdb->posts} WHERE post_title = '$title'"` — interpolated SQL (Rule 4).
|
|
4. `permission_callback => '__return_true'` on a POST route (Rule 3).
|
|
5. `curl_init()` inside a plugin (Rule 5) — breaks proxies, blocks, and filters that `wp_remote_*` honors.
|
|
6. Echoed `<script>` blocks with interpolated PHP — combines Rules 1 and 5; use `wp_enqueue_script()` + `wp_add_inline_script()`/`wp_localize_script()`.
|