# Policy-Based File Execution Redirection

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FIedBdYTtl4MJVD5Mc5lf%2Fimage.png?alt=media&#x26;token=9c83a4f1-18a1-4ac1-aee8-029ec6190a38" alt=""><figcaption></figcaption></figure>

**Audience:** System administrators

This page explains how to configure and use **file redirect** in Keeper Endpoint Privilege Manager (KEPM). When a privilege elevation request is **allowed** by policy, redirect lets you **substitute a different executable** so the user gets the intended experience while policy stays in control.

## What is a File Redirect?

When a privilege elevation request is allowed by policy, KEPM normally launches the requested executable with elevation. A redirect intercepts that flow and launches a **substitute executable** instead.

**Example:** A user requests elevation for PowerShell 7 (`pwsh.exe`). Policy allows it, but the redirect rule substitutes Windows PowerShell 5.1 (`powershell.exe`) — the user gets the intended shell while the organization controls which binary runs elevated.

Key behaviors:

* Redirect applies only to **Privilege Elevation** events — not File Access or other event types.
* When a rule matches, the job sends **DENY** to the caller and launches the substitute executable elevated.
* When redirect is disabled or no rule matches, normal elevation flow proceeds.
* Policy evaluation and controls (MFA, justification, approval) are **unchanged** — redirect happens after the request is allowed.

Redirect rules are stored in the **RedirectEvaluator** plugin configuration under `metadata.redirect`.

## Requirements

<table><thead><tr><th width="245.3333740234375">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><strong>LaunchPrivilegeElevation job</strong></td><td>Must be deployed and registered. Contains the <code>check-redirect</code> task that calls RedirectEvaluator.</td></tr><tr><td><strong>RedirectEvaluator plugin</strong></td><td>Plugin config must have <code>metadata.redirect.enabled: true</code> and at least one rule in <code>metadata.redirect.rules</code>.</td></tr><tr><td><strong>Privilege Elevation policy</strong></td><td>A policy that <strong>allows</strong> the source application. Without this, the request is denied and LaunchPrivilegeElevation never runs.</td></tr><tr><td><strong>SettingsUpdate policy</strong></td><td>Pushes the full RedirectEvaluator JSON (including redirect rules) to endpoints so <code>Plugins/RedirectEvaluator.json</code> is updated.</td></tr><tr><td><strong>Process Configuration Policies job</strong></td><td>Runs the ConfigurationPolicyProcessor, which writes SettingsUpdate policy content to plugin files.</td></tr><tr><td><strong>Reload of plugin settings</strong></td><td>After the JSON file is updated, the service must load the new config. The only ways to reload are: <strong>UpdateSettings</strong> policy, <strong>restart KEPM service</strong>, or <strong>restart the machine</strong>. KEPM admin endpoints cannot be called from terminal or scripts — the calling process must be signed like KEPM.</td></tr><tr><td><strong>UpdateSettings policy</strong> <em>(optional)</em></td><td>When present and preprocessed, triggers revert-all to reload settings <strong>without</strong> restarting the service.</td></tr></tbody></table>

## Redirect Rule Format

Rules live under `metadata.redirect.rules` in the RedirectEvaluator plugin JSON.

<table><thead><tr><th width="199">Field</th><th width="116">Required</th><th>Description</th></tr></thead><tbody><tr><td><strong>sourceExePattern</strong></td><td>Yes</td><td>Regex matched against the <strong>executable file name</strong> only (e.g. <code>pwsh\.exe</code>). Case-insensitive. Use <code>\\.</code> for a literal dot.</td></tr><tr><td><strong>commandLinePattern</strong></td><td>Yes</td><td>Regex matched against the full <strong>command line</strong>. Cannot be empty — use <code>.*</code> to match any command line.</td></tr><tr><td><strong>elevationOnly</strong></td><td>Yes</td><td>Set <code>true</code> so the rule applies only to Privilege Elevation events.</td></tr><tr><td><strong>nonAdminOnly</strong></td><td>No</td><td>If <code>true</code>, rule applies only when the requesting user is <strong>not</strong> an administrator.</td></tr><tr><td><strong>targetExe</strong></td><td>Yes</td><td>Substitute executable: full path or a product-known name (e.g. <code>Keeper.NetworkConnections</code>) resolved from Jobs/bin or Plugins/bin.</td></tr><tr><td><strong>targetArguments</strong></td><td>No</td><td>Arguments for the substitute (often <code>""</code>).</td></tr></tbody></table>

{% hint style="info" %}
**Important:** Both `sourceExePattern` and `commandLinePattern` must be non-empty. To redirect regardless of command line, use `".*"` for `commandLinePattern`. The **first** matching rule wins — place more specific rules before general ones.
{% endhint %}

## Setup

{% stepper %}
{% step %}
**Privilege Elevation Policy**

Create a policy that **allows** the application you want to redirect. If the request is denied, LaunchPrivilegeElevation is not triggered and redirect never runs.

1. Create a **Privilege Elevation** policy in your management console or policy store.
2. Set **PolicyType** to `"PrivilegeElevation"` and **Status** to `"enabled"`.
3. Configure **ApplicationCheck** to match the source executable (e.g. a path containing `PowerShell\7\pwsh.exe`).
4. Set **Controls** to allow elevation (e.g. `["ALLOW"]`, or include MFA/Justify/Approval as needed).
5. Assign to the appropriate user and machine collections, then deploy/sync.

**Example (conceptual):**

```json
{
  "PolicyId": "allow-pwsh-elevation",
  "PolicyName": "Allow PowerShell 7 elevation (redirect to 5.1)",
  "PolicyType": "PrivilegeElevation",
  "Status": "enabled",
  "Controls": ["ALLOW"],
  "Filters": {
    "ApplicationCheck": { "Applications": ["*pwsh*"] }
  }
}
```

{% endstep %}

{% step %}
**SettingsUpdate Policy (Redirect Rules)**

This policy pushes the **full** RedirectEvaluator plugin JSON to `Plugins/RedirectEvaluator.json` on each endpoint.

1. Build the full RedirectEvaluator JSON, including all required fields: `id`, `name`, `description`, `version`, `pluginType`, `executablePath`, `Subscription`, `metadata`, etc.
2. Set `metadata.redirect.enabled` to `true` and populate `metadata.redirect.rules` with your rules.
3. Create a **SettingsUpdate** policy with **Extension.PluginName** `"RedirectEvaluator"`, **Extension.Action** `"Update"`, and **Extension.SettingsJson** set to the full plugin JSON. Object format is easier to read and avoids escaping errors.
4. Assign to the appropriate collections and deploy/sync.

**Example SettingsUpdate policy:**

```json
{
  "PolicyName": "Update RedirectEvaluator settings",
  "PolicyType": "SettingsUpdate",
  "Status": "enforce",
  "UserCheck": ["*"],
  "MachineCheck": ["NSBYFNaHnhkIgVIazYhFXA"],
  "ApplicationCheck": ["*"],
  "Extension": {
    "PluginName": "RedirectEvaluator",
    "Action": "Update",
    "SettingsJson": {
      "id": "RedirectEvaluator",
      "name": "Redirect Evaluator",
      "version": "1.0.0",
      "pluginType": "Executable",
      "executablePath": "../Jobs/bin/RedirectEvaluator/RedirectEvaluator.exe",
      "arguments": "--baseurl {KeeperApiBaseUrl}",
      "Subscription": { "Topic": "RedirectEvaluator" },
      "metadata": {
        "redirect": {
          "enabled": true,
          "rules": [
            {
              "sourceExePattern": "rundll32\\.exe",
              "commandLinePattern": "ncpa\\.cpl",
              "elevationOnly": true,
              "nonAdminOnly": false,
              "targetExe": "Keeper.NetworkConnections",
              "targetArguments": ""
            },
            {
              "sourceExePattern": "Notepad\\.exe",
              "commandLinePattern": "WindowsApps",
              "elevationOnly": true,
              "nonAdminOnly": false,
              "targetExe": "C:\\\\Windows\\\\notepad.exe",
              "targetArguments": ""
            },
            {
              "sourceExePattern": "WindowsTerminal\\.exe",
              "commandLinePattern": ".*",
              "elevationOnly": true,
              "nonAdminOnly": false,
              "targetExe": "C:\\\\Windows\\\\System32\\\\cmd.exe",
              "targetArguments": ""
            },
            {
              "sourceExePattern": "pwsh\\.exe",
              "commandLinePattern": ".*",
              "elevationOnly": true,
              "nonAdminOnly": false,
              "targetExe": "C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe",
              "targetArguments": ""
            }
          ]
        }
      }
    }
  }
}
```

{% hint style="info" %}
`SettingsJson` must be the **complete** plugin JSON — all fields including `id`, `name`, `executablePath`, `Subscription`, and `metadata` are required.
{% endhint %}
{% endstep %}

{% step %}
**Run Process Configuration Policies**

The **Process Configuration Policies** job (ConfigurationPolicyProcessor) reads SettingsUpdate policies and writes `Extension.SettingsJson` to `Plugins/RedirectEvaluator.json` on each endpoint.

* **Scheduled:** Runs automatically on its next cycle after sync.
* **On demand:** Use the KeeperClient **Refresh** option to trigger policy sync and preprocessing immediately.

After this step, the plugin file on disk contains your redirect rules. The running service may still use the old in-memory config until settings are reloaded (Step 4).
{% endstep %}

{% step %}
**Reload Plugin Settings**

After the plugin JSON file is updated, the service must load the new settings. The only ways to reload are:

1. **UpdateSettings policy** — Triggers revert-all during policy preprocessing (see Step 5).
2. **Restart KEPM service** — Reads plugin config from disk on startup. Most reliable for a first-time load.
3. **Restart the machine** — Same effect as restarting the service.

{% hint style="info" %}
KEPM admin endpoints cannot be triggered from terminal, PowerShell, curl, or other unsigned tools.
{% endhint %}
{% endstep %}

{% step %}
**Optional: UpdateSettings Policy for Reload Without Restart**

1. Create a policy with **PolicyType** `"UpdateSettings"` and **Status** `"enabled"`.
2. Assign to the appropriate collections and deploy/sync.
3. When KeeperPolicy preprocesses policies, it finds the UpdateSettings policy and calls revert-all once, re-importing plugin settings from the current in-memory configuration into storage.

{% hint style="info" %}
**Note:** UpdateSettings re-imports from the current in-memory configuration — it does not re-read JSON files from disk. For the **first** push of a new `RedirectEvaluator.json`, a service restart is the most reliable approach. Use UpdateSettings for subsequent reloads once the config is already loaded.
{% endhint %}
{% endstep %}
{% endstepper %}

## Runtime Behavior

When a user triggers a privilege elevation request that matches a redirect rule:

1. **User requests elevation** — e.g. `rundll32.exe` with `ncpa.cpl` in the command line.
2. **Policy evaluation** — The Privilege Elevation policy allows the request; controls (MFA, justification, approval) run as normal.
3. **LaunchPrivilegeElevation job starts** — The `check-redirect` task runs when `metadata.redirect.enabled` is `true`.
4. **RedirectEvaluator is invoked** — Called with context (FilePath, CommandLine, IsAdmin, OriginalEventType). It returns JSON to stdout; the executor merges it and adds aliases so downstream tasks see `DenyOriginalRequest: true`, `RedirectTargetExe`, and `RedirectTargetArgs`.
5. **Job branches on outcome:**
   * **send-deny-redirect** — Publishes DENY to the caller so the original executable is not launched.
   * **launch-substitute** — HTTP POST to launch-elevated with the resolved substitute path and arguments.
   * **send-did-elevate-response** — Sends DidElevate so the client shows success; the user sees the substitute application.

When redirect is **disabled**, `check-redirect` sets `DenyOriginalRequest: false` and the job continues with the normal launch-elevated path.

## Target Executable Path Resolution

`targetExe` values like `Keeper.NetworkConnections` are resolved to full paths by the task executor before the launch-substitute call. The executor looks in **Jobs/bin** (and Plugins/bin as applicable). Only paths under the manager's control are used for substitute launches.

## Limitations

<table><thead><tr><th width="260">Limitation</th><th>Description</th></tr></thead><tbody><tr><td><strong>Privilege Elevation only</strong></td><td>Redirect is not evaluated for File Access or other event types.</td></tr><tr><td><strong>Both patterns required</strong></td><td><code>sourceExePattern</code> and <code>commandLinePattern</code> must both be non-empty.</td></tr><tr><td><strong>Policy must allow first</strong></td><td>The elevation request must be allowed by policy. If denied, LaunchPrivilegeElevation does not run and redirect is never evaluated.</td></tr><tr><td><strong>Tampering protection</strong></td><td>If KEPM detects <code>Plugins/RedirectEvaluator.json</code> was modified after initial load, it may skip the file on hot reload. Restart the KEPM service so the file is read at startup.</td></tr><tr><td><strong>Target executable</strong></td><td><code>targetExe</code> must resolve under Jobs/bin or Plugins/bin and be launchable on the endpoint.</td></tr><tr><td><strong>First matching rule wins</strong></td><td>Order rules from most specific to least specific.</td></tr><tr><td><strong>UpdateSettings scope</strong></td><td>Re-imports from in-memory config only — does not re-read JSON from disk. Use a service restart to load a file that has never been loaded before.</td></tr><tr><td><strong>No API from terminal/scripts</strong></td><td>Admin endpoints require the calling process to be signed like KEPM. Terminal, PowerShell, and curl cannot call them.</td></tr></tbody></table>

## Related Documentation

* [Reference: Redirect](/keeperpam/endpoint-privilege-manager/reference/redirect-capability.md) — Redirect capability and rule fields.
* [Example: Update Settings](/keeperpam/endpoint-privilege-manager/policies/policy-types/advanced-policy-types/update-settings-policy-type.md) — SettingsUpdate policy and Process Configuration Policies job.
* [Reference: Plugin & Task Settings](/keeperpam/endpoint-privilege-manager/reference/plugin-and-task-settings.md) — Plugin settings API, revert-all, and revert.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/policies/policy-examples/advanced-examples/policy-create-a-file-redirect.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.