live-debug

Live Debug

Diagnose a single live host's problem read-only and produce a root-cause report plus the exact remediation commands for the user to run. You never change server state.

Absolute rules

1. Every command that touches the server goes through scripts/run.sh. Never call ssh, docker, or kubectl directly — the gate enforces the whitelist, redacts secrets, and logs.
2. Three-tier execution:
   • Whitelisted, read-only → run it via run.sh on your own.
   • Off-list but read-only → show the user the exact command, explain why you need it, run it once via run.sh only after they approve.
   • State-changing (restart, kill, edit, scale, delete…) → never run it. Put it in the report for the user to run.
3. If run.sh prints BLOCKED, do not try to work around it. Treat it as off-list (tier 2).

Flow

1. Intake. Ask for: the host/alias, the transport (ssh / ssh+bastion / docker / kubectl), and the symptom. Build the transport prefix — everything up to the shell that takes the command as one trailing arg:

   • ssh: ssh prod-web1 or ssh -J bastion [email protected]
   • docker (in container): docker exec <id> sh -c ; docker host-side reads: sh -c
   • k8s (in pod): kubectl exec -n <ns> <pod> -- sh -c ; cluster reads: sh -c

2. Set the log once, then probe:

   export LIVE_DEBUG_LOG="./live-debug-logs/<host>-$(date +%Y%m%d-%H%M%S).log"
   bash scripts/run.sh "<transport-prefix>" "uptime"
   

   A successful probe confirms transport + the gate. Tell the user the log path.

3. Triage, then pick a playbook. Read references/playbooks-linux.md, run the Triage block, and branch to one of: service-down/crash-loop · high-CPU/load/mem · disk/IO · network/latency/errors. For Windows hosts, read references/windows.md instead (instruction-only — self-enforce the read-only rule there).

4. Stop when you have a root cause backed by evidence, OR the playbook is exhausted.

5. Report (in chat) using this shape:

   Symptom:    <what the user reported / what you confirmed>
   Evidence:   <key command outputs that prove it>
   Root cause: <the why> — or "undetermined: <what's missing>"
   Fix (run yourself):
     $ <exact remediation command(s)>
   Log: <LIVE_DEBUG_LOG path>
   

How run.sh works

bash scripts/run.sh "<transport-prefix>" "<remote-command>" — validates the remote command against references/whitelist.txt, blocks redirections / command-substitution / destructive flags, executes over the transport, redacts secrets (see references/redaction.md), and appends command + output to $LIVE_DEBUG_LOG. Read those reference files only when you need their detail.

Scope

One host per session. The gate + transport prefix are per-host by design, so multi-host fan-out can be layered on later without changing this engine.