ahmido
6a15fe978a
## Summary Automated scanning of Entra ID directory roles to surface high-privilege role assignments as trackable findings with alerting support. ## What's included ### Core Services - **EntraAdminRolesReportService** — Fetches role definitions + assignments via Graph API, builds payload with fingerprint deduplication - **EntraAdminRolesFindingGenerator** — Creates/resolves/reopens findings based on high-privilege role catalog - **HighPrivilegeRoleCatalog** — Curated list of high-privilege Entra roles (Global Admin, Privileged Auth Admin, etc.) - **ScanEntraAdminRolesJob** — Queued job orchestrating scan → report → findings → alerts pipeline ### UI - **AdminRolesSummaryWidget** — Tenant dashboard card showing last scan time, high-privilege assignment count, scan trigger button - RBAC-gated: `ENTRA_ROLES_VIEW` for viewing, `ENTRA_ROLES_MANAGE` for scan trigger ### Infrastructure - Graph contracts for `entraRoleDefinitions` + `entraRoleAssignments` - `config/entra_permissions.php` — Entra permission registry - `StoredReport.fingerprint` migration (deduplication support) - `OperationCatalog` label + duration for `entra.admin_roles.scan` - Artisan command `entra:scan-admin-roles` for CLI/scheduled use ### Global UX improvement - **SummaryCountsNormalizer**: Zero values filtered, snake_case keys humanized (e.g. `report_deduped: 1` → `Report deduped: 1`). Affects all operation notifications. ## Test Coverage - **12 test files**, **79+ tests**, **307+ assertions** - Report service, finding generator, job orchestration, widget rendering, alert integration, RBAC enforcement, badge mapping ## Spec artifacts - `specs/105-entra-admin-roles-evidence-findings/tasks.md` — Full task breakdown (38 tasks, all complete) - `specs/105-entra-admin-roles-evidence-findings/checklists/requirements.md` — All items checked ## Files changed 46 files changed, 3641 insertions(+), 15 deletions(-) Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #128
91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# 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`
|