94 lines
5.3 KiB
Markdown
94 lines
5.3 KiB
Markdown
# Feature Specification: Enable Endpoint Security Policy Restore (023)
|
|
|
|
**Feature Branch**: `feat/023-endpoint-security-restore`
|
|
**Created**: 2026-01-03
|
|
**Status**: Implemented (ready to merge)
|
|
**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 **restore-mode enablement** with additional validation/testing and targeted restore hardening, 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
|