Skip to content

Plugin Configuration

Settings are on the pages of the Logystera menu in your WordPress admin: Credentials, Settings and the others described in the Admin Panel Reference.

Connection

Credentials are configured automatically when you use the Connect to Logystera button (see Installation). You can also enter them manually on the Credentials page.

Setting Description
Gateway URL Gateway endpoint. Leave as default unless self-hosting.
Entity Token Your entity's public token. Required.
Entity Secret Your entity's HMAC signing secret. Required. Never expose publicly.

To rotate credentials, use Rotate Credentials on the Credentials page — new credentials are delivered automatically.

Event Capture

Configure under Event Capture on the Settings page.

Setting Default Description
Collect On Enable/disable local event capture. When off, no events are written to the buffer.
Ingest On Enable/disable shipping to the gateway. When off, events stay local. Automatically disabled when Collect is off.

Delivery

Setting Default Description
Batch size 100 on new installs Events sent in one request to the gateway, from 50 to 1000. Larger batches mean fewer requests; smaller ones keep each request short on slow hosts.
Flush interval Every 5 minutes How often the scheduled send runs: every minute, 2, 5 or 15 minutes.

Batch Size and Flush Interval are disabled when Ingest is off.

Page visits only record events to a file on your server; sending happens on the scheduled run, or when you click Send Now (Flush Queue) on the Status page. With WordPress's built-in cron the scheduled run only happens when someone loads a page, so a quiet site may send later than the interval. With a system cron (DISABLE_WP_CRON) the interval is the minimum gap between sends and cannot be shorter than your host's cron schedule. See Setup and Sending.

Since 1.0.0, on servers that cannot finish a response before sending (typically Apache with mod_php), a send made at the end of a request is capped at about one second and one batch; anything left is delivered by the scheduled send.

Privacy

Setting Default Description
Anonymize IPs On Truncate IPs to /24 (IPv4) or /48 (IPv6) before sending.

When IP anonymization is enabled:

  • labels.actor.ip on every non-system signal is truncated (IPv4 → /24, IPv6 → /48).
  • payload.ip_hash on wp.rest.enumeration and wp.waf.event is hashed from that truncated address, not the raw IP. With the setting off, those hashes stay the raw-IP pseudonym (unsalted SHA-256 truncated to 16 hex chars — fleet-joinable, not irreversible for IPv4).
  • 203.0.113.42 → 203.0.113.0
  • 2001:db8:1234:5678::1 → 2001:db8:1234::

Usernames are always HMAC-SHA256 hashed. Whether the raw name is also sent is controlled by two independent settings in the Privacy group of Event Hooks below:

  • Readable attempted usernames (default on) — sends the name tried at a failed login, but only when WordPress confirms it belongs to a real account and the name contains no @. Turn this off to report only the hash and whether the account exists, never the raw name.
  • Readable e-mail logins (default off) — on a site where an account's own username is an email address, sends that address on user-lifecycle and file-edit events instead of the [email] placeholder. An ordinary (non-email) username on those events is sent readable either way.

The plugin integrates with the WordPress Privacy Policy guide via wp_add_privacy_policy_content(). When editing your site's Privacy Policy page, a suggested Logystera section is available in the policy guide sidebar.

Local history

The plugin can maintain a local MySQL history of events for review in the admin panel.

Setting Default Description
Enable Local Event History Off Store shipped events in MySQL for browsing on the Events page.
Max events 10,000 Maximum events stored locally. Gateway-managed — not user-editable.
Retention 7 days How long to keep history. Gateway-managed, read-only.

Tables created: wp_logystera_events and wp_logystera_gateway_logs (via dbDelta on enable). Tables are kept when the feature is disabled (data preserved for re-enabling). Use Wipe local history to permanently drop tables.

Event hooks

Individual signal groups are toggled on the Settings page, under Advanced settings → Event Hooks. Check all and Uncheck all change every hook at once; click Save Event Settings to apply. Hooks are organized into these groups:

Identity & Access

Hook Default Description
HTTP request tracking On Record requests that reach WordPress.
Firewall-blocked requests Off Record requests that end before WordPress finishes loading. Coverage depends on how the firewall is loaded; the Status page shows it for your site.
Wordfence block log Off Under Wordfence Extended protection, read the blocks Wordfence recorded in its own log (read-only).
Firewall security decisions On Record supported firewall decision events such as lockouts, blocks and throttles.
Sensitive file probes On Record when a request for a sensitive file (wp-config.php backups, debug.log, .env and similar) is answered with a 2xx instead of being blocked.
Login attempts On Track successful and failed logins. Essential for brute-force detection.
Logout events On Track explicit user logouts.
User signals On Track new user registrations and admin role changes.
Denied permission checks On Record when a logged-in user is refused a capability. A run of refusals on one account can show a privilege-escalation attempt.
REST API enumeration On Record requests to REST endpoints that list or look up users and other content, a common way to collect usernames before a login attack.
XML-RPC calls On Record one summary per XML-RPC request that got past login. Failed XML-RPC logins are covered by Login attempts.

Security

Hook Default Description
Content and comment changes On Record when published posts, pages or comments change: counts of links (including hidden ones), sizes, and who made the change (as a hash). The text itself never leaves your site. With this off, injected spam links in your content are not detected.

File Uploads

Hook Default Description
Blocked uploads On Track attempts to upload dangerous file types (.php, .exe, etc.).

Configuration & Supply Chain

Hook Default Description
Email signals On Track email send success and failure with metadata (recipient count, subject category).
Plugin/theme/core changes On Track plugin activations and deactivations, theme switches, and core, plugin and theme updates.
Vulnerability & update monitoring On Send a snapshot of installed plugins and themes with their versions, plus an administrator-account summary and configuration facts, about once a day. Known-vulnerability and outdated-software checks run against it.
Security-relevant option changes On Record changes to a fixed list of options an attacker has reason to change, such as site URL, admin email, open registration, the default role for new users and active plugins.
Theme file editor On Record each save attempt from the built-in theme file editor: which file, who saved it, content hashes and sizes, and whether the new code looks obfuscated.
Plugin file editor On The same for the built-in plugin file editor.

Traffic

Hook Default Description
Search queries On Track site search queries for top-searches analysis.

Health & Errors

Hook Default Description
Cron health On Track missed scheduled posts and overdue cron jobs.
File integrity On Detect changes to wp-config.php and .htaccess by hash comparison.
Plugin, theme and upload files Off Watch plugin, theme and uploads folders for PHP files that change or appear outside normal updates, and for executable files in uploads. Only file names, sizes and fingerprints are sent.
Environment snapshot On Report WordPress version, PHP version, plugin count and theme on each flush cycle.
Fatal errors On Capture PHP fatal errors. Essential for incident detection.
PHP warnings On Capture individual PHP warnings and notices with file, line and plugin attribution.
Database errors On Track $wpdb errors (deadlocks, connection failures, etc.).
Memory warnings On Alert when PHP memory usage exceeds 90% of the limit.
Webhook delivery results On Record the result of each webhook the Gravity Forms Webhooks add-on sends. Changes nothing on a site without that add-on.
Failed outbound requests On Record when a request this site makes to another server fails or times out. Only the destination host, the plugin that made the request and the kind of failure are sent.

Performance (Advanced)

Off by default. Enable with caution on shared hosting.

Hook Default Description
Hook timing Off Track execution time of WordPress hooks. Sampled at 10% of requests.
Cache statistics Off Track the object cache hit/miss ratio and backend type.
Slow queries Off Track database queries exceeding 500ms. Sampled at 10% of requests. Works best with SAVEQUERIES defined.
Agent overhead Off Measure the time and memory the plugin itself costs a request.
Hook circuit breaker Off Stop measuring a hook that keeps running long, so the measurement cannot become the cost.

Privacy

Hook Default Description
Anonymize IPs On Mask IPs before sending (see Privacy above).
Readable attempted usernames On Send the name tried at a failed login when it matches a real account. Off reports only a hash and whether the account exists, never the raw name.
Readable e-mail logins Off On a site where a username is itself an email address, send that address on account-lifecycle and file-edit events instead of [email]. Does not affect login attempts.

Visitor IP behind Cloudflare or another proxy

If your site sits behind Cloudflare (or another reverse proxy), the agent resolves each visitor's IP from REMOTE_ADDR by default — and Cloudflare's edge address is a normal, publicly routable IP, not an internal one. The agent doesn't trust X-Forwarded-For / X-Real-IP automatically in that case, on purpose: those headers are just as easy for a malicious visitor to set as for a real proxy, so trusting them without knowing a proxy actually sits in front of the site would let anyone claim to be any IP. The result, until you configure it: every visitor is recorded as one of a handful of Cloudflare addresses, and per-visitor detection (failed logins, brute-force, login anomalies) can't tell them apart.

Two wp-config.php constants control this:

Constant Type What it does
LOGYSTERA_TRUST_PROXY_HEADERS boolean When true, always trust X-Forwarded-For / X-Real-IP to resolve the visitor IP. Without it, the agent only trusts those headers when REMOTE_ADDR looks like an internal hop (a private/reserved address) — which a Cloudflare-fronted site never is.
LOGYSTERA_TRUSTED_PROXIES array or comma-separated string Extra proxy IPs to peel off the X-Forwarded-For chain, for setups with more than one hop in front of the site (your own load balancer in front of Cloudflare, for example). Exact-IP match only — no CIDR ranges. Not needed for a plain Cloudflare setup.

Before setting LOGYSTERA_TRUST_PROXY_HEADERS, lock your origin server so it only accepts traffic from Cloudflare's IP ranges. Without that, a client can bypass Cloudflare, connect to your origin directly, and forge the same headers itself — exactly the spoofing this setting is meant to avoid. Once the origin is locked, add:

// wp-config.php
define( 'LOGYSTERA_TRUST_PROXY_HEADERS', true );

To confirm it worked, open Logystera → Debug (the Debug page) and check the Client IP & Proxy card: it shows the resolved client IP, REMOTE_ADDR, the X-Forwarded-For chain with each hop classified, and whether headers are currently trusted, with a ✅ once the resolved IP matches the real visitor instead of a Cloudflare address. See Troubleshooting → All visitors show as the same few IP addresses if it's still wrong.

wp-config.php constants

A small number of settings can be set via wp-config.php constants. Constants take precedence over database settings.

Constant Description
LOGYSTERA_DEBUG Enable debug logging to wp-content/debug.log.
LOGYSTERA_GATEWAY_DEFAULT Override the default gateway URL (shown as default in the UI).
LOGYSTERA_FLUSH_BUDGET Time limit in seconds for a single cron flush run. Example: define('LOGYSTERA_FLUSH_BUDGET', 30.0);
LOGYSTERA_TRUST_PROXY_HEADERS Trust X-Forwarded-For / X-Real-IP for the visitor IP. See Visitor IP behind Cloudflare or another proxy above.
LOGYSTERA_TRUSTED_PROXIES Proxy IPs to peel from the X-Forwarded-For chain on multi-hop setups. See above.

WP-Cron dependency

The plugin uses WP-Cron for two scheduled tasks:

Cron hook Interval Purpose
logystera_flush_queue_event Every 5 minutes (configurable) Flush buffered events to gateway
logystera_agent_heartbeat_event Every 15 minutes Heartbeat check — missing heartbeat triggers an alert

If your server uses DISABLE_WP_CRON = true and runs WordPress cron externally, make sure your cron job calls wp-cron.php at least as often as your Flush interval; every minute is the usual choice. Setup and Sending shows how.