cortex-dr

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

2. Gather host context:

   • uname -srm
   • systemd-detect-virt

3. Check prerequisites for server mode:

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

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

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

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

7. Check service state:

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

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

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

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

11. Check optional Docker ingest hosts:

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

12. 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:

Check	Status	Detail
Env: kernel	INFO	value
Storage: writable	PASS/WARN/FAIL	detail
Service: state	PASS/WARN/FAIL	detail
Runtime: freshness	PASS/FAIL	CURRENT or stale/fail detail
MCP: stats	PASS/FAIL	totals or error
Fleet host	PASS/FAIL	detail

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"