# Quickstart: Entra Admin Roles Evidence + Findings (Spec 105)

**Branch**: `105-entra-admin-roles-evidence-findings`

## Prerequisites

- Laravel Sail running (`vendor/bin/sail up -d`)
- Database migrated (`vendor/bin/sail artisan migrate`)
- At least one tenant with a provider connection configured
- Spec 104 (Provider Permission Posture) deployed (`stored_reports` table exists)

## New Files Created (Implementation Order)

### Phase A — Foundation (Config + Migration + Constants)

```
config/entra_permissions.php                                  # NEW: Entra permission registry
database/migrations/XXXX_add_fingerprint_to_stored_reports.php  # NEW: fingerprint + previous_fingerprint columns
```

### Phase B — Catalog + Report Service

```
app/Services/EntraAdminRoles/HighPrivilegeRoleCatalog.php     # NEW: role classification
app/Services/EntraAdminRoles/EntraAdminRolesReportResult.php  # NEW: value object
app/Services/EntraAdminRoles/EntraAdminRolesReportService.php # NEW: Graph fetch + report creation
```

### Phase C — Finding Generator

```
app/Services/EntraAdminRoles/EntraAdminRolesFindingResult.php # NEW: value object
app/Services/EntraAdminRoles/EntraAdminRolesFindingGenerator.php # NEW: findings lifecycle
```

### Phase D — Job + Scheduling

```
app/Jobs/ScanEntraAdminRolesJob.php                           # NEW: orchestrator job
```

### Phase E — UI Widget

```
app/Filament/Widgets/Tenant/AdminRolesSummaryWidget.php       # NEW: dashboard card
resources/views/filament/widgets/tenant/admin-roles-summary.blade.php  # NEW: card template
```

## Modified Files Summary

| File | Change |
|------|--------|
| `app/Models/StoredReport.php` | Add `REPORT_TYPE_ENTRA_ADMIN_ROLES` constant, add `fingerprint`+`previous_fingerprint` to fillable |
| `app/Models/Finding.php` | Add `FINDING_TYPE_ENTRA_ADMIN_ROLES` constant |
| `app/Models/AlertRule.php` | Add `EVENT_ENTRA_ADMIN_ROLES_HIGH` constant |
| `app/Support/OperationRunType.php` | Add `EntraAdminRolesScan` case |
| `app/Support/Auth/Capabilities.php` | Add `ENTRA_ROLES_VIEW`, `ENTRA_ROLES_MANAGE` constants |
| `app/Support/Badges/Domains/FindingTypeBadge.php` | Add `entra_admin_roles` badge mapping |
| `app/Services/Intune/TenantPermissionService.php` | Merge `entra_permissions.php` into `getRequiredPermissions()` |
| `app/Jobs/Alerts/EvaluateAlertsJob.php` | Add `entraAdminRolesHighEvents()` method + call in `handle()` |
| `config/graph_contracts.php` | Add `entraRoleDefinitions` + `entraRoleAssignments` type entries |
| `app/Support/Auth/RoleCapabilityMap.php` (or equivalent) | Map new capabilities to roles |
| `app/Filament/Resources/AlertRuleResource.php` | Add `EVENT_ENTRA_ADMIN_ROLES_HIGH` to event type dropdown |
| `routes/console.php` | Register daily scan schedule |
| `database/factories/FindingFactory.php` | Add `entraAdminRoles()` state |

## Running Tests

```bash
# All Spec 105 tests
vendor/bin/sail artisan test --compact --filter=EntraAdminRoles

# Specific test files
vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/HighPrivilegeRoleCatalogTest.php
vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/EntraAdminRolesReportServiceTest.php
vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/EntraAdminRolesFindingGeneratorTest.php
vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/ScanEntraAdminRolesJobTest.php
vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/AdminRolesAlertIntegrationTest.php
vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/AdminRolesSummaryWidgetTest.php
```

## Key Design Decisions

1. **Fingerprint on stored_reports**: Migration adds nullable columns — existing permission_posture reports unaffected
2. **HighPrivilegeRoleCatalog**: Static PHP catalog using Microsoft template_ids (GUIDs), extensible later via workspace settings
3. **Finding per (principal, role)**: One finding per role assignment, not per principal — enables precise auto-resolve
4. **Registry merge**: `TenantPermissionService::getRequiredPermissions()` now merges both `intune_permissions.php` and `entra_permissions.php`
5. **Alert integration**: Same pattern as existing alert event producers — new method in `EvaluateAlertsJob`
6. **Widget not Resource**: Admin Roles card is a widget on the tenant dashboard, not a full CRUD resource
7. **RBAC boundary**: `ENTRA_ROLES_VIEW` gates card+report only; findings use existing `FINDINGS_VIEW`