Skip to content

Audit and Logging

xNetVN Development edited this page Nov 12, 2026 · 1 revision

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.

What a row records

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.

What it never records

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.

Retention and privacy options

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).

Investigating a suspicious call

  1. Open Agent Hub > Activity. Start with the key or owner, then narrow by outcome and date range. Use denied and auth_failed to find refused attempts, and success to find what actually ran.
  2. 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 denied can be a tier, toolset, ability or capability denial. The error_code column preserves that distinction.
  3. Correlate the request. Use request_id when several rows belong to one request, and compare duration_ms, transport and mcp_method with the client's own timeline.
  4. 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.
  5. 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.
  6. 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.

Access and separation

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.

Clone this wiki locally