=== SOCHQ AI Log Agent ===
Contributors: cyberneticsplus
Tags: logging, webhook, telemetry, monitoring
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Lightweight agent that batches WordPress request telemetry and ships it via HTTPS to your webhook/SOCHQ for AI analysis and policy-driven blocking via your WAF.

== Description ==

**SOCHQ AI Log Agent** collects lightweight PHP/WordPress request telemetry (method, path, status, timing, and optional client traits) and periodically ships it as compact JSON batches to *your* HTTPS Webhook (typically a SOCHQ ingestion endpoint). Collection is non-blocking and scheduled (default: every 15 minutes) to keep overhead minimal.

This plugin by itself is a **telemetry forwarder**. The AI analysis and any blocking decisions happen in the **SOCHQ** platform after the batch is received.

### What the plugin does (on your WordPress site)
- **Collects request telemetry** for each PHP request: HTTP method, URI/path, status code, execution time, and optional fields (user-agent, referrer, client IP).
- **Buffers and batches** events locally, then **sends via HTTPS** to your configured Webhook at fixed intervals (default: 15 minutes using WP-Cron).
- **Fails safely**: undelivered batches are retried on the next run; sending pauses if the Webhook URL is cleared.
- **Minimal footprint**: only low-sensitivity fields are enabled by default; optional fields are configurable to fit your privacy policy.

> If you disable WP-Cron, set a server cron to call `wp-cron.php` so batching runs on schedule.

### How SOCHQ analyzes your telemetry (in the platform)
Once a batch lands in SOCHQ, your data flows through an **AI-driven pipeline**:

1. **Ingestion & Normalization**  
   Validate, deduplicate, and normalize fields (method, path, status, timings, UA, referrer, IP).

2. **Feature Extraction**  
   Time-window features (RPS, burstiness), path semantics (login/admin patterns, traversal markers), client traits (headless/bot indicators), and reputation (IP/ASN/geo anomalies).

3. **Detection (AI agents + rules)**  
   - **Anomaly detection** for spikes, rare paths, unusual method/status combos  
   - **Behavioral signatures** for brute-force/credential stuffing, directory enumeration, path traversal/LFI, CVE probing, noisy scraping  
   - **Correlation** across endpoints/sites/tenants (if enabled) to reveal coordinated campaigns

4. **Scoring & Triage**  
   Each IP/client/session receives a **risk score** with **explainable evidence** (top paths, error ratios, timings, matched signatures) so you can audit the “why”.

5. **Response & Blocking (optional integrations)**  
   SOCHQ can enforce policy via your controls:  
   - **WAF/CDN** (e.g., Cloudflare IP lists/rules)  
   - **Reverse proxy / NGINX** (managed deny lists)  
   - **App-level webhooks** back to your stack  
   Choose **monitor-only**, **challenge/rate-limit**, or **block**.

> **Note:** This plugin **does not** block on its own. Enforcement happens in your **WAF/proxy/firewall** via SOCHQ orchestration.

### What gets sent?
By default the agent aims to send **low-sensitivity** telemetry:
- Timestamp, HTTP method, request URI/path, response status code
- Execution time and memory hints (if available)
- A site identifier (non-PII, e.g., hashed home URL)
- **Optional (toggleable):** user-agent, referrer, client IP

Review configuration and your privacy obligations before enabling optional fields.

### Security & performance
- Outbound delivery is **HTTPS-only**.
- **Batched** delivery reduces overhead and network chatter.
- Collection is **non-blocking** and runs off the request path.

== Installation ==

1. Upload and activate the plugin.  
2. Go to **Settings → SOCHQ AI Log Agent** and enter your **HTTPS Webhook URL** (SOCHQ ingestion endpoint recommended).  
3. (Optional) Toggle extra fields (user-agent, referrer, client IP) as needed for your use case.  
4. Ensure **WP-Cron** is active; if disabled, set a system cron to call `wp-cron.php` so batches ship on schedule.

== Privacy ==

This plugin forwards request telemetry **from your site to your chosen HTTPS Webhook**. It does not store data in the WordPress database beyond transient buffers needed for batching.

**Default data categories**  
- Required: method, path, status, timing, timestamp, non-PII site identifier  
- Optional (you control): user-agent, referrer, client IP

**Controls**  
- Disable optional fields in the plugin settings to reduce data sensitivity.  
- Clear the Webhook URL to pause all outbound forwarding.  
- If WP-Cron is disabled, ensure a server cron triggers `wp-cron.php` so scheduled sends occur.

**Downstream processing in SOCHQ**  
- Data transmitted to SOCHQ is processed under your SOCHQ account configuration and retention settings.  
- SOCHQ uses the data to generate AI-assisted detections and to orchestrate enforcement via your connected WAF/proxy.  
- For DPA/agreements and retention specifics, refer to your SOCHQ plan settings and documentation.

**GDPR/PII guidance**  
- Avoid enabling client IP or other optional fields if you do not need them for security operations.  
- If enabled, ensure you have an appropriate legal basis and disclosures in your site’s privacy policy.

== Frequently Asked Questions ==

= Does this plugin block attacks by itself? =
No. It only forwards telemetry. **Blocking** happens via your connected **WAF/proxy/firewall** orchestrated by SOCHQ (e.g., Cloudflare IP lists/rules).

= What data is sent to SOCHQ? =
By default: method, path, status, timing, timestamp, and a non-PII site identifier. Optional fields (user-agent, referrer, client IP) can be enabled/disabled in settings.

= Will this affect site performance? =
Impact is minimal. Collection is non-blocking and events are **batched** for scheduled delivery (defaults to every 15 minutes).

= What if I have WP-Cron disabled? =
Set a system cron to call `wp-cron.php` at a regular interval so the batch job can run.

= Can I use a non-SOCHQ webhook? =
Yes. Any HTTPS endpoint that accepts JSON is supported. SOCHQ provides additional AI detections, correlated insights, and automated enforcement.

= How does SOCHQ decide to flag or block traffic? =
SOCHQ combines anomaly models, signature rules (e.g., brute force, enumeration, traversal/LFI), reputation, and correlation. Each finding includes a **risk score** and evidence. Enforcement policy (monitor/challenge/block) is your choice.

= How do I stop sending data? =
Clear the Webhook URL in the settings. The plugin will stop forwarding batches.

= Where do I see detections and blocks? =
Inside your SOCHQ dashboard (detections, scores, evidence) and in your connected control plane (e.g., Cloudflare IP lists/rules activity).

== Screenshots ==
1. Settings screen with Webhook URL and optional fields
2. Example JSON batch (redacted)

== Changelog ==
= 1.0.0 =
* Initial release of SOCHQ AI Log Agent
* Telemetry batching via HTTPS webhook
* Optional fields (user-agent, referrer, client IP)
* Documentation: Description, Privacy, FAQ