Skip to content

Hodei-Shield Agent: beta guide for macOS

Install the 2.20.0 release on macOS 13 or later (Apple Silicon or Intel). You need an administrator account, outbound 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 (brew install openssl@3; the system openssl is LibreSSL and cannot do the check). Crash reports go to Sentry by default: to opt out, create the marker before installing the .pkg (end of this guide).

Not yet measured on a Mac. Every step below is NOT RUN: it is written from the packaging. You are among the first to follow it. If a step misbehaves, stop and write to info@hodeitek.com; do not retry the enrollment.

1. Download

Only from the release store, never from a link in an e-mail or chat. 

V="${V:?set V to the version you were given}"
B=https://hs-agent-releases.s3.gra.io.cloud.ovh.net
mkdir hodei-install && cd hodei-install
curl -fsSLO "$B/agent/$V/hodei-shield-$V-universal.pkg"
curl -fsSLO "$B/agent/$V/SHA256SUMS"
curl -fsSLO "$B/agent/$V/SHA256SUMS.sig"

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

2. Verify

Standalone version of this check: verify-release.md. The .pkg is signed with an Apple Developer ID and notarized; SHA256SUMS.sig is the release signature (Ed25519) over SHA256SUMS. Save as hodei-shield-release.pub.pem (this is the key's fingerprint, not the package's checksum; the package is checked against SHA256SUMS below. To compute the fingerprint of the key you saved: /opt/homebrew/opt/openssl@3/bin/openssl pkey -pubin -in hodei-shield-release.pub.pem -outform DER | tail -c 32 | shasum -a 256 → 8b730d2fcbd90e2656bd9b3f265638f1e8e8ac2379d48b0636feb5efe5a88f07 -): 

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAEUqKd+ot7BESwk+vf6EVBKudMi6F6jmY3dJeHXfCWkQ=
-----END PUBLIC KEY-----
Use the OpenSSL 3 full path (/usr/local/opt/openssl@3/bin/openssl on Intel): 
SSL=/opt/homebrew/opt/openssl@3/bin/openssl
$SSL base64 -d -A -in SHA256SUMS.sig -out SHA256SUMS.sig.raw
$SSL pkeyutl -verify -rawin -pubin -inkey hodei-shield-release.pub.pem \
  -sigfile SHA256SUMS.sig.raw -in SHA256SUMS      # Signature Verified Successfully
grep " hodei-shield-$V-universal\.pkg\$" SHA256SUMS | shasum -a 256 -c -   # ...pkg: OK
pkgutil --check-signature "hodei-shield-$V-universal.pkg"   # Developer ID Installer: Hodeitek
Anything else means do not install: delete the files and tell Hodeitek.

3. Install

sudo installer -pkg "hodei-shield-$V-universal.pkg" -target /
sudo -u _hodeishield tee /var/lib/hodei-shield/hodei-shield.toml >/dev/null <<'EOT'
platform_url = "https://<platform host>"
state_dir = "/var/lib/hodei-shield"
EOT
/usr/local/bin/hodei-shield version
The package creates the service account _hodeishield, the state folder and the CA file, and starts the service, which waits quietly until you enroll. A service that restarts over and over is a fault.

What the installer puts on your Mac

installer only prints its own progress lines (ending in The install was successful.). The package's own messages go to the Installer log; to read them:

sudo grep 'postinstall:' /var/log/install.log

The package installs: - /usr/local/bin/hodei-shield: the agent (root:wheel 0755). - /Applications/Hodei-Shield.app: the optional status window. It only reads a status file and holds no keys. - /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist and /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist: the agent service. It runs as the _hodeishield system account, never as root. - /Library/PrivilegedHelperTools/com.hodeitek.hodei-shield.update and /Library/LaunchDaemons/com.hodeitek.hodei-shield.update.plist: the update helper. It is loaded but idle: stable macOS releases do not update themselves, and you update by installing the new .pkg. - /etc/hodei-shield/platform-ca.pem (the platform's CA), /etc/newsyslog.d/com.hodeitek.hodei-shield.conf (log rotation; not active yet in 2.20.1, so /var/log/hodei-shield grows until you clear it), /usr/local/libexec/hodei-shield/uninstall.sh (the uninstaller), /usr/local/share/doc/hodei-shield/THIRD-PARTY-NOTICES. - Folders: /var/lib/hodei-shield (0700, state and the private key), /var/log/hodei-shield (0750, logs), /var/run/hodei-shield (status for the window), /private/var/db/hodei-shield-update (root 0700, update records).

To remove everything: sudo /usr/local/libexec/hodei-shield/uninstall.sh (add --purge to also delete the state and the logs).

Login Items: after installing, macOS may notify you that background items were added, and System Settings → General → Login Items → Allow in the Background lists the agent as "Hodeitek SL". That is the Hodei-Shield agent (signed by Hodeitek S.L.). Leave it switched on: if you turn it off, the agent stops running and the host stops reporting.

Menu bar icon: in this version the menu bar shows a grey shield, even when everything is working. That is normal and does not mean the agent is stopped. Hover over it to see the status, or open Hodei-Shield.app for details.

4. Enroll

Once per machine. The token is typed hidden, never on a command line. 

cd /
IFS= read -rs HODEI_TOKEN && echo
printf '%s' "$HODEI_TOKEN" | sudo -u _hodeishield env \
  HODEI_PLATFORM_URL="https://<platform host>" \
  HODEI_STATE_DIR=/var/lib/hodei-shield \
  /usr/local/bin/hodei-shield enroll --token-stdin --agent-id '<this machine id>'
unset HODEI_TOKEN
sudo launchctl kickstart -k system/com.hodeitek.hodei-shield
Once it is running with both, it evaluates and submits straight away, then again every submit interval (default 3600 seconds). Success prints enrolled: producer=endpoint_agent:<id> public_key_id=… tenant_id=….

What you will see

{"timestamp":"…","level":"INFO","fields":{"message":"enrolled as a signing producer","public_key_id":"…","producer":"\"endpoint_agent:<your-agent-id>\"","tenant_id":"…"},"target":"agent_enroll::producer"}
enrolled: producer=endpoint_agent:<your-agent-id> public_key_id=<uuid> tenant_id=<uuid>
If the agent service is stopped, start it: sudo launchctl load -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist. If it is running and was waiting for this enrollment, it will pick it up within 5 minutes; to pick it up now: sudo launchctl kickstart -k system/com.hodeitek.hodei-shield
The first line is the agent's log entry; the enrolled: line is the result: note the public_key_id. Then run the kickstart command it suggests so the agent starts reporting now instead of within 5 minutes. If it fails, do not reuse the token: ask your administrator for a new one. Certificate or TLS error: add no certificate and turn no check off; the agent trusts only /etc/hodei-shield/platform-ca.pem. Send the output of hodei-shield diagnose to your administrator; other failures: troubleshooting.

5. Check in the console

sudo launchctl print system/com.hodeitek.hodei-shield | head, and this must exit 0: sudo -u _hodeishield sh -c 'cd /var/lib/hodei-shield && exec /usr/local/bin/hodei-shield self-test'. The machine appears under Endpoints after its first cycle. Logs (the folder is readable only by the service account, so use sudo): sudo tail -50 /var/log/hodei-shield/hodei-shield.err.log, or both logs with sudo sh -c 'tail -50 /var/log/hodei-shield/*.log'. A Mac with no EDR or antivirus reports one fail (Third-party EDR present and active); that is true, not a fault.

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.

6. Update by hand

macOS has no update applier: updates are a manual .pkg. Do not enroll again. /var/lib/hodei-shield is untouched. Download and verify the new .pkg as in steps 1 and 2, then: 

V=<new version>
sudo cp -p /usr/local/bin/hodei-shield ~/hodei-shield.prev    # rollback copy
sudo installer -pkg "hodei-shield-$V-universal.pkg" -target /
/usr/local/bin/hodei-shield version                           # the new version
sudo -u _hodeishield sh -c 'cd /var/lib/hodei-shield && exec /usr/local/bin/hodei-shield self-test'
Rollback: sudo launchctl bootout system/com.hodeitek.hodei-shield, then sudo install -o root -g wheel -m 0755 ~/hodei-shield.prev /usr/local/bin/hodei-shield, then sudo launchctl bootstrap system /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist.

7. Uninstall

First ask your administrator to revoke the machine (console: Endpoints, the endpoint, Revoke enrolment). The 2.20.0 .pkg ships an uninstaller (NOT RUN on a Mac): 

sudo /usr/local/libexec/hodei-shield/uninstall.sh            # as root; keeps the key and the logs
sudo /usr/local/libexec/hodei-shield/uninstall.sh --purge    # also deletes key, queue, config, logs (irreversible)
It removes the daemons, the program, the update helper (/Library/PrivilegedHelperTools/com.hodeitek.hodei-shield.update), the app, the CA bundle and the receipt, and the _hodeishield account if the package created it. Without --purge it keeps /var/lib/hodei-shield (private key, queue, hodei-shield.toml; handed to root before the account goes, NOT RUN; a reinstall gives it back) and /var/log/hodei-shield; /etc/hodei-shield stays if it holds telemetry-off. Logs are not rotated yet (the rule ships switched off): /var/log/hodei-shield grows until you delete it. Older .pkg files have no uninstaller: remove them by hand: 
sudo launchctl unload -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist
sudo launchctl unload -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist
sudo rm /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist
sudo rm /usr/local/bin/hodei-shield
sudo dscl . -delete /Users/_hodeishield; sudo dscl . -delete /Groups/_hodeishield
sudo pkgutil --forget com.hodeitek.hodei-shield
/var/lib/hodei-shield keeps the machine's private key: delete it only on purpose.

Privacy and help. Error reports (crashes only, no personal data) go to Sentry; to turn them off: sudo mkdir -p /etc/hodei-shield && sudo touch /etc/hodei-shield/telemetry-off (before installing the .pkg). Help: info@hodeitek.com or the Beta button in the console.