Cortex Doctor

Run a full PASS / WARN / FAIL diagnostic for cortex. Use this when the user needs broad deployment confidence rather than a narrow log query.

Workflow

1. Display resolved plugin config, excluding sensitive token values:

• server/client mode
• server URL
• syslog bind and MCP bind
• data dir
• retention and storage limits
• Docker ingest status and fleet hosts

1. Gather host context:

• uname -srm
• systemd-detect-virt

1. Check prerequisites for server mode:

• command -v docker, docker version --format {{.Server.Version}}, docker compose version

1. Check storage and permissions for $CLAUDE_PLUGIN_OPTION_DATA_DIR:

• directory exists
• writable by the service user
• free space is at least max_db_size_mb * 1.2, or at least 2048 MB when max DB size is disabled

1. Check auth mode and token quality without printing token values:

• If $CLAUDE_PLUGIN_OPTION_NO_AUTH is true, record WARN (auth disabled by plugin config) and do not fail an empty token.
• If OAuth mode is configured, verify OAuth config presence and skip bearer-token strength checks unless a bearer fallback token is also configured.
• In bearer mode with auth enabled, empty token is FAIL.
• In bearer mode with auth enabled, length under 24 characters is WARN.
• Known weak placeholders are FAIL: your-secret-token, changeme, test, placeholder, secret, token, password, abc123, default.
• Otherwise PASS.

1. Check ports:

• syslog TCP and UDP port
• MCP TCP port
• PASS only when the port is free or held by the expected cortex process/container

1. Check service state:

• Inspect Compose state and container health, and include docker compose logs cortex --tail 30 --no-color when not running.

1. Check HTTP and MCP:

• curl -sS -m 3 "$CLAUDE_PLUGIN_OPTION_SERVER_URL/health"; expect status ok.
• Use the cortex MCP tool for read-only stats, hosts, and tail n=1; report totals, host count, write_blocked, DB size, free disk, and most recent timestamp. If the MCP tool fails, record the error and continue with HTTP-only evidence.

1. Check runtime freshness in server mode:

• Run ${CLAUDE_PLUGIN_ROOT}/scripts/check-runtime-current.sh.
• PASS only when the final verdict starts with CURRENT:.
• FAIL on STALE: or FAIL: and include the printed fix: line when present.
• The checker compares the running container image ID to the local Compose image ID. This is a local-cache check; use cortex-version-check --pull when the user specifically wants to pull first and detect a stale registry tag.

1. Check listener reachability:

• Parse host from $CLAUDE_PLUGIN_OPTION_SERVER_URL.
• TCP syslog: nc -z -w2 <host> "${CLAUDE_PLUGIN_OPTION_SYSLOG_HOST_PORT:-$CLAUDE_PLUGIN_OPTION_SYSLOG_PORT}"
• MCP auth: curl -sS -o /dev/null -w "%{http_code}" -m 3 "$CLAUDE_PLUGIN_OPTION_SERVER_URL/mcp".
• If auth is disabled (NO_AUTH=true or no bearer/OAuth auth configured), 200 or MCP protocol-level 400/405 is acceptable as route evidence; do not flag open access as a failure because it matches configuration.
• If bearer or OAuth auth is enabled, expect 401 for an unauthenticated request.
• 404 means the route is wrong or another service owns the port.

1. Check optional Docker ingest hosts:

• For each host in $CLAUDE_PLUGIN_OPTION_FLEET_HOSTS, curl -sf -m 3 http://<host>:2375/_ping; expect OK.

1. Check fleet rsyslog forwarding in server mode when $CLAUDE_PLUGIN_OPTION_FLEET_HOSTS is non-empty:

• SSH reachability
• drop-in contains the expected target and externally reachable port
• rsyslog is active
• host appears in MCP hosts output with last_seen within 30 minutes (low-volume hosts that send infrequently may legitimately fail a stricter threshold — use WARN rather than FAIL when last_seen is between 30 minutes and retention window)

Report

Produce one results table:

If service-state checks failed, include a ## Service Logs section with the captured logs.

End with one verdict:

• All checks passed
• Ready with warnings
• <N> checks failed

For each warning or failure, include a concrete next step. Add a footer that deep functional validation is bash scripts/smoke-test.sh.

Note: if smoke-test.sh is missing, manually send a test syslog: logger -n 127.0.0.1 -P 1514 "cortex smoke test"