What leaves your machine¶
This page is for people who are about to install the Hodei-Shield Agent during the beta and want to know, in plain words, what the program sends out of the computer, to whom, and what it never sends. It is a description of the program, not a legal document. Each claim below was checked against the program's source code. Where the code does not settle a question, the page says so.
The legal side (what the sub-processors are, your rights) is not on this page. For the error reports, Hodeitek is the controller, the legal basis is legitimate interest, and reports are kept for 90 days (see Error reports). The console's privacy notice is at https://app.hodeishield.com/privacy. The website's list of sub-processors (the annex) is not published yet; it will be linked here when it is.
The short version¶
- The agent checks the configuration of the computer (is the disk encrypted, is the firewall on, does the screen lock, and so on) and reports the result of each check to your organisation's Hodei-Shield platform.
- Each result is a small, signed record. It says which check ran, whether it
passed, failed, was not applicable or could not run, when, and a few
allowed facts (for example
"backend": "nftables"). It never carries free text, files, documents, browsing, passwords, keys or tokens. - With every report the agent also sends the host name, the routable IP addresses and the operating system name, version and architecture of the machine, so that the console can show which machine is which.
- If something goes wrong inside the agent, it can send an error report to our error-tracking service. It goes through your console, is off by default per tenant (a build from source sends nothing), is described in Error reports, and you can switch it off.
- The agent's private key never leaves the computer.
1. The observations: the main thing the agent sends¶
Every cycle the agent runs its checks and sends the results as one envelope
to the platform URL in its configuration (for the beta,
https://app.hodeishield.com). The envelope is a JSON document whose shape is fixed by a contract; the fields are listed below.
The envelope¶
| Field | What it is |
|---|---|
schema_version |
The version of the format ("1.0") |
agent_id |
An identifier (a UUID) the platform assigned to this agent's key when it enrolled. It is not your host name |
agent_version |
The version of the agent program |
producer |
endpoint_agent:<name>. <name> is the machine name you chose at enrolment (the host name if you did not choose one) |
producer_run_id |
A counter that grows with each run, so a resend is recognised as a resend |
observations |
The list of check results (next table) |
inventory |
Facts about the machine (section 3) |
signature |
The signature over all of the above (section 4) |
There is no tenant or organisation field: the platform works out which organisation you belong to from the enrolment, not from the content.
One observation¶
| Field | What it holds |
|---|---|
check_code |
Which check ran, for example chk.os.disk_encryption.enabled |
subject_type, subject_ref |
Whom the result is about. The agent reports tenant with a null reference, meaning "this host's own organisation" |
target_kind, target_ref |
The kind of thing checked (endpoint) and its name: the host name as the operating system reports it |
status |
pass, fail, na (not applicable) or error (the check could not run). The agent never reports pass when it is unsure |
severity |
low, medium, high or critical, fixed per check |
observed_at |
When the check ran (UTC) |
freshness_sla_seconds |
How long the result should be considered current |
detail |
The allowed facts about the result (section 2) |
What the checks look at¶
The agent's check registry lists 173 check codes (agent-check-registry.v1.json). They are configuration questions about the operating system. By area: accounts (auto-login, lockout, minimum password length), audit logging, automatic updates, boot integrity, disk encryption, host firewall, screen lock, time synchronisation, kernel hardening, malware protection and EDR presence, remote access (SSH settings), mandatory access control, system integrity protection, credential-exposure settings (two Windows registry hardening switches), the agent's own health, and three sets of published hardening baselines (SCAP Security Guide for Ubuntu, macOS Security Compliance Project, and DISA STIG for Windows). Not every check exists on every operating system. The registry file shows which checks exist for which system.
The window and the tray icon only show five of these (disk encryption, firewall, screen lock, automatic updates, agent health); the platform receives every check the agent runs.
Where the code cannot settle it: the code of every one of the checks was not read for this page. What each check reads from the operating system is defined in the program's source. What can leave is bounded by the rules in the next section regardless of what a check reads.
2. The detail field: what it can and cannot contain¶
detail is where a check puts the facts behind its result. It is the field
most worth worrying about, so the code does not trust the checks: every detail
is built through one gate, SanitizedDetail, and if anything in it breaks a rule
the whole content is dropped.
What is allowed
- A flat list of
key: valuepairs, at most 32 pairs and 4096 bytes in total. - Keys: lowercase letters, digits,
_and-only, at most 64 characters. Each check also has its own short list of keys it may use; a key outside the list drops the wholedetail. - Values: only true/false, a whole number (between -2^53 and 2^53, no decimals), or a short word (at most 64 characters).
What is refused
- Lists, nested objects, empty values (
null), decimals and very large numbers. - Any text that looks like a secret or personal data. The gate rejects a value
or key that contains: a PEM block (
-----BEGIN), a bearer token, something shaped like a JWT, an e-mail address, or any run of 32 or more letters, digits,+or/(which catches keys, digests and tokens). The only exception is a fixed list of published SSH algorithm names that happen to look like e-mail addresses (such aschacha20-poly1305@openssh.com), matched whole.
What happens when a rule is broken. The check does not send the offending
value, and does not send an empty detail that looks fine. It sends a marker,
{"detail_dropped": true, "detail_dropped_reason": "<class>"}, where the
class is one of a fixed list of labels (key_not_allowed, looks_sensitive,
type_not_permitted, too_many_pairs, too_large) and never any part of the
rejected value. The agent writes the same class, and only the class, to its log.
What the gate cannot promise. It is a pattern filter. It stops secrets and
personal data from being sent as text, in the shapes listed above. It does not
read meaning: a short word such as a user name of 10 letters is not a pattern
this gate recognises. That is why the checks use fixed vocabularies of keys, and
why the main protection is that checks report states ("active": false) and
counts ("encrypted_volumes": 1), not names. The code of every check was not
audited for this page.
3. The inventory: facts about the machine¶
Every envelope also carries an inventory. These are the only fields in it, and
each one is optional (if it cannot be read, it is left out, never sent empty):
| Field | What it holds |
|---|---|
hostname |
The host name, only if it is a valid DNS-style name (letters, digits, hyphens and dots; no underscore). Otherwise left out. It is the same name the observations carry as target_ref |
ip_addresses |
Up to 16 IPv4/IPv6 addresses of the machine's real network interfaces, as plain text |
os.family |
linux, windows or macos |
os.name, os.version |
What the operating system says about itself (for example Ubuntu, 24.04) |
os.arch |
The processor architecture the agent was built for (for example x86_64) |
Which IP addresses are left out: loopback, link-local, multicast,
unspecified and broadcast addresses; every address on a loopback, Docker,
virtual-machine bridge or container interface (names such as docker*, br-*,
veth*, virbr*, vmnet*, vboxnet*, cni*, podman*, vEthernet*); and
IPv6 addresses whose second half is built from the network card's hardware
(MAC) address. Kept: private ranges (10.x, 192.168.x, fd..) and VPN
tunnel addresses. So the console receives your internal addresses.
Not sent: the MAC address. The code never reads it into the envelope, by design.
The inventory is sent with every envelope, not only when it changes. The platform keeps the last value it received.
4. Identity and signature¶
When you enrol, the agent creates a key pair on the machine. Only the public key is sent (once, together with the one-time enrolment token, the machine name you chose and the agent version). From then on every envelope is signed with the private key, and the envelope carries:
| Field | What it holds |
|---|---|
signature.alg |
ed25519, or ml-dsa-65 (post-quantum) in builds that include it |
signature.public_key_id |
The identifier of the public key, so the platform knows which key to verify with. This is what identifies the machine to the platform |
signature.value |
The signature itself |
What is not sent: the private key. It stays in the agent's state folder (permissions restricted to the agent's own service account). No field of the envelope or of the enrolment request carries it (the lists above are complete). The same is true of the key that encrypts the offline queue.
The connection to the platform is encrypted (TLS) and the agent trusts only the certificate authority that ships inside its own installer, not the operating system's store. The agent does not present a client certificate; the signature is what identifies it.
5. If the platform cannot be reached¶
Signed envelopes that could not be sent are kept in an offline queue in the agent's state folder, encrypted on disk, and are sent later. The queue is capped (10,000 items and 32 MiB); when full it refuses new items rather than deleting old ones. Nothing in the queue is readable without the agent's queue key. How the queue is paced, and how a failed send delays the next cycle, is in section 1.
If the platform refuses the agent. After a 401 or 403 (the credential
is refused) the agent becomes dormant (in plain words: the platform refused the computer's credential, so the computer waits on standby, neither evaluating nor sending, and only re-checks now and then). It stays running, evaluates and
sends nothing, and makes no network call of any kind (not even the update
check) except one real batch to re-check: first after 1 hour, then at growing
intervals up to 24 hours after a 401 (6 hours after a 403). After a 400
(a batch refused for good) the agent becomes halted (in plain words: the platform refused a batch for good, or the agent itself withheld the computer's name before sending; the agent stops evaluating and sending, and that batch is never sent again): it queues and sends
nothing, and sends one fresh batch as a probe on the same curve (1 hour,
growing to 24 hours); the refused batch itself is never sent again. A halt
caused by the agent's own screening of the host name sends no probe at all and
ends when the host name changes. A halted agent still makes the update check
(section 7). A probe the platform accepts ends either state. How often hosts
reach these states in production cannot be known from the code.
6. Error reports¶
Today, measured 2026-11-17: no console offers this yet. The console does not serve the diagnostics route or the signed policy yet, so an agent of version 2.23.0 or later sends no error report at all. It will start only once your console authorises it.
In the beta the official builds can send error and crash reports. They go
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
(POST {platform_url}/api/v1/agent/diagnostics), which forwards it from its
own address. The agent never contacts the service and has no fallback to it.
Per the relay design the service therefore does not see the endpoint's IP
address; the console you already send observations to sees the connection, as
it does for every other request. They are off by default per tenant: the
agent sends one only while it holds an unexpired (24 hours) signed "yes" from
the console; with no document, an invalid or expired one, or a "no", it sends
none. The agent puts no personal data in them by design (the SDK's
send_default_pii is off). A healthy agent sends nothing; a failure
counts, and so does an anomaly in the self-update channel (reported at most
once per kind per run of the process). Hodeitek is
the controller of these reports, the legal basis is legitimate
interest, and they are kept for 90 days. On a host you can also force
them off whatever the console says: create the marker file or set
HODEI_SENTRY_DSN=off. The fields that leave and the ones that never do, and the
exact per-system switch, follow below.
What an error report contains, and how to force it off¶
The agent builds each report from an allowlist: it starts from an empty event and copies in only the agent version (release), the
environment (production or beta), a closed class name of the failure (never its text), the operating-system family and
a coarse version (major.minor), the architecture, the Rust type name and the function names of the agent's own code and of its
dependencies, and, on Windows, the debug identifiers of the agent's own executables. It never sends the error text, the user,
the request, the host name, any device identifier or file paths, and there is no free text. Each report is signed with the host's key and
carries no cookie or forwarding header. A report is dropped, with no retry and no fallback, if the console cannot be reached or does not accept it.
There are at most 20 per class of failure and 60 per process, 256 KiB each.
To force reports off on a host, whatever the console says, create the marker file (its contents are ignored; it survives upgrades; restart
the service after creating it) or set HODEI_SENTRY_DSN=off:
| System | Marker file |
|---|---|
| Linux, macOS | /etc/hodei-shield/telemetry-off |
| Windows | %ProgramData%\Hodei-Shield\telemetry-off |
A fleet tool can drop the file before or after installing the agent. The per-system commands are in the quick start.
Agents up to 2.22 behave differently. They send error reports straight to the error-tracking service, on by default since
2026-10-06, and the marker file (or HODEI_SENTRY_DSN=off) is how a host opts out; in that case the service does receive the IP address
the report is sent from.
Two points belong on this page too:
- Where it goes: the service's EU region, as measured on the published
v2.12.1binary. - Not in the error reports: the check results and their
detail. Those go only to your organisation's platform.
7. Updates¶
The check. Every cycle (by default hourly, section 1), including while the
machine is paused and while it is halted, but not while it is dormant, the
agent downloads a small signed update manifest and its signature from the
public download edge, downloads.hodeishield.com, asked first; if it cannot
answer, from our release store:
two plain GET requests to fixed addresses. They carry no identifier, token or
parameter of yours. Whichever host answers, like any web server, sees the
connection's IP address and time. Setting update_edge = "none" makes the host
use the store only (see the agent command-line reference). A host whose owner has opted out of updates makes neither request.
Which systems. In the code of this repository only Linux makes the check: on Windows and macOS it stops before any network call, so those builds send nothing for it. The exception is a Windows beta build cut with the Windows update switch turned on (the 2.17.0 betas, beta channel only); it checks and updates like Linux. Which builds are in the field is not something the code can tell. On macOS, and on Windows in the stable channel (2.17.0 included), updating is done by hand by whoever administers the machine.
The request to the console. Only when the verified manifest offers a newer
version does the agent send the console one signed request,
POST /api/v1/agent/update-policy. Unlike the manifest download, this request
does carry identifiers: the agent identifier (the same as agent_id in the
envelopes), the producer name, the current version, the operating system, the
architecture, the channel, the candidate version with the digests of its
manifest and of its package, a random one-time number, the time of the request
and the signature. It carries no check result.
The download. Only if the console's signed answer allows it (on Windows: approves that exact MSI's digest), and the host's owner has pinned its update identity and not opted out, does the agent download the package and its per-version manifest from the addresses the signed manifest names; otherwise the agent never replaces a program (see the self-update notes of the agent). On Windows, checking the MSI's signature may make Windows itself fetch Microsoft's root certificate through automatic root update (seen on 2026-10-19); that request is Windows', not the agent's, and carries nothing of yours.
8. What the status window shows, versus what is sent¶
The agent has an optional status window and tray icon. They read small files the agent writes locally (the main one is "the projection"). They hold no key, and the window's program has no HTTP client among its dependencies, so it has no way of its own to reach the network.
| Shown on the machine | Sent to the platform |
|---|---|
| Whether the agent is enrolled, its name, since when | Yes, in effect: the producer name and agent_id are in every envelope |
| For the five headline checks, ok / needs attention / error / not applicable, with a short history | Yes, the same results, together with all the others |
| How many items wait in the offline queue, the time of the last submission, the update state | No: the platform knows what it received, not what is queued |
The detail of any check |
Not shown at all: the window never renders detail. The platform does receive it (section 2) |
| A desktop notice when a check starts failing, only if your organisation turned it on | No. Nothing about whether a notice was shown flows back |
The status window also has a button to re-run one check locally. It starts the
agent's own command line check as an ordinary program under your own account.
That command does not submit anything and has no network access.
How the desktop notice works and who controls it is in the next section.
9. What else could leave, and your controls¶
- Support bundle.
hodei-shield diagnoseprints a redacted report (versions, configuration summary, permissions, enrolment state, reachability, queue sizes, the tail of the log). It is printed to your screen and goes nowhere unless you attach it to a ticket. Its single network call is oneGETto the platform's health endpoint, which--offlineskips. - Pause. An administrator can pause evaluation and submission on a machine
(
hodei-shield pause;resumeundoes it). - Uninstall and revocation. See section 8 of the quick start.
What this page cannot tell you¶
- It does not describe what the platform does with the data after it arrives: retention, who can see it, where it is stored. That belongs to the console's privacy notice, https://app.hodeishield.com/privacy.
- It does not list the platform's sub-processors. The website annex is not published yet and will be linked here when it is.
- It does not say that every check was reviewed one by one for what it reads. It says what the code allows to leave the machine.
- The desktop notice and the status window have not yet been verified on a real desktop; see What the status window shows.