Endpoint agent¶
The HodeiShield endpoint agent is a lightweight program you install on a laptop or server to check its security posture and feed the Endpoints module in the console. It does not replace your EDR or antivirus: it observes them, along with the rest of the system's security configuration, and reports the result to your tenant.
What it checks¶
The agent's contract with the platform lists 172 checks (measured on 2026-10-01): 29 point-in-time checks, grouped by area in the table below, plus 143 open-baseline checks (137 per-rule codes and 6 per-profile codes, described in the next section). Each check is registered only for the operating systems it applies to. Each check answers pass / fail / not applicable / error, without sending the raw data behind it:
| Area | What it looks at |
|---|---|
| Accounts and authentication | Password policy, account lockout after failed attempts |
| EDR and antimalware | Whether protection is active and its definitions are current |
| Disk encryption | Whether the system volume is encrypted |
| Firewall | Whether the operating system's firewall is active |
| Secure boot | Boot integrity (Secure Boot / UEFI) |
| Auditing | Whether system audit logging is active and persists |
| Remote access (SSH) | Supported ciphers, root login, password authentication |
| Network hardening | IP forwarding, ICMP redirects |
| Updates | Whether automatic security updates are enabled |
| System integrity | Native OS protections (SIP on macOS, mandatory access control on Linux) |
| System clock | Whether the clock is synchronized |
These checks feed the endpoint posture score you see under Endpoints in the console.
Open configuration baselines¶
Status of this section: the agent's check registry (the contract of agent 2.17.0, with no code withheld) registers 173 check codes. A machine shows "no data" for a baseline until the agent installed on it reports that baseline, never a made-up percentage. A given endpoint's results depend on the agent version it runs.
Beyond the point-in-time checks in the table above, the agent evaluates full configuration baselines, per operating system, against open reference sources:
| Family | Source | Systems covered |
|---|---|---|
| SSG | ComplianceAsCode / SCAP Security Guide | Ubuntu 22.04, Ubuntu 24.04 |
| mSCP | NIST macOS Security Compliance Project | macOS 14, macOS 15 |
| STIG | DISA STIG | Windows 11, Windows Server 2022 |
Only level 1 (L1) is evaluated — the baseline level, designed not to disrupt normal use of the machine. These baselines are distinct from a commercial benchmark: they are public standards maintained by their own projects, and HodeiShield does not reproduce their text or claim certification against a third party's registered trademark.
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.
How to read the per-endpoint percentage¶
Each baseline applicable to a machine shows on its Endpoints detail page as a compliance percentage: how many rules of the reference profile pass out of the rules that apply to that specific system. A rule that does not apply to your configuration (for example, a rule about a service you do not have installed) counts neither for nor against.
The percentage is computed on the machine itself and travels signed alongside the rest of the agent's evidence — the same as any other check. The console does not re-run the scan on its own: it shows what the agent has reported.
What this does NOT measure yet¶
- Level 2 (L2), the stricter tier, is not covered in this phase.
- The rule-by-rule breakdown (exactly which check failed) does not travel inside the aggregate result itself — it depends on an additional evidence format the agent does not publish yet.
- These baselines are not mapped to CIS Controls or CIS Benchmarks, and no CIS coverage is claimed. CIS is outside the scope of the beta.
- No commercial (paid) benchmark is covered by this feature.
Installation¶
There is one installer per operating system:
| System | Format |
|---|---|
| Windows (x64) | .msi, installed as a Windows service |
| macOS (Apple Silicon and Intel) | universal .pkg, installed as a LaunchDaemon |
| Linux (x86_64) | compressed archive, installed as a systemd service |
Download the installer for your system from Endpoints in the console and run it with administrator privileges. During installation you will be asked for an enrollment token: a one-time credential, generated by your administrator from the same screen, that identifies the machine to your tenant. The agent starts automatically on system boot.
Before installing, verify the download signature.
Fixed in 2.14.2: fresh macOS installs
On a Mac where the agent was never installed, the .pkg of agent versions 2.14.0 and
2.14.1 ended with "Install Failed" and the service did not start. Agent 2.14.2 and later
include the fix. If you run an older version, upgrade; if you have trouble installing on a
Mac, write to info@hodeitek.com.
The platform certificate bundle. The agent does not use the operating system's trust
store: it trusts only the HodeiShield platform certificate bundle, a PEM file, and the
enroll command requires you to point it at that file with --ca-root. You do not add
anything to the macOS Keychain or to the Windows certificate store, but the file must be on
the machine before you enroll. The installation steps the console shows under Endpoints
download it from your console, check its SHA-256 digest, and pass it to enroll. Copy those
steps instead of assembling your own: they already carry the right flags. The Linux archive
also contains the bundle as platform-ca.pem. The console's default location is:
| System | Default path of the bundle |
|---|---|
| Linux | /etc/hodei-shield/platform-ca.pem |
| macOS | /etc/hodei-shield/platform-ca.pem |
| Windows | C:\ProgramData\Hodei-Shield\state\platform-ca.pem |
Pass the token through stdin, not on the command line
If you enroll by hand, give the token to the agent through standard input so it never appears in your shell history or in the process list:
```sh
printf '%s' "$HODEI_TOKEN" | sudo -u hodei-shield \
HODEI_PLATFORM_URL='https://<platform-host>' HODEI_STATE_DIR=/var/lib/hodei-shield \
/usr/local/bin/hodei-shield enroll --token-stdin --ca-root /etc/hodei-shield/platform-ca.pem
```
or the same `enroll` line with `< token-file` instead of the `printf` pipe, with the file
at mode `0600`. This requires an agent with `--token-stdin` (version 2.12.0 or later),
which is the form the console proposes. Do not use `enroll --token <value>`. The two
variables make the command independent of the directory you run it from, and
`--ca-root` is required: without it `enroll` stops with a usage error. On macOS the
service account is `_hodeishield`, and on Windows the console gives you the PowerShell
equivalent.
flowchart LR
A[Administrator<br/>generates a one-time token] --> B[Downloads the installer<br/>for their system]
B --> C[Runs the installer<br/>with administrator privileges]
C --> D{Enters the<br/>enrollment token}
D -->|valid token| E[Endpoint active<br/>in the tenant]
D -->|invalid or expired token| F[Enrollment rejected]
E --> G[Sends signed checks<br/>every cycle]
E -.revoke from the console.-> H[Identity revoked]
The token is generated and consumed once; revoking is an explicit act in the console, not automatic on uninstall (see "Honest limits" below).
Possible cloned host and re-enrolment¶
An agent that supports it binds its enrolment to the machine it was made on, with a keyed hash of the operating system's machine identifier that the platform cannot reverse. If signed reports for an endpoint later present another machine's binding (for example, a copied virtual machine or a restored disk image running the same agent), the console marks the endpoint as a possible cloned host and sends an alert. Its evidence is still accepted, but those reports no longer update its last contact or inventory, and key rotation is refused.
To resolve it:
- Remove the agent from every copy of the machine.
- Revoke the endpoint in the console.
- Issue a new enrolment token (Endpoints) and re-enrol the original machine with it
(
hodei-shield enroll --forcewith the new token). The new enrolment is a separate endpoint, bound to that machine.
An endpoint revoked while it was marked as a possible cloned host cannot be reinstated: reinstating it could hand its identity to the copy. Re-enrolling is the only way back. An endpoint shown as "not bound to its machine" was enrolled by an agent without this binding; re-enrolling it with a current agent binds it.
What it does NOT collect¶
The agent is designed to observe security posture, not user activity. It does not collect:
- File contents or browsing history.
- Running processes, or CPU/memory usage.
- Passwords or any kind of credential.
- The device's MAC address.
What it does send¶
Besides the result of each check, the agent sends minimal machine identification: hostname, public IP addresses, and the operating system's family, name and version. Every submission is cryptographically signed with the agent's identity, so the platform can confirm it came from the machine it claims to be.
Error reports (off by default)¶
From agent 2.23.0, error reports go only through your Hodei-Shield console, never directly to the error-tracking service: each report is signed with the host's key and sent to your console, which forwards it from its own address, so the service does not see the endpoint's IP address. They are off by default per tenant: the agent sends one only while it holds an unexpired signed "yes" from the console. Today no console offers them yet, so an agent of 2.23.0 or later sends none. A healthy agent sends nothing, there is no periodic traffic, and a report never carries check results, the host name, the user or any personal data.
Agents up to 2.22 behave differently: they send error reports straight to the service, on by default since 2026-10-06, and the marker file below is how a host opts out.
To force error reports off on a host whatever the console says, create the marker file before installing (or, if the service is already running, create it and restart the service; it is read when the process starts):
| OS | Marker |
|---|---|
| Linux, macOS | /etc/hodei-shield/telemetry-off |
| Windows | %ProgramData%\Hodei-Shield\telemetry-off |
The full list of what leaves the machine is in What leaves your machine.
Install with error reports off¶
Instead of creating the marker by hand, you can ask the installer to create it. It can only make the agent send less: any other value, or none, does nothing, and an existing marker is never removed.
| Package | How | What it does |
|---|---|---|
.deb |
sudo TELEMETRY=off apt-get install ./<package>.deb |
creates /etc/hodei-shield/telemetry-off |
.rpm |
sudo TELEMETRY=off rpm -i <package>.rpm (or sudo TELEMETRY=off dnf install ./<package>.rpm) |
creates /etc/hodei-shield/telemetry-off |
.msi |
msiexec /i <package>.msi TELEMETRY=off |
creates %ProgramData%\Hodei-Shield\telemetry-off |
.pkg (macOS) |
the installer takes no parameters: set the key Telemetry to off in a configuration profile for com.hodeitek.hodei-shield before installing |
creates /etc/hodei-shield/telemetry-off |
On Linux the variable must reach the package scripts, so keep it in the sudo command as shown. If the
installer is asked for off and cannot create the marker (for example, the folder is not owned by
root), it stops and the package stays unconfigured rather than installing with reports on; on macOS the
install fails. Not every combination has been run on every system; check with hodei-shield version
(see above).
Behind a proxy¶
The agent can send its traffic (enrolment, check results and update checks) through an HTTP proxy.
| Setting | Meaning |
|---|---|
proxy in hodei-shield.toml, or HODEI_PROXY |
system (default), none, or http://host:port / https://host:port |
no_proxy, or HODEI_NO_PROXY |
hosts that go direct: suffixes such as .corp.example or networks such as 10.0.0.0/8 (a list, or one comma-separated string) |
- With
system, the agent usesHTTPS_PROXYfrom the service's own environment; if there is none, the machine setting of the operating system (WinHTTP on Windows,scutil --proxyon macOS, nothing on Linux). - The address needs an explicit port and no path.
- Credentials in the proxy address are refused, from every source: the proxy must accept the agent without a user and password.
- No PAC or WPAD scripts, and no NTLM or Kerberos. A host that only has a PAC setting connects directly, and the agent logs a warning.
- A proxy value that cannot be read is an error, never a silent direct connection.
- The decision is made once per process and logged as
proxy: host:portordirect. - A proxy that inspects TLS needs its CA to be trusted: see the troubleshooting page for certificate errors.
How long it is kept¶
The periods are applied automatically by the console's daily retention task, tenant by tenant:
| Data | Period |
|---|---|
| Check results (observations) | 365 days from when the platform receives them; then deleted. |
| The state of each control derived from those results | While your organisation keeps the service. |
| The device's hostname, IP addresses and operating system | Only the latest value, erased when the endpoint is revoked. |
| Identity of a revoked endpoint and its enrolment records (enrolment tokens) | 365 days after revocation; then deleted. |
| Record of the updates the agent was allowed to install | 90 days. |
An endpoint that has not communicated with the platform for 90 days is revoked automatically, and revoking it erases its inventory (the revoked identity is kept for 365 days and then deleted). If you retire it sooner, revoke it yourself from Endpoints. We process this data on behalf of your organisation (Art. 28(3) GDPR); when the service ends it is returned or deleted as your organisation instructs.
Honest limits¶
- Updates: the agent includes an automatic update mechanism (it downloads a signed manifest, verifies signature and hash, self-tests the new binary and rolls back on failure), but do not count on it: on the current stable release (2.23.2) only Linux hosts apply updates by themselves; Windows and macOS hosts do not, so update them manually. To move to a newer version, download the latest installer and reinstall — your enrollment is preserved, no new token is needed.
- Support period: each MAJOR version of the agent is supported for 5 years, counted from 1.0.0. End of support is announced 12 months in advance. Security updates remain available after a subscription lapses; new features require an active subscription.
- Revocation: to retire an endpoint, uninstall the agent on the machine (or stop its service) and revoke it from Endpoints in the console. An un-revoked endpoint's identity stays active even after the agent is no longer installed, until the automatic revocation after 90 days without communication closes it.
- This agent takes no automatic remediation action on the system: it only observes and reports.