audit-tenant-settings

# Audit Tenant Settings

Audit Fabric / Power BI tenant settings against a curated baseline, surface drift, enumerate delegated overrides at capacity / domain / workspace scope, investigate the Entra security groups those settings reference, and turn findings into a grounded discussion about what to do next. Always invoke the `fabric-cli` skill alongside this skill; it provides the `fab` CLI guidance, admin API references, and the `microsoft-learn` MCP server that this skill depends on.

## Prerequisites

This plugin is an add-on to the `fabric-cli` plugin. It requires:

- **fabric-cli plugin** installed and enabled; provides `fab` CLI guidance, the `microsoft-learn` MCP server, and admin API reference docs.
- **fab CLI** (`ms-fabric-cli`) authenticated with a Fabric / Power BI admin account.
- **az CLI** authenticated with Graph permissions (`Group.Read.All`, `User.Read.All`, `Directory.Read.All`, `RoleManagement.Read.Directory`) when investigating security groups.

## Settings

Per-project configuration via `.claude/fabric-admin.local.md`:

```markdown
---
enabled: true
tenant_label: "Contoso"
snapshot_path: "~/.cache/fabric-admin-audit/last-snapshot.json"
drift_threshold_high: 5
drift_threshold_medium: 15
notification_level: "info"
schedule: "weekly"
---

# Fabric Admin Configuration

Additional context or tenant-specific notes.
```

| Field | Type | Default | Purpose |
|---|---|---|---|
| `enabled` | bool | `true` | Toggle the plugin on/off |
| `tenant_label` | string | none | Label for PDF masthead and audit reports |
| `snapshot_path` | string | `~/.cache/fabric-admin-audit/last-snapshot.json` | Where to store/read the last-run snapshot JSON |
| `drift_threshold_high` | int | `5` | Alert when high-risk drift count exceeds this |
| `drift_threshold_medium` | int | `15` | Alert when total drift count exceeds this |
| `notification_level` | string | `info` | Verbosity: `quiet`, `info`, `verbose` |
| `schedule` | string | `weekly` | Preferred audit cadence: `daily`, `weekly`, `monthly`, `ad-hoc` |


## When to use this skill

Invoke for any tenant-, delegation-, or SG-scoped governance question that needs an interpreted answer rather than a raw API call. Typical asks:

- "Run a tenant governance audit"
- "Has anything drifted since last month?"
- "What does PublishToWeb do and should we have it on?"
- "Which settings are scoped to the PowerBI_ServicePrincipals group and who is in it?"
- "Show me every capacity / domain / workspace override"
- "Is this setting safe to enable for my scenario?"


## Critical rules

- **Never guess.** Tenant-setting behavior, SG membership, and override effects must come from the curated metadata, the live API, or Microsoft Learn. When sources are silent or contradict each other, say so plainly. 
- **Gather requirements.** Use your `AskUserQuestion` skill to regularly interview the user about their tenant, user behavior, and adoption. Use the `fabric-cli` skill and `fab` to understand an inventory of what's in the tenant, how it's structured, and the activity log / events to understand user adoption and activity. Flag key patterns, anomalies, and high-risk operations or scenarios (like publish-to-web, exports, and sharing with external users, full-org, or C-level employees)
- **Do not fabricate portal titles, descriptions, recommendations, risk levels, SG membership, or ACL shapes.** If the metadata or API lacks the fact, fetch it.
- **No absolute compliance claims** (HIPAA, SOC 2, GDPR, etc.). Limit conclusions to observed drift against the curated baseline and the raw API findings.
- **Recommendations are general, not prescriptive or universal.** The curated `recommended` field reflects subjective and community defaults, not the user's scenario. Always present the nuance and let the user decide.
- **Be pragmatic and critical; avoid alarmist language.** Consider the practicality of the user's scenario and engage with them in decision-making and planning so that they can understand the functional consequences of their current tenant setting configuration:
   - What does this mean for governance: what users can do, access, and create?
   - How does this affect key processes like creation, sharing, and distribution?
   - How does it affect capacity usage in Fabric and resource constraints?
   - How does it create friction that could inhibit effective analytics?
   - Would enabling or disabling result in blocking users or creating new dependencies?

## Authoritative sources (in order)

1. **Curated metadata**: `references/tenant-settings-metadata.yaml`. Holds `human_name`, `description`, `preview`, `source_url`, `recommended`, `risk`, and `recommendation_nuance` for every known setting. Check this first for any tenant-settings question.
2. **Live APIs** via `fab api` and `az`:
   - Tenant-wide state: `fab api "admin/tenantsettings"`
   - Delegated overrides: `fab api "admin/capacities/delegatedTenantSettingOverrides"`, `admin/domains/...`, `admin/workspaces/...`
   - Entra groups and role assignments: `az ad group`, `az rest --method get --uri https://graph.microsoft.com/v1.0/...`
3. **Microsoft Learn** via the `microsoft-learn` MCP server (`microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search`) or the `pbi-search` CLI as an alternative. Use when metadata is stale, the setting is brand new, or the user asks a feature question the baseline cannot answer.

## Workflow

Follow these steps in order. Skip a step only with a clear reason; never silently drop one.

### 1. Verify prerequisites

- `fab --version` is current; run `uv tool upgrade ms-fabric-cli` if stale.
- `fab auth status` confirms a live session; ask the user to run `fab auth login` if not.
- Admin access sanity check: `fab api "admin/capacities" 2>&1 | head -5`. A 401 / 403 means the account is not a Fabric / Power BI admin; stop and ask the user how to proceed (ask an admin to run it, or pivot to the non-admin scripts).
- If any SG investigation will be needed, `az account