> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/english/plugins/how-can-i-run-plugins-in-unprivileged-mode-in-enginsight.md).

# How can I run plugins in unprivileged mode in Enginsight?

By default, the Enginsight agent Pulsar runs custom scripts, known as plugins, with the same elevated privileges as the agent itself. However, this carries the risk that malicious or faulty plugins are also executed with system or root privileges and can therefore initiate further harmful actions.

Unprivileged plugin execution, on the other hand, implements the principle of least privilege by running plugins exclusively under an unprivileged service account (Windows) or as an unprivileged service user (Linux). This reduces the attack surface on the host, as malicious or faulty plugins can only access what the restricted account or restricted user is allowed to access.

To enable unprivileged plugin execution, you must configure various settings in the Enginsight platform and make additional configuration changes. The following sections show you which steps are required.

***

## Step 1: Enabling the Unprivileged Mode on the Host

First, you must enable unprivileged plugin execution on the host itself. You have two options for doing so:

#### Enabling it in the Host Settings of a Specific Host

1. Navigate to **Hosts** → **Overview** in the Enginsight platform and click the name of a host to open the host detail menu on the dashboard.
2. In the host detail menu, click [Settings](https://docs.enginsight.com/docs/manual/english/platform-usage/host-detail-view/settings) to configure the host.
3. In the **Core Feature** section, select the checkbox next to **Run Custom Plugins** and the checkbox next to **Unprivileged Plugin Execution**.
4. Click **Save Changes** to apply the changes to the host.

#### Enabling it via the Policy Manager

1. Navigate in the Enginsight platform to **Hosts** → **Management** → [Policy Manager](https://docs.enginsight.com/docs/manual/english/platform-usage/hosts/management/policy-manager) and click **Add Policy** in the upper-right corner to create a new Policy Manager, or edit an existing Policy Manager.
2. In the **Available Settings** → **Plugins** section, click the **Add New Setting** field to expand the available options.
3. Select the **Unprivileged Plugin Execution** option.
4. Click **Add Policy** or **Save Changes** to apply the changes to the assigned hosts.

### Newly Created Accounts

When unprivileged plugin execution is enabled, the Pulsar creates a dedicated, restricted account on the corresponding host or hosts, depending on the operating system:

<table><thead><tr><th width="177.75">Operating system</th><th>Created account</th></tr></thead><tbody><tr><td>Windows</td><td>Virtual service account <code>NT SERVICE\enginsight-plugin-user</code></td></tr><tr><td>Linux</td><td>System user and group <code>enginsight-plugin-user</code></td></tr><tr><td>macOS</td><td>Role account <code>enginsight-plugin-user</code></td></tr></tbody></table>

### Note on Enabling this Setting on macOS Systems

{% hint style="danger" %}
**Please note**: Using unprivileged plugin execution on macOS hosts is possible, but it is not officially supported by Enginsight. Use it at your own risk!
{% endhint %}

If you still want to use unprivileged plugin execution on macOS, you must first manually enable **Full Disk Access** on your host.

1. To do this, navigate on your macOS host to **System Settings** → **Privacy & Security** → **Full Disk Access**.
2. Enable the toggle next to **Enginsight Pulsar** so that the Pulsar can create the required user entry.

### Notes on Disabling the Unprivileged Mode

If you disable unprivileged plugin execution after enabling it, the Pulsar removes the created restricted account again. If you enable the setting again, the account is recreated.

Whether the access permissions you granted to the respective account in [Step 2](#step-2-grant-access-permissions-to-the-created-account) remain in place depends on the operating system of your host.

#### Windows

Permissions you granted to the virtual service account `NT SERVICE\enginsight-plugin-user` remain effective.

The account identity is tied to its name and does not change when it is recreated, so existing permissions continue to apply.

#### Linux / macOS

Permissions are stored using the numerical user and group ID of the account. In most cases, the permissions remain effective because the recreated account usually receives the same ID.

However, this cannot be guaranteed. If other system accounts were created in the meantime, the ID might change. In that case, permissions tied to the owner or group no longer apply.

Permissions opened for all users, meaning the "other" bits of a file, always remain effective.

After enabling the setting again, therefore check whether your plugins still have the required access.

***

## Step 2: Granting Access Rights to the Created Account

Because unprivileged plugins now run under the newly created restricted account and no longer with elevated privileges, they also only have restricted access to resources.

You must therefore explicitly make every file, directory, registry key, and any other resource that a plugin needs to read or write accessible to the account.

{% hint style="warning" %}
**Please note**: Only grant the corresponding accounts the permissions that are actually required. Otherwise, the principle of least privilege is no longer effective.
{% endhint %}

Grant the required permissions using the standard access control tools of your operating system, for example:

* **Windows**: Grant the virtual service account `NT SERVICE\enginsight-plugin-user` read/execute permissions, and write permissions if required, on the relevant files or folders via the **Security** tab in the file properties or by using `icacls`.
* **Linux**: Grant the user or group `enginsight-plugin-user` access to the relevant paths, for example via ownership, file permissions, group membership, or ACLs.
* **macOS**: Grant the account `enginsight-plugin-user` access to the relevant paths via file permissions or ACLs.

***

## Step 3: Configuring and Running Plugins in Unprivileged Mode

For each plugin, you can define whether it should be executed with privileged or unprivileged permissions. To do this, proceed as follows:

1. Navigate in the Enginsight platform to **Hosts** → **Management** → [Plugins](https://docs.enginsight.com/docs/manual/english/platform-usage/hosts/management/plugins) and click **Add Plugin** in the upper-right corner to create a new plugin, or edit an existing plugin.
2. Click **Advanced Settings** to show available options.
3. Select the checkbox next to **Unprivileged Plugin Execution** to enable the unprivileged mode.
4. Click **Add Plugin** once you have fully configured the plugin, or click **Save Changes**.

Together with the host setting from [Step 1](#step-1-enabling-the-unprivileged-mode-on-the-host), this results in a combination of settings that determines how the plugin is executed:

### Behavior by Setting cCombination

Depending on whether unprivileged plugin execution is **enabled** or **disabled** on the host and/or on the plugin, the following behavior applies:

<table><thead><tr><th width="197.84375">Host setting</th><th width="185.29296875">Plugin setting</th><th>Result</th></tr></thead><tbody><tr><td>Enabled</td><td>Enabled</td><td>The plugin runs with reduced privileges under the <strong>restricted account</strong>. This corresponds to the intended principle of least privilege.</td></tr><tr><td>Enabled</td><td>Disabled</td><td>The plugin runs with <strong>elevated privileges</strong>. It explicitly exempts itself from privilege reduction.</td></tr><tr><td>Disabled</td><td>Disabled</td><td>The plugin runs with <strong>elevated privileges</strong>.</td></tr><tr><td>Disabled</td><td>Enabled</td><td><p>The plugin is <strong>not executed</strong>. It requires the restricted account, but the host does not provide it.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>Please note</strong>: A plugin explicitly marked as unprivileged is never silently executed with elevated privileges!</p></div></td></tr></tbody></table>

***

## Note on Writing Unprivileged Plugin Scripts

If the unprivileged mode is enabled, every step of a plugin that requires elevated privileges is denied. This is the correct behavior, but it means that the plugin might not be executed without errors.

The Pulsar evaluates the successful execution of a plugin script based on its exit code. Exit code 0 indicates success, while exit code 1 indicates failure.

However, many common tools and scripts only output permission-related errors as text to the error stream and still terminate with exit code 0, meaning success.

To handle this issue, we recommend that you write scripts that explicitly signal a failure to the Pulsar even when permission issues occur:

* Check the required permissions in advance in your scripts and terminate the script with exit code 1 if an error occurs.
* In PowerShell, for example, set `$ErrorActionPreference = 'Stop'` (optionally with `try` / `catch`) so that a denied operation becomes a terminating error and the script exits with a value other than 0.

If a plugin requires root or administrator privileges to work at all, we recommend that you disable the unprivileged mode.

***