---
title: "Clarity Connect Scripts"
slug: "clarity-connect-scripts"
tags: ["Active Directory", "Clarity Connect", "How-To", "Microsoft", "on-prem", "Powershell", "Workflows"]
status: "new"
updated: 2026-10-29T19:05:11Z
published: 2026-10-29T19:05:11Z
canonical: "help.claritysecurity.com/clarity-connect-scripts"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.claritysecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clarity Connect Scripts

**Estimated time to complete:** 15 minutes

If you run into any problems, please contact your support team or support@claritysecurity.io.

## Overview

ClarityConnect Scripts lets Clarity run **PowerShell** and **Bash** scripts on your own servers through your ClarityConnect agent. Use it for tasks that standard connectors can’t do, such as converting a leaver’s mailbox to shared, scrambling a compromised account’s password, or managing local Linux users.

You can:

- Use **prebuilt scripts** that Clarity provides and maintains.
- Write your own **custom scripts** (see [Custom Scripts](/home/docs/custom-scripts)).
- Run scripts **manually** from the Script Library, or **automatically** as a step in a workflow.
- Run scripts on the ClarityConnect server itself, or on another server through a **Script Host**.
- Review every run, with its output and errors, in **Command History**.

## Before you begin

- **Administrator role.** Only Clarity administrators can run scripts, create custom scripts, and manage Script Hosts. Users with the **ReadAll** or **Audit** role can view the Script Library and Command History.
- **A running ClarityConnect agent.** See [Configuring Clarity Connect (On-Premises)](/home/docs/configuring-clarity-connect).
- **Scripts enabled for your tenant.** If you don’t see the **Script Library** and **Script Hosts** buttons described below, ask your customer success team to enable the feature.

## The Script Library

1. Go to **Applications** and open the **ClarityConnect** tab.
2. Click **Script Library**.

The Script Library shows every script you can run, grouped by category. Use the **Instance** dropdown in the top-right to switch between ClarityConnect agents. Prebuilt scripts are the same for every agent; custom scripts belong to the agent they were created on.

The header also has:

- **History**: opens Command History.
- **Hosts**: opens Script Hosts.
- **Create Script**: creates a custom script.

## Prebuilt scripts

Prebuilt scripts are written, tested, and maintained by Clarity. Most are safe to run again: they check the current state first (for example, whether the user is already in the group) and finish without error if there’s nothing to do.

| Category | Script | What it does |
| --- | --- | --- |
| Active Directory | Add User to AD Group | Adds a user to an Active Directory group. |
| Active Directory | Remove User from AD Group | Removes a user from an Active Directory group. |
| Active Directory | Disable AD Account | Disables an Active Directory user account. |
| Active Directory | Move User to OU | Moves a user to a different Organizational Unit. |
| Active Directory | Scramble AD Password | Sets a user’s password to a random value, for emergency lockout of a compromised account. |
| Exchange | Create Exchange Mailbox | Creates an Exchange mailbox for an existing AD user. |
| Exchange | Disable Exchange Mailbox | Removes the Exchange mailbox but keeps the AD account. |
| Exchange | Convert Mailbox to Shared | Converts a user mailbox to a shared mailbox, and can grant Full Access to specified users. |
| Exchange | Reassign Shared Mailbox | Removes all existing Full Access on a shared mailbox and grants it to the specified users. |
| Exchange | Add Distribution Group Member | Adds a member to a classic Exchange Online distribution list. |
| Exchange | Remove Distribution Group Member | Removes a member from a classic Exchange Online distribution list. |
| Linux | Create Linux User | Creates a local user on a Linux server. |
| Linux | Add User to Linux Group | Adds a user to a local Linux group. |
| Linux | Remove User from Linux Group | Removes a user from a local Linux group. |
| Linux | List Local Groups | Lists all local groups and their members. |
| Linux | Test SSH Connection | Checks that ClarityConnect can reach a host over SSH. |
| Windows | Test WinRM Connection | Checks that ClarityConnect can reach a Windows host over WinRM. |

> [!NOTE]
> Note
> 
> The two distribution group scripts are normally run automatically by Clarity’s distribution list provisioning, not by hand. See [Managing Entra Distribution List Membership](/home/docs/manage-entra-distribution-list-membership).
> 
> Exchange scripts sign in with the **Exchange Credentials** saved on the Script Host they run on (see [Script Hosts](/docs/clarity-connect-scripts#script-hosts)). You don’t enter those credentials when running the script.

## Running a script manually

1. In the Script Library, find the script and click **Execute**.
2. Select the **ClarityConnect Instance** that should run it.
3. Choose a **Target Host**: **Local (ClarityConnect Server)** runs it on the ClarityConnect server, or select a Script Host to run it on that server.
4. Fill in the parameters. Required fields are marked with an asterisk (*), and each field explains what to enter.
5. Click **Execute**.

You’ll see **Script execution queued successfully!** with a **Command ID**. Click **View in Command History** to follow it.

ClarityConnect checks for new commands every 30 seconds, so a script can take up to about half a minute to start.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-IBN3KGCH.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-8PDXIHYE.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

### Command statuses

| Status | Meaning |
| --- | --- |
| **Pending** | Queued in Clarity, waiting for ClarityConnect to pick it up. |
| **Fetched** | ClarityConnect has picked it up. |
| **Running** | The script is running. |
| **Complete** | The script finished successfully (exit code 0). |
| **Error** | The script failed, or ClarityConnect refused to run it. Open the command to see why. |

## Command History

Click **History** in the Script Library header to see every script run.

- **Filters:** Instance, Status, and a From/To date range. Click **Clear** to reset them.
- **Auto-refresh:** turn it on to refresh the list every 5 seconds while you watch a script run.
- **Columns:** Script Name, Instance, Status, Created By (a user’s name, or **Workflow Execution**), Created At, and Completed At.

Click any row to open **Command Details**, which shows:

- The **Arguments** the script was run with.
- When it was created and fetched, and how long it took to run.
- The **Exit Code**, **Standard Output**, and **Standard Error**, each with a copy button.

Parameters marked **Sensitive** always show as [REDACTED].

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-WKUF9M4U.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

## Custom scripts

Administrators can write their own PowerShell or Bash scripts. Click **Create Script** in the Script Library header. For the full walkthrough, including how parameter values reach your script and how exit codes work, see [Custom Scripts](/docs/custom-scripts).

A few things to know:

- **Parameters** can be String, Integer, Boolean, or Array, up to 20 per script. Check **Sensitive** for anything secret, such as a password, so it’s redacted in Command History.
- **Default Target Host** pre-selects a Script Host whenever the script is run.
- **Version History** in the edit window shows each saved version, when it changed, and who changed it.
- **Inactive scripts disappear from the Script Library** and can’t be run. You also can’t reopen them from the Script Library to switch them back on, so if you need a script again, contact support instead of re-creating it.
- **Deleting** a script removes it from the Script Library.

## Script Hosts

By default, scripts run on the ClarityConnect server. A **Script Host** lets ClarityConnect connect to another server and run the script there, for example a Windows server with the Active Directory or Exchange PowerShell modules installed.

### Adding a Script Host

1. Go to **Applications**, open the **ClarityConnect** tab, and click **Script Hosts** (or click **Hosts** in the Script Library).

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-1B613NNP.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-JUIE2W67.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

1. Click **Add Host** (in the top right)

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-ZF3CKVY8.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

1. Fill in the form:

| Section | Field | What to enter |
| --- | --- | --- |
| Connection | Connection type | **SSH** or **WinRM**. |
| Connection | Hostname / Port | The server’s hostname or IP address. Leave the port blank for the default: 22 for SSH, 5985 for WinRM, or 5986 with **Use SSL (HTTPS)** checked. |
| Connection | OS | **Linux** or **Windows**. WinRM is always Windows. |
| Authentication | Auth type | **SSH:** **SSH Key** (recommended) or **Password**. **WinRM:** **NTLM** (enter the **Domain**) or **Basic**. If you use Basic, check **Use SSL (HTTPS)** so the password isn’t sent unencrypted. |
| Authentication | Username / credential | The account ClarityConnect signs in as. Scripts run with this account’s permissions on that server. |
| Details | Name / Description | A name that makes the server’s purpose clear. |
| Exchange Credentials | Username / password / server | Only needed for Exchange scripts. See [Exchange Credentials](/docs/clarity-connect-scripts#exchange-credentials). |
| Advanced | Jump Host | Leave as **None - direct connection**. See the note below. |
| Advanced | Assign to Instances | The ClarityConnect agents allowed to use this host. |
| — | Status | **Active**. |

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-P73OTL7D.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

1. Click **Create**.

> [!WARNING]
> **Important**
> 
> Jump hosts (bastion / ProxyJump) are not currently supported. The field appears in the form, but scripts sent through a jump host fail with an error. ClarityConnect must be able to reach the Script Host directly.

### Testing a Script Host

In the Script Hosts list, use **Test Connection** on a host’s row. It runs **Test SSH Connection** or **Test WinRM Connection** against that host, so you can confirm it works before relying on it. The row also lets you edit, activate or deactivate, and delete the host.

### Exchange Credentials

Exchange scripts need an Exchange account in addition to the server sign-in account. Enter it in the **Exchange Credentials** section of the Script Host.

- **On-premises Exchange scripts** (create, disable, convert, and reassign mailboxes) use these credentials to reach your Exchange server from the Script Host. This avoids the Windows “double-hop” sign-in problem. Enter the Exchange server name in **Exchange server**, or leave it blank to use the Script Host itself.
- **Distribution list scripts** use them to sign in to Exchange Online. Leave **Exchange server** blank. For the full requirements, see [Managing Entra Distribution List Membership](/home/docs/manage-entra-distribution-list-membership).

The section is labelled optional because other scripts don’t need it. If it’s blank, Exchange scripts fail.

![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-NEGQF7ZD.png?sv=2026-02-06&spr=https&st=2026-10-30T10%3A35%3A29Z&se=2026-10-30T11%3A35%3A29Z&sr=c&sp=r&sig=c6Ieq32986a%2Bds4frEmTK5s5%2Fv%2FhALoe%2BKoUMqW4MrI%3D)

## Using scripts in workflows

Scripts can run automatically as a step in a workflow, for example to convert a leaver’s mailbox to shared or disable their AD account.

### Dynamic Workflows

Add the **Trigger Custom Script** action (under **Integrations**) and fill in:

- **ClarityConnect Instance**
- **Script Type**: **Pre-built Script** or **Custom Script**
- **Script**
- **Target Host**
- **Script Arguments**: for each parameter, either enter a fixed value or select a value from the workflow context, such as the identity’s email or an earlier step’s output. Clarity suggests a mapping where it can.

The step **waits for the script to finish**. If the script ends in **Error**, the step fails. The step’s outputs (**Response Status**, **Script Output**, and **Error Message**) can be used by later steps.

### Workflows (legacy)

Add the **Execute CCScript** action. The fields are the same, and each parameter can be set to a **Static Value** or a **Workflow Context** value, such as the identity’s or supervisor’s email, the entitlement, the application, or any identity attribute.

> [!NOTE]
> Note
> 
> In legacy Workflows, the step finishes as soon as the script is queued. It doesn’t wait for the result. Check Command History to confirm the script succeeded.

## Security

- Scripts run on your own infrastructure (the ClarityConnect server or your Script Hosts), never in Clarity’s cloud.
- Script Host passwords and keys are stored with Clarity’s credential management and are only sent to ClarityConnect when it picks up a command for that host.
- ClarityConnect verifies prebuilt scripts before running them, so a modified prebuilt script isn’t run.
- Every run is recorded in Command History, including who or what started it.
- Use dedicated service accounts with only the permissions the scripts need.

## Limits and settings

| Setting | Default | Notes |
| --- | --- | --- |
| Script timeout | 5 minutes | Can be raised to 30 minutes. Contact support to change it. |
| Script categories | All allowed | Clarity can allow or block categories (such as Exchange) per agent. A blocked script ends in **Error** with a message saying so. |
| Custom scripts | Allowed | Clarity can turn custom scripts off per agent. |

There’s no scheduling: scripts run only when started manually or by a workflow. Script actions can’t be undone automatically; to reverse a change, run another script or make the change by hand.

## Troubleshooting

### A script stays in Pending

ClarityConnect hasn’t picked it up. Pending commands don’t expire on their own.

- Check that the ClarityConnect agent is running and can reach Clarity.
- Check the ClarityConnect logs for errors.

### A script ends in Error

1. Open the command in Command History.
2. Read **Standard Error** and **Error**. Prebuilt scripts explain what went wrong.
3. Check the **Arguments** for wrong or missing values.

“Missing required parameter: *name*” means a required parameter was blank. When running manually, fill in every required field. In a workflow, check the parameter mapping.

### Can’t connect to the Script Host

- Use **Test Connection** on the host.
- Check that the server is reachable from ClarityConnect on the right port (22 for SSH, 5985/5986 for WinRM).
- Check the username and password or key. SSH keys must be in OpenSSH format.
- Make sure **Jump Host** is set to **None**.

### Permission denied on the Script Host

ClarityConnect signed in, but the account can’t do what the script needs. Check that the account can run the script’s commands on that server. On Windows, also check that PowerShell remoting is set up.

### A custom script is missing from the Script Library

- Check that you’ve selected the right **Instance**. Custom scripts belong to one agent.
- The script may have been set to inactive or deleted. Contact support.

### The script times out

- Check the network between ClarityConnect and the Script Host.
- Make the script do less per run, if you can.
- Contact support if the script genuinely needs longer than the timeout.

## Need Help?

If you have any problems, contact your customer success team. You can also get in touch with our general support [via email](mailto:support@claritysecurity.io), open a [support ticket](https://support.claritysecurity.com/home). Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.

## Related

- [Configuring Clarity Connect](/configuring-clarity-connect.md)
- [Active Directory (On-Premises)](/active-directory-on-premises.md)
- [Entra ID](/entra-id.md)
- [Custom Scripts](/custom-scripts.md)
- [Entra - Managing Distribution List Membership](/manage-entra-distribution-list-membership.md)