azcomputerguru/claudetools
1
0
Fork 0
Code Issues 59 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 a7afd52c76
commit 2eb2d2f9dc
7 changed files with 728 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
.claude/skills/remediation-tool/references/gotchas.md
View File

@@ -1,77 +1,113 @@
# Gotchas — Permissions, Roles, Consent
## App identity
## App Suite (tiered architecture)
- **App ID (client_id):** `fabb3421-8b34-484b-bc17-e46de9703418`
- **Internal name (home tenant / registration):** Claude-MSP-Access
- **Display name in customer tenants:** **ComputerGuru - AI Remediation**
- **Client secret:** SOPS vault `msp-tools/claude-msp-access-graph-api.sops.yaml` -> field `credentials.credential`
Five multi-tenant apps replace the old single over-permissioned app. Use minimum necessary tier.
When searching customer admin portals for the service principal (role assignments, app role assignments, conditional access exclusions), **search for "ComputerGuru - AI Remediation"** — not "Claude-MSP-Access".
| Tier | Display name in customer tenant | App ID | Vault file |
|---|---|---|---|
| `investigator` / `investigator-exo` | ComputerGuru Security Investigator | `bfbc12a4-f0dd-4e12-b06d-997e7271e10c` | `computerguru-security-investigator.sops.yaml` |
| `exchange-op` | ComputerGuru Exchange Operator | `b43e7342-5b4b-492f-890f-bb5a4f7f40e9` | `computerguru-exchange-operator.sops.yaml` |
| `user-manager` | ComputerGuru User Manager | `64fac46b-8b44-41ad-93ee-7da03927576c` | `computerguru-user-manager.sops.yaml` |
| `tenant-admin` | ComputerGuru Tenant Admin | `709e6eed-0711-4875-9c44-2d3518c47063` | `computerguru-tenant-admin.sops.yaml` |
| `defender` | ComputerGuru Defender Add-on | `dbf8ad1a-54f4-4bb8-8a9e-ea5b9634635b` | `computerguru-defender-addon.sops.yaml` |
**Deprecated (do not use):** ~~ComputerGuru - AI Remediation~~ (`fabb3421`) — old single-app with 159 permissions including Defender ATP. Broke consent on tenants without MDE license. Retire/delete from portal when confirmed no active tenants depend on it.
When searching customer admin portals for a service principal (role assignments, app role assignments, CA exclusions), search by the display name for that tier (e.g., "ComputerGuru Security Investigator").
## Per-tenant prerequisites
Graph API permissions alone are not enough. Most privileged operations require directory roles on the service principal *in that tenant*:
Graph API permissions alone are not enough. Most privileged operations require directory roles on the specific service principal *in that tenant*:
| Operation | Required directory role |
|---|---|
| Password reset, user property updates | User Administrator |
| Exchange REST (hidden inbox rules, mailbox permissions, SendAs, transport rules, Get-Mailbox) | Exchange Administrator |
| Conditional Access policy reads/writes | Conditional Access Administrator OR Security Administrator |
| Teams policies | Teams Administrator |
| Operation | App tier | Required directory role on that SP |
|---|---|---|
| Exchange REST read (Get-InboxRule, Get-Mailbox) | `investigator-exo` | Exchange Administrator |
| Exchange REST write (Set-Mailbox, Remove-InboxRule) | `exchange-op` | Exchange Administrator |
| Password reset, user property updates | `user-manager` | User Administrator |
| MFA method reset | `user-manager` | Authentication Administrator |
| Conditional Access reads/writes | `tenant-admin` | Conditional Access Administrator OR Security Administrator |
| Teams policies | `tenant-admin` | Teams Administrator |
### How to assign a role to the SP in a customer tenant
### How to assign a role to an SP in a customer tenant
1. Sign into the customer's Entra admin center as Global Admin:
`https://entra.microsoft.com/#@{customer-domain}`
2. Identity -> Roles & admins -> All roles -> select the role (e.g., Exchange Administrator).
3. Add assignments -> search **"ComputerGuru - AI Remediation"** -> Assign (Active, permanent — service principals cannot activate eligible assignments).
`https://entra.microsoft.com/#@{customer-domain}`
2. Identity -> Roles & admins -> All roles -> select the role (e.g., Exchange Administrator)
3. Add assignments -> search by the app display name (e.g., "ComputerGuru Security Investigator") -> Assign
(Active, permanent — service principals cannot activate eligible assignments)
## Admin consent
## Admin consent URLs
When you add new Graph scopes to the app manifest in the home tenant, each customer tenant must re-consent for those scopes to flow into tokens.
**Admin consent URL (per tenant):**
Each app must be individually consented in each customer tenant. Format:
```
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=fabb3421-8b34-484b-bc17-e46de9703418&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient
https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id={app-id}&redirect_uri=https://azcomputerguru.com&prompt=consent
```
- Customer admin must sign in as Global Admin of that tenant.
- The consent page lists all permissions in the current manifest; admin clicks Accept.
- Redirect lands on a blank Microsoft "native client" page that looks like an error — **that is normal**. Consent is recorded on Accept, not on redirect success.
- Verify consent took effect by checking `/servicePrincipals/{sp-id}/appRoleAssignments` — the timestamps on new grants should be `today`.
**Security Investigator** (consent this first — needed for all breach checks):
```
https://login.microsoftonline.com/{TENANT_ID}/adminconsent?client_id=bfbc12a4-f0dd-4e12-b06d-997e7271e10c&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**Exchange Operator** (consent when remediation scope is needed):
```
https://login.microsoftonline.com/{TENANT_ID}/adminconsent?client_id=b43e7342-5b4b-492f-890f-bb5a4f7f40e9&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**User Manager**:
```
https://login.microsoftonline.com/{TENANT_ID}/adminconsent?client_id=64fac46b-8b44-41ad-93ee-7da03927576c&redirect_uri=https://azcomputerguru.com&prompt=consent
```
**Tenant Admin**:
```
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 — AADSTS650052 if no MDE license):
```
https://login.microsoftonline.com/{TENANT_ID}/adminconsent?client_id=dbf8ad1a-54f4-4bb8-8a9e-ea5b9634635b&redirect_uri=https://azcomputerguru.com&prompt=consent
```
The customer admin signs in as Global Admin, clicks Accept. Redirect lands on azcomputerguru.com — expected. Verify via `/servicePrincipals/{sp-id}/appRoleAssignments` (grants timestamped today confirm success).
## Diagnosing "required scopes are missing"
Token returned 403 with `"required scopes are missing in the token"`:
1. Decode the JWT payload (2nd segment, base64url) and check the `roles` claim.
2. If the scope you expected is not in `roles`:
- Confirm the scope is in the app's API permissions in the home tenant (not just selected in the picker — must be saved).
2. If the expected scope is missing from `roles`:
- Confirm the scope is in the app manifest in the home tenant (saved, not just selected).
- Grant admin consent in the home tenant.
- Re-run the customer admin consent URL above.
- Re-run the customer admin consent URL above for that specific app.
3. If the scope IS in `roles` but you still get 403: check for a missing directory role (see table above).
## Diagnosing Exchange REST 403
- Invalid token scope: make sure you requested `https://outlook.office365.com/.default` (not the Graph scope).
- Missing Exchange Administrator role on the SP in that tenant.
- Propagation delay: newly assigned role can take up to 15 minutes to reach Exchange Online. If you just assigned it, wait and retry.
- Wrong token scope: must request `https://outlook.office365.com/.default` (use `investigator-exo` or `exchange-op` tier, NOT `investigator`).
- Missing Exchange Administrator role on the specific SP in that tenant.
- Propagation delay: newly assigned role can take up to 15 minutes to reach Exchange Online. If just assigned, wait and retry.
## AADSTS650052 — service not licensed
If token request or API call returns AADSTS650052 referencing `WindowsDefenderATP` (`fc780465`): the tenant does not have an MDE license. Do not use the `defender` tier for this tenant. Security investigation proceeds with `investigator` + `investigator-exo` only.
## Common, benign "failures" in sign-in logs
- `error 50140` "Keep me signed in interrupt" — KMSI prompt, not a real failure.
- `error 65001` "has not consented to use the application" — this fires during onboarding consent and when a user (or admin) signs in before granting consent. If the `appDisplayName` is **ComputerGuru - AI Remediation**, those are our own consent attempts, not attacker activity.
- `error 50126` from the sysadmin account during our onboarding is typo/retry noise — check `ipAddress` matches Mike's known IPs before flagging.
- `error 65001` "has not consented to use the application" — fires during onboarding and before consent granted. If `appDisplayName` matches any ComputerGuru app, those are our own consent attempts, not attacker activity.
- `error 50126` from the sysadmin account during onboarding is typo/retry noise — check `ipAddress` against Mike's known IPs before flagging.
## Tenants where the app is already set up (as of 2026-04-16)
## Tenants where apps are consented (as of 2026-04-20)
| Tenant | Tenant ID | Directory roles assigned | Notes |
|---|---|---|---|
| Valleywide Plastering | 5c53ae9f... | User Administrator | |
| Dataforth | 7dfa3ce8... | User Administrator, Exchange Administrator | |
| Cascades Tucson | 207fa277-e9d8-4eb7-ada1-1064d2221498 | User Administrator, Exchange Administrator | IdentityRiskyUser scope still not consented as of 2026-04-16 |
| Grabblaw | 032b383e-96e4-491b-880d-3fd3295672c3 | none | Consent broken (2026-03-31); Reyna needs full access to Jsosa mailbox |
| Tenant | Tenant ID | Security Investigator | Exchange Operator | User Manager | Tenant Admin | Defender | Directory roles | Notes |
|---|---|---|---|---|---|---|---|---|
| Valleywide Plastering | 5c53ae9f... | old app only | — | — | — | — | User Admin (old app) | Needs migration to new app suite |
| Dataforth | 7dfa3ce8... | old app only | — | — | — | — | User Admin + Exchange Admin (old app) | Needs migration |
| Cascades Tucson | 207fa277-e9d8-4eb7-ada1-1064d2221498 | old app only | — | — | — | — | User Admin + Exchange Admin (old app) | IdentityRiskyUser scope still not consented as of 2026-04-16 |
| Grabblaw | 032b383e-96e4-491b-880d-3fd3295672c3 | YES (2026-04-20) | — | YES (2026-04-20) | — | — | none | No directory roles assigned yet |
Keep this table updated when you roll out to a new tenant.
**Migration note:** Valleywide, Dataforth, and Cascades still use the old deprecated app. Next visit: consent Security Investigator + assign Exchange Administrator role to new SP, then retire old app consent.
Keep this table updated when rolling out to new tenants or migrating existing ones.