Hodei-Shield Agent: beta guide for Windows

Install the 2.20.0 release (Windows needs 2.13.0 or later) on Windows 10/11 or Server 2016 and later, x64. Use Windows PowerShell 5.1 as Administrator. You need HTTPS to your platform URL and to hs-agent-releases.s3.gra.io.cloud.ovh.net, one enrollment token (works once; your administrator, or your MSSP's, creates it in the console), an agent id (letters, digits, . _ : -; it becomes the machine's permanent name), the platform URL (https://…) and OpenSSL 3 (Git for Windows ships one; a clean Windows has none, see step 2). MEASURED: run on a clean Windows host. If a step misbehaves, stop and write to info@hodeitek.com. Crash reports go to Sentry by default: to opt out, create the marker right after the .msi installs (end of this guide).

1. Download

MEASURED (with an earlier published version in $V). Only from the release store, never from an e-mail or chat link.

$V = '<version>'
$B = 'https://hs-agent-releases.s3.gra.io.cloud.ovh.net'
$file = "hodei-shield-$V-x86_64.msi"
New-Item -ItemType Directory hodei-install | Out-Null; cd hodei-install
foreach ($n in $file, 'SHA256SUMS', 'SHA256SUMS.sig') { Invoke-WebRequest "$B/agent/$V/$n" -OutFile $n }

Before you run anything, check that the download is authentic: verify an agent release and verify the download.

2. Verify and install

The .msi carries an Authenticode signature (publisher Hodeitek S.L.), and SHA256SUMS.sig is the release signature (Ed25519) over SHA256SUMS. Save the release key (standalone page; its fingerprint, not the package's checksum (the package is checked against SHA256SUMS), is the SHA-256 of its raw 32 bytes: 8b730d2fcbd90e2656bd9b3f265638f1e8e8ac2379d48b0636feb5efe5a88f07):

@'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAEUqKd+ot7BESwk+vf6EVBKudMi6F6jmY3dJeHXfCWkQ=
-----END PUBLIC KEY-----
'@ | Set-Content -Encoding ascii hodei-shield-release.pub.pem

Paste the whole block at once into a PowerShell console (not line by line, not the ISE); it installs only if every check passes. MEASURED: the checks, refusal of tampered files, and a successful install of the signed 2.13.0 set.

& { $ErrorActionPreference = 'Stop'
  if (-not (Test-Path -LiteralPath $file)) { throw "$file is not in this folder" }
  $auth = Get-AuthenticodeSignature .\$file
  $auth | Format-List Status, SignerCertificate, TimeStamperCertificate
  if ($auth.Status -ne 'Valid' -or $auth.SignerCertificate.Subject -notmatch 'CN=Hodeitek S\.L\.') { throw 'Authenticode: not Valid or not signed by Hodeitek S.L.' }
  $ssl = 'C:\Program Files\Git\usr\bin\openssl.exe'
  if (-not (Test-Path -LiteralPath $ssl)) { throw "OpenSSL 3 not found at $ssl" }
  if (-not (Test-Path -LiteralPath hodei-shield-release.pub.pem)) { throw 'hodei-shield-release.pub.pem is missing: write it first' }
  & $ssl version
  & $ssl base64 -d -A -in SHA256SUMS.sig -out SHA256SUMS.sig.raw
  if ($LASTEXITCODE -ne 0) { throw 'SHA256SUMS.sig is not valid base64' }
  (Get-Item SHA256SUMS.sig.raw).Length
  & $ssl pkeyutl -verify -rawin -pubin -inkey hodei-shield-release.pub.pem -sigfile SHA256SUMS.sig.raw -in SHA256SUMS
  if ($LASTEXITCODE -ne 0) { throw 'Signature Verification Failure: do not install' }
  $want = ((Get-Content SHA256SUMS | Where-Object { $_ -match ('  ' + [regex]::Escape($file) + '$') }) -split '\s+')[0]
  if ($file -notmatch '\.msi$' -or -not $want) { throw "$file is not an .msi listed in SHA256SUMS" }
  if ((Get-FileHash $file -Algorithm SHA256).Hash -ieq $want) { 'OK' } else { throw 'checksum mismatch: do not install' }
  $p = Start-Process msiexec.exe -ArgumentList '/i', "`"$PWD\$file`"", '/qn', '/l*v', "`"$PWD\install.log`"" -Wait -PassThru
  if ($p.ExitCode -ne 0) { throw "msiexec exit $($p.ExitCode): see install.log" }
}

No OpenSSL on this machine? A clean Windows has none. Either install Git for Windows (it includes OpenSSL 3 at that path) or run this signature check on another computer that has OpenSSL 3, using the same three files. The installer's own Authenticode signature is checked separately (Get-AuthenticodeSignature must say Valid, signer Hodeitek S.L.), so do not skip that one.

Expect 64, Signature Verified Successfully, OK. Never run a bare msiexec or put the token on an installer line. The service waits quietly until you enroll.

3. Configure and enroll

MEASURED. The token is typed at a prompt and kept in an admin-only file.

@'
platform_url = "https://app.hodeishield.com"
state_dir = 'C:\ProgramData\Hodei-Shield\state'
'@ | Set-Content -Encoding ascii 'C:\Program Files\Hodei-Shield\Agent\hodei-shield.toml'
$ErrorActionPreference = 'Stop'
New-Item -ItemType Directory C:\ProgramData\Hodei-Shield\token -ErrorAction Stop | Out-Null
icacls C:\ProgramData\Hodei-Shield\token /inheritance:r /grant:r '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-18:(OI)(CI)F'
if ($LASTEXITCODE -ne 0) { throw 'icacls failed' }
$secure = Read-Host -AsSecureString 'Enrollment token for THIS machine'
[Net.NetworkCredential]::new('', $secure).Password | Set-Content -NoNewline -Encoding ascii C:\ProgramData\Hodei-Shield\token\enroll.token
$secure.Dispose()
cd 'C:\Program Files\Hodei-Shield\Agent'
try {
Get-Content -Raw C:\ProgramData\Hodei-Shield\token\enroll.token | & '.\hodei-shield.exe' enroll --token-stdin --agent-id '<the id you wrote down for THIS machine>'
} finally { Remove-Item -Recurse -Force C:\ProgramData\Hodei-Shield\token }
Restart-Service hodei-shield

Success prints this (a few JSON log lines such as secret store ACL measured and ACCEPTED and enrolled as a signing producer also appear; ids are examples):

enrolled: producer=endpoint_agent:<your-agent-id> public_key_id=<uuid> tenant_id=<uuid>
self-update: after checking these against the console, run from an elevated prompt (Run as administrator) in the agent's install folder (<Program Files>\Hodei-Shield\Agent):
  hodei-shield.exe pin-update-identity --tenant <uuid> --producer "endpoint_agent:<your-agent-id>" --public-key-id <uuid>
If the agent service is stopped, start it: Start-Service hodei-shield. If it is running and was waiting for this enrollment, it will pick it up within 5 minutes; to pick it up now: Restart-Service hodei-shield

Check that the tenant_id and the agent id match what the console shows, then run the pin-update-identity line it prints, exactly as printed, from an elevated prompt in C:\Program Files\Hodei-Shield\Agent. It records which tenant and identity may authorize future updates of this agent; it changes nothing else. Then Restart-Service hodei-shield so the agent starts reporting now. The first report can take several minutes on Windows.

If it fails, do not reuse the token: ask for a new one. Certificate or TLS error: add no certificate and turn no check off; the agent trusts only C:\ProgramData\Hodei-Shield\state\platform-ca.pem. Send the output of hodei-shield.exe diagnose to your administrator. MEASURED (Windows 11, 2026-10-28): a silent install exits 1603 with Error 1925 in install.log if you are not running as Administrator; nothing is installed (not measured on Server). Other failures: troubleshooting.

4. Check in the console

MEASURED. Running and self-test exiting 0 (it prints INFO lines):

Get-Service hodei-shield; & 'C:\Program Files\Hodei-Shield\Agent\hodei-shield.exe' self-test

The machine appears under Endpoints in the console after its first cycle.

Expected warning: stable macOS and Windows releases do not update themselves. About once an hour the log shows a WARN line update poll/apply did not succeed; continuing on current version with the reason self-update is not supported on this OS by this release. It is expected and harmless: you update by installing the new package. (A later release logs it once, as information.)

Controls showing "Error" in this beta: some controls may show "Error" on systems whose language is not English, or because the agent runs without administrator rights. This does not mean the control is failing: the agent could not read it reliably, and it does not count it as compliant. The next beta version corrects this.

Known issue (OpenSSH Server on Windows): if your sshd service starts with a non-default configuration file (-f <path> in the service's command line) on a Windows whose display language is not English, the SSH controls may be evaluated against the default C:\ProgramData\ssh\sshd_config instead of your file. The default setup is not affected. Fixed in the next release; until then, tell us if you use -f.

5. Update by hand

Do not enroll again. The stable 2.20.0 does not apply Windows updates itself: update by hand with the new .msi, no new token. (Beta-channel builds can update themselves, only when the console's signed policy approves the new MSI digest and an administrator has pinned the update identity once, else identity_unpinned; MEASURED 2026-10-27 by Hodeitek on Windows 11, 2.17.0-beta.1 to beta.3.) MEASURED (2.12.3 to 2.12.4: configuration and state kept, next submission accepted). Back up the configuration, download the new .msi as in step 1, then run the step 2 block again with the new $V and $file. The installer refuses older versions (exit 1603).

Copy-Item 'C:\Program Files\Hodei-Shield\Agent\hodei-shield.toml' "$HOME\hodei-shield.toml.bak"

Afterwards Get-Service hodei-shield must say Running, & '.\hodei-shield.exe' version the new version, and self-test exit 0. If hodei-shield.toml is missing, copy the backup back and Restart-Service hodei-shield.

6. Uninstall

MEASURED. First ask your administrator to revoke the machine (console: Endpoints, the endpoint, Revoke enrolment). Use the absolute path of the .msi you kept. Left behind: C:\ProgramData\Hodei-Shield\state (private key, queue, CA bundle), the logs folder C:\Program Files\Hodei-Shield\Agent\logs (MEASURED, Windows 11 and Server 2022, 2026-10-28), Agent\hodei-shield.toml only if you created one, telemetry-off, and %APPDATA%\Hodei-Shield per user.

$msi = (Resolve-Path '<folder where you downloaded it>\hodei-shield-<version>-x86_64.msi').Path
(Start-Process msiexec.exe -ArgumentList '/x', "`"$msi`"", '/qn' -Wait -PassThru).ExitCode

Purge (MEASURED, Windows 11, 2026-10-29; irreversible, only after revoking). The state folder is protected so that only Administrators, SYSTEM and the service account can open it, and a protected folder can refuse deletion even to an elevated prompt. The guard stops if a folder was replaced by a link:

foreach ($p in 'C:\ProgramData\Hodei-Shield', 'C:\Program Files\Hodei-Shield') {
  if (Test-Path -LiteralPath $p) {
    if ((Get-Item -LiteralPath $p -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) { throw "$p is a link: stop and ask for help" }
    Remove-Item -LiteralPath $p -Recurse -Force
  }
}
Remove-Item -LiteralPath "$env:APPDATA\Hodei-Shield" -Recurse -Force -ErrorAction SilentlyContinue   # per user

Privacy and help. Error reports (crashes only, no personal data) go to Sentry; turn off with New-Item -ItemType File -Force "$env:ProgramData\Hodei-Shield\telemetry-off" | Out-Null; Restart-Service hodei-shield (MEASURED). Help: info@hodeitek.com or the Beta button in the console.