ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
b6e376e875
TenantAtlas/specs/105-entra-admin-roles-evidence-findings/plan.md

8.5 KiB
Raw Blame History

Plan — 105 Entra Admin Roles Evidence + Findings

Feature Branch: 105-entra-admin-roles-evidence-findings Created: 2026-02-21 Depends on: Spec 104 (stored_reports, posture patterns), Alerts v1 (099), Findings + OperationRuns

Phase 1 — Infrastructure & Permissions Registry

1.1 Add Entra required permissions registry

  • Create config/entra_permissions.php following config/intune_permissions.php schema.
  • Declare RoleManagement.Read.Directory (type: application, features: ['entra-admin-roles']).
  • Optionally: Directory.Read.All as fallback entry (type: application, features: ['entra-admin-roles']).

1.2 Merge registry loader

  • Locate where config('intune_permissions.permissions') is loaded (TenantPermissionService or equivalent).
  • Extend the loader to also read config('entra_permissions.permissions') and merge into the combined required-permissions list.
  • Existing Intune posture flows must remain unchanged (no breaking change).
  • Add test: registry merger returns combined set; existing tests still pass.

1.3 Register Graph endpoints in config/graph_contracts.php

  • Add entries for:
    • GET /roleManagement/directory/roleDefinitions
    • GET /roleManagement/directory/roleAssignments?$expand=principal
  • Follow existing contract registration patterns (endpoint key, method, URI, scopes).

1.4 Add RBAC capabilities

  • Add to App\Support\Auth\Capabilities:
    • ENTRA_ROLES_VIEW = 'entra_roles.view'
    • ENTRA_ROLES_MANAGE = 'entra_roles.manage'
  • Update role-to-capability mapping:
    • Readonly/Operator → ENTRA_ROLES_VIEW
    • Manager/Owner → ENTRA_ROLES_VIEW + ENTRA_ROLES_MANAGE

1.5 Add OperationRunType case

  • Add EntraAdminRolesScan = 'entra.admin_roles.scan' to App\Support\OperationRunType enum.

Phase 2 — Core Services

2.1 Implement HighPrivilegeRoleCatalog

  • Create App\Services\EntraAdminRoles\HighPrivilegeRoleCatalog.
  • Hardcoded mapping of template_id → (display_name, severity).
  • Public methods:
    • isHighPrivilege(string $templateId, ?string $displayName): bool
    • severityFor(string $templateId, ?string $displayName): ?string
    • allTemplateIds(): array
    • globalAdminTemplateId(): string
  • Fallback: if template_id not in catalog, check display_name.
  • Full unit test coverage.

2.2 Implement EntraAdminRolesReportService

  • Create App\Services\EntraAdminRoles\EntraAdminRolesReportService.
  • Responsibilities:
    1. Fetch roleDefinitions via Graph (using registered contract).
    2. Fetch roleAssignments?$expand=principal via Graph.
    3. Build payload per spec (role_definitions, role_assignments, totals, high_privilege).
    4. Compute fingerprint: SHA-256 of sorted (role_template_or_id, principal_id, scope_id) tuples.
    5. Determine previous_fingerprint from latest existing report for this tenant.
    6. Dedupe: if current fingerprint == latest report's fingerprint, skip creation.
    7. Create StoredReport with report_type=entra.admin_roles.
  • Add REPORT_TYPE_ENTRA_ADMIN_ROLES = 'entra.admin_roles' constant to StoredReport model.
  • Tests: report creation, dedupe, fingerprint computation, previous_fingerprint chaining.

2.3 Implement EntraAdminRolesFindingGenerator

  • Create App\Services\EntraAdminRoles\EntraAdminRolesFindingGenerator.
  • Responsibilities:
    1. Accept report payload (or structured DTO).
    2. For each role assignment where role is high-privilege (per HighPrivilegeRoleCatalog):
      • Compute fingerprint: entra_admin_role:{tenant_id}:{role_template_or_id}:{principal_id}:{scope_id}
      • Upsert finding: finding_type=entra_admin_roles, source=entra.admin_roles
      • Set severity per catalog (critical for GA, high otherwise)
      • Populate evidence_jsonb with role, principal, scope details
      • Update times_seen, last_seen_at on existing findings
    3. Aggregate check: count GA principals > threshold (5) → aggregate finding with distinct fingerprint.
    4. Auto-resolve: query open findings for this tenant+source not in current scan's fingerprint set → resolve.
    5. Re-open: if a resolved finding's fingerprint matches current data → set status=new, clear resolved fields.
    6. Collect alert events for new/re-opened findings.
  • Add FINDING_TYPE_ENTRA_ADMIN_ROLES = 'entra_admin_roles' constant to Finding model.
  • Tests: creation, idempotency, auto-resolve, re-open, aggregate finding, alert events.

Phase 3 — Job & Scheduling

3.1 Implement ScanEntraAdminRolesJob

  • Create App\Jobs\EntraAdminRoles\ScanEntraAdminRolesJob (implements ShouldQueue).
  • Lifecycle:
    1. Check tenant has provider connection; skip if not.
    2. Create OperationRun (entra.admin_roles.scan, status=running).
    3. Call EntraAdminRolesReportService::generate().
    4. Call EntraAdminRolesFindingGenerator::generate().
    5. Dispatch alert events via AlertDispatchService.
    6. Mark OperationRun completed (success/failure with error details).
  • Active-run uniqueness: check for existing running OperationRun before starting.
  • Tests: job dispatching, OperationRun lifecycle, skip on no connection, failure handling.

3.2 Add to workspace dispatcher

  • Register ScanEntraAdminRolesJob in the daily workspace dispatch schedule.
  • Same pattern as existing scheduled scans: iterate tenants with active connections, dispatch per tenant.

Phase 4 — Alerts Integration

4.1 Add alert event type

  • Add constant EVENT_ENTRA_ADMIN_ROLES_HIGH = 'entra.admin_roles.high' to AlertRule model.
  • Add to event type options array (used in alert rule form dropdown).

4.2 Extend EvaluateAlertsJob

  • Add a new producer section in EvaluateAlertsJob that:
    • Queries findings where source=entra.admin_roles, severity>=high, status in (new).
    • Produces events with event_type=entra.admin_roles.high.
    • Uses finding fingerprint as fingerprint_key for cooldown/dedupe.
  • Tests: alert rule matching, delivery creation, cooldown.

Phase 5 — Badge Catalog

5.1 Add entra_admin_roles to FindingTypeBadge

  • Extend App\Support\Badges\Domains\FindingTypeBadge mapper with:
    • Finding::FINDING_TYPE_ENTRA_ADMIN_ROLES => new BadgeSpec('Entra admin roles', 'danger', 'heroicon-m-shield-exclamation')
  • Test: badge renders correctly for new type.

Phase 6 — UI

6.1 Tenant card widget "Admin Roles"

  • Create a Livewire/Filament widget for the tenant dashboard.
  • Displays: last scan timestamp, high-privilege assignment count.
  • CTA: "Scan now" (visible only if user has ENTRA_ROLES_MANAGE).
  • Link: "View latest report" (stored reports viewer filtered by entra.admin_roles).
  • Empty state: "No scan performed" + gated "Scan now" CTA.

6.2 Report viewer enhancements

  • Extend existing stored reports viewer to handle report_type=entra.admin_roles:
    • Summary section showing totals.
    • Table of high-privilege role assignments (principal display name, type, role, scope).
  • Filter by report_type on report listing.

Phase 7 — Tests

7.1 Unit tests

  • HighPrivilegeRoleCatalog: classification by template_id, fallback to display_name, unknown role returns false.
  • EntraAdminRolesReportService: report creation, fingerprint computation, dedupe, previous_fingerprint.
  • EntraAdminRolesFindingGenerator: finding creation, severity assignment, idempotent upsert, auto-resolve, re-open, aggregate finding.
  • Registry merge: combined Intune + Entra permissions.

7.2 Feature tests

  • ScanEntraAdminRolesJob: full lifecycle (report + findings + alerts), skip unconnected, failure handling.
  • Alerts: event type matching, delivery creation, cooldown.
  • RBAC: ENTRA_ROLES_VIEW can view; ENTRA_ROLES_MANAGE can scan; missing capability → 403; non-member → 404.

7.3 Posture integration smoke test

  • With Entra permissions in merged registry, posture generator includes them in score calculation.

7.4 Run full suite

  • vendor/bin/sail artisan test --compact — all tests green.
  • vendor/bin/sail bin pint --dirty — code style clean.

Filament v5 Compliance Notes

  1. Livewire v4.0+: All widget components are Livewire v4 compatible.
  2. Provider registration: No new panel providers — existing admin panel in bootstrap/providers.php.
  3. Global search: No new globally searchable resources.
  4. Destructive actions: "Scan now" is non-destructive (read-only Graph call); no requiresConfirmation() needed.
  5. Asset strategy: No new heavy assets. Widget uses standard Filament components.
  6. Testing plan: Widget tested as Livewire component; finding generator + report service unit tested; job feature tested; RBAC positive/negative tests included.