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
3.9 KiB
3.9 KiB
Specification Quality Checklist: Entra Admin Roles Evidence + Findings
Purpose: Validate specification completeness and quality before proceeding to implementation Created: 2026-02-21 Last Validated: 2026-02-22 (post-analysis remediation) Feature: spec.md
Content Quality
- No implementation details (languages, frameworks, APIs) in user stories
- Focused on user value and business needs
- Written for non-technical stakeholders (user stories section)
- All mandatory sections completed (Scope Fields, User Scenarios, Requirements, Success Criteria, UI Action Matrix)
Requirement Completeness
- No [NEEDS CLARIFICATION] markers remain
- Requirements are testable and unambiguous (21 FRs, each with MUST + verifiable condition)
- Success criteria are measurable (SC-001 through SC-008 with quantitative metrics)
- Success criteria are technology-agnostic (no framework/language references)
- All acceptance scenarios are defined (6 user stories with 18 total acceptance scenarios)
- Edge cases are identified (8 documented: partial data, service principals, group-assigned roles, scoped assignments, missing template_id, zero assignments, concurrent scans, threshold hardcode)
- Scope is clearly bounded (Non-Goals section: no PIM, no remediation, no EvidenceItems, no RBAC refactor)
- Dependencies and assumptions identified (Spec 104, Spec 099, Findings model, Graph RBAC API, no PIM, StoredReports retention)
Feature Readiness
- All functional requirements have clear acceptance criteria (FRs map to acceptance scenarios in user stories)
- User scenarios cover primary flows (scan → report → findings → alerts → UI)
- Feature meets measurable outcomes defined in Success Criteria
- No implementation details leak into specification (entities section describes domain concepts, not code)
Spec ↔ Plan ↔ Tasks Consistency (post-analysis)
- No stale clarifications contradict plan/tasks (I1 remediated: migration Q&A corrected)
- All 21 FRs have ≥1 implementation task (FR-021 is test-only; T035 confirms viewer rendering assumption first)
- All success criteria are testable by ≥1 task (SC-005 now covered by T028(5); SC-006 backed by retention assumption; SC-008 deferred to staging)
- Edge case: scoped assignments tested (T025(15) added)
- Edge case: group = 1 principal tested (T025(11) covers principal types including group)
- Posture score impact tested (T028(5) added)
- Phase dependency D1 noted as advisory — US4 can start after Phase 2 (not blocked on Phase 4)
Constitution Alignment
- Constitution alignment (required) — Graph contracts, safety gates, tenant isolation, run observability, tests
- Constitution alignment (RBAC-UX) — authorization planes, 404/403 semantics, capability registry, authorization tests
- Constitution alignment (OPS-EX-AUTH-001) — N/A documented
- Constitution alignment (BADGE-001) — new finding type badge documented with test (T014)
- Constitution alignment (Filament Action Surfaces) — UI Action Matrix completed; widget exemption documented
- Constitution alignment (UX-001) — Exemption for no new Create/Edit pages documented
Notes
- All items pass. Spec + plan + tasks are consistent and ready for
/speckit.implement. - Plan.md and tasks.md have been written and validated against spec.
- High-Privilege Role Catalog includes Microsoft well-known template IDs for v1 classification.
- "Too many Global Admins" threshold is hardcoded at 5 with documented TODO for settings migration.
- SC-008 (scan performance ≤30s / 200 assignments) is not testable in standard Pest suite — validate on staging.
- FR-021 (report viewer) assumes existing viewer handles
entra.admin_rolespayload; T035 confirms this first. - StoredReports retention (default 90 days) is assumed to be handled by existing infrastructure (documented in Assumptions).