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).

• 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).

• 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.

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.

Exchange scripts sign in with the Exchange Credentials saved on the Script Host they run on (see 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.

Command statuses

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].

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.

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).

2. Click Add Host (in the top right)

3. Fill in the form:

4. Click Create.

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.

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

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

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

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?