Overview

The Windows Registry Policy lets you safely modify specific Windows Registry keys and values on managed Windows devices using Swif.

Admins can use this policy to:

Create or update registry values (for app or OS configuration)
Delete registry values that should no longer exist
Enforce desired registry state in an idempotent way (re‑runs do not keep rewriting compliant values)

This is useful when you want GPO‑like control or to replace manual scripts with a policy-driven approach.

Requirements

Administrator privileges on the target device
The Swif Windows agent must run with sufficient rights to modify the specified registry hives/paths.
Minimum OS: Windows 10 or later
Supported platform: Windows only

Policy type and structure

Policy display name: Windows Registry Policy
Policy type: WINDOWS_REGISTRY_POLICY

Fields

`rules` (required)

Type: array of objects
Description: List of registry modification rules to apply on the device.
Each rule describes one operation (ADD, REPLACE, or DELETE) against a specific registry path and value name.

Registry rule fields

Each item in the rules array has the following fields:

`path` (required)

Type: string
Description: Full registry path to the key you want to modify.
Examples:
- HKEY_LOCAL_MACHINE\\Software\\Company\\Product
- HKLM\\Software\\TestRegistry
- HKEY_CURRENT_USER\\Software\\Swif\\Settings
Notes:
- Must start with a valid hive prefix, for example:
  - HKEY_LOCAL_MACHINE or HKLM
  - HKEY_CURRENT_USER or HKCU
- The agent will handle key creation where needed for ADD/REPLACE operations (see behavior below).

`field` (optional but recommended for ADD/REPLACE)

Type: string
Description: Registry value name to set or delete under the specified key.
Examples:
- "field": "SwifValue"
- "field": "AutoUpdateEnabled"
Notes:
- If omitted and the key supports a default unnamed value, the operation may target that default value. For clarity and safety, Swif strongly recommends always providing a field name.
- For delete operations, this is the name of the value to remove.

`operation` (required)

Type: string
Description: The operation to perform on the registry value.
Allowed values:
- "ADD" – Create a new value if missing, or set it if it exists.
- "REPLACE" – Ensure the value exists with the specified data. If it doesn’t exist, it will be created.
- "DELETE" – Delete the value if it exists.
Default: "REPLACE" if not specified.
Behavior:
- ADD
  - Creates the key (if needed) and sets the value.
  - If the value already exists and is the same, it is treated as compliant (no unnecessary rewrite).
- REPLACE
  - Ensures the value’s data matches the desired state.
  - If current data is already equal, the rule is treated as compliant and skipped.
- DELETE
  - Deletes the specified value if present.
  - If it is already missing, the rule is treated as compliant/no-op.

Note: Internally, the Windows agent logs per-rule status such as:

SUCCESS - Created key and set value (type: REG_SZ)
SUCCESS - Deleted value successfully

`data` (optional, required for ADD/REPLACE)

Type: string
Description: The value data to write for ADD/REPLACE operations.
Examples:
- "data": "TestFromAgent123"
- "data": "0"
When required:
- Required for "ADD" and "REPLACE" operations.
- Ignored for "DELETE" operations.
Data type:
- The v1 implementation uses string values (e.g. REG_SZ) for testing and most use cases.
- Additional types such as REG_DWORD may be supported by interpreting the string (e.g. "1", "0"); consult your Swif contact if you have specific type requirements.

Behavior and enforcement details

How enforcement works

When a Windows device evaluates the Windows Registry Policy:

The agent downloads the policy and parses the rules array.
For each rule:
- Validates the hive and path.
- Applies the requested operation (ADD, REPLACE, DELETE).
- Ensures idempotence:
  - If the value already matches the desired state (for ADD/REPLACE), it is considered compliant and not rewritten repeatedly.
  - If the value is already missing (for DELETE), the rule is treated as compliant/no‑op.
The agent logs a result for each rule:
- SUCCESS
- FAILED (with error details like invalid path, access denied)
- SKIPPED (for certain error or no-op states)
Overall policy status is reported back to the Swif platform.

Permissions and safety

The agent requires sufficient privileges to modify the target hives (for example, HKLM changes typically require admin rights).
If the agent cannot modify a value (e.g., due to access denied or an invalid path), it:
- Logs the error locally.
- Reports the failure in the policy evaluation result so you can troubleshoot.
Swif performs server-side validation to:
- Reject clearly malformed registry definitions.
- Help protect against obviously unsafe patterns.

Example configurations

Create or update a registry value (ADD)

This example creates a new key and adds a string value under HKEY_LOCAL_MACHINE\Software\TestRegistry.

Policy content:

{
  "policyName": "Registry Test - Add Value",
  "policyType": "WINDOWS_REGISTRY_POLICY",
  "policy": {
    "rules": [
      {
        "path": "HKEY_LOCAL_MACHINE\\Software\\TestRegistry",
        "field": "SwifValue",
        "operation": "ADD",
        "data": "TestFromAgent123"
      }
    ]
  }
}

What happens on the device:

The agent creates HKEY_LOCAL_MACHINE\Software\TestRegistry if it does not already exist.
It sets SwifValue to "TestFromAgent123" as a string (REG_SZ).
On subsequent evaluations, if the value is already present with the same data, the rule is treated as compliant and not re-applied.

Verification with PowerShell:

Get-ItemProperty -Path "HKLM:\Software\TestRegistry" -Name "SwifValue"

You should see:

SwifValue    : TestFromAgent123 
PSPath       : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\TestRegistry 
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software 
PSChildName  : TestRegistry 
PSDrive      : HKLM 
PSProvider   : Microsoft.PowerShell.Core\Registry

Best practices

Test in a non‑production test device first
Registry changes can impact system behavior or application stability. Always validate on a test machine before rolling out widely.
Avoid broad or ambiguous paths
Use explicit paths and value names to prevent accidental changes (e.g., avoid targeting generic keys where multiple apps store data).
Keep policies small and focused
Group related changes into a single policy (e.g. “Disable X feature across all devices”) instead of mixing unrelated registry tweaks into one large policy.
Document what each rule does
Use the policy name and description in Swif to record the intent of each rule (for example, “Disable Chrome background apps,” “Disable legacy protocol,” etc.).
Review logs when troubleshooting
For failures, use Swif’s logs and the Windows agent logs to identify issues like:
- Incorrect path or hive prefix
- Access denied
- Conflicting local settings or security tooling