Cut 5083 admu exe upload to jc commands option by shashisinghjc · Pull Request #249 · TheJumpCloud/jumpcloud-ADMU

shashisinghjc · 2026-04-06T09:55:26Z

Issues

CUT-5083 - ADMU Exe Upload to JC Commands Option

What does this solve?

This change introduces support for using locally available executables to mitigate failures caused by GitHub API rate limiting during JC Command execution.

Adds validation logic to check for gui_jcadmu.exe in C:\Windows\Temp (and uwp_jcadmu in C:\Windows) when localEXEs=true
Verifies SHA and ensures the binary is the latest version before use
Skips GitHub download if local validation succeeds
Falls back to GitHub download (with retry + backoff) if local files are missing
Handles API rate limit scenarios gracefully by issuing a warning and using local copies when validation is not possible
Ensures strict failure (exit 1) when required conditions are not met

Is there anything particularly tricky?

NA

How should this be tested?

Set localEXEs to $true in the script.
Run the script and verify: The script validates the SHA256 of the EXE against the GitHub release. Success and error/warning messages are logged as expected.
For negative testing, modify the EXE or simulate GitHub API rate limiting and confirm the script handles these cases correctly.

Screenshots

Note

Medium Risk
Touches migration execution paths and executable download/validation logic (GUI + UWP), which can block or skip parts of migration if misconfigured. Changes are gated behind localEXEs but still alter retry/validation behavior and error handling.

Overview
Adds an opt-in localEXEs mode for remote/command-driven ADMU runs to prefer locally provided gui_jcadmu.exe/uwp_jcadmu.exe, validating SHA256 (and version metadata when available) against the latest GitHub release and gracefully handling GitHub API rate limits.

Updates the JC Agent invoke script to pre-check required local binaries (and copy uwp_jcadmu.exe into C:\Windows when present), pass localEXEs through to migrations, and refactors GUI exe retrieval to return a resolved path (download or validated local). In Start-Migration, UWP app restoration now uses a helper that either enforces/validates a local uwp_jcadmu.exe or downloads via the releases/latest/download URL with retry/backoff, skipping UWP restore with a warning if it cannot be prepared.

Bumps module version to 2.12.3 and updates documentation/help text (docs + help XML) to include the new parameter and minor formatting fixes; UI window titles are updated to the new version, and a placeholder acceptance test file is added.

^{Reviewed by Cursor Bugbot for commit b95883c. Bugbot is set up for automated code reviews on this repo. Configure here.}

…bled

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1

… or API failures (not just rate limiting)

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

…t a version match

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 21ac223. Configure here.}

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1

kmaranionjc · 2026-04-07T22:57:05Z

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1

+$localEXEs = $false # When true, require gui_jcadmu.exe in C:\Windows\Temp and uwp_jcadmu.exe in C:\Windows
+
+# If localEXEs is enabled, ensure uwp_jcadmu.exe is copied from Temp to Windows if needed
+if ($localEXEs) {


This works great, thanks for the changes here

kmaranionjc

Functionality looks good to me. Was able to migrate 2 users. This exe scenario is more for Invoke and validating GUI exe in the temp folder. There should be no need for Start-Migration changes

kmaranionjc · 2026-04-07T23:03:52Z

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1

    systemContextBinding      = $systemContextBinding
    LeaveDomainAfterMigration = $LeaveDomainAfterMigration
    removeMDM                 = $removeMDM
+    localEXEs                 = $localEXEs


I don't think we need to change or add local exe validation in Start-Migration

The Start-Migration updates ensure that users running the script directly receive the same reliability, validation, and fallback logic as the GUI/Invoke flow. While the specific deployment (GUI with pre-uploaded EXEs) is less impacted, these changes maintain consistency and robustness across all methods.

Let me know if it helps, else we can remove this. Shouldn't be a big trouble.

kmaranionjc · 2026-04-07T23:04:37Z

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

            HelpMessage = "When set to true, the ADMU will remove any existing MDM enrollment from the system. This parameter requires the `leaveDomain` parameter to also be set to true. This parameter will remove MDM enrollment profiles if they have non-null ProviderIDs, and UPNs associated with them. This parameter will not remove JumpCloud MDM enrollments.")]
        [bool]
        $removeMDM = $false,
+        [Parameter(


Same here, I don't think we need to change or add local exe validation in Start-Migration.

The Start-Migration updates ensure that users running the script directly receive the same reliability, validation, and fallback logic as the GUI/Invoke flow. While the specific deployment (GUI with pre-uploaded EXEs) is less impacted, these changes maintain consistency and robustness across all methods.

Let me know if it helps, else we can remove this. Shouldn't be a big trouble.

I disagree, we need to inform the Start-Migration function that we will be supplying the local version of the uwp_jcadmu.exe file in order to drive the behavior in the card acceptance criteria.

kmaranionjc · 2026-04-07T23:04:56Z

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

        $isForm = $PSCmdlet.ParameterSetName -eq "form"
        $trackAccountMerge = $false
+
+        function Get-UwpJcadmuReleaseInfo {


Same here, I don't think we need to change or add local exe validation in Start-Migration.

The Start-Migration updates ensure that users running the script directly receive the same reliability, validation, and fallback logic as the GUI/Invoke flow. While the specific deployment (GUI with pre-uploaded EXEs) is less impacted, these changes maintain consistency and robustness across all methods.

Let me know if it helps, else we can remove this. Shouldn't be a big trouble.

jworkmanjc

A few thoughts here to start.

It's not super well documented but in order to add a new parameter to the EXE, we need to update the Deploy/Functions/New-ADMUTemplate.ps1 file to include the localEXEs parameter. I rebuilt the exe with that change and was able to test the exe as if it were called via the invoke script. This would need to be changed in order to make the changes in the jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1 prevent replacement of the uwp exe.

You did hit the nail on the head though, there's no need to validate the gui exe once we are running start-migration because the exe invoking the script is the gui_jcadmu.exe.

There are three new functions added to Start-Migration.ps1. These should be private functions, each with basic tests we can call to validate the behavior.

You are right in adding this new parameter to start migration though, when we set the parameter in the invoke script & supply the gui/uwp exes, when we call the gui exe, we need to tell the tool that there's no need to download a new version of the uwp. I'm not seeing that totally work just yet but perhaps I'm missing something in the way you've tested this.

Running through the AC:
I believe you've ticked off the requirements for the invoke script. We just need to figure out how to get the last part of the Start-Migration script and functions working correctly.

For the Start-Migration behavior
When you run

. "C:\Users\jworkman\Desktop\gui_jcadmu.exe" -SelectedUserName "S-1-12-1-1616384916-1297768490-51239584-3993624739" -JumpCloudUserName "george.costanza" -TempPassword "TempPass!123!123" -adminDebug:$true -autoBindJCUser:$false -localExes:$true

The migration should continue and not download the latest uwp, it should instead log if the UWP is present, the version and not throw if it's missing. Right now I'm getting that error with Get-FileHash and I'm not seeing the private functions continue.

When you run

. "C:\Users\jworkman\Desktop\gui_jcadmu.exe" -SelectedUserName "S-1-12-1-1616384916-1297768490-51239584-3993624739" -JumpCloudUserName "george.costanza" -TempPassword "TempPass!123!123" -adminDebug:$true -autoBindJCUser:$false -localExes:$false

The migration should continue and download the latest uwp (default behavior). This appears to be working.

In Summary, we need to:

Update the New-ADMUTemplate.ps1 file to actually allow for the exe to make use of your new localExes param
The functions added to Start-Migration, I'd like to see these moved to the private functions locations and get tests generated for those files.
I'm not sure Test-UwpJcadmuExe function is working as intended. When I test, Get-FileHash is throwing an error.

jworkmanjc · 2026-04-08T19:17:08Z

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

+
+            if ($localEXEs) {
+                if (-not (Test-Path -Path $destinationPath -PathType Leaf)) {
+                    throw "localEXEs is enabled, but required file 'uwp_jcadmu.exe' was not found at '$destinationPath'."


Right now the failure to download the UWP is not a breaking error. I'm hesitant to make it one here which would be a change from how we perform migrations currently.

The ADMU will write the items to the storage device, specifically the user's directory who's being migrated, the UWP can always be run again post-migraiton so I don't want this to throw or otherwise halt a migration that's been successful up to this point.

jworkmanjc · 2026-04-08T19:18:29Z

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

+                    }
+                }
+
+                throw "Failed to validate UWP executable: $errorMessage"


Potentially an issue here if we throw, this could be a terminating error and we don't want migration to halt in that case.

jworkmanjc · 2026-04-08T20:54:37Z

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

            HelpMessage = "When set to true, the ADMU will remove any existing MDM enrollment from the system. This parameter requires the `leaveDomain` parameter to also be set to true. This parameter will remove MDM enrollment profiles if they have non-null ProviderIDs, and UPNs associated with them. This parameter will not remove JumpCloud MDM enrollments.")]
        [bool]
        $removeMDM = $false,
+        [Parameter(


I disagree, we need to inform the Start-Migration function that we will be supplying the local version of the uwp_jcadmu.exe file in order to drive the behavior in the card acceptance criteria.

jworkmanjc · 2026-04-08T20:59:44Z

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1

+
+            $localFile = Get-Item -Path $FilePath -ErrorAction Stop
+            $localVersion = $localFile.VersionInfo.FileVersion
+            $localFileHash = (Get-FileHash -Path $FilePath -Algorithm SHA256).Hash.ToLower()


Getting some error here:

Although I am able to run this outside the ADMU which is odd.

shashisinghjc added 4 commits April 2, 2026 12:56

Initial hanges pushed - Added SHA validation and localEXE options ena…

67a7b80

…bled

changelog

c280912

Build updated

e471b8d

Copy uwp_jcadmu.exe to C:\windows if localexe = True

76e1146

shashisinghjc requested a review from a team as a code owner April 6, 2026 09:55

shashisinghjc requested a review from kmaranionjc April 6, 2026 09:55

shashisinghjc added ADMU ADMU Module Release patch Patch version release labels Apr 6, 2026

Build updated

7100d24

cursor bot reviewed Apr 6, 2026

View reviewed changes

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1 Show resolved Hide resolved

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1 Show resolved Hide resolved

$RetryDelaySeconds configured

f7bc903

cursor bot reviewed Apr 6, 2026

View reviewed changes

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1 Outdated Show resolved Hide resolved

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1 Outdated Show resolved Hide resolved

download url for uwp_jcadmu.exe set to static

a42c83d

cursor bot reviewed Apr 6, 2026

View reviewed changes

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1 Outdated Show resolved Hide resolved

fixed "UWP exe copy skips update when destination already exists"

c15e2c3

cursor bot reviewed Apr 6, 2026

View reviewed changes

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1 Outdated Show resolved Hide resolved

The fallback for AllowUnvalidatedOnApiFailure now handles all network…

d6aac12

… or API failures (not just rate limiting)

cursor bot reviewed Apr 6, 2026

View reviewed changes

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1 Show resolved Hide resolved

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1 Show resolved Hide resolved

cursor review fixes

0c470c9

cursor bot reviewed Apr 6, 2026

View reviewed changes

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1 Outdated Show resolved Hide resolved

Configured IsValid to be determined by only valid hash match

0f21d1f

cursor bot reviewed Apr 7, 2026

View reviewed changes

jumpcloud-ADMU/Powershell/Public/Start-Migration.ps1 Outdated Show resolved Hide resolved

The UWP EXE validation now only requires a hash match for IsValid, no…

21ac223

…t a version match

cursor bot reviewed Apr 7, 2026

View reviewed changes

jumpcloud-ADMU-Advanced-Deployment/InvokeFromJCAgent/3_ADMU_Invoke.ps1 Outdated Show resolved Hide resolved

changelog updated

b95883c

kmaranionjc reviewed Apr 7, 2026

View reviewed changes

kmaranionjc requested changes Apr 7, 2026

View reviewed changes

kmaranionjc requested a review from jworkmanjc April 7, 2026 23:06

jworkmanjc requested changes Apr 8, 2026

View reviewed changes

Conversation

shashisinghjc commented Apr 6, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issues

What does this solve?

Is there anything particularly tricky?

How should this be tested?

Screenshots

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kmaranionjc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jworkmanjc left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

shashisinghjc commented Apr 6, 2026 •

edited by cursor bot

Loading

jworkmanjc left a comment •

edited

Loading