ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
e15eee8f26
TenantAtlas/specs/105-entra-admin-roles-evidence-findings/quickstart.md
ahmido 6a15fe978a feat: Spec 105 — Entra Admin Roles Evidence + Findings (#128) 
## 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
2026-02-22 02:37:36 +00:00

4.4 KiB
Raw Blame History

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

# 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