ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

spec: add 007 device config & compliance spec

Browse Source
This commit is contained in:
Ahmed Darrazi 2025-12-27 01:22:45 +01:00
parent d2dbc52a32
commit ba468de486
3 changed files with 231 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
specs/007-device-config-compliance/plan.md Normal file
View File

@ -0,0 +1,79 @@
# Implementation Plan: Device Configuration and Compliance Coverage
**Branch**: `007-device-config-compliance` | **Date**: 2025-12-26 | **Spec**: ./spec.md
**Input**: Feature specification from `/specs/007-device-config-compliance/spec.md`
## Summary
Expand backup and restore coverage for device configuration, compliance, scripts, and update rings. This plan focuses on policy type coverage, assignment capture, and safe restore behavior using existing foundation mappings and assignment logic.
Phase outputs:
- Phase 0 research: n/a (no new research artifact yet)
- Phase 1 design: n/a (no new data model artifact yet)
## Technical Context
**Language/Version**: PHP 8.4 (Laravel 12)
**Primary Dependencies**: Laravel 12, Filament v4, Livewire v3, Microsoft Graph (custom client abstraction)
**Storage**: PostgreSQL (JSONB payload storage for snapshots)
**Testing**: Pest v4 + PHPUnit 12
**Target Platform**: Docker/Sail locally; container deploy via Dokploy
**Project Type**: Web application (Laravel backend + Filament admin UI)
**Performance Goals**: Restore preview for 100 selected items in under 2 minutes
**Constraints**: Restore must be defensive (no deletions); assignments only applied with valid mapping; audit logs required
**Scale/Scope**: Tenants with mixed configuration and compliance policies, including scripts and update rings
## Constitution Check
The constitution at `.specify/memory/constitution.md` is currently an unfilled template. For this feature, adopt the repo rules as gates:
- Sail-first local dev/test commands.
- Spec gate: code changes must be accompanied by `specs/007-device-config-compliance/` updates.
- Tests required for behavior changes (Pest).
- Restore safety: never delete; skip unsafe assignments; record reasons.
- Auditability: backup and restore outcomes are logged per tenant.
## Project Structure
### Documentation (this feature)
```text
specs/007-device-config-compliance/
├── spec.md
├── plan.md
└── tasks.md
```
### Source Code (expected touch points)
```text
app/
├── Filament/
│ └── Resources/
├── Models/
│ ├── BackupItem.php
│ ├── Policy.php
│ └── PolicyVersion.php
├── Services/
│ ├── Graph/
│ └── Intune/
└── Jobs/
config/
├── graph_contracts.php
├── intune_permissions.php
└── tenantpilot.php
tests/
├── Feature/
└── Unit/
```
**Structure Decision**: Extend existing services (PolicySnapshotService, PolicyCaptureOrchestrator, RestoreService) and Filament resources, adding only targeted helpers where needed.
## Complexity Tracking
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| n/a | n/a | n/a |

78
specs/007-device-config-compliance/spec.md Normal file
View File

@ -0,0 +1,78 @@
# Feature Specification: Device Configuration and Compliance Coverage
**Feature Branch**: `007-device-config-compliance`
**Created**: 2025-12-26
**Status**: Draft
**Input**: Workload list for Intune backup and restore coverage (MVP vs full scope).
## Program Scope Reference (MVP vs Full)
### MVP Scope (Phase 1)
- Device configuration and compliance: administrative templates; settings catalog policies; device configurations (including custom OMA-URI); device compliance policies; assignments.
- Scripts and remediations: PowerShell scripts (Windows); macOS shell scripts (where supported); proactive remediations and assignments.
- Enrollment and Autopilot: Autopilot deployment profiles and assignments; Enrollment Status Page (ESP) if used.
- Update management (Windows): software update rings and assignments.
- Endpoint security: endpoint security configurations (antivirus, firewall, disk encryption, EDR, ASR, account protection) and assignments.
- Tenant administration foundations: assignment filters; scope tags; notification message templates.
### Full Scope (Phase 2+)
- Compliance actions and notifications: actions for noncompliance; compliance notifications and templates.
- Apps and app management: client apps; app protection policies; app configuration policies; assignments; supersedence metadata.
- Enrollment: enrollment restrictions; enrollment notifications; terms and conditions; ADE tokens and profiles.
- Update management: feature update policies; quality update policies; driver update policies; expedite/hotpatch policies.
- Endpoint security: security baselines (Windows security baseline, Microsoft Defender, Microsoft Edge); endpoint privilege management policies.
- Tenant administration: device cleanup rules; RBAC roles and role assignments.
- Connectors and tokens (metadata-only): APNs; VPP tokens; managed Google Play; certificate connectors; remote help settings.
## Overview
Expand backup and restore coverage for device configuration and compliance workloads, including scripts and remediations. This feature focuses on policy types that are already core to DR and rollback, and builds on existing foundations and assignment mapping capabilities.
## User Scenarios and Testing (mandatory)
### User Story 1 - Backup and Restore Core Configuration Policies (Priority: P1)
As an admin, I want to back up and restore device configuration and compliance policies with their assignments and scope tags, so that a restore reproduces targeting accurately.
**Independent Test**: Select at least one settings catalog policy, one device configuration policy (including an OMA-URI policy), and one device compliance policy. Create a backup with assignments and scope tags enabled. Restore into a tenant with different group IDs and verify assignments are mapped or skipped with clear reasons.
**Acceptance Scenarios**:
1. Given policies with assignments and scope tags, when a backup is captured, then assignments and scope tag metadata are stored alongside the snapshot.
2. Given a restore run with group mapping, when policies are restored, then assignments are applied using mapped group IDs and assignment filters.
3. Given missing mappings, when restore executes, then assignments are skipped and a human readable reason is recorded.
### User Story 2 - Compliance Actions and Notifications (Priority: P2)
As an admin, I want actions for noncompliance and compliance notification templates to be captured and restored, so that compliance workflows remain intact after restore.
**Independent Test**: Create a compliance policy with scheduled actions and a notification template. Capture a backup including foundations. Restore into a tenant without that template and verify the template is created and referenced correctly.
**Acceptance Scenarios**:
1. Given a compliance policy referencing a notification template, when restore executes, then the template is restored first and the policy references the mapped template ID.
2. Given a missing template and no mapping, when restore executes, then the policy is restored without that action and a skip reason is recorded.
### User Story 3 - Scripts and Remediations (Priority: P3)
As an admin, I want scripts and remediations to be captured and restored with assignments, so that endpoint automation is preserved.
**Independent Test**: Capture a PowerShell script and a proactive remediation with assignments. Restore into a test tenant and verify assignments are applied safely.
**Acceptance Scenarios**:
1. Given a script policy with assignments, when restore executes, then the script is recreated or updated and assignments are applied.
2. Given a remediation with missing assignment filter mapping, when restore executes, then the assignment is skipped and the remediation is still restored.
## Requirements (mandatory)
### Functional Requirements
- **FR-007.1**: System MUST support backup and restore for administrative templates, settings catalog policies, device configurations (including OMA-URI), and device compliance policies.
- **FR-007.2**: System MUST capture assignments and scope tags when the backup flags are enabled, using the existing capture orchestrator.
- **FR-007.3**: System MUST handle compliance actions and notification templates by restoring templates first and mapping references in policies.
- **FR-007.4**: System MUST restore scripts and remediations with assignments, applying foundation mappings and group mappings where available.
- **FR-007.5**: System MUST keep Conditional Access restore preview-only until identity dependency mapping is supported.
- **FR-007.6**: System MUST record audit logs for backup and restore actions, including skipped assignments and template mapping outcomes.
### Non-Goals
- No support for app workloads in this feature (tracked separately).
- No connector or token restore (metadata-only handled in a later phase).
## Success Criteria (mandatory)
- **SC-007.1**: For a backup containing at least 10 mixed configuration/compliance items, restore completes with 100% of items in Applied, Partial, or Skipped with reason (no silent failures).
- **SC-007.2**: At least 95% of assignments in a mixed restore are either applied successfully or explicitly skipped with a recorded reason.
- **SC-007.3**: Restore preview for 100 selected items completes in under 2 minutes in a typical admin environment.

74
specs/007-device-config-compliance/tasks.md Normal file
View File

@ -0,0 +1,74 @@
# Tasks: Device Configuration and Compliance Coverage (007)
**Branch**: `feat/007-device-config-compliance` | **Date**: 2025-12-26
**Input**: [spec.md](./spec.md), [plan.md](./plan.md)
## Task Format
- **Checkbox**: `- [ ]` for incomplete, `- [x]` for complete
- **Task ID**: Sequential T001, T002, T003...
- **[P] marker**: Task can run in parallel (different files, no blocking dependencies)
- **[Story] label**: User story tag (US1, US2, US3...)
- **File path**: Always include exact file path in description
## Phase 1: Policy Types, Contracts, Permissions
**Purpose**: Add missing device configuration, compliance, scripts, and update ring types with Graph contract coverage.
- [ ] T001 [P] Expand policy type registry for device configuration, compliance, scripts, and update rings in `config/tenantpilot.php` (labels, categories, restore mode, risk).
- [ ] T002 [P] Add/update Graph contracts and assignment endpoints for new policy types in `config/graph_contracts.php`.
- [ ] T003 [P] Verify and extend permissions for the new workloads in `config/intune_permissions.php`.
- [ ] T004 Update type metadata helpers and filters in `app/Filament/Resources/PolicyResource.php` and `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`.
**Checkpoint**: New policy types are recognized across UI metadata and Graph contract registry.
---
## Phase 2: Snapshot Capture and Metadata
**Purpose**: Ensure snapshots, assignments, and scope tags are captured for the new workloads.
- [ ] T005 Update `app/Services/Intune/PolicySnapshotService.php` to fetch and hydrate the new policy types correctly (filters, select fields).
- [ ] T006 Extend `app/Services/Intune/PolicyCaptureOrchestrator.php` to capture assignments and scope tags for the new types with existing resolvers.
- [ ] T007 Update `app/Services/Intune/BackupService.php` to capture snapshots for the new types and propagate warnings.
- [ ] T008 Add or extend normalization support in `app/Services/Intune/PolicyNormalizer.php` for the new policy types.
**Checkpoint**: Backups include snapshots and metadata for configuration/compliance policies.
---
## Phase 3: Restore Logic and Mapping
**Purpose**: Restore new policy types safely using assignment and foundation mappings.
- [ ] T009 Update `app/Services/Intune/RestoreService.php` to restore the new policy types using Graph contracts.
- [ ] T010 Extend `app/Services/AssignmentRestoreService.php` for assignment endpoints of the new types.
- [ ] T011 Ensure compliance notification templates are restored and referenced via mapping in `app/Services/Intune/RestoreService.php`.
- [ ] T012 Add audit coverage for compliance action mapping outcomes in `app/Services/Intune/AuditLogger.php`.
**Checkpoint**: Restore applies policies and assignments or skips with clear reasons.
---
## Phase 4: Admin UX
**Purpose**: Surface restore and compliance details clearly in the UI.
- [ ] T013 Update `resources/views/filament/infolists/entries/restore-preview.blade.php` to surface compliance action/template warnings.
- [ ] T014 Update `resources/views/filament/infolists/entries/restore-results.blade.php` to show compliance action mapping outcomes and skip reasons.
**Checkpoint**: Admins can see compliance related mapping results in preview and results.
---
## Phase 5: Tests and Verification
**Purpose**: Cover new workloads with Pest tests and verify formatting.
- [ ] T015 Add unit tests for snapshot and normalization coverage in `tests/Unit/PolicySnapshotServiceTest.php` and `tests/Unit/PolicyNormalizerTest.php`.
- [ ] T016 Add feature tests for backup and restore flows in `tests/Feature/Filament/RestorePreviewTest.php` and `tests/Feature/Filament/RestoreExecutionTest.php`.
- [ ] T017 Run tests: `./vendor/bin/sail artisan test tests/Unit/PolicySnapshotServiceTest.php tests/Unit/PolicyNormalizerTest.php tests/Feature/Filament/RestorePreviewTest.php tests/Feature/Filament/RestoreExecutionTest.php`
- [ ] T018 Run Pint: `./vendor/bin/pint --dirty`
**Checkpoint**: Tests pass and formatting is clean.