=== Aegisify Audit Agent ===
Contributors: Aegisify
Tags: wordpress security, audit, phpcs, wpcs, telemetry
Requires at least: 6.0
Tested up to: 6.9
Stable tag: 1.9.13
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Local WordPress security agent for Aegisify Audit SaaS with inventory, telemetry, and PHPCS/WPCS code findings.

Know about your security flaws before hackers do.

This agent is not meant to operate as a completely standalone scanner. It is designed to work with an active Aegisify Audit SaaS account, a verified domain, and an encrypted agent key issued from the Aegisify dashboard.

Signing up to Aegisify is easy, go to https://aegisify.com to do a real public scan or Subscribe a paid subscription at https://aegisify.com/secure-audit/subscribe/.

== Description ==

Aegisify Audit Agent is built for WordPress security professionals, agencies, developers, and site owners who want reporting, validation, and follow-up.

Why security experts use Aegisify:

- Centralized SaaS visibility for WordPress security operations.
- Encrypted agent-to-SaaS connectivity tied to a verified domain.
- Local WordPress inventory and host-aware findings.
- Local Deep Code Analysis using bundled PHPCS + WPCS.
- Metadata-only telemetry controls so customer content is not transmitted.
- Cached findings, escalations, remediated states, and filtered review in wp-admin.
- A stronger way to identify weaknesses before attackers do.

Core capabilities in this build:

- Encrypted connectivity to Aegisify Audit SaaS over HTTPS.
- Domain-aware verification against aegisify.com.
- Local WordPress inventory collection.
- Hardening, malware, permission, diff, inventory, and correlation scans.
- Deep Code Analysis with bundled PHPCS + WPCS and Aegisify custom sniffs.
- Optional local Wordfence CLI integration when available on the host.
- Optional local compliance rule support.
- Telemetry access control with category-level allow/block settings.
- Detailed Findings screen with filters, escalations, remediated tracking, and cached results.

Privacy model:

This agent is designed around metadata-only reporting for telemetry and SaaS synchronization. It is intended to avoid sending customer content such as post bodies, comments, order contents, usernames, emails, secrets, tokens, API keys, and raw database row content.

== Installation ==

1. In WordPress admin, go to Plugins > Add New > Upload Plugin.
2. Upload the Aegisify Audit Agent ZIP package and install it.
3. Activate the plugin.
4. In wp-admin, open Aegisify Audit Agent from the left menu.
5. Confirm your WordPress site is served over HTTPS and that the server can make outbound HTTPS requests.
6. Make sure you already have an Aegisify Audit SaaS account and that the target domain has been set up in the SaaS dashboard.
7. Copy the long Encryption / Security Key from the Aegisify Audit SaaS Agent Details panel.
8. Paste the key into the Aegisify Audit Agent screen.
9. Click Save Encryption Key.
10. Click Connect to verify the encrypted connection to Aegisify Audit SaaS.
11. After the connection is verified, configure telemetry and local scan settings as needed.
12. Use Scan Now to run the local agent scan workflow.

== Feature Configuration Instructions ==

= 1. Encryption Key and Connection =

- Open wp-admin > Aegisify Audit Agent.
- Paste the long encryption/security key from your Aegisify Audit SaaS Agent Details panel.
- Click Save Encryption Key.
- Click Connect.
- The status indicator should confirm that the agent is connected and the verified domain matched successfully.
- Use Disconnect if you need to revoke the current local connection state.

Important:
- The agent validates SaaS connections specifically against aegisify.com over SSL/HTTPS.
- The domain in the key payload must match the local WordPress site.
- The domain must already be verified in the Aegisify Audit SaaS dashboard.
- If the domain is not verified or the key is invalid, the connection will be blocked.

= 2. Telemetry Access Control =

The Telemetry Access Control card lets you decide whether the agent is allowed to push metadata-only telemetry to Aegisify Audit SaaS.

Enable or disable:
- Metadata-only telemetry push to SaaS.
- Category-level telemetry access.

Telemetry categories in this build include:
- Plugin, theme, and WordPress core version metadata.
- Integrity hashes for selected landmark files.
- Admin and user inventory counts by role.
- Cron and scheduled event inventory.
- Backup and restore telemetry markers.
- Snapshot diffs.
- File drift timeline.
- Privileged configuration states.

The intent is to support defensive visibility without sending customer content.

Recommended setup:
- Leave telemetry disabled until you have validated your privacy requirements.
- Then enable only the categories you want Aegisify SaaS to consume.
- Save the Telemetry Policy after changes.

= 3. Detailed Findings and Workflow =

The Detailed Findings screen provides:
- Local scan execution status.
- Plugin selection for static code analysis scope.
- Cached findings filters by severity and plugin.
- Escalated findings for follow-up.
- Remediated findings tracking.
- Sorting and pagination for finding review.

Finding workflow actions include:
- Escalate.
- Ignore.
- Remediated.
- Delete saved action state.
- Override severity for triage review.

Recommended workflow:
- Run a scan.
- Filter the findings by severity or plugin.
- Escalate important items that require follow-up.
- Mark resolved items as remediated after verification.

== Encrypted Connectivity Instructions to Aegisify Audit SaaS ==

Aegisify Audit Agent requires an active Aegisify SaaS relationship to function properly.

If you do not already have an account:
- Go to https://aegisify.com to run a real public scan.
- Or subscribe at https://aegisify.com/secure-audit/subscribe/ for a paid Aegisify Audit subscription.

To connect the agent:

1. Sign in to your Aegisify Audit SaaS account.
2. Add or verify the WordPress domain inside the SaaS dashboard.
3. Open the Agent Details panel in Aegisify Audit SaaS.
4. Copy the long encryption/security key.
5. In the WordPress site running this plugin, open wp-admin > Aegisify Audit Agent.
6. Paste the key into the key field.
7. Click Save Encryption Key.
8. Click Connect.
9. Wait for the connection status to confirm verification.

What the agent is checking:
- The destination host in the key is aegisify.com.
- The request is made over HTTPS with SSL verification enabled.
- The verified domain returned by SaaS matches the current WordPress home URL.
- The key and site are accepted by the Aegisify Audit SaaS verification endpoint.

If connection is not verified:
- Re-check that the site URL matches the verified domain in SaaS.
- Confirm the key was copied fully with no missing characters.
- Confirm the site can reach aegisify.com over outbound HTTPS.
- Confirm the site itself is configured correctly for HTTPS.
- Re-save the key and retry Connect.

Important operating note:
- Scan Now is disabled until the agent has an active encrypted and verified connection to Aegisify Audit SaaS.

== Local Scanning with PHPCS and How It Works ==

Deep Code Analysis in this build uses bundled PHPCS + WPCS locally on the WordPress host.

How it works:

1. You select which installed plugins to include in the static code analysis scope.
2. You click Scan Now in the agent admin screen.
3. The agent first checks for an active encrypted and verified SaaS connection.
4. If the connection is verified, the scan is queued and run in the background.
5. The agent builds a local report that includes multiple security checks and cached findings.
6. PHPCS + WPCS are executed locally for Deep Code Analysis.
7. The resulting findings are normalized into the agent report and shown in the Detailed Findings table.
8. Aegisify SaaS can then consume the approved metadata and connection-backed results for the broader dashboard and workflow experience.

Important requirement:
- Even though PHPCS runs locally, this build still requires a verified SaaS connection before manual scanning is allowed.

What the local code analysis covers:
- Bundled PHPCS + WPCS for WordPress coding standard and code security analysis.
- Aegisify custom sniff support layered into the local analysis model.
- Cached local findings by file, line, type, rule/code, severity, and plugin.
- Review filters for severity and plugin scope.

Host capability notes:
- PHPCS runtime support depends on the host PHP environment.
- The host should support subprocess execution.
- The tokenizer, xmlwriter, and SimpleXML PHP extensions should be available.
- The temporary directory should be writable.

Optional local tooling:
- Wordfence CLI can be used when available on the host for local vulnerability validation.
- Composer audit and pip-audit can support manifest-driven dependency visibility when available.

== Why a WordPress Security Expert Would Need Aegisify ==

WordPress security is not just about installing a firewall or running a one-time scan. Real-world WordPress defense requires visibility into configuration, code quality, plugin risk, permissions, drift, malware indicators, and operational change over time.

Aegisify helps by combining:
- Local agent awareness on the actual WordPress site.
- Encrypted SaaS-backed validation and centralized security workflow.
- Cached findings and remediation review inside wp-admin.
- Broader SaaS oversight for real public scanning, subscription-backed features, and a security operations view.

For security professionals, this means you can:
- Catch weaknesses early.
- Validate the local WordPress environment before attackers abuse it.
- Reduce blind spots between local code issues and SaaS-level reporting.
- Review findings in a more actionable way.
- Know about your security flaws before hackers do.

== Troubleshooting ==

= The agent will not connect =
- Verify the site is on HTTPS.
- Verify the domain is already verified in Aegisify Audit SaaS.
- Verify the encryption key belongs to this exact site/domain.
- Verify outbound HTTPS requests to aegisify.com are allowed.

= Scan Now is disabled =
- The agent connection has not been verified yet.
- Reconnect the agent and confirm the verified status first.

= Deep Code Analysis does not return results =
- Check that the selected plugins actually contain PHP or JavaScript source files.
- Check that subprocess execution is available on the host.
- Check that tokenizer, xmlwriter, and SimpleXML are enabled in PHP.
- Check that the temporary directory is writable.


== Changelog ==

= 1.9.1 =
- Readme prepared for encrypted SaaS connectivity, telemetry controls, and local PHPCS/WPCS-based Deep Code Analysis.
