Skip to content
Skills Library
Security · Building & coding

shortcode-block-security

/shortcode-block-security

Use when registering a shortcode with add_shortcode or a dynamic block with a render_callback, or processing shortcode / block attributes. Normalizes attributes with shortcode_atts, validates against allowlists, and escapes all rendered output for its context with esc_html, esc_attr, esc_url, or wp_kses_post. Prevents stored and reflected XSS in rendered content.

Licence
MIT
Last repository change
29.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
12
Deprecation

No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: references/secure-shortcode-block.php

What it does and when to use it

Use when registering a shortcode with add_shortcode or a dynamic block with a render_callback, or processing shortcode / block attributes. Normalizes attributes with shortcode_atts, validates against allowlists, and escapes all rendered output for its context with esc_html, esc_attr, esc_url, or wp_kses_post. Prevents stored and reflected XSS in rendered content.

Original author description

Use when registering a shortcode with add_shortcode or a dynamic block with a render_callback, or processing shortcode / block attributes. Normalizes attributes with shortcode_atts, validates against allowlists, and escapes all rendered output for its context with esc_html, esc_attr, esc_url, or wp_kses_post. Prevents stored and reflected XSS in rendered content.

How it works

  1. When to use this skill
  2. Core principles (and why they matter)
  3. Step-by-step implementation
  4. Common AI mistakes / anti-patterns
  5. Correct code examples
  6. Checklist
  7. Official references
Original SKILL.md headings · 192 lines, 912 words
SKILL.md preview
---
name: shortcode-block-security
description: >
  Use when registering a shortcode with add_shortcode or a dynamic block with a
  render_callback, or processing shortcode / block attributes. Normalizes
  attributes with shortcode_atts, validates against allowlists, and escapes all
  rendered output for its context with esc_html, esc_attr, esc_url, or
  wp_kses_post. Prevents stored and reflected XSS in rendered content.
compatibility: "Examples generally use PHP 7.4 syntax; check each API against target WordPress/PHP versions. Use maintained WordPress and supported PHP in production. Shell examples require their named tools."
license: MIT
metadata:
  tags: "wordpress, security, php, shortcode, block, xss, gutenberg"
---

# Shortcode & dynamic block security

## When to use this skill

Use this skill whenever code renders content from shortcodes or dynamic blocks:

- Registering a shortcode with `add_shortcode()`.
- Reading or outputting shortcode attributes (`$atts`) or enclosed content (`$content`).
- Registering a dynamic block with a `render_callback`.
- Reading block attributes in a server-side render.
- Building HTML, URLs, or classes from shortcode/block input.

Shortcodes and dynamic blocks are stored XSS sinks: a contributor enters `[my_card title="<script>..."]`
and the render callback echoes it unescaped. Every attribute must be sanitized and every output escaped.

Related: see the `output-escaping` skill for context-correct escaping and the
`gutenberg-block-editor-security` skill for broader block-editor surfaces.

## Core principles (and why they matter)

1. **`shortcode_atts()` sets defaults; it does NOT sanitize.** The returned array still holds
   raw user input. Sanitize each value before use.
2. **Block attributes are user input too.** Declaring `type: 'string'` in `block.json` does not
   escape HTML or JavaScript for you; sanitize on render.
3. **Escape at render for the exact context.** HTML body → `esc_html()`. HTML attribute →
   `esc_attr()`. URL → `esc_url()`. Rich HTML → `wp_kses_post()` with an allowlist.
4. **Do not store unescaped attribute values.** If you persist them, sanitize on save and escape
   on read.
5. **Never pass shortcode/block input to `do_shortcode()` or `eval()` uncontrolled.** Both can
   execute arbitrary shortcodes or code.
6. **Return, don't echo.** Shortcode and block render callbacks must return strings; echoing
   produces unexpected output placement.

## Step-by-step implementation

1. In the shortcode callback, call `shortcode_atts()` with a complete default map.
2. Sanitize each attribute to its expected type (`absint`, `sanitize_text_field`, `esc_url_raw`,
   `sanitize_key`).
3. In a block `render_callback`, read attributes from the `$attributes` array and sanitize them
   the same way.
4. Build the markup by concatenating escaped values.
5. Return the complete markup string.
6. For rich content, use `wp_kses_post()` or a tightly scoped `wp_kses()` allowlist.

### Supporting references

| Reference | Load when |
| --- | --- |
| [Shortcode & dynamic block security checklist](references/checklist.md) | Before final verification of the shortcode & dynamic block security controls. |
| [Secure shortcode and dynamic block](references/secure-shortcode-block.php) | Implementing shortcode and dynamic-block render callbacks with validated attributes and escaped markup. |

## Common AI mistakes / anti-patterns

### Mistake 1 — Echoing `$atts` directly

```php
// ❌ Insecure: stored XSS through the title attribute.
function my_plugin_card_shortcode( $atts ) {
    return '<div class="card"><h3>' . $atts['title'] . '</h3></div>';
}
```

```php
// ✅ Secure: default, then sanitize, then escape.
function my_plugin_card_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'title' => '',
            'link'  => '',
        ),
        $atts,
        'my_plugin_card'
    );

    $title = sanitize_text_field( $atts['title'] );
    $link  = esc_url_raw( $atts['link'] );

    $output = '<div class="card">';
    if ( $link ) {
        $output .= '<h3><a href="' . esc_url( $link ) . '">' . esc_html( $title ) . '</a></h3>';
    } else {
        $output .= '<h3>' . esc_html( $title ) . '</h3>';
    }
    $output .= '</div>';

    return $output;
}
```

### Mistake 2 — Trusting `shortcode_atts()` to sanitize

```php
// ❌ Insecure: shortcode_atts only supplies defaults and filters unknown keys.
$atts = shortcode_atts( array( 'class' => '' ), $atts );
echo '<div class="' . $atts['class'] . '">...</div>';
```

```php
// ✅ Secure: sanitize the value after normalizing it.
$atts  = shortcode_atts( array( 'class' => '' ), $atts, 'my_plugin_box' );
$class = sanitize_html_class( $atts['class'] );
echo '<div class="' . esc_attr( $class ) . '">...</div>';
```

### Mistake 3 — Dynamic block render callback echoing attributes

```php
// ❌ Insecure: block attributes echoed raw.
function my_plugin_render_banner( $attributes ) {
    ?>
    <div class="banner" style="background: <?php echo $attributes['bgColor']; ?>">
        <?php echo $attributes['heading']; ?>
    </div>
    <?php
}
```

```php
// ✅ Secure: sanitize attributes and escape for the output context.
function my_plugin_render_banner( $attributes ) {
    $bg_color = isset( $attributes['bgColor'] ) ? sanitize_hex_color( $attributes['bgColor'] ) : '#ffffff';
    $heading  = isset( $attributes['heading'] ) ? sanitize_text_field( $attributes['heading'] ) : '';

    return sprintf(
        '<div class="banner" style="background: %s"><h2>%s</h2></div>',
        esc_attr( $bg_color ),
        esc_html( $heading )
    );
}
```

### Mistake 4 — Allowing arbitrary HTML through attributes

```php
// ❌ Insecure: an attacker can inject script/event handlers.
function my_plugin_render_note( $attributes ) {
    return '<div>' . $attributes['content'] . '</div>';
}
```

```php
// ✅ Secure: constrain rich markup with wp_kses_post.
function my_plugin_render_note( $attributes ) {
    $content = isset( $attributes['content'] ) ? $attributes['content'] : '';
    return '<div>' . wp_kses_post( $content ) . '</div>';
}
```

### Mistake 5 — Running `do_shortcode()` on untrusted input

```php
// ❌ Insecure: executes arbitrary shortcodes supplied by a visitor.
echo do_shortcode( $_POST['content'] );
```

```php
// ✅ Secure: do not run do_shortcode on user input; if required, sanitize first.
$content = wp_kses_post( wp_unslash( $_POST['content'] ?? '' ) );
```

## Correct code examples

A complete secure shortcode and dynamic-block render callback is in
[`references/secure-shortcode-block.php`](references/secure-shortcode-block.php).

## Checklist

- [ ] `shortcode_atts()` provides defaults for every supported attribute.
- [ ] Each shortcode attribute is sanitized to its expected type after normalization.
- [ ] Block attributes are sanitized inside `render_callback`, not trusted from `block.json` types.
- [ ] All rendered output is escaped for its context (`esc_html`, `esc_attr`, `esc_url`, `wp_kses_post`).
- [ ] CSS classes use `sanitize_html_class()` (or `esc_attr()` with an allowlist).
- [ ] Colors use `sanitize_hex_color()` where appropriate.
- [ ] The callback returns a string; it does not echo directly.
- [ ] `do_shortcode()` is never run on untrusted input.

## Official references

- [`add_shortcode()`](https://developer.wordpress.org/reference/functions/add_shortcode/)
- [`shortcode_atts()`](https://developer.wordpress.org/reference/functions/shortcode_atts/)
- [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/)
- [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/)
- [`esc_html()`](https://developer.wordpress.org/reference/functions/esc_html/)
- [`esc_attr()`](https://developer.wordpress.org/reference/functions/esc_attr/)
- [`esc_url()`](https://developer.wordpress.org/reference/functions/esc_url/)
- [`wp_kses_post()`](https://developer.wordpress.org/reference/functions/wp_kses_post/)
- [`sanitize_html_class()`](https://developer.wordpress.org/reference/functions/sanitize_html_class/)
- [`sanitize_hex_color()`](https://developer.wordpress.org/reference/functions/sanitize_hex_color/)
- [Shortcode API — Plugin Handbook](https://developer.wordpress.org/plugins/shortcodes/)
- [Block Editor Handbook](https://developer.wordpress.org/block-editor/)
Files in this package (3)
  • SKILL.md 8 KB
  • references/checklist.md 1 KB
  • references/secure-shortcode-block.php 3 KB

Versions

The database has no other skills named shortcode-block-security.

Database snapshot: 13.11.2026 · package version 1adc22ca94b1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100gutenberg-block-editor-security
    Use when building dynamic blocks or block-editor features - a render_callback, server-side rendered blocks via ServerSideRender, REST-backed block data, or register_rest_field for the editor. Sanitizes block attributes per type, escapes server render output, sets a real…
  • 100output-escaping
    Use when echoing or printing any dynamic value in WordPress PHP or templates — into HTML, attributes, URLs, inline JavaScript, or textareas. Escapes at the point of output with esc_html, esc_attr, esc_url, esc_js, esc_textarea, or wp_kses_post, including the i18n variants…
  • 100xss-prevention
    XSS attack prevention with input sanitization, output encoding, Content Security Policy. Use for user-generated content, rich text editors, web application security, or encountering stored XSS, reflected XSS, DOM manipulation, script injection errors.
  • 100orchardcore-shortcodes
    Skill for creating and using shortcodes in Orchard Core. Covers shortcode template creation via admin UI, the ShortcodeTemplates recipe step and deployment step, the ManageShortcodeTemplates permission, code-based shortcode providers using delegate and class patterns, built-in…
  • 100wpml-compatibility-audit
    Audit whether a WordPress plugin or classic theme is WPML-compatible end to end. Use when asked "is this plugin WPML compatible?", "why does this shortcode/string/page not translate?", or when code has wpml-config.xml, stored page/product/term IDs, get_permalink/home_url,…
  • 100verify
    Run the Navidrome website locally and check a change in a real browser. Use to verify layout, shortcode, content, or apps-catalog changes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.