Immutable Audit Log

​

Overview

GetMCP signs every call log entry with an HMAC-SHA256 signature at the moment it is written. If any stored field is later modified — whether accidentally or deliberately — the signature no longer matches, and the verifier flags the row as tampered. This makes the call log effectively append-only: entries can be deleted (and that deletion is itself detectable by gaps), but they cannot be silently edited.

---

​

How Signing Works

When a call log row is inserted into wp_getmcp_call_logs, GetMCP:

1. Assembles a canonical string from the row’s key fields in a fixed order.
2. Derives a signing key from WordPress’s AUTH_KEY constant using HKDF with the domain string getmcp-log-signing-v1.
3. Computes HMAC-SHA256(canonical_string, signing_key).
4. Stores the 64-character hex digest in the signature column of the same row.

The signing key is zeroed from memory after use (sodium_memzero) when the PHP sodium extension is available.

---

​

Canonical Fields

The canonical string includes the following fields (joined with |): Fields not included in the canonical form (so adding them later doesn’t break old signatures):

• upstream_bytes / delivered_bytes
• replay_data

---

​

Verifying the Audit Log

Go to GetMCP → Logs, open the More actions (⋮) kebab menu in the toolbar, and choose Verify integrity. GetMCP will:

1. Fetch all rows matching your current filter (date range, server, status).
2. Recompute the HMAC for each row.
3. Compare it to the stored signature.
4. Report the outcome as a toast notification.

​

Verification result states

When every row checks out, the toast is green and reads Integrity OK — 21 verified. The clauses N legacy (unsigned) and limit reached — narrow filters to scan more are appended only when they apply. If any row fails, the toast turns red instead: Tampering detected: N row(s) failed verification. IDs: … listing the first ten offending IDs.

---

​

Requirements

---

​

Security Considerations

​

Key rotation

The signing key is derived from AUTH_KEY. If you rotate AUTH_KEY (e.g. after a security incident), all existing signatures will fail verification — they were signed with the old key. This is expected behaviour. After rotation, treat all pre-rotation rows as unsigned legacy rows.

​

What tampering looks like

A tampered row has a stored signature value that no longer matches the HMAC of its current field values. The verifier flags it as Tampered and shows the row ID so you can investigate. Common accidental causes of failed verification:

• Directly editing rows in phpMyAdmin or a MySQL client
• A database migration that modified existing rows
• Restoring a partial DB backup that mixed rows from two different AUTH_KEY periods

​

What the audit log does not prevent

The audit log detects tampering — it does not prevent it. A user with direct MySQL access can delete rows or the entire table. Use database-level access controls and regular off-site backups for defence-in-depth.

---

​

Daily Automated Verification

A WordPress cron job (getmcp_daily_audit_verify) runs once per day and re-verifies every signed row from the previous calendar day (UTC). If any row’s signature does not match, GetMCP sends an alert via wp_mail() to the notification email configured at GetMCP → Settings → Notifications (falls back to the WordPress admin_email if unset). No email is sent on a clean run. The same scan can be triggered ad-hoc against any filter range from GetMCP → Logs → More actions → Verify integrity, or via POST /wp-json/getmcp/v1/analytics/audit/verify for scripted full-history sweeps. A getmcp_audit_tampering_detected action also fires with the list of tampered row IDs, so you can hook into it from a custom plugin (e.g. to forward to a SIEM).