From d6a57c1828d784431831665bc6edd4087684ec40 Mon Sep 17 00:00:00 2001 From: ahmido Date: Sat, 3 Jan 2026 03:27:28 +0000 Subject: [PATCH] feat/023-endpoint-security-restore (#24) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary ## Spec-Driven Development (SDD) - [ ] Es gibt eine Spec unter `specs/-/` - [ ] Enthaltene Dateien: `plan.md`, `tasks.md`, `spec.md` - [ ] Spec beschreibt Verhalten/Acceptance Criteria (nicht nur Implementation) - [ ] Wenn sich Anforderungen während der Umsetzung geändert haben: Spec/Plan/Tasks wurden aktualisiert ## Implementation - [ ] Implementierung entspricht der Spec - [ ] Edge cases / Fehlerfälle berücksichtigt - [ ] Keine unbeabsichtigten Änderungen außerhalb des Scopes ## Tests - [ ] Tests ergänzt/aktualisiert (Pest/PHPUnit) - [ ] Relevante Tests lokal ausgeführt (`./vendor/bin/sail artisan test` oder `php artisan test`) ## Migration / Config / Ops (falls relevant) - [ ] Migration(en) enthalten und getestet - [ ] Rollback bedacht (rückwärts kompatibel, sichere Migration) - [ ] Neue Env Vars dokumentiert (`.env.example` / Doku) - [ ] Queue/cron/storage Auswirkungen geprüft ## UI (Filament/Livewire) (falls relevant) - [ ] UI-Flows geprüft - [ ] Screenshots/Notizen hinzugefügt ## Notes Co-authored-by: Ahmed Darrazi Reviewed-on: https://git.cloudarix.de/ahmido/TenantAtlas/pulls/24 --- .../checklists/requirements.md | 14 +++ specs/023-endpoint-security-restore/plan.md | 32 +++++++ specs/023-endpoint-security-restore/spec.md | 93 +++++++++++++++++++ specs/023-endpoint-security-restore/tasks.md | 32 +++++++ 4 files changed, 171 insertions(+) create mode 100644 specs/023-endpoint-security-restore/checklists/requirements.md create mode 100644 specs/023-endpoint-security-restore/plan.md create mode 100644 specs/023-endpoint-security-restore/spec.md create mode 100644 specs/023-endpoint-security-restore/tasks.md diff --git a/specs/023-endpoint-security-restore/checklists/requirements.md b/specs/023-endpoint-security-restore/checklists/requirements.md new file mode 100644 index 0000000..2da1d80 --- /dev/null +++ b/specs/023-endpoint-security-restore/checklists/requirements.md @@ -0,0 +1,14 @@ +# Requirements Checklist (023) + +**Created**: 2026-01-03 +**Feature**: [spec.md](../spec.md) + +- [ ] `endpointSecurityPolicy.restore` is changed to `enabled` in `config/tenantpilot.php`. +- [ ] Restore preview validates template existence and reports missing/ambiguous templates. +- [ ] Restore execution blocks on missing/ambiguous templates with a clear, actionable error message. +- [ ] Settings instances are validated against resolved template definitions before execution. +- [ ] Template mapping strategy is defined for cross-tenant differences (if required) and is tested. +- [ ] Restore create + update paths for Endpoint Security policies are covered by automated tests. +- [ ] Assignments mapping/application for Endpoint Security policies are covered by automated tests. +- [ ] Audit log entries exist for restore execution attempts (success and failure). + diff --git a/specs/023-endpoint-security-restore/plan.md b/specs/023-endpoint-security-restore/plan.md new file mode 100644 index 0000000..c843861 --- /dev/null +++ b/specs/023-endpoint-security-restore/plan.md @@ -0,0 +1,32 @@ +# Plan: Endpoint Security Policy Restore (023) + +**Branch**: `feat/023-endpoint-security-restore` +**Date**: 2026-01-03 +**Input**: [spec.md](./spec.md) + +## Goal +Enable full restore execution for Endpoint Security Policies (`endpointSecurityPolicy`) instead of preview-only, with defensive validation around templates and settings payloads. + +## Approach +1. Enable restore execution in `config/tenantpilot.php` by switching `endpointSecurityPolicy.restore` from `preview-only` to `enabled`. +2. Add template existence validation during restore preview: + - Resolve the snapshot’s `templateReference` (family/id/display name where available). + - Confirm the referenced template is resolvable in the target tenant before execution. + - Surface warnings in preview and fail execution with a clear error when missing. +3. Add settings instance validation prior to execution: + - Resolve template definitions for the target tenant. + - Validate that settings instances are structurally compatible with the resolved template. + - Treat validation failures as preview warnings, and block execution when the payload cannot be made safe. +4. Ensure restore uses the existing generic configuration policy create/update flow: + - Create when no match exists; update when matched (per existing restore matching rules). + - Apply assignments using existing mapping logic. +5. Add targeted tests covering: + - Create + update restore execution for `endpointSecurityPolicy`. + - Preview warnings and execution failure when template is missing. + - Settings validation failure paths. + - Assignment application expectations. + +## Decisions / Notes +- Assume template identifiers may differ across tenants; prefer mapping by `templateFamily` with display-name fallback when required. +- Safety-first: if template resolution is ambiguous, treat as missing and block execution. + diff --git a/specs/023-endpoint-security-restore/spec.md b/specs/023-endpoint-security-restore/spec.md new file mode 100644 index 0000000..81b3fd5 --- /dev/null +++ b/specs/023-endpoint-security-restore/spec.md @@ -0,0 +1,93 @@ +# Feature Specification: Enable Endpoint Security Policy Restore (023) + +**Feature Branch**: `feat/023-endpoint-security-restore` +**Created**: 2026-01-03 +**Status**: Draft +**Priority**: P1 (Quick Win) + +## Context +Endpoint Security Policies are already in the `tenantpilot.php` config as `endpointSecurityPolicy` with `restore => 'preview-only'`. Based on Microsoft's recommendation to use the unified `deviceManagement/configurationPolicies` endpoint (over the deprecated `intents` API for new creations), we should enable full restore for this type. + +This is a **configuration-only change** with additional validation/testing, not a new policy type implementation. + +## User Scenarios & Testing + +### User Story 1 — Restore Endpoint Security Policies (Priority: P1) +As an admin, I want to restore Endpoint Security Policies (Firewall, Defender, ASR, BitLocker, etc.) from backup, so I can recover from configuration errors or replicate security baselines across tenants. + +**Why this priority**: These are high-impact security policies; restore is a core safety feature. + +**Independent Test**: Restore an Endpoint Security Policy snapshot; verify settings and assignments are applied correctly. + +**Acceptance Scenarios** +1. Given an Endpoint Security Policy snapshot (e.g., Firewall), when I restore to a tenant without that policy, then a new policy is created with matching settings. +2. Given an Endpoint Security Policy snapshot, when I restore to a tenant with an existing policy (name match), then the policy is updated. +3. Given such a policy has assignments, when I restore, then assignments are mapped and applied. + +### User Story 2 — Template Validation (Priority: P1) +As an admin, I want clear warnings if an Endpoint Security template is not available in the target tenant, so I understand restore limitations. + +**Why this priority**: Templates are version-dependent; missing templates must be surfaced. + +**Independent Test**: Attempt to restore a policy referencing a template not present in target; verify preview shows a warning. + +**Acceptance Scenarios** +1. Given a policy snapshot references a template ID, when I restore to a tenant without that template, then preview warns about missing template. +2. Given such a scenario, when I execute restore, then the operation fails gracefully with a clear error message. + +### User Story 3 — Settings Instance Consistency (Priority: P2) +As an admin, I want settings instances to be validated against template definitions, so restored policies are valid. + +**Why this priority**: Settings must match template structure; invalid settings break policies. + +**Independent Test**: Restore a policy with settings; verify Graph API accepts the settings payload. + +**Acceptance Scenarios** +1. Given a policy snapshot with settings, when I restore, then settings are validated before submission to Graph API. +2. Given settings validation detects structural issues, when running preview, then warnings indicate which settings may be problematic. + +## Requirements + +### Functional Requirements +- **FR-001**: Change `restore` value from `'preview-only'` to `'enabled'` for `endpointSecurityPolicy` in config +- **FR-002**: Add template existence validation in restore preview +- **FR-003**: Ensure settings instance validation against template structure +- **FR-004**: Update Graph contract for `endpointSecurityPolicy` if needed (may already exist) +- **FR-005**: Add template ID mapping (if templates have different IDs across tenants) +- **FR-006**: Add comprehensive restore tests for common Endpoint Security policy types: + - Antivirus (Defender) + - Firewall + - Disk Encryption (BitLocker) + - Attack Surface Reduction (ASR) + - Account Protection + +### Non-Functional Requirements +- **NFR-001**: Restore preview must complete within 5 seconds for typical policy +- **NFR-002**: Template validation must not significantly slow down preview +- **NFR-003**: All common Endpoint Security policy types must be covered by tests + +### Graph API Details +- **Endpoint**: `https://graph.microsoft.com/beta/deviceManagement/configurationPolicies` +- **Filter** (if needed): `templateReference/templateFamily eq 'endpointSecurity...'` +- **Template Families**: + - `endpointSecurityAntivirus` + - `endpointSecurityFirewall` + - `endpointSecurityDiskEncryption` + - `endpointSecurityAttackSurfaceReduction` + - `endpointSecurityAccountProtection` + - etc. +- **Required Permissions**: `DeviceManagementConfiguration.ReadWrite.All` + +### Known Considerations +- **Template Versioning**: Templates can evolve; settings structure may change +- **Platform Differences**: Some templates are Windows 10 only, others support Windows 11+ +- **Settings Validation**: Graph API will reject invalid settings; catch this in preview + +## Success Criteria +- **SC-001**: Config change applied: `endpointSecurityPolicy` has `restore => 'enabled'` +- **SC-002**: Restore preview shows accurate change summary for Endpoint Security policies +- **SC-003**: Restore executes successfully for common policy types (Firewall, Antivirus, BitLocker) +- **SC-004**: Template existence validation catches missing templates before execution +- **SC-005**: Settings instance validation prevents invalid payloads +- **SC-006**: No regressions in sync or backup for this policy type +- **SC-007**: Feature tests cover restore success and failure scenarios diff --git a/specs/023-endpoint-security-restore/tasks.md b/specs/023-endpoint-security-restore/tasks.md new file mode 100644 index 0000000..049479b --- /dev/null +++ b/specs/023-endpoint-security-restore/tasks.md @@ -0,0 +1,32 @@ +# Tasks: Endpoint Security Policy Restore (023) + +**Branch**: `feat/023-endpoint-security-restore` +**Date**: 2026-01-03 +**Input**: [spec.md](./spec.md), [plan.md](./plan.md) + +## Phase 1: Setup +- [x] T001 Create spec/plan/tasks and checklist. + +## Phase 2: Inventory & Design +- [ ] T002 Confirm current restore mode + code paths for `endpointSecurityPolicy` (`config/tenantpilot.php`, restore services). +- [ ] T003 Decide template resolution strategy (ID vs family/display name) and required Graph calls. +- [ ] T004 Define settings instance validation rules (warning vs block) for restore preview/execution. + +## Phase 3: Tests (TDD) +- [ ] T005 Add feature tests for restore execution create/update for `endpointSecurityPolicy`. +- [ ] T006 Add feature tests for preview warnings when template is missing. +- [ ] T007 Add feature tests asserting restore execution fails gracefully when template is missing. +- [ ] T008 Add tests for settings validation failure paths (invalid/unknown settings instances). +- [ ] T009 Add feature tests asserting assignments are applied for endpoint security policies. + +## Phase 4: Implementation +- [ ] T010 Enable restore for `endpointSecurityPolicy` in `config/tenantpilot.php`. +- [ ] T011 Implement template existence validation in restore preview and execution gating. +- [ ] T012 Implement settings instance validation against resolved template definitions. +- [ ] T013 Implement template mapping (if required) and ensure restore payload uses mapped template reference. +- [ ] T014 Ensure restore applies assignments for endpoint security policies using existing mapping logic. + +## Phase 5: Verification +- [ ] T015 Run targeted tests. +- [ ] T016 Run Pint (`./vendor/bin/pint --dirty`). +