diagnostic-version-audit

Diagnostic: Version & Compatibility Audit

You perform comprehensive version auditing for WordPress installations to identify outdated software, compatibility issues, and available updates. This diagnostic uses WP-CLI commands executed over SSH and WordPress.org API queries — no external API keys required.

Overview

This skill checks four critical version areas:

1. WordPress Core Version — Current version vs. available updates
2. PHP Version — Runtime version vs. security support status
3. MySQL/MariaDB Version — Database version vs. compatibility recommendations
4. Plugin & Theme Updates — Outdated extensions vs. available updates with compatibility checks

How It Works

Prerequisites

Before running checks, you need:

• Site connection profile from sites.json (loaded by CoWork)
• SSH access credentials (user, host, SSH key)
• WordPress path on remote server
• WP-CLI path on remote server (or indication that it's unavailable)

If WP-CLI is not available, return a single Warning finding and skip WP-CLI-dependent checks.

Check 1: WordPress Core Version

Command:

ssh {user}@{host} "cd {wp_path} && {wp_cli_path} core version"

Parse output: Extract version number (e.g., "6.4.3")

Check for updates:

ssh {user}@{host} "cd {wp_path} && {wp_cli_path} core check-update --format=json"

Response format:

[
  {
    "version": "6.5.0",
    "update_type": "major",
    "package_url": "https://downloads.wordpress.org/release/wordpress-6.5.0.zip"
  }
]

Empty array = no updates available.

Severity Logic:

• Update available with "update_type": "major" → Critical (major version updates often include security fixes)
• Update available with "update_type": "minor" → Warning (minor updates, bug fixes)
• No update available → Info (document current version for reference)

Finding ID Format: DIAG-VERSION-{3-char-md5-of-"wordpress-core"}

Example Finding (Update Available):

{
  "id": "DIAG-VERSION-a1b",
  "severity": "Critical",
  "category": "Version & Compatibility",
  "title": "WordPress core update available",
  "summary": "Your WordPress version is outdated. A newer version with security and bug fixes is available.",
  "detail": "Current version: 6.4.3. Available version: 6.5.0 (major update). Major updates often include critical security patches.",
  "location": "WordPress Core",
  "fix": "Update via WP-CLI: `wp core update` or use WordPress admin dashboard (Dashboard > Updates)."
}

Example Finding (Up to Date):

{
  "id": "DIAG-VERSION-a1b",
  "severity": "Info",
  "category": "Version & Compatibility",
  "title": "WordPress core is up to date",
  "summary": "Your WordPress installation is running the latest version.",
  "detail": "Current version: 6.5.0. No updates available.",
  "location": "WordPress Core",
  "fix": "No action required."
}

Check 2: PHP Version

Command:

ssh {user}@{host} "php -v"

Parse output: Extract version number from first line (e.g., "PHP 8.2.10...")

Version Support Status (as of 2026):

• PHP < 7.4: Critical — End of security support
• PHP 7.4: Critical — End of security support (November 2022)
• PHP 8.0: Warning — End of security support (November 2023)
• PHP 8.1: Info — Active support until November 2024, security support until November 2025
• PHP 8.2+: Info — Actively supported

Finding ID Format: DIAG-PHP-{3-char-md5-of-php-version}

Example Finding (Outdated):

{
  "id": "DIAG-PHP-c3d",
  "severity": "Critical",
  "category": "Version & Compatibility",
  "title": "PHP version is end-of-life",
  "summary": "Your PHP version no longer receives security updates, putting your site at risk.",
  "detail": "Current PHP version: 7.4.33. This version reached end of life in November 2022. Security vulnerabilities discovered after this date will not be patched.",
  "location": "Server PHP Runtime",
  "fix": "Contact your hosting provider to upgrade PHP to version 8.1 or higher. Test your site on a staging environment first, as some plugins may require updates for compatibility."
}

Example Finding (Current):

{
  "id": "DIAG-PHP-c3d",
  "severity": "Info",
  "category": "Version & Compatibility",
  "title": "PHP version is current",
  "summary": "Your PHP version is actively supported with security updates.",
  "detail": "Current PHP version: 8.2.10. This version receives active support and security updates.",
  "location": "Server PHP Runtime",
  "fix": "No action required."
}

Check 3: MySQL/MariaDB Version

Command:

ssh {user}@{host} "cd {wp_path} && {wp_cli_path} db version"

Parse output: Extract database type and version (e.g., "mysql Ver 8.0.35" or "MariaDB 10.6.16")

Version Compatibility:

• MySQL < 5.7 or MariaDB < 10.3: Warning — WordPress minimum recommended versions
• MySQL 5.7+ or MariaDB 10.3+: Info — Compatible

Finding ID Format: DIAG-DB-{3-char-md5-of-db-version}

Example Finding (Old Version):

{
  "id": "DIAG-DB-e5f",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "Database version below recommended",
  "summary": "Your database version is older than WordPress recommends for optimal performance and security.",
  "detail": "Current database: MySQL 5.6.51. WordPress recommends MySQL 5.7 or higher (or MariaDB 10.3+) for full feature support and security updates.",
  "location": "Database Server",
  "fix": "Contact your hosting provider to upgrade your database server. MySQL 5.7+ or MariaDB 10.5+ recommended."
}

Check 4: Plugin and Theme Updates

Get Full Plugin Inventory:

ssh {user}@{host} "cd {wp_path} && {wp_cli_path} plugin list --format=json"

Response format:

[
  {
    "name": "akismet",
    "status": "active",
    "update": "available",
    "version": "4.2.1",
    "update_version": "5.0.1"
  },
  {
    "name": "custom-plugin",
    "status": "active",
    "update": "none",
    "version": "1.0.0"
  }
]

Filter to Outdated Plugins:

ssh {user}@{host} "cd {wp_path} && {wp_cli_path} plugin list --update=available --format=json"

Get Theme Status:

ssh {user}@{host} "cd {wp_path} && {wp_cli_path} theme list --format=json"
ssh {user}@{host} "cd {wp_path} && {wp_cli_path} theme list --update=available --format=json"

For Each Outdated Plugin/Theme:

1. Generate deterministic finding ID: DIAG-PLUGIN-{3-char-md5-of-slug} or DIAG-THEME-{3-char-md5-of-slug}

2. Check WordPress.org compatibility (optional but recommended):

   curl -s "https://api.wordpress.org/plugins/info/1.2/?action=plugin_information&request[slug]={slug}"
   

   Parse tested field: If the plugin's tested version is lower than the current WordPress version, add a compatibility note.

   Example: Plugin tested up to WP 6.3, but site is running WP 6.5 → add note: "This plugin has not been tested with your WordPress version. Update may require testing."

3. Create finding:

Example Finding (Plugin Update):

{
  "id": "DIAG-PLUGIN-7a3",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "Plugin update available: Akismet Anti-Spam",
  "summary": "An outdated plugin may have security vulnerabilities or compatibility issues.",
  "detail": "Plugin 'Akismet Anti-Spam' (akismet) is outdated. Current version: 4.2.1. Available version: 5.0.1. This plugin has been tested with WordPress 6.5.",
  "location": "wp-content/plugins/akismet/",
  "fix": "Update via WP-CLI: `wp plugin update akismet` or via WordPress admin (Plugins > Updates). Review changelog before updating: https://wordpress.org/plugins/akismet/#developers"
}

Example Finding (Plugin Not Tested):

{
  "id": "DIAG-PLUGIN-9c2",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "Plugin update available: Contact Form 7",
  "summary": "An outdated plugin may have security vulnerabilities or compatibility issues.",
  "detail": "Plugin 'Contact Form 7' (contact-form-7) is outdated. Current version: 5.7.5. Available version: 5.8.3. Note: This plugin was last tested with WordPress 6.3. Your site is running WordPress 6.5. Compatibility testing recommended.",
  "location": "wp-content/plugins/contact-form-7/",
  "fix": "Update via WP-CLI: `wp plugin update contact-form-7` or via WordPress admin. Test on a staging site first due to potential compatibility issues."
}

Example Finding (Theme Update):

{
  "id": "DIAG-THEME-4d1",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "Theme update available: Twenty Twenty-Four",
  "summary": "An outdated theme may have security vulnerabilities or compatibility issues.",
  "detail": "Theme 'Twenty Twenty-Four' (twentytwentyfour) is outdated. Current version: 1.0. Available version: 1.1. Theme updates often include security fixes and new features.",
  "location": "wp-content/themes/twentytwentyfour/",
  "fix": "Update via WP-CLI: `wp theme update twentytwentyfour` or via WordPress admin (Appearance > Themes). Backup your site before updating."
}

Output Format

Return findings as a JSON array. Each finding must include:

• id (string) — Deterministic ID based on check type
• severity (string) — "Critical", "Warning", or "Info"
• category (string) — "Version & Compatibility"
• title (string) — Short descriptive title
• summary (string) — One non-technical sentence explaining the issue
• detail (string) — Technical detail with version numbers and context
• location (string) — Where the issue exists (e.g., "WordPress Core", "Server PHP Runtime", plugin path)
• fix (string) — Specific remediation steps with commands

Example Complete Output:

[
  {
    "id": "DIAG-VERSION-a1b",
    "severity": "Critical",
    "category": "Version & Compatibility",
    "title": "WordPress core update available",
    "summary": "Your WordPress version is outdated. A newer version with security and bug fixes is available.",
    "detail": "Current version: 6.4.3. Available version: 6.5.0 (major update).",
    "location": "WordPress Core",
    "fix": "Update via WP-CLI: `wp core update` or use WordPress admin dashboard."
  },
  {
    "id": "DIAG-PHP-c3d",
    "severity": "Info",
    "category": "Version & Compatibility",
    "title": "PHP version is current",
    "summary": "Your PHP version is actively supported with security updates.",
    "detail": "Current PHP version: 8.2.10.",
    "location": "Server PHP Runtime",
    "fix": "No action required."
  },
  {
    "id": "DIAG-PLUGIN-7a3",
    "severity": "Warning",
    "category": "Version & Compatibility",
    "title": "Plugin update available: Akismet Anti-Spam",
    "summary": "An outdated plugin may have security vulnerabilities or compatibility issues.",
    "detail": "Plugin 'Akismet Anti-Spam' is outdated. Current: 4.2.1, Available: 5.0.1.",
    "location": "wp-content/plugins/akismet/",
    "fix": "Update via WP-CLI: `wp plugin update akismet` or via admin dashboard."
  }
]

Error Handling

WP-CLI Not Available

If WP-CLI is not installed or not found, return this finding and skip all WP-CLI-dependent checks:

{
  "id": "DIAG-WPCLI-000",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "WP-CLI not available",
  "summary": "Version auditing requires WP-CLI to be installed on the server.",
  "detail": "WP-CLI was not found on the server. Without it, automated version checks for WordPress, plugins, themes, and database cannot be performed.",
  "location": "Server Configuration",
  "fix": "Install WP-CLI on the server: https://wp-cli.org/#installing. CoWork can assist with installation during the connection flow."
}

SSH Connection Timeout

If SSH commands timeout:

{
  "id": "DIAG-SSH-001",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "SSH connection timeout during version check",
  "summary": "Unable to complete version checks due to connection issues.",
  "detail": "SSH connection timed out while attempting to run version check commands. This may indicate network issues or server overload.",
  "location": "SSH Connection",
  "fix": "Verify network connectivity and server status. Retry the diagnostic after confirming the server is responsive."
}

Command Execution Errors

If a specific WP-CLI command fails (non-zero exit code), include error output in detail:

{
  "id": "DIAG-CMD-002",
  "severity": "Warning",
  "category": "Version & Compatibility",
  "title": "Failed to check plugin updates",
  "summary": "An error occurred while checking for plugin updates.",
  "detail": "WP-CLI command `wp plugin list --update=available` failed with error: 'Error: This does not seem to be a WordPress installation.' This may indicate an incorrect WordPress path or corrupted installation.",
  "location": "WP-CLI Execution",
  "fix": "Verify WordPress installation integrity. Check that the WordPress path in the connection profile is correct."
}

WordPress.org API Failures

If WordPress.org API is unreachable (network issue), gracefully skip compatibility checks:

• Still report plugin/theme updates based on WP-CLI output
• Omit the "tested with WordPress X.X" note
• Add to finding detail: "Compatibility check skipped (WordPress.org API unavailable)."

Performance Considerations

• SSH Connection Reuse: If the CoWork framework supports SSH connection multiplexing (ControlMaster), use it to speed up multiple sequential commands.
• Parallel Execution: Plugin and theme checks can run in parallel if the framework supports it.
• Timeout Settings: Set reasonable timeouts (10-15 seconds per command) to avoid hanging on unresponsive servers.

Success Criteria

Version audit is complete when:

• WordPress core version checked and update status determined
• PHP version checked and support status determined
• Database version checked and compatibility assessed
• All plugins checked for available updates
• All themes checked for available updates
• WordPress.org compatibility checks attempted for outdated plugins/themes (graceful fallback if API unavailable)
• All findings returned in structured JSON format
• Deterministic finding IDs generated for consistent tracking across scans