diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index f6932a5..f3f59cc 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -252,6 +252,7 @@ Vault structure: `infrastructure/`, `clients/`, `services/`, `projects/`, `msp-t | `/remediation-tool` | M365 breach checks, tenant sweeps, gated remediation | | `/feature-request` | Howard submits a GuruRMM feature request — Claude classifies it and messages Mike | | `/shape-spec` | Pre-implementation spec for a GuruRMM feature — produces plan.md, shape.md, references.md, standards.md | +| `/rmm-audit` | Full end-to-end audit of GuruRMM: API coverage, UI gaps, Rust/TS quality, security, data integrity. Produces timestamped report + updates UI_GAPS.md | --- diff --git a/.claude/skills/rmm-audit/SKILL.md b/.claude/skills/rmm-audit/SKILL.md new file mode 100644 index 0000000..7d6efc6 --- /dev/null +++ b/.claude/skills/rmm-audit/SKILL.md @@ -0,0 +1,404 @@ +--- +name: rmm-audit +description: | + Periodic end-to-end verification of the GuruRMM codebase. Runs 5 parallel audit + passes: (1) API/route inventory cross-reference, (2) UI coverage and gap update, + (3) Rust code quality and standards compliance, (4) TypeScript/frontend quality, + (5) security and data integrity. Produces a timestamped audit report and updates + the living docs (UI_GAPS.md, FEATURE_ROADMAP.md). Takes 10-20 minutes. + + Invoke explicitly only — no auto-trigger. Use /rmm-audit for a full audit. + Optional arg: --pass= to run a single pass (api, ui, rust, ts, security). +--- + +# GuruRMM End-to-End Audit + +Periodic full-stack sanity check. Read-only by default — findings are written to a +report file and living docs are updated. No code is changed. + +--- + +## Execution Overview + +``` +Phase 0: Context load (coordinator reads key files) +Phase 1: Spawn 4 parallel audit agents +Phase 2: Collect findings, aggregate, score +Phase 3: Write report + update living docs +Phase 4: Present summary to user +``` + +The audit is orchestrated here (Claude coordinator). All heavy passes run in +parallel subagents. Each agent returns structured findings; the coordinator +aggregates and writes the final report. + +--- + +## Phase 0: Context Load (Coordinator Reads These) + +Before spawning agents, read these yourself: + +1. `projects/msp-tools/guru-rmm/CONTEXT.md` — project overview and current state +2. `projects/msp-tools/guru-rmm/docs/UI_GAPS.md` — living gap tracker (may be stale) +3. `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` — planned features +4. `.claude/CODING_GUIDELINES.md` — development standards + +Capture from `server/src/api/mod.rs` the complete route list (all `.route(...)` calls). +This becomes the **authority route list** passed to both the API and UI audit agents. + +--- + +## Phase 1: Parallel Audit Agents + +Spawn all four agents simultaneously in a single message. Each agent receives the +full context it needs inline — do not assume they share context. + +--- + +### Agent A — API Coverage & Route Inventory + +**Goal:** Find server endpoints with no dashboard UI exposure, and dashboard API +client functions calling non-existent or mismatched server routes. + +**Instructions for agent:** + +1. Read `server/src/api/mod.rs` in full — extract every `.route(path, method)` into + a list grouped by resource (agents, clients, sites, policies, etc.). + +2. Read `dashboard/src/api/client.ts` — extract every API function and the URL path + it calls. + +3. Cross-reference: + - Server routes with no client.ts function → **ORPHANED ROUTE** (dead code or + intentionally backend-only — distinguish by context) + - Client.ts functions whose URL doesn't match any server route → **BROKEN CALL** + - Server routes that exist but the client uses a different HTTP method → **METHOD MISMATCH** + +4. Read `dashboard/src/App.tsx` (or wherever routes are defined) — list all frontend + pages and their paths. + +5. For each API resource group, assess whether a UI page exposes the major CRUD + operations. Flag any resource that has full CRUD on the server but only partial + or no UI. + +6. Return structured findings: `[SEVERITY] Description — file:line`. + +--- + +### Agent B — Rust Code Quality & Standards + +**Goal:** Find violations of the established Rust coding standards and common quality +issues across the server codebase. + +**Instructions for agent:** + +Read `.claude/CODING_GUIDELINES.md` first to know the rules. Then check: + +**Compliance checks:** +- `.unwrap()` or `.expect()` calls outside of `#[cfg(test)]` blocks — these panic in + production. Flag every occurrence with context. Note: `.expect("invariant reason")` + in truly-impossible paths is acceptable if the reason is clear. +- `todo!()` or `unimplemented!()` macros in non-test production code paths. +- `sqlx::query!` / `sqlx::query_as!` macros (banned — project uses SQLX_OFFLINE=true + with runtime queries only). +- `format!()` used to construct SQL strings (injection risk — parameterize instead). +- `unwrap_or_default()` on `Option` producing empty strings that get used as + real values without validation. + +**Auth coverage:** +- Read `server/src/api/mod.rs` — identify which route groups use + `.layer(middleware::from_fn(...))` or similar auth middleware vs. which are public. +- Any non-public route that doesn't go through JWT auth or agent-key auth middleware + is a `[CRITICAL]` finding. +- Check that agent-key-authenticated routes cannot be accessed with JWT tokens and + vice versa (separation of agent vs. admin plane). + +**Logging hygiene:** +- Grep for `tracing::` / `log::` calls that include agent keys, passwords, tokens, + or PII (email addresses, user names). These should use redacted representations. + +**Error handling:** +- HTTP handlers returning 500 with `e.to_string()` — raw error messages can leak + internals to API callers. Should be logged server-side, generic message returned. + +**Search paths:** `server/src/` only. Exclude `server/src/db/mod.rs` re-exports. + +Return structured findings with file:line references. + +--- + +### Agent C — TypeScript / Frontend Quality + +**Goal:** Find frontend code quality issues, standards violations, and missing +UI patterns. + +**Instructions for agent:** + +**TypeScript quality:** +- `any` type annotations in `dashboard/src/` — each is a type safety gap. +- `@ts-ignore` or `@ts-expect-error` comments — note reason and whether they're + still needed. +- `console.log` / `console.error` left in production code (not in dev-only blocks). +- Hardcoded API base URLs instead of using `import.meta.env.VITE_API_URL`. + +**Component patterns:** +- React components without error boundaries on data-fetching sections — if the + query throws, the entire page crashes. +- `useQuery` calls with no `isLoading` or `isError` handling — silent failures. +- Forms with no validation on submit (empty strings submitted as values). +- Missing `key` prop on mapped elements. + +**API client completeness:** +- For each resource in `client.ts`, verify the TypeScript interface matches what + the server actually returns. Focus on fields that were added recently: + `Agent` should have `is_dc`, `maintenance_mode_note`, `agent_version`. + `AgentUsers` should have `is_dc: boolean`, `groups: GroupEntry[]`. + Any missing field means the UI silently shows `undefined`. + +**Accessibility basics:** +- Buttons with icon-only content (no text) — need `title` or `aria-label`. +- Form inputs without associated `