feat(rmm): onboarding diagnostic (Phase 1) - probe + triage + baseline

/rmm diagnose: dispatches a Windows security/health probe to a newly onboarded
agent, grades RED/AMBER/GREEN, writes an immutable per-client baseline
(clients/<slug>/onboarding-baselines/), diffs vs prior, and alerts CRITICALs to
#dev-alerts. Probe is PS5.1/ASCII/SYSTEM-safe, never-abort, base64 chunked upload
around the agent command-size cap. Code-reviewed (no blockers); folded in
immutability guard, severity-independent finding ids, Defender-unknown sentinel,
expanded competitor/backup detection.

First baselines captured: Rednour FRONTDESKRECEPT + LEGALASST (both RED - prior
MSP ScreenConnect/Splashtop/Syncro still live; LEGALASST OS EOL).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-29 13:08:43 -07:00
parent 02c402ea78
commit df9be01065
7 changed files with 4033 additions and 0 deletions

View File

@@ -24,6 +24,7 @@ Interact with the GuruRMM agent fleet: list agents, run remote commands (PowerSh
/rmm cancel <command_id> Cancel a pending or running command
/rmm history <hostname|uuid> [N] Recent command history (default 10, max 500)
/rmm onboard <client name> [site] Create a new client + site, vault the one-time enrollment key
/rmm diagnose <hostname|uuid> [client] Run onboarding health/security diagnostic + baseline
```
---
@@ -679,6 +680,84 @@ git -C "$VR" add "clients/$SLUG/gururmm-site-main.sops.yaml" && git -C "$VR" com
---
## Onboarding diagnostic (`/rmm diagnose`)
Run a one-shot security + health + inventory probe against a newly onboarded
Windows agent and produce a prioritized "take this seriously" report plus an
immutable before/after baseline. This is the Phase 1 tooling implementation;
a native GuruRMM feature (DB-backed storage, scheduled re-baselines) is Phase 3.
**Runner:** `.claude/scripts/run-onboarding-diagnostic.sh <hostname|uuid> [client-slug]`
**Probe:** `.claude/scripts/onboarding-diagnostic.ps1` (Windows PowerShell 5.1, ASCII, runs as SYSTEM)
```bash
bash "$REPO_ROOT/.claude/scripts/run-onboarding-diagnostic.sh" FrontDeskReception rednour
```
If no client-slug is given, it is derived by slugifying the agent's `client_name`.
### Workflow
1. Authenticate to RMM (vault creds, same as the rest of this skill).
2. Resolve the agent (exact UUID, exact hostname, then partial). Windows-only.
3. Upload the probe to the endpoint **base64-encoded, in <24 KB chunks** (the
agent caps an inline command body at ~32-40 KB; the probe is ~60 KB), then a
final small command decodes it to a `.ps1`, runs it, and deletes both temp
files. Every check in the probe is wrapped in try/catch, so one failing check
becomes an `unknown`-severity finding instead of aborting the probe.
4. The probe emits a single JSON object fenced by `===DIAG-JSON-START===` /
`===DIAG-JSON-END===`; the runner extracts it from between the markers.
5. Grade, write two baseline files, diff against any prior baseline, alert.
### Grade model
| Grade | Meaning |
|-------|---------|
| **RED** | At least one `critical` finding |
| **AMBER** | At least one `warning`, no `critical` |
| **GREEN** | No `critical` and no `warning` |
`unknown`-severity findings (a check that failed to run) do not change the grade
but are listed in the report for manual follow-up.
### What it checks
- **Security:** Defender state (RTP/service/signature age/tamper), 3rd-party AV
conflicts, leftover competitor RMM / remote-access agents (ScreenConnect,
NinjaRMM, Datto, Atera, Kaseya, TeamViewer, AnyDesk, Splashtop, N-able,
Syncro, Action1, Automate, LogMeIn), firewall profiles, BitLocker (laptop-aware),
local admins / built-in Administrator / non-expiring passwords, patch posture +
OS EOL, RDP/NLA, SMBv1, UAC, LAPS.
- **Health:** disk free %, SMART/physical-disk health, 14-day stability
(unexpected shutdown / BSOD / disk errors), pending reboot, uptime, failed
auto-start services, domain secure channel, time source, battery (laptops),
backup-agent presence.
- **Inventory baseline (info):** model/serial, CPU/RAM, BIOS, TPM, Secure Boot,
OS edition/build/activation, full installed-software list, local users/groups,
network, scheduled tasks + Run-key autoruns.
### Where baselines are stored
`clients/<slug>/onboarding-baselines/` — two files per run, both timestamped
`<HOST>-<UTC-YYYYMMDDTHHMMSS>`:
- `*.json` — the raw immutable snapshot (do not edit; it is the source of truth
for diffs).
- `*.md` — the human report: grade, findings grouped critical -> warning ->
info -> unknown, inventory summary, and a diff section vs the most recent prior
baseline (new / resolved / regressed findings, software added/removed).
Baselines are immutable and append-only. GuruRMM-DB storage of baselines arrives
with the Phase 3 native feature.
### Alerting
Each **CRITICAL** finding and a **RED** overall grade auto-post a one-line
`[RMM]` alert to **#dev-alerts** via `post-bot-alert.sh` (ASCII only, soft-fail).
Example: `[RMM] Onboarding diag <HOST> (<client>) = RED: <n> critical - <titles>`.
---
## Known enrolled agents (verify with GET /api/agents — UUIDs change on re-enroll)
Do not use this table as authoritative — always resolve live. Treat as a starting hint only.