ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
6b381e9517
TenantAtlas/specs/105-entra-admin-roles-evidence-findings/quickstart.md
Ahmed Darrazi d25290d95e plan: spec 105 — Entra Admin Roles Evidence + Findings 
Phase 0 research (R1-R10) + Phase 1 design artifacts:
- research.md: 10 decisions (fingerprint migration, Graph API, catalog, alerts)
- data-model.md: stored_reports migration, model/enum changes, new classes
- contracts/internal-services.md: 3 service + job contracts
- quickstart.md: implementation guide with file list + test commands
- plan.md: 6-phase implementation plan (A-F) with constitution check

Agent context: copilot-instructions.md updated
2026-02-22 00:15:34 +01: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