# WordPress

> Add Centinel Analytica to your WordPress website.

Source: https://docs.centinelanalytica.com/platforms/cms/wordpress

## Overview

This guide covers installing, configuring, and verifying the Centinel Analytica WordPress plugin. You'll upload the plugin ZIP, enter your keys, choose what to protect, and optionally gate uploads.

> **Get your keys first:** Go to the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
> and copy your **Site Key** and **Secret Key**.

## Prerequisites

* WordPress 5.6+ (tested up to 6.7) and PHP 8.0+
* Administrator access
* Ability to upload and activate plugins
* Server rewrite access if you enable uploads protection on nginx or IIS

## Install

1. **Download the plugin ZIP**

   [Download the WordPress plugin ZIP](https://docs.centinelanalytica.com/downloads/centinel-analytica-wordpress.zip). Keep it as a `.zip` file, don't unzip.

2. **Upload and activate the plugin**

   **WordPress Admin UI**

   1. Go to **Plugins → Add New**.
   2. Click **Upload Plugin**.
   3. Select the downloaded `centinel-analytica-wordpress.zip`.
   4. Click **Install Now**, then **Activate Plugin**.

   **WP-CLI**

   ```bash
   wp plugin install /path/to/centinel-analytica-wordpress.zip --activate
   ```

3. **Configure the plugin**

   Go to **Settings → Centinel Analytica** and fill in:

   * **Site Key** and **Secret Key** from your dashboard.
   * **Block Page URL** where blocked users land (default: `/block`).
   * **Apply protection to** the areas you want covered:
     * **Front-end pages**, **WP REST API**, **Login**, and optional **Uploads directory**.

   The Login option validates login attempts. It does not validate later requests to `/wp-admin/`.

   * **Uploads directory** protection routes `/wp-content/uploads/*` requests through the validator. Enable it only for gated downloads, premium PDFs, or media that needs bot protection.

   * **Included Paths** limits protection to specific paths (one per line, leave empty to protect everything). Supports wildcards: `/checkout`, `/api/*`, `/wp-login.php`.

   * **Excluded Paths** skips protection on matching paths (one per line, wins over included). Supports wildcards: `/api/webhook`, `/wp-content/uploads/*`, `*.jpg`.

   Click **Save Changes**.

   > **Tip:** Start with front-end, REST API, and login protection enabled. Add uploads protection only for folders that need static-file gating.

4. **Enable uploads protection (optional)**

   Turn on **Uploads directory** if you want Centinel to validate files under `/wp-content/uploads/*`.

   **Apache / LiteSpeed**

   On Apache or LiteSpeed, the plugin attempts to write the required `.htaccess` rewrite automatically when you save settings. If WordPress shows a warning, copy the `.htaccess` block from the settings panel into your site root `.htaccess` file.

   **nginx**

   Copy the nginx snippet from the settings panel into your server block, then reload nginx. The rewrite sends uploads requests to WordPress with `ca_uploads_file` so the plugin can validate and serve the file.

   **IIS**

   Copy the IIS rewrite rule from the settings panel into `<system.webServer><rewrite><rules>` in `web.config`, then reload the site.

   > **Uploads protection adds request overhead:** Every protected upload request boots WordPress and calls the validator. Use included paths to narrow protection to sensitive folders like `/wp-content/uploads/private/*`, and excluded paths to skip public images or thumbnails.

5. **Edit the block page (optional)**

   The plugin creates a `/block` page on activation. Edit it under **Pages → Access Blocked** whenever you want.

   > **Changing the URL:** Update **Block Page URL** in plugin settings to match the new permalink.

## Configure

### Script injection

On WordPress 6.3 and later, the plugin loads the [collector script](https://docs.centinelanalytica.com/install/scripts.md) in `<head>` with `async` on every front-end page and `wp-login.php`. On WordPress 5.6 through 6.2, WordPress loads the script in the footer. The plugin uses the Site Key from settings automatically. No manual script placement is needed.

A `whenCentinelReady(cb)` helper is injected after the script for theme developers who need to gate actions on collector readiness.

### Path rules

When both included and excluded paths are set:

1. Excluded match → skip (no validator call).
2. Included paths set but no match → skip.
3. Everything else → protect.

Excluded always wins over included.

### Uploads protection

The uploads toggle protects files under `/wp-content/uploads/*` by routing static-file requests through WordPress before the file is served. Included and excluded paths apply to the public uploads URL, so `/wp-content/uploads/private/*` can be protected while `/wp-content/uploads/cache/*` stays public.

The plugin serves allowed files with `Last-Modified`, `ETag`, and `Range` support so browsers can cache, resume, and stream PDFs, video, and audio. It rejects path traversal, null bytes, and script-like file extensions before validation.

If your WordPress install stores uploads outside the default location, developers can override the resolved base directory with the `centinel_uploads_basedir` filter.

### Decision handling

| Decision                | Front-end                                                                                 | REST API                                                                            | Login       | Uploads                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| `allow` / `not_matched` | Pass through                                                                              | Pass through                                                                        | Proceed     | Serve file                                                                        |
| `block`                 | Redirect to block page                                                                    | 403 JSON                                                                            | Login error | Block HTML or 403                                                                 |
| `redirect`              | Interstitial HTML when `response_html` is present. Otherwise, redirect to the block page. | HTML in JSON when `response_html` is present. Otherwise, return the block-page URL. | Login error | Challenge HTML when `response_html` is present. Otherwise, return a block status. |

## Verify

Browse your site and check **Centinel Analytica → Analytics** for incoming traffic.

## Changelog

* **v1.7.0** — Uploads directory protection
* **v1.6.1** — Response header passthrough
* **v1.6.0** — Login page script support
* **v1.5.0** — Wildcard path matching
* **v1.4.0** — Cookie forwarding
* **v1.3.0** — Auto-create block page
* **v1.2.0** — REST API protection
* **v1.1.0** — Configurable block page
* **v1.0.0** — Initial release