Skip to main content

Deploy the Shadow AI collector through your RMM

Step-by-step setup for running the Activate Shadow AI collector script through NinjaOne, Datto, ConnectWise, N-able, Kaseya, Syncro, Action1, Tactical RMM, SuperOps, or Intune.

The Shadow AI collector is a script that finds the AI tools used on a prospect's devices and reports them to that prospect's Shadow AI Scan card in Hatz Activate. The prospect is the client whose devices you're scanning.

Open the prospect's Shadow AI Scan card and click Set up collector. Download the script for each operating system the client's devices run, and copy the admission token. The token is shown only once and is valid for 14 days. If you lose it, click Generate new admission token in the same dialog.

When deploying to Macs, make sure your RMM agent has Full Disk Access so the scan can read browser history. This is usually granted with a privacy (PPPC) profile from your MDM (in Intune, a PPPC configuration profile).

Choose your RMM:

NinjaOne

  1. Go to Administration → Organizations → Organization custom fields and add a Secure field named hatzshadowaiadmissiontoken. Set its Automations permission to Read Only.

  2. Open each client organization and paste the client's token into the field.

  3. Add the Windows script (.ps1) or the macOS script (.sh) to NinjaOne's script library, with Architecture set to 64-bit for the Windows script, and add the line below for its OS.

Windows: first line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = Get-NinjaProperty -Name "hatzshadowaiadmissiontoken"

macOS: line 2, directly below #!/usr/bin/env bash.

export HATZ_SHADOW_AI_ADMISSION_TOKEN="$(/Applications/NinjaRMMAgent/programdata/ninjarmm-cli get hatzshadowaiadmissiontoken)"

Run the script on one device with Run As set to System and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

Datto RMM

  1. Open the client's site and go to Settings → Variables → Add Variable. Name the variable HATZ_SHADOW_AI_ADMISSION_TOKEN, paste the client's token as its value, and turn on Masked.

  2. Create a component from the Windows script (.ps1) with the PowerShell script type, or from the macOS script (.sh) with the Bash script type.

Run the component on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

ConnectWise RMM (Asio)

  1. Create a Company-level custom field. On each client company, paste the client's token into it.

  2. Create a task. Add a Set Pre-defined Variable row of type Custom Field that reads that field into a variable named HatzToken.

  3. Add a PowerShell row (Windows) or a Bash row (macOS) to the task and paste the Windows script (.ps1) or the macOS script (.sh) into it. Add the line below to the script in that same row, not in a separate row.

Windows: first line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = "@HatzToken@"

macOS: line 2, directly below #!/usr/bin/env bash.

export HATZ_SHADOW_AI_ADMISSION_TOKEN="@HatzToken@"

Run the task on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

ConnectWise Automate

These steps are for Windows devices.

  1. Create a client-level Extra Data Field with Masked and Encrypt turned on. On each client, paste the client's token into it.

  2. In the Automate script, add an ExtraData Get Value step that reads that field into a variable named HatzToken.

  3. Add an Execute Script step with Script Type set to PowerShell and paste the Windows script (.ps1) into it. Add the line below to the script in that step.

First line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = '@HatzToken@'

Run the script on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

macOS: contact Hatz support.

N-able N-central

These steps are for Windows devices.

  1. Go to Administration → Custom Properties → Add → By Customers → Password Type and create a property for the token. On each customer, enter the client's token as its value.

  2. In Automation Manager, create a policy. Click Input, and on the policy's Input Parameters tab add a Password parameter named HatzClientToken. This is the policy's parameter.

  3. Drag a Run PowerShell Script object into the policy. In the object's input parameters, click Add and add a Password parameter named HatzToken. This is the script object's parameter. Click the link icon beside HatzToken, click StartObject, and under Values choose the policy's HatzClientToken.

  4. On the script object's Script tab, paste the Windows script (.ps1) and add the line below as its first line, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = $HatzToken

  1. Choose File → Upload to upload the policy to N-central.

  2. In N-central, go to Configuration → Scheduled Tasks → Add/Delete → Add → Automation Policy, choose the policy, and set the policy's HatzClientToken parameter to the custom property from step 1.

Run the task on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

macOS: contact Hatz support.

N-able N-sight

N-sight isn't supported at this time.

Kaseya VSA 9

  1. In Variable Manager, create a managed variable named HatzToken. Give each client's machine group the client's token as its value.

  2. Upload the Windows script (.ps1) or the macOS script (.sh) in Manage Files Stored on Server.

  3. Create an agent procedure. Add a writeFile step that writes that file to the device, to the path below for that OS.

Windows:

#vAgentConfiguration.agentTempSecureDir#\hatz-shadow-ai.ps1

macOS:

#vAgentConfiguration.agentTempSecureDir#/hatz-shadow-ai.sh

  1. In the same procedure, add the step below for that OS. Replace <script path> with the same path. Keep <HatzToken> as written; VSA fills in the token.

Windows: an executePowerShell64BitSystem step with this command.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN='<HatzToken>'; & '<script path>'

macOS: an executeShellCommand step set to Execute as the system account, with this command.

export HATZ_SHADOW_AI_ADMISSION_TOKEN='<HatzToken>'; /bin/bash '<script path>'

Run the procedure on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

Kaseya VSA X / VSA 10

These steps are for Windows devices.

  1. Create an Organization-level Text custom field. On each organization, paste the client's token into it.

  2. Create a PowerShell script and paste the Windows script (.ps1) into it.

  3. In the script's Inputs, add a variable named HatzToken and set it to use that custom field's value.

  4. Add the line below to the script.

First line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = $HatzToken

Run the script on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

macOS: contact Hatz support.

Syncro

These steps are for Windows devices.

  1. Create a customer custom field. On each customer, paste the client's token into it.

  2. Create a script, paste the Windows script (.ps1) into it, and set Run As to System.

  3. Add a script variable named HatzToken of type Platform that points at that custom field.

  4. Add the line below to the script.

First line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = $HatzToken

Run the script on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

macOS: contact Hatz support.

Action1

  1. In each Action1 organization, create a Run Script automation with the language set to PowerShell (Windows) or Bash (macOS), and paste the Windows script (.ps1) or the macOS script (.sh) into it.

  2. Add the client's token for that OS as shown below.

Windows: add a String script parameter named HatzToken with the client's token as its value, and add this line as the first line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = $HatzToken

macOS: add this line as line 2, directly below #!/usr/bin/env bash, with <token> replaced by the client's token.

export HATZ_SHADOW_AI_ADMISSION_TOKEN="<token>"

Run the automation on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

Tactical RMM

  1. Create a Client custom field of type Text named HatzToken. On each client, paste the client's token into it.

  2. In Script Manager, add the Windows script (.ps1) as a PowerShell script with Run As User off, and the macOS script (.sh) as a Shell script.

  3. Set the script timeout to 30 minutes (1800 seconds).

  4. In the script's Environment Vars box, add the line below.

HATZ_SHADOW_AI_ADMISSION_TOKEN={{client.HatzToken}}

Run the script on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

SuperOps

  1. Create a client custom field. On each client, paste the client's token into it.

  2. Create a script with the language set to PowerShell (Windows) or Bash (macOS), Run as set to System/Root, and Script timeout set to 30 minutes. Paste the Windows script (.ps1) or the macOS script (.sh) into it.

  3. Add a placeholder variable named HatzToken and choose that client custom field from the dropdown.

  4. Add the line below for that OS to the script.

Windows: first line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = "$HatzToken"

macOS: line 2, directly below #!/usr/bin/env bash.

export HATZ_SHADOW_AI_ADMISSION_TOKEN="$HatzToken"

Run the script on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

Microsoft Intune

  1. Make one copy of the Windows script (.ps1) or the macOS script (.sh) for each client, and add the line below for its OS to each copy, with <token> replaced by that client's token.

Windows: first line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = "<token>"

macOS: line 2, directly below #!/usr/bin/env bash.

export HATZ_SHADOW_AI_ADMISSION_TOKEN="<token>"

  1. In that client's Intune admin center, add the copy as a script. Windows: Devices → Scripts and remediations → Platform scripts → Add → Windows 10 and later. macOS: Devices → By platform → macOS → Manage devices → Scripts → Add.

  2. Windows: set Run this script using the logged on credentials to No and Run script in 64 bit PowerShell Host to Yes. macOS: set Run script as signed-in user to No.

  3. Assign the script to the devices to scan: under Assignments, choose Select groups to include, and pick the group that contains those devices.

Once the script has run on one device, check that its Device status in Intune shows Success and that the prospect's Shadow AI Scan card in Activate counts the device as scanned. If the device isn't counted, see If a device doesn't report.

Other RMMs

Any RMM that can run a PowerShell or bash script as SYSTEM or root can run the collector.

  1. Add the script for each operating system to your RMM, set to run as SYSTEM (Windows) or root (macOS).

  2. Add the line below for the script's OS, with <token> replaced by the client's token.

Windows: first line of the script, above the <# comment block.

$env:HATZ_SHADOW_AI_ADMISSION_TOKEN = "<token>"

macOS: line 2, directly below #!/usr/bin/env bash.

export HATZ_SHADOW_AI_ADMISSION_TOKEN="<token>"

Run the script on one device and check that the prospect's Shadow AI Scan card in Activate counts the device as scanned, then run it on the client's other devices. If the device isn't counted, see If a device doesn't report.

If a device doesn't report

Read the job output from the device. A successful run ends with Upload complete - N finding(s) recorded. (Windows) or a line that starts Shadow AI scan complete. (macOS). Otherwise, find the message below and apply the fix.

  • HATZ_SHADOW_AI_ADMISSION_TOKEN is required. The token never reached the script. Check that the client's token field is filled in and that the token line is in the script exactly as shown in your RMM's section.

  • rejected (HTTP 410) (or 401, 403 or 404). Hatz refused the token: it is more than 14 days old, a newer token replaced it, or it was pasted wrong. Click Generate new admission token in the prospect's Shadow AI Scan setup dialog and paste the new token into your RMM. The script file doesn't change.

  • reach ai.hatz.ai after 3 attempts. The device couldn't connect. Allow outbound HTTPS (port 443) to ai.hatz.ai. If devices use a proxy, set HATZ_SHADOW_AI_PROXY to its address (for example http://proxy.example.local:8080) the same way you set the token.

  • blocked by the proxy (HTTP 407). The proxy needs a login. Also set HATZ_SHADOW_AI_PROXY_USER and HATZ_SHADOW_AI_PROXY_PASSWORD the same way you set the token.

  • Shadow AI scan uploads are temporarily paused by Hatz. or Hatz is still rate limiting uploads. Run the job again later. No change is needed.

  • run through the RMM as root (macOS) or Unable to securely load/persist installation identity (Windows). The job didn't run as root or SYSTEM. Set your RMM's run-as account to System or root.

  • Any other message that mentions installation identity. The identity data saved on the device by an earlier run can't be trusted. Contact Hatz support with the full job output.

  • ingest failed with HTTP followed by a code. Hatz rejected the upload. Run the job again, and if it repeats, contact Hatz support with the full job output.

  • Refusing ingest URL. On a Mac, python3 isn't installed: install it and run the job again. On Windows, download the script again and replace the copy in your RMM, keeping only the token line you added.

  • The output stops without one of these messages or the success line. Your RMM stopped the job early. Set its script timeout to 30 minutes.

  • No output at all. The script never ran. Check that the job targeted the right devices and that the script was saved in your RMM.

  • The device reports, but Macs show no browser history. Give your RMM agent Full Disk Access, usually with your MDM's privacy (PPPC) profile.

Exit codes (some RMMs show these as the job result):

  • 0: uploaded.

  • 1: couldn't reach Hatz, the upload failed after retries, Hatz was still rate limiting, or the job was cancelled.

  • 2: a setup problem, such as a missing or rejected token, a refused proxy setting, paused uploads, or not running as SYSTEM or root.

Still stuck? Contact Hatz support with the RMM name, the device's OS, and the full job output.

Did this answer your question?