claudetools/.claude/commands/remediation-tool.md

description

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 <upn>	10-point breach check on a single user
/remediation-tool sweep <domain>	Tenant-wide signals (sign-ins, audits, risky users, guests)
/remediation-tool signins <domain> [--user upn] [--failed-only] [--days N]	Ad-hoc sign-in query
/remediation-tool consent-url <domain>	Emit admin consent URL for a tenant
/remediation-tool remediate <upn> <action>	GATED: password-reset, revoke-sessions, disable-forwarding, remove-inbox-rules, disable-account

<domain> 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 <domain> — 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 <tenant-id> 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 <upn> -> bash scripts/user-breach-check.sh <tenant> <upn>. Script runs all 10 checks in parallel where possible and dumps raw JSON to /tmp/remediation-tool/{tenant}/user-breach/<slug>/. Claude then interprets findings against the rubric in references/checklist.md and writes a report.

• sweep <domain> -> bash scripts/tenant-sweep.sh <tenant>. 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 <domain> — 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/<slug>/ 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/<slug>/.

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: <action> for <target>. Do not push unless the user asks.

---

Remediation (gated)

When the user runs /remediation-tool remediate <upn> <action>:

1. Confirm read-only context first: the skill must have recently run a check <upn> in this session (check /tmp/remediation-tool/{tenant}/user-breach/<slug>/ 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/<slug>-YYYY-MM-DDTHHMMSS.json.
5. Update the user's report with a ## Remediation Actions section appending what was done and the result.

Allowed <action> 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