azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Session log: remediation skill rewrite (5-app tiered arch) + Cascades breach check John Trozzi

Browse Source 
- Rewrote get-token.sh: tiered app system (investigator/exchange-op/user-manager/tenant-admin/defender)
- Updated SKILL.md, command, gotchas, checklist, graph-endpoints for new app suite
- Cascades breach check: mailbox clean, inbound phishing received by John, DMARC gap noted

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-04-20 11:34:59 -07:00
parent b0db273e1e
commit 26df2c47b9
7 changed files with 728 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
.claude/commands/remediation-tool.md
View File

@@ -1,15 +1,33 @@
---
description: M365 tenant investigation + remediation via the Claude-MSP-Access Graph API app. Breach checks, tenant sweeps, consent URLs, and gated remediation actions.
description: M365 tenant investigation + remediation via the ComputerGuru tiered MSP app suite. 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"**).
M365 investigation and remediation using the **ComputerGuru tiered MSP app suite** — five multi-tenant apps covering read-only investigation, Exchange write operations, user lifecycle management, high-privilege tenant admin, and optional Defender ATP.
**Default posture: READ-ONLY.** Remediation actions require explicit `YES` confirmation in chat.
---
## App Tiers (quick reference)
| Tier flag | App | App ID | Use for |
|---|---|---|---|
| `investigator` | ComputerGuru Security Investigator | `bfbc12a4` | All read-only breach checks via Graph |
| `investigator-exo` | ComputerGuru Security Investigator | `bfbc12a4` | Exchange read: Get-InboxRule (hidden), Get-Mailbox, permissions |
| `exchange-op` | ComputerGuru Exchange Operator | `b43e7342` | Exchange write: Set-Mailbox, Remove-InboxRule, session revoke |
| `user-manager` | ComputerGuru User Manager | `64fac46b` | User create/disable, license assign, MFA reset, password reset |
| `tenant-admin` | ComputerGuru Tenant Admin | `709e6eed` | App role assignments, CA policy, high-privilege directory |
| `defender` | ComputerGuru Defender Add-on | `dbf8ad1a` | Alerts, machine risk, vuln data — MDE-licensed tenants only |
Pass the tier flag to `get-token.sh`:
```bash
bash .claude/skills/remediation-tool/scripts/get-token.sh <tenant-id> <tier>
```
---
## Subcommands
| Form | What it does |
@@ -17,8 +35,8 @@ M365 investigation and remediation using the **Claude-MSP-Access Graph API** mul
| `/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 |
| `/remediation-tool consent-url <domain> [--app <tier>]` | Emit admin consent URL for a tenant + app |
| `/remediation-tool remediate <upn> <action>` | **GATED:** revoke-sessions, disable-forwarding, remove-inbox-rules, disable-account, password-reset |
`<domain>` accepts a tenant domain (`cascadestucson.com`), a UPN (`user@domain.com`), or a tenant GUID.
@@ -38,38 +56,93 @@ Run `bash .claude/skills/remediation-tool/scripts/resolve-tenant.sh <domain>`
### 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`).
Use the minimum-privilege tier for the task. Most breach checks only need:
```bash
GT=$(bash .claude/skills/remediation-tool/scripts/get-token.sh <tenant-id> investigator)
ET=$(bash .claude/skills/remediation-tool/scripts/get-token.sh <tenant-id> investigator-exo)
```
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.
Escalate to write tiers only for remediation:
```bash
# Exchange write (disable-forwarding, remove-inbox-rules)
EXO_WRITE=$(bash .claude/skills/remediation-tool/scripts/get-token.sh <tenant-id> exchange-op)
# User write (revoke-sessions, disable-account, password-reset, MFA reset)
UT=$(bash .claude/skills/remediation-tool/scripts/get-token.sh <tenant-id> user-manager)
# Defender (MDE tenants only)
DT=$(bash .claude/skills/remediation-tool/scripts/get-token.sh <tenant-id> defender)
```
Tokens cache at `/tmp/remediation-tool/{tenant}/{tier}.jwt` with 55-minute TTL.
If a token returns 403/401 on first use, check `.claude/skills/remediation-tool/references/gotchas.md` for per-tenant prerequisites and emit the appropriate consent or role-assignment link.
### 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.
- **`check <upn>`** -> `bash scripts/user-breach-check.sh <tenant> <upn>`. Runs all 10 checks and dumps raw JSON to `/tmp/remediation-tool/{tenant}/user-breach/<slug>/`. Interpret against `references/checklist.md` and write 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.
- **`sweep <domain>`** -> `bash scripts/tenant-sweep.sh <tenant>`. Pulls tenant-wide failed sign-ins (30d), successful non-US sign-ins, directory audits filtered for consent/auth-method/service-principal changes, risky users, B2B guest invites. Claude summarizes priority findings.
- **`signins`** — build ad-hoc `curl` against Graph `/auditLogs/signIns` with the requested filter.
- **`signins`** — build ad-hoc `curl` against Graph `/auditLogs/signIns` with the requested filter. Use `investigator` tier.
- **`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."
- **`consent-url <domain> [--app <tier>]`** — emit the appropriate admin consent URL (see below). Default to Security Investigator (`investigator`) unless `--app` specifies another tier.
- **`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:
Location: `clients/{client-slug}/reports/YYYY-MM-DD-{action}.md` (UTC date). Derive client slug from 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.
- `grabblaw.com` -> `grabblaw`
- Use existing `clients/<slug>/` directory if present; if no match, ask the user for the slug.
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>/`.
Use `templates/breach-report.md` as skeleton. For single-user checks, fill per-check findings from raw JSON.
### 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.
Short chat summary: top findings, blocked checks (with remediation links), next actions. Save raw JSON artifact paths in the report.
### 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.
After writing the report, delegate to the **Gitea Agent** to commit with `Remediation report: <action> for <target>`. Do not push unless the user asks.
---
## Admin Consent URLs
Each app must be individually consented in each customer tenant. Consent URL format:
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id={app-id}&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**Security Investigator** (read-only — consent this first):
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=bfbc12a4-f0dd-4e12-b06d-997e7271e10c&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**Exchange Operator** (EXO write — consent when remediation needed):
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=b43e7342-5b4b-492f-890f-bb5a4f7f40e9&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**User Manager** (user/license write):
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=64fac46b-8b44-41ad-93ee-7da03927576c&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**Tenant Admin** (high-privilege — use sparingly):
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=709e6eed-0711-4875-9c44-2d3518c47063&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**Defender Add-on** (MDE-licensed tenants only):
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=dbf8ad1a-54f4-4bb8-8a9e-ea5b9634635b&redirect_uri=https://azcomputerguru.com&prompt=consent
```
The customer admin must sign in as Global Admin of that tenant and click Accept. Redirect lands on azcomputerguru.com — that is expected. Verify consent via `/servicePrincipals/{sp-id}/appRoleAssignments` (new grants should be timestamped today).
---
@@ -77,21 +150,22 @@ After writing the report, delegate to the **Gitea Agent** to commit with a messa
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.
1. **Confirm read-only context first**: skill must have recently run `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** (curl command, cmdlet name, parameters).
3. **Require explicit `YES` in chat** — not a permission prompt. Anything else aborts.
4. Execute via the appropriate app tier. Capture response to `/tmp/remediation-tool/{tenant}/remediation/<slug>-YYYY-MM-DDTHHMMSS.json`.
5. Update the user's report with a `## Remediation Actions` section.
Allowed `<action>` values:
Allowed actions and which tier handles them:
| Action | API | Result |
| Action | App tier | API |
|---|---|---|
| `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 |
| `revoke-sessions` | `user-manager` | Graph `POST /users/{upn}/revokeSignInSessions` |
| `disable-account` | `user-manager` | Graph `PATCH /users/{upn}` with `accountEnabled: false` |
| `password-reset` | `user-manager` | Graph `PATCH /users/{upn}` with new `passwordProfile` |
| `disable-forwarding` | `exchange-op` | Exchange REST `Set-Mailbox -ForwardingAddress $null -ForwardingSmtpAddress $null -DeliverToMailboxAndForward $false` |
| `remove-inbox-rules` | `exchange-op` | Exchange REST `Remove-InboxRule` per non-default rule (ask which to keep first) |
| `disable-smtp-auth` | `exchange-op` | Exchange REST `Set-CASMailbox -SmtpClientAuthenticationDisabled $true` |
---
@@ -103,7 +177,8 @@ Allowed `<action>` values:
- `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`
- `consent-url grabblaw.com --app exchange-op`
- `remediate megan.hiatt@cascadestucson.com revoke-sessions`
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.
@@ -115,4 +190,3 @@ If the user's phrasing is loose ("check john's box at cascades", "who's being at
- 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`