Using PowerShell and Bash Scripts with ClarityConnect

Estimated time to complete: 10 minutes

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

Overview

ClarityConnect can run custom PowerShell or Bash scripts on your on-premises systems — useful for operations that aren’t available through a standard connector or LDAP, such as Exchange mailbox management, Active Directory operations beyond basic group membership, or Linux local user administration.

Scripts can be run manually from the Script Library, or triggered automatically as a step in a Dynamic Workflow (for example, during a joiner or leaver process).

Before You Begin

• You’ll need administrator access to the ClarityConnect instance’s Script Library.

• The target machine must be reachable by ClarityConnect — either the ClarityConnect instance itself, or a separate host it’s configured to reach.

Creating a Custom Script

1. Go to Applications > ClarityConnect > Scripts and select Create Custom Script.

2. Fill in:

   • Name and Description

   • Language — PowerShell or Bash

   • Script Body — your script content

   • Parameters — the inputs your script needs (see below)

3. Save. The script is active by default and available to run immediately.

How Input Values Reach Your Script

Each parameter you define is delivered to your script as an environment variable, named CC_PARAM_<PARAMETER NAME> in uppercase. This is true for both PowerShell and Bash, and for both custom scripts and Clarity’s built-in prebuilt scripts.

Powershell:

# PowerShell — parameter named "work_email"
$workEmail = $env:CC_PARAM_WORK_EMAIL

Bash:

# Bash — parameter named "work_email"
work_email="$CC_PARAM_WORK_EMAIL"

Each execution runs in its own fresh process with its own set of these variables — values from a previous run are never carried over, and each run only ever sees the values submitted for that specific execution.

Running a Script

1. From the Script Library, select the script and choose Execute.

2. Enter a value for each parameter, and select a target host if the script runs somewhere other than the ClarityConnect instance itself.

3. Submit. ClarityConnect queues the command, the instance picks it up, runs it, and reports back the exit code and any output.

4. Check Command History to view status, exit code, and captured output for each run.

Exit Codes

Your script’s exit code tells Clarity whether the run succeeded:

• exit 0 — success

• Any non-zero exit code — failure

Set this explicitly at the end of your script (including in any error-handling block) — a script that doesn’t set an exit code may report success even when it actually failed partway through.

Example: Force Sign-Out for a Microsoft Entra User

A common security/offboarding action is revoking a user’s active sign-in sessions in Microsoft Entra ID via Microsoft Graph, using an app registration with certificate-based authentication.

1. Create a new custom script with Language set to PowerShell.

2. Define one parameter: upn (required) — the user’s Microsoft Entra User Principal Name.

3. Enter the script body (replace the client_id / tenant_id / certificate thumbprint placeholders with your own app registration’s values, and adjust the UPN pattern to match your tenant’s domain):

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
$WarningPreference = 'SilentlyContinue'
$InformationPreference = 'SilentlyContinue'

$pattern = '(?i)^(?:v-)?[a-z]+([0-9]{0,2})*@yourcompany\.com$'
$upn = $env:CC_PARAM_UPN

if ($upn.Length -lt 3 -or $upn.Length -gt 128) { throw "UPN length is less than 3 or greater than 128" }
if ($upn -notmatch $pattern) { throw "UPN is not valid" }

$mgUser = $null
$clientId = "<your-app-registration-client-id>"
$tenantId = "<your-entra-tenant-id>"
$certThumbprint = "<your-certificate-thumbprint>"

try {
    Import-Module Microsoft.Graph.Users -Force
    Import-Module Microsoft.Graph.Users.Actions -Force
    Import-Module Microsoft.Graph.Identity.DirectoryManagement -Force
    Import-Module Microsoft.Graph.Authentication -Force
}
catch { throw 'Import-Module Failed' }

try { Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateThumbprint $certThumbprint -ContextScope Process -NoWelcome | Out-Null }
catch { throw }

try { $mgUser = Get-MgUser -UserId $upn -Property Id, UserPrincipalName }
catch {
    Disconnect-MgGraph | Out-Null
    throw 'MgUser lookup failed'
}

try { Revoke-MgUserSignInSession -UserId $mgUser.Id -Confirm:$false | Out-Null }
catch {
    Disconnect-MgGraph | Out-Null
    throw 'Revoke-MgUserSignInSession failed'
}

Disconnect-MgGraph | Out-Null
Write-Host "Finished Successfully"
exit

1. Save, then select Execute and enter a value for UPN.

Notice the script reads exactly one input, $env:CC_PARAM_UPN, matching the single upn parameter defined in step 2 — uppercased with the CC_PARAM_ prefix, per the convention above. Validating the input’s format and length before doing anything else, and using try/catch/throw to fail fast with a specific error message at each step, is a good pattern to reuse for any script that touches identity data.

Tips & Best Practices

• Log progress with Write-Host (PowerShell) or echo (Bash). Anything written to standard output shows up in Command History, which is invaluable when a run doesn’t behave as expected.

• Validate your parameters early. Check that required $env:CC_PARAM_* values aren’t empty before doing any real work, and exit with a clear message if something’s missing.

• Don’t log secrets. Avoid printing passwords or tokens directly — log lengths or a masked value instead if you need to confirm one was received.

• Test with a non-production value first, especially for scripts that send notifications or modify accounts.

Need Help?