--- description: M365 tenant investigation + remediation via the Claude-MSP-Access Graph API app. Breach checks, tenant sweeps, consent URLs, and gated remediation actions. --- # /remediation-tool M365 investigation and remediation using the **Claude-MSP-Access Graph API** multi-tenant app (App ID `fabb3421-8b34-484b-bc17-e46de9703418`, display name in customer tenants: **"ComputerGuru - AI Remediation"**). **Default posture: READ-ONLY.** Remediation actions require explicit `YES` confirmation in chat. --- ## Subcommands | Form | What it does | |---|---| | `/remediation-tool check ` | 10-point breach check on a single user | | `/remediation-tool sweep ` | Tenant-wide signals (sign-ins, audits, risky users, guests) | | `/remediation-tool signins [--user upn] [--failed-only] [--days N]` | Ad-hoc sign-in query | | `/remediation-tool consent-url ` | Emit admin consent URL for a tenant | | `/remediation-tool remediate ` | **GATED:** password-reset, revoke-sessions, disable-forwarding, remove-inbox-rules, disable-account | `` accepts a tenant domain (`cascadestucson.com`), a UPN (`user@domain.com`), or a tenant GUID. --- ## Workflow Claude should follow ### 0. Parse invocation - Extract subcommand, target, and any flags from `$ARGUMENTS`. - Normalize: UPN -> domain (split on `@`), domain -> look up tenant-id. - If the target is ambiguous or missing, ask the user once and proceed. ### 1. Resolve tenant ID Run `bash .claude/skills/remediation-tool/scripts/resolve-tenant.sh ` — returns tenant GUID via OpenID discovery. If it fails, the domain is not in Entra ID; surface the error and stop. ### 2. Acquire tokens (cached) Run `bash .claude/skills/remediation-tool/scripts/get-token.sh graph` and `... exchange` as needed. Tokens cache at `/tmp/remediation-tool/{tenant}/{scope}.jwt` with 55-minute TTL. The script pulls the app secret from the SOPS vault (`msp-tools/claude-msp-access-graph-api.sops.yaml`, field `credentials.credential`). If either token returns 403/401 on first use, check `.claude/skills/remediation-tool/references/gotchas.md` for the per-tenant prerequisites (directory roles, admin consent) and emit the remediation link to the user. ### 3. Run the requested checks - **`check `** -> `bash scripts/user-breach-check.sh `. Script runs all 10 checks in parallel where possible and dumps raw JSON to `/tmp/remediation-tool/{tenant}/user-breach//`. Claude then interprets findings against the rubric in `references/checklist.md` and writes a report. - **`sweep `** -> `bash scripts/tenant-sweep.sh `. Script pulls tenant-wide failed sign-ins (30d), successful non-US sign-ins, directory audits filtered for consent/auth-method/service-principal changes, risky users (if permission granted), B2B guest invites, user location profile. Claude summarizes priority findings. - **`signins`** — build ad-hoc `curl` against Graph `/auditLogs/signIns` with the requested filter. - **`consent-url `** — emit `https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=fabb3421-8b34-484b-bc17-e46de9703418&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient` plus the note that the nativeclient landing page "looks like an error, that's normal." - **`remediate`** — see Remediation section below. ### 4. Write the report Location: `clients/{client-slug}/reports/YYYY-MM-DD-{action}.md` (UTC date). Derive the client slug from the domain: - `cascadestucson.com` -> `cascades-tucson` - `foobarwidgets.com` -> `foobar-widgets` - Use existing `clients//` directory if present; if no matching client dir exists, ask the user for the slug before creating one. Use `templates/breach-report.md` as the skeleton. For single-user checks, fill in per-check findings using raw JSON in `/tmp/remediation-tool/{tenant}/user-breach//`. ### 5. Summarize to the user Short chat summary: top findings, blocked checks (with remediation links), next actions. Save raw JSON artifacts paths in the report for later re-analysis. ### 6. Auto-commit After writing the report, delegate to the **Gitea Agent** to commit with a message like `Remediation report: for `. Do not push unless the user asks. --- ## Remediation (gated) When the user runs `/remediation-tool remediate `: 1. **Confirm read-only context first**: the skill must have recently run a `check ` in this session (check `/tmp/remediation-tool/{tenant}/user-breach//` exists). If not, tell the user to run the check first. 2. **Display the exact action** that will run (curl command, cmdlet name, parameters). 3. **Require explicit `YES` in chat** — not approval via permission prompt. If the user types anything else, abort. 4. Execute via Graph/Exchange REST. Capture response to a remediation log at `/tmp/remediation-tool/{tenant}/remediation/-YYYY-MM-DDTHHMMSS.json`. 5. Update the user's report with a `## Remediation Actions` section appending what was done and the result. Allowed `` values: | Action | API | Result | |---|---|---| | `password-reset` | Graph `PATCH /users/{upn}` with new `passwordProfile` | Forces sign-in; revokes refresh tokens | | `revoke-sessions` | Graph `POST /users/{upn}/revokeSignInSessions` | Kills all active sessions | | `disable-forwarding` | Exchange REST `Set-Mailbox -ForwardingAddress $null -ForwardingSmtpAddress $null -DeliverToMailboxAndForward $false` | Clears all forwarding | | `remove-inbox-rules` | Exchange REST `Remove-InboxRule` for each non-default rule | Asks which to keep first | | `disable-account` | Graph `PATCH /users/{upn}` with `accountEnabled: false` | Hard disable | --- ## Arguments `$ARGUMENTS` — the full invocation text. Parse freely; common forms: - `check john.trozzi@cascadestucson.com` - `sweep cascadestucson.com` - `signins cascadestucson.com --user megan.hiatt@cascadestucson.com --failed-only --days 30` - `consent-url cascadestucson.com` - `remediate megan.hiatt@cascadestucson.com password-reset` If the user's phrasing is loose ("check john's box at cascades", "who's being attacked"), infer intent from CONTEXT.md and session logs. Prefer asking one clarifying question to guessing. --- ## Scope and references - Detailed check rubric: `.claude/skills/remediation-tool/references/checklist.md` - Permission/role gotchas + consent URLs: `.claude/skills/remediation-tool/references/gotchas.md` - Endpoint cheatsheet: `.claude/skills/remediation-tool/references/graph-endpoints.md` - Report template: `.claude/skills/remediation-tool/templates/breach-report.md` - Memory note on what the tool IS: `.claude/memory/feedback_365_remediation_tool.md`