Windows mass rollout pilot

To enrol many Windows machines, deploy the Theseus Agent MSI with Microsoft Intune, Configuration Manager or Group Policy. The MSI runs the same installer as the console's one-line command, with the same token, the same certificate check and the same result.

Pilot

The MSI is new. Deploy it to a small pilot group first, check the results on the Agents page, then widen the assignment. The MSI is not signed yet: read Unsigned MSI before you start.

Get the MSI

Every Theseus server serves the same file:

https://<your domain>/enroll/files/theseus-agent-windows-amd64.msi

Its SHA-256 is listed in https://<your domain>/enroll/SHA256SUMS. The file contains nothing specific to your installation: the address and the token are given on the command line, so one file serves every rollout of a Theseus release. A new Theseus release can bring a new MSI (with a new SHA-256 and product code); the one you deployed keeps working.

Check the download on Windows:

(Get-FileHash .\theseus-agent-windows-amd64.msi -Algorithm SHA256).Hash.ToLower()

How the MSI works

1. It installs a small setup script to C:\Program Files\Theseus\Setup\.
2. Still inside the MSI installation, as SYSTEM, the script checks the properties and downloads install.ps1 from SERVER with the console command's certificate check. If that fails, the MSI fails (exit code 1603) and nothing stays installed.
3. When the MSI has finished, a one-shot SYSTEM scheduled task (\Theseus\Theseus Agent Setup) runs install.ps1 with your token: the monitoring agent, the Theseus agent with PATCHING=1, and the enrolment. It removes itself when done.

The last step runs after the MSI because the monitoring agent is itself an MSI, and Windows runs only one MSI installation at a time. So msiexec returning 0 means "staged", not "enrolled". To get the real result, run the wait helper after msiexec, as the command lines below do. It waits for the setup (up to 30 minutes) and exits with the installer's exit code.

If the failure is temporary (network, rate limit, server busy), the task tries again every 15 minutes for a day, and at every startup. The token is deleted from the machine once the setup has succeeded or failed for good.

Properties

Property	Required	Meaning
SERVER	yes	Your console address, for example https://soc.example.com
TOKEN	yes	The enrolment token, THS- and 32 characters
PATCHING	no	1 also installs the Theseus agent for patching (-Patching). Default 0
PIN	with the internal CA	The certificate thumbprint from the console's Windows command (below)
NAME	no	Agent name (-Name). Leave it out for mass rollout: each machine uses its computer name
KEEPAGENT	no	1 on uninstall: remove only the MSI and keep the agent

The console writes the command line for you: create a token (Agents → Add agents or Get started, see Enrol endpoints) and open the tab Windows (MSI, for Intune/ConfigMgr/GPO). It shows the msiexec command line with SERVER, TOKEN and, with the internal CA, PIN filled in (and PATCHING=1 when Also enable patching is on, NAME when you set an agent name), and a Download the MSI link. Run it as SYSTEM with your rollout tool, and add the wait helper as in the command lines below.

To take the values from the Windows command instead, copy it. It contains all three:

...GetCertHashString() -eq '3F1A...C9'}; ... DownloadString('https://soc.example.com/enroll/install.ps1'))) -Token 'THS-...'
                            ^^^^^^^^^^ PIN                    ^^^^^^^^^^^^^^^^^^^^^^^ SERVER               ^^^^^^ TOKEN

With a certificate from a public CA, the command has no GetCertHashString part: leave PIN out. SERVER may include /enroll or not.

For the token, set Machines to the number of machines you roll out to (up to 500) and Valid for to cover the rollout window (up to 30 days). A machine that is already enrolled and gets the MSI keeps its identity and uses no token place. Revoke the token when the rollout is done.

Command lines

Install, and wait for the result (for Intune and Configuration Manager):

cmd /c msiexec /i theseus-agent-windows-amd64.msi SERVER=https://soc.example.com TOKEN=THS-... PIN=3F1A...C9 /qn /l*v "%WINDIR%\Temp\theseus-agent-msi.log" && "%ProgramData%\Theseus\setup\theseus-setup-wait.cmd"

Install only (the setup finishes in the background):

msiexec /i theseus-agent-windows-amd64.msi SERVER=https://soc.example.com TOKEN=THS-... PIN=3F1A...C9 /qn

Uninstall (removes the monitoring agent and the Theseus agent), and wait for the result:

cmd /c msiexec /x {PRODUCT-CODE} /qn && "%ProgramData%\Theseus\setup\theseus-setup-wait.cmd"

Run all of them as SYSTEM or from an elevated prompt. {PRODUCT-CODE} is the MSI's product code: Intune fills it in for you. On a machine, find it with:

Get-ChildItem HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall |
  Get-ItemProperty | Where-Object DisplayName -eq 'Theseus Agent' | Select-Object PSChildName, DisplayVersion

Uninstalling the MSI does not remove the machine from Theseus: remove it on the Agents page as well, so its name can be reused. Uninstalling leaves C:\ProgramData\Theseus\setup (the log and the setup script) and the result in the registry.

Microsoft Intune

Win32 app or line-of-business app

Use a Win32 app. A line-of-business (LOB) MSI app does not fit this MSI:

• Intune detects a LOB app by its MSI product code. The MSI stays installed when the setup that follows it fails (bad token, licence limit), so Intune would report those machines as installed.
• A LOB app cannot run the wait helper, so Intune never sees the installer's exit code.
• A LOB app has no custom return codes and no retry for temporary failures.

A Win32 app runs the command line above, detects success by a registry value that is written only after enrolment, and reports the installer's exit code.

Create the app

1. Download the MSI and check its SHA-256 (above).

2. Put it alone in a folder and package it with the Microsoft Win32 Content Prep Tool:

   IntuneWinAppUtil.exe -c C:\pkg\theseus -s theseus-agent-windows-amd64.msi -o C:\pkg\out

3. In the Intune admin center, go to Apps → Windows → Create → Windows app (Win32) and upload theseus-agent-windows-amd64.intunewin.

4. Program:

   Field	Value
   Install command	cmd /c msiexec /i theseus-agent-windows-amd64.msi SERVER=https://soc.example.com TOKEN=THS-... PIN=3F1A...C9 /qn /l*v "%WINDIR%\Temp\theseus-agent-msi.log" && "%ProgramData%\Theseus\setup\theseus-setup-wait.cmd"
   Uninstall command	cmd /c msiexec /x {PRODUCT-CODE} /qn && "%ProgramData%\Theseus\setup\theseus-setup-wait.cmd" (Intune proposes msiexec /x {...} /qn: add the rest)
   Installation time required	60 minutes
   Install behavior	System
   Device restart behavior	No specific action

   Add PATCHING=1 to the install command for patching. Under Return codes, keep the defaults and add 24, 25, 30, 31, 41 and 50 as Retry. Every other non-zero code is a failure.

5. Requirements: operating system architecture x64; minimum operating system Windows 10.

6. Detection rules: Manually configure detection rules → Registry:

   Field	Value
   Key path	HKEY_LOCAL_MACHINE\SOFTWARE\Theseus\Agent Setup
   Value name	Result
   Detection method	String comparison
   Operator	Equals
   Value	enrolled
   Associated with a 32-bit app on 64-bit clients	No

7. Assignments: assign as Required to a device group. Start with a pilot group, then add groups in steps (see Limits).

The install command, including the token, is visible to every Intune administrator who can read the app. Use a token made for this rollout, and revoke it afterwards.

Read failures

In the Intune admin center, open the app → Device install status. A failed device shows the exit code, sometimes in hexadecimal (0x15 is 21). Match it with the exit codes. On the machine, the Intune Management Extension log (C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\AppWorkload.log, or IntuneManagementExtension.log on older versions) shows the command and its exit code.

Configuration Manager

Create an application with a Windows Installer (*.msi file) deployment type, then change it:

• Installation program: the install command line above (with the wait helper).
• Uninstall program: the uninstall command line above.
• Detection method: a registry setting, HKEY_LOCAL_MACHINE\SOFTWARE\Theseus\Agent Setup, value Result, data type String, equals enrolled, 64-bit ticked.
• User experience: install for system, whether or not a user is logged on; maximum run time 60 minutes.
• Return codes: add 24, 25, 30, 31, 41 and 50 as Failure (retry later) if your version offers it, otherwise leave them as failures.

Deploy as Required to a device collection.

Group Policy

Group Policy software installation cannot pass properties on a command line. To use it:

1. Create a transform (.mst) that sets SERVER, TOKEN and, with the internal CA, PIN in the Property table, with an MSI editor such as Orca from the Windows SDK.
2. Put the MSI and the transform on a share that the computer accounts can read. Restrict the share: the transform contains the token.
3. In Computer Configuration → Policies → Software Settings → Software installation, add the MSI as Assigned, with the transform on the Modifications tab.
4. Turn on Computer Configuration → Administrative Templates → System → Logon → Always wait for the network at computer startup and logon: the MSI needs the network to reach SERVER.

The MSI installs at the next startup. Group Policy does not report the installer's result: check the machines on the Agents page, or the registry on the machine (below). Removing the deployment with Uninstall this application when it falls out of the scope of management uninstalls the agent.

A computer startup script that runs the console's one-line command is an alternative that needs no transform.

Exit codes

The wait helper and the console's Windows command exit with these codes. The MSI itself returns 1603 when staging fails; the code below is then in the registry and in the MSI log (CustomAction TheseusStage returned actual error code ...).

Code	Meaning	What to do
0	Installed and enrolled (or removed)
1	Unexpected error	Read the message in setup.log
10	Not elevated	Run as SYSTEM or as Administrator
11	Invalid properties: SERVER, TOKEN, PIN, NAME, or a NAME that differs from the machine's existing agent	Fix the command line
12	Not 64-bit x86 Windows	Unsupported machine
20	Token refused: invalid, expired, revoked or used up	Create a new token
21	Licence limit reached	Raise the limit, or remove agents (Licence)
22	Name or identity conflict on the server	Remove the old agent in Theseus, or use NAME
23	PATCHING=1, but patch management is off on your server	Turn the patch module on, or drop PATCHING=1
24	Rate limited	Retried; stagger the rollout
25	Enrolment service unavailable	Retried; check the server
26	Enrolment refused for another reason	Read the message in setup.log
30	Network or certificate failure reaching SERVER	Retried; check the address, the firewall and PIN
31	Download failed (the installer, the monitoring agent, or the Theseus agent)	Retried; the machine needs HTTPS to SERVER and to packages.wazuh.com
32	Signature or checksum check failed for a download	Check for a proxy that rewrites downloads
40	Local installation failed (the monitoring agent, its service, the agent key)	Read setup.log and the MSI log
41	Windows Installer stayed busy with another installation for 10 minutes	Retried
50	The wait helper gave up after 30 minutes; the setup is still running or retrying	Intune retries and checks again
51	Nothing staged, or the MSI was rolled back	Read the MSI log

Check a machine

Get-ItemProperty 'HKLM:\SOFTWARE\Theseus\Agent Setup'      # State, Action, ExitCode, Message, Result
Get-Content C:\ProgramData\Theseus\setup\setup.log -Tail 40  # the installer's output, every attempt
Get-ScheduledTask -TaskPath \Theseus\                       # 'Theseus Agent Setup' only while pending

Unsigned MSI

The MSI is not signed with a code-signing certificate yet. What that changes:

• Opened by hand: a downloaded copy carries the mark of the web, so Windows SmartScreen can warn "Windows protected your PC", and the elevation prompt shows Unknown publisher. Check the SHA-256, then run Unblock-File .\theseus-agent-windows-amd64.msi, or install it from an elevated prompt with msiexec.
• Intune, Configuration Manager, Group Policy: none of them requires a signed MSI, and SmartScreen does not check silent installations that run as SYSTEM. The SHA-256 is how you check that the file is the one your server serves.
• Application control: with WDAC or AppLocker rules for installers, allow the MSI by its file hash. The hash changes with each Theseus release that changes the MSI.
• PowerShell: the MSI runs its setup script as a script block, like the console's command, so a PowerShell execution policy (even AllSigned) does not block it. PowerShell constrained language mode, which WDAC or AppLocker script rules can enforce, blocks both the MSI and the console's command.

When the MSI is signed, Windows shows Theseus as the publisher, SmartScreen stops warning once the certificate has reputation, application control can allow every release with one publisher rule, and Get-AuthenticodeSignature shows a valid signature. The command lines, detection rule and exit codes stay the same.

Limits

• Rate limits: at most 20 enrolment requests per 10 minutes from one address, and after 5 failures an address is blocked for an hour. Machines behind one NAT address must be staggered: assign in groups of about 20 per address, or let the retries (code 24) spread the rest. See rate limits.
• Licence: machines beyond your licence's agent limit are refused (code 21). See Licence and agent limits.
• Platforms: 64-bit Windows 10, 11 and Windows Server 2016 or later, with Windows PowerShell 5.1.
• Network: during setup, HTTPS to SERVER and to packages.wazuh.com; afterwards TCP 1514 to the manager and, with patching, HTTPS to your server.