> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security & Privacy Configuration

> Configure data collection, filtering, and privacy settings for the WordPress plugin

## Privacy & Compliance

The plugin is designed to work with analytics while respecting user privacy:

* **No cookies**: Pure server-side implementation
* **No JavaScript**: No client-side tracking code
* **Data minimization**: Only HTTP metadata, no content
* **Automatic redaction**: Sensitive parameters removed
* **Public only**: Admin and user areas excluded

<Warning>
  Full IP addresses are collected as they are essential for accurate bot detection and traffic analysis. If your jurisdiction requires IP anonymization, additional configuration may be needed.
</Warning>

## Data Collection

The plugin collects standard HTTP request metadata from public pages:

### Required Fields

The following fields are **required** for every log entry sent to Agent Analytics:

| Field         | Format   | Max Length | Description                            |
| ------------- | -------- | ---------- | -------------------------------------- |
| `timestamp`   | ISO 8601 | -          | UTC timestamp of the request           |
| `method`      | String   | 10 chars   | HTTP method (GET, POST, etc.)          |
| `host`        | String   | 255 chars  | Request hostname                       |
| `path`        | String   | 2048 chars | URL path (without query string)        |
| `status_code` | Integer  | 100-599    | HTTP response status code              |
| `ip`          | String   | 45 chars   | Client IP address (supports IPv4/IPv6) |
| `user_agent`  | String   | 1024 chars | User agent string                      |

<Note>
  All required fields must be present for successful log ingestion. Missing fields will result in validation errors on the API side.
</Note>

### Optional Fields

These fields are included when available but not required:

| Field          | Format  | Max Length | Description                               |
| -------------- | ------- | ---------- | ----------------------------------------- |
| `query_params` | Object  | 100 keys   | Query string parameters (after redaction) |
| `referer`      | String  | 2048 chars | HTTP referer header                       |
| `bytes_sent`   | Integer | -          | Response size in bytes                    |
| `duration_ms`  | Integer | -          | Request processing time                   |

<Note>
  The plugin **does not** collect: page content, form data, WordPress user information, admin activity, database queries, or any server-side application data.
</Note>

## Automatic Path Filtering

### Always Excluded Paths

The following paths are **automatically excluded** from logging and cannot be overridden:

```
wp-admin         # All admin pages and subdirectories
wp-login.php     # Login page
wp-cron.php      # Cron jobs
admin-ajax.php   # Admin AJAX calls
xmlrpc.php       # XML-RPC interface
wp-json/wp/*     # WordPress core REST API
```

<Warning>
  These exclusions use substring matching, so they work regardless of WordPress installation directory (e.g., `/blog/wp-admin/` is also excluded).
</Warning>

### Request Type Exclusions

The plugin automatically skips:

* **Admin-referred requests**: Any request with a referer containing `wp-admin`
* **REST API calls**: Requests with `rest_route=/wp/*` query parameter
* **CLI operations**: WP-CLI commands
* **Edit context**: REST requests with `context=edit` parameter

### Path Filtering Priority

Paths are evaluated in this order:

1. **Built-in exclusions** (wp-admin, wp-login.php, etc.)
2. **Custom deny paths** (user-configured patterns)
3. **Referer check** (requests from wp-admin)
4. **REST API check** (WordPress core API)

First match wins - if any check matches, the request is excluded.

## Query Parameter Redaction

### Default Redacted Parameters

The following query parameter keys are automatically redacted (replaced with `[REDACTED]`):

```
password    # Password fields
pass        # Alternative password fields
token       # Authentication tokens
secret      # Secret keys
card        # Credit card fields
cc          # Credit card abbreviation
ssn         # Social security numbers
```

<Info>
  Redaction uses substring matching. Any parameter containing these strings will be redacted (e.g., `user_password`, `api_token`, `card_number`).
</Info>

### Redaction Example

Original query string:

```
?username=john&password=secret123&product=widget&api_token=abc123
```

After redaction:

```json theme={null}
{
  "username": "john",
  "password": "[REDACTED]",
  "product": "widget",
  "api_token": "[REDACTED]"
}
```

## Log Ingestion Token Security

### Storage Methods

The plugin supports three methods for Log Ingestion Token configuration, in order of security preference:

<Tabs>
  <Tab title="Environment Variable (Most Secure)">
    Add to your server environment:

    ```bash theme={null}
    WP_ENV_AGENT_ANALYTICS_API_KEY=bot_PROFOUND_LOG_INGESTION_TOKEN
    ```

    Or in `wp-config.php`:

    ```php theme={null}
    define('WP_ENV_AGENT_ANALYTICS_API_KEY', 'bot_PROFOUND_LOG_INGESTION_TOKEN');
    ```
  </Tab>

  <Tab title="WordPress Constant">
    Add to `wp-config.php`:

    ```php theme={null}
    define('AGENT_ANALYTICS_API_KEY', 'bot_PROFOUND_LOG_INGESTION_TOKEN');
    ```
  </Tab>

  <Tab title="Database (Encrypted)">
    Enter via WordPress admin. The key is:

    * Encrypted using Sodium library (if available)
    * Falls back to WordPress salts for encryption
    * Stored in `wp_options` table
    * Masked in UI (only last 4 characters shown)
  </Tab>
</Tabs>

<Warning>
  For production environments, use environment variables or constants. Database storage should only be used for testing or when file access is restricted.
</Warning>

## IP Address Handling

### Detection Order

The plugin attempts to detect the real client IP in this order:

1. `HTTP_X_FORWARDED_FOR` - First IP in the list (for proxies/load balancers)
2. `HTTP_CF_CONNECTING_IP` - Cloudflare's real IP header
3. `HTTP_X_REAL_IP` - Alternative proxy header
4. `HTTP_TRUE_CLIENT_IP` - Cloudflare Enterprise header
5. `REMOTE_ADDR` - Direct connection (fallback)

<Info>
  The plugin automatically handles reverse proxies used by managed WordPress hosts (WP Engine, Kinsta, etc.) and CDNs (Cloudflare, Fastly).
</Info>

### IP Privacy Considerations

* **No anonymization**: Full IP addresses are captured for accurate bot detection
* **Required for service**: IP data is essential for geographic analysis and reverse DNS lookups
* **GDPR compliance**: Consider your legal requirements for IP data collection

## Configuration Options

### General Settings

| Setting            | Default                                                 | Description                                 |
| ------------------ | ------------------------------------------------------- | ------------------------------------------- |
| **Enable Logging** | Off                                                     | Master switch for log collection            |
| **API Endpoint**   | `https://artemis.api.tryprofound.com/v1/logs/wordpress` | Destination for logs                        |
| **Batch Size**     | 500                                                     | Number of logs per send (50-1000)           |
| **Send Interval**  | 60 seconds                                              | How often to process queue (30-600 seconds) |

### Privacy Settings

| Setting               | Default                                  | Options              | Description                                   |
| --------------------- | ---------------------------------------- | -------------------- | --------------------------------------------- |
| **Skip Admin**        | On                                       | On/Off               | Exclude `/wp-admin/` requests                 |
| **Skip Cron**         | On                                       | On/Off               | Exclude cron job requests                     |
| **Skip AJAX**         | On                                       | On/Off               | Exclude admin AJAX calls                      |
| **Skip REST**         | Off                                      | On/Off               | Exclude ALL REST API requests (not just core) |
| **Redact Query Keys** | `password,pass,token,secret,card,cc,ssn` | Comma-separated list | Parameters to redact                          |

### Advanced Settings

| Setting                       | Default    | Description                                          |
| ----------------------------- | ---------- | ---------------------------------------------------- |
| **Custom Deny Paths**         | Empty      | Newline-separated path patterns (supports wildcards) |
| **Max Queue Size**            | 100,000    | Maximum logs to store before dropping old entries    |
| **Retention Days**            | 7          | Days to keep unsent logs                             |
| **Circuit Breaker Threshold** | 3          | Consecutive failures before pausing                  |
| **Circuit Breaker Cooldown**  | 30 minutes | Pause duration after threshold reached               |

## Custom Path Filtering

### Wildcard Pattern Examples

Add custom path exclusions using these patterns:

```
/private/*           # Exclude all paths starting with /private/
*/temp/*            # Exclude paths containing /temp/
*.pdf               # Exclude all PDF files
/api/v1/internal/*  # Exclude internal API endpoints
staging.*           # Exclude staging subdomains
```

## Data Retention

### Plugin-Side Retention

* **Queue entries**: Deleted after successful send
* **Failed entries**: Retried up to 6 times with exponential backoff
* **Old entries**: Auto-cleaned after retention period (default 7 days)
* **Maximum queue**: Oldest entries dropped when limit reached (100,000)

### API-Side Processing

* **Successful logs**: Processed immediately by Agent Analytics
* **Validation errors**: Logged but entry still deleted from queue
* **Authentication failures**: Queue paused, circuit breaker activated

## Performance Characteristics

<AccordionGroup>
  <Accordion title="Request Impact">
    * **Processing overhead**: \< 1ms per request
    * **Memory usage**: Minimal (single array per request)
    * **Database operations**: One INSERT per request
    * **No output buffering**: Does not delay response delivery
  </Accordion>

  <Accordion title="Background Processing">
    * **Send interval**: Every 60 seconds (configurable)
    * **Batch size**: Up to 500 logs per send (configurable)
    * **Timeout**: 5 second maximum per batch
    * **Queue limit**: 100,000 entries maximum
  </Accordion>

  <Accordion title="Reliability Features">
    * **Automatic retry**: Exponential backoff on failures
    * **Circuit breaker**: Pauses after 3 consecutive failures
    * **Queue persistence**: Logs preserved during outages
    * **Lock mechanism**: Prevents concurrent processing
  </Accordion>
</AccordionGroup>

## Security Best Practices

* Store Log Ingestion Tokens in environment variables rather than the database for production sites.

* Ensure all sensitive areas of your site are excluded from logging.

* Check the Status tab regularly to ensure logs are sending properly.

* Use the "Send Test Event" feature to verify connectivity without affecting real data.

* Ensure your WordPress site uses HTTPS to protect data in transit to your server.

<Note>
  If you discover any security issues or need assistance with configuration, please contact [support@tryprofound.com](mailto:support@tryprofound.com) immediately.
</Note>