Cloud Secure Edge Docs
Event Hooks Implementation Guide
This feature is supported on Windows devices with desktop app version 4.10.0+ and on macOS devices with desktop app version 4.2.0+. For an overview of how Event Hooks work, see Event Hooks for Post-Connection Scripts.
Overview
This guide walks through a working, end-to-end Event Hooks deployment that fires a script every time a user connects to a Service Tunnel. It covers:
- The artifacts that need to land on each managed endpoint.
- Step-by-step Windows setup using Task Scheduler.
- Step-by-step macOS setup using launchd QueueDirectories.
- Fleet rollout via any RMM or MDM tool, with N-able N-sight as the worked example.
- A worked use case that replicates the legacy NetExtender Run domain login scripts behavior on Cloud Secure Edge.
- Troubleshooting and a pilot/rollout plan.
Why script execution lives in the operating system, not in the desktop app: Allowing a remote access client to spawn arbitrary scripts opens an attack surface that endpoint detection software cannot easily monitor. Delegating execution to Windows Task Scheduler and macOS launchd keeps script execution inside a heavily managed, observable subsystem while preserving the same end-user outcome.
Prerequisites
- CSE desktop app is installed on the endpoint and the user is enrolled.
- The desktop app meets the minimum version listed in the note above.
- A Service Tunnel is published to the resources the script needs to reach (file servers, domain controllers, internal hosts).
- The endpoint protection product permits script execution from the path the Scheduled Task or launchd job calls. If endpoint protection is blocking the trigger directory or event channel, the hook will not fire.
- For Windows domain logon scenarios: the endpoint is joined to on-premises Active Directory, and the user has a logon script defined in the AD Profile tab.
Windows implementation
The Windows path uses three artifacts placed on the endpoint:
| File | Purpose |
|---|---|
C:\ProgramData\SCS\Invoke-EventHook.xml | Scheduled Task definition. Listens for the CSE event and launches the hidden VBScript launcher. |
C:\ProgramData\SCS\Invoke-EventHook.vbs | One-line launcher that starts the PowerShell wrapper with no visible console window. |
C:\ProgramData\SCS\Invoke-EventHook.ps1 | Wrapper that performs the admin's chosen action (drive mapping, gpupdate, custom logic). |
macOS implementation
The macOS path uses two artifacts placed on the endpoint:
| File | Purpose |
|---|---|
~/Library/LaunchAgents/com.sonicwall.cse.eventhook.plist | launchd job. Watches the CSE connect queue directory and runs the wrapper script. |
~/Library/Application Support/sonicwallcse/scripts/event-hook.sh | Wrapper script that performs the admin's chosen action. |
Deploying to a fleet via RMM or MDM
Any device management tool that can place files on a managed endpoint and register a Scheduled Task or load a launchd plist can deploy Event Hooks at scale. The general pattern is the same regardless of which tool you use.
Worked use case: NetExtender domain logon script parity
Admins migrating from SonicWall NetExtender often rely on the Run domain login scripts option to map drives and apply Group Policy after the VPN authenticates. Cloud Secure Edge does not include a client-side script execution toggle, but the Windows wrapper in this guide produces equivalent end-user behavior with no per-user RMM customization.
The wrapper resolves the user's scriptPath attribute against Active Directory at execution time, so:
- Changes to a user's logon script in the AD Profile tab take effect on the next connect with no RMM redeployment.
- Different users can have entirely different logon scripts (for example,
finance.vbsversussupport.vbs); the wrapper picks up whatever is assigned to the signed-in user. - Conditional and location-specific Group Policy drive maps continue to apply because the wrapper triggers
gpupdate.
This is the supported migration path from NetExtender's Run domain login scripts checkbox.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Event ID 9001 does not appear in Event Viewer. | Endpoint protection software is blocking the CSE event writer. | Add the CSE Connect agent install path to the antivirus exclusion list, then reconnect the tunnel. |
| Task runs but no drives appear. | Task is executing as SYSTEM rather than the interactive user. | Confirm the Principal in the Scheduled Task XML is S-1-5-32-545 (Users) and Context is Author, not Highest. |
| Drives appear but GPO maps are missing. | gpupdate ran before a domain controller was reachable. | Increase the Start-Sleep value in the wrapper from 2 seconds to 5–15 seconds depending on tunnel ramp-up time. |
| Script runs twice on reconnect. | CSE wrote more than one tunnel-up event during the reconnect. | The MultipleInstancesPolicy value of IgnoreNew suppresses overlapping runs. If they still occur, add a one-minute file-timestamp guard. |
| PowerShell execution policy blocks the wrapper. | Group Policy restricts script execution. | The launcher already passes -ExecutionPolicy Bypass. Confirm no Constrained Language Mode policy is enforced on the endpoint. |
| A console window briefly flashes on the user's screen. | Task is calling powershell.exe directly instead of the wscript.exe launcher. | Confirm the Scheduled Task Action is wscript.exe with Invoke-EventHook.vbs, not powershell.exe with the .ps1 file. | |
| macOS launchd job does not fire. | The plist was not loaded, or the QueueDirectories path was quoted incorrectly. | Run launchctl list | grep cse.eventhook. If absent, launchctl load the plist. Confirm the path uses ~/Library/Application Support/.... |
| macOS job fires once and never again. | The script did not drain the queue directory, so launchd does not observe new files. | Confirm the wrapper deletes processed files from the queue directory (see Step 1 of the macOS section). |
Pilot and rollout plan
| Phase | Scope | Exit criteria |
|---|---|---|
| Lab validation | One technician workstation joined to your test domain. | Tunnel-up event fires, Scheduled Task runs, transcript shows the expected action completed. |
| Customer pilot | Five endpoints, including at least one with conditional GPO maps. | All pilot users report the expected outcome within thirty seconds of connect for three consecutive days. |
| Site rollout | Remaining endpoints at the pilot site. | Help desk volume related to the hooked workflow does not increase over the prior week's baseline. |
| Fleet rollout | Remaining sites, grouped by deployment ring. | Standing automation policy in your RMM covers every newly enrolled CSE device. |
Forward-looking notes
VBScript deprecation
Microsoft has announced that VBScript will move from default-disabled to fully removed in future Windows servicing updates. The wrapper script in the Windows section handles .vbs, .bat, .cmd, and .ps1 logon scripts, so the same deployment carries forward as you migrate users off VBScript. To migrate a script, change the scriptPath attribute on the corresponding user in Active Directory. No change is required in your RMM or in the Scheduled Task.
Support
For support questions outside the scope of this guide, open a case at https://helpdesk.sonicwall.com.
