d25290d95e
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
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`
|