6.4 KiB
Feature Specification: Scripts Management
Feature Branch: 013-scripts-management
Created: 2026-01-01
Status: Draft
Input: User description: "Add end-to-end support for management scripts (Windows PowerShell scripts, macOS shell scripts, and proactive remediations) including readable normalized settings, backup snapshots, and safe restore with assignments."
User Scenarios & Testing (mandatory)
User Story 1 - Restore a script safely (Priority: P1)
As an admin, I want to restore a script policy from a saved snapshot so I can recover from accidental or unwanted changes.
Why this priority: Restoring known-good configuration is the core safety value of the product.
Independent Test: Can be fully tested by restoring one script policy into a tenant where the script is missing or changed, and verifying the script and its assignments match the snapshot.
Acceptance Scenarios:
- Given a saved script snapshot and a target tenant where the script does not exist, When I run restore for that item, Then the system creates a new script policy from the snapshot and reports success.
- Given a saved script snapshot and a target tenant where the script exists with differences, When I run restore for that item, Then the system updates the existing script policy to match the snapshot and reports success.
- Given a saved script snapshot with assignments, When I run restore, Then the system applies the assignments using the snapshot data and reports assignment outcomes.
User Story 2 - Readable script configuration (Priority: P2)
As an admin, I want to view a readable, normalized representation of a script policy so I can understand what it does and compare versions reliably.
Why this priority: If admins cannot quickly understand changes, version history and restore become risky and slow.
Independent Test: Can be tested by opening a script policy version page and confirming that normalized settings display key fields consistently across versions.
Acceptance Scenarios:
- Given a script policy version, When I open the policy version details, Then I see a normalized settings view that is stable (same input yields same output ordering/shape).
- Given two versions of the same script policy with changes, When I view their normalized settings, Then the differences are visible without reading raw JSON.
User Story 3 - Reliable backup capture (Priority: P3)
As an admin, I want backups/version snapshots of script policies to be captured reliably so I can restore later with confidence.
Why this priority: Restore is only as good as the snapshot quality.
Independent Test: Can be tested by capturing a snapshot of each script policy type and validating it contains the expected configuration fields for that policy.
Acceptance Scenarios:
- Given an existing script policy, When I capture a snapshot/backup, Then the saved snapshot contains the complete configuration needed to restore the script policy.
[Add more user stories as needed, each with an assigned priority]
Edge Cases
- Restoring a snapshot whose policy type does not match the target item (type mismatch) must fail clearly without making changes.
- Restoring when the snapshot contains fields that are not accepted by the target environment must result in a clear failure reason and no partial silent data loss.
- Assignments referencing groups or foundations that cannot be mapped must be reported as manual-required for those assignments.
- Script policies with very large or complex configuration should still render a readable normalized settings view (with safe truncation if needed).
Requirements (mandatory)
Functional Requirements
- FR-001: System MUST support listing and viewing script policies for the supported script policy types.
- FR-002: System MUST allow capturing a snapshot of a script policy that is sufficient to restore the policy later.
- FR-003: System MUST allow restoring a script policy from a snapshot in a safe manner (create when missing; update when present).
- FR-004: System MUST support restoring assignments for script policies using the assignments saved with the snapshot.
- FR-005: System MUST present a readable normalized settings view for script policies and script policy versions.
- FR-006: System MUST prevent execution of restore if the snapshot policy type does not match the restore item type.
- FR-007: System MUST record an audit trail for restore preview and restore execution attempts.
Key Entities (include if feature involves data)
- Script Policy: A configuration object representing a management script (platform-specific variants), identified by a stable external identifier and a display name.
- Script Policy Snapshot: An immutable capture of a script policy’s configuration at a point in time, used for diffing and restore.
- Script Assignment: A target association that applies a script policy to a defined scope (e.g., groups/filters), stored with the snapshot and restored with mapping when needed.
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: An admin can complete a restore preview for a single script policy in under 1 minute.
- SC-002: In a test tenant, restoring a script policy results in the target script policy and assignments matching the snapshot for 100% of supported script policy types.
- SC-003: Normalized settings for a script policy are readable and stable: repeated views of the same snapshot produce identical normalized output.
- SC-004: Restore failures provide a clear reason (actionable message) in 100% of failure cases.