Repository navigation
Audit and Logging
The activity log answers a narrow question: who called which reviewed ability, with what outcome, when, and from where — without becoming a second copy of the request. It is deliberately metadata-only. The design decision is recorded in docs/en/adr/0010-minimal-audit.md, and the implementation is split between src/Audit/AuditLogger.php, src/Audit/AuditEvent.php and src/Persistence/WpdbAuditRepository.php.
Each logical tool call can produce one row. Authentication failures and pre-execution denials also produce rows, so a refused request is visible even when no ability ran.
| Field | Meaning |
|---|---|
occurred_at |
UTC timestamp |
request_id |
Random request correlation identifier |
key_id |
Public key identifier, never the secret |
user_id |
Authenticated owner, or null for an anonymous failure |
transport |
http or stdio
|
mcp_method |
Protocol method, typically tools/call
|
ability |
Canonical reviewed ability name, when known |
outcome |
success, denied, error, invalid_input, rate_limited or auth_failed
|
error_code |
Fixed safe reason code, never a raw exception |
duration_ms |
Execution time in milliseconds |
ip |
Socket peer, optionally masked |
ua_short |
Truncated user agent, at most 120 bytes |
arg_keys |
Names of top-level arguments, sorted and bounded to 100 |
The table is indexed by time, key plus time, user plus time, and ability plus time, which supports the filters exposed by Agent Hub > Activity (src/Persistence/Schema.php). The management listing accepts owner, key, ability, outcome, page and date-range filters; cross-owner filters require the management capability (src/Rest/AuditController.php).
denied means the call was refused before execution. auth_failed records the internal failure reason, such as a revoked key or a missing credential. invalid_input covers a protocol schema rejection. error covers a safe execution failure. Hidden and unknown tools produce the same wire response to the caller.
The logger stores no argument values. It extracts only the already-separated top-level names from the call hooks or the protocol payload (src/Mcp/ServerGateway.php). Bodies, bearer headers, cookies, passwords, tool outputs, file contents, SQL and stack traces are not stored. Argument names that look sensitive are dropped: authorization, password, current_password, secret, secret_hash, token, access_token, api_key, pepper, cookie, and any name beginning with the credential prefix (AuditEvent::row() in src/Audit/AuditEvent.php).
This means the log can show that a call supplied content or meta, but not what those values were. It cannot reconstruct a prompt, a post body, an uploaded file or a password. That is intentional: the audit trail must not become a credential or personal-data store (ADR-0010).
Writes are bounded and batched. The logger keeps at most 1,000 pending rows per request, inserts them in one batch at shutdown, and fires xnetvn_agent_hub_wp_audit_unavailable if storage fails rather than exposing SQL or an exception (src/Audit/AuditLogger.php). A failed audit write does not silently claim that a row exists.
| Setting | Default | Effect |
|---|---|---|
| Audit retention in days | 90 | Daily cleanup removes rows older than the cutoff |
| Mask IP addresses in audit and key metadata | Off | Stores only the IPv4 /24 or IPv6 /48 network |
| Delete plugin data when uninstalled | On | Drops keys and activity, options, events and notification preferences |
Retention runs daily and deletes at most 1,000 rows per invocation. If more remain, it schedules an hourly continuation rather than claiming a zero backlog (src/Audit/Retention.php). Expired rate-limit buckets are purged in the same maintenance path. A retention failure also fires the audit-unavailable action; it never reports success for an unreadable store.
WordPress's personal-data exporter returns the requesting user's keys, activity rows and notification preference. The eraser deletes that user's keys and preference, removes the related notification markers, and anonymizes remaining activity rows by clearing the user, key, request identifier, IP, user agent and argument names (src/Audit/PrivacyEraser.php, src/Persistence/WpPrivacyStore.php). Uninstall follows the per-site Delete plugin data setting; with it off, the site's data is kept but scheduled events are still removed (docs/user-guide.md).
-
Open Agent Hub > Activity. Start with the key or owner, then narrow by outcome and date range. Use
deniedandauth_failedto find refused attempts, andsuccessto find what actually ran. -
Read the reason, not just the status. An authentication 401 may be expired, revoked or unknown. An authentication 403 is an IP, site-state, transport or owner-capability refusal; a tool-level
deniedcan be a tier, toolset, ability or capability denial. Theerror_codecolumn preserves that distinction. -
Correlate the request. Use
request_idwhen several rows belong to one request, and compareduration_ms, transport andmcp_methodwith the client's own timeline. - Check the key record. Confirm the key state, scope, expiry and last-used time on Agent Hub > Keys. A changed network may also have triggered the unusual-use email.
- Check what changed. Review posts, media, comments, terms and users in the same window. The log tells you which ability ran; WordPress revisions and backups tell you what the content was.
- Contain and preserve. Revoke the key if it is compromised. Export or record the relevant rows before retention or a privacy erasure removes them. Do not paste credentials into the case notes.
| Question | Filter |
|---|---|
| What did this key do? | Key identifier, then date range |
| Which calls were refused? | Outcome denied or auth_failed
|
| Which ability failed? | Ability name plus outcome error or invalid_input
|
| Was the client throttled? | Outcome rate_limited
|
| Who used a key? | Owner and key identifier |
| When did activity start? | Date range, ascending |
The log cannot prove intent, and it cannot show argument values. Treat it as an index that points to WordPress objects and server-side evidence, not as a full transaction record. If a host or proxy log is needed for payload-level evidence, handle it under the host's own privacy and secret-handling policy.
The activity API is a management route. It requires a logged-in cookie session, a wp_rest nonce and the relevant capability; a bearer key cannot read it (src/Rest/ManagementGate.php, src/Rest/AuditController.php). Responses are marked no-store and nosniff. Owners see their own rows; managers can select another owner or all owners. The audit trail is per site, like keys, settings and the pepper.
See Key-Management for revoking a suspect credential, Security-Model for why credentials never enter the log, and Operations for incident handling.
xNetVN Agent Hub WP · GPL-2.0-or-later · Copyright (c) 2026 xNetVN Inc.
This wiki summarizes the repository documentation. The source of truth is the repository; when they disagree, the repository wins.
Start here
Using the plugin
Security
Engineering
Project