TenantAtlas/specs/023-endpoint-security-restore/spec.md

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