Skip to content

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: value pairs, 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 whole detail.
  • 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 as chacha20-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.1 binary.
  • 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 diagnose prints 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 one GET to the platform's health endpoint, which --offline skips.
  • Pause. An administrator can pause evaluation and submission on a machine (hodei-shield pause; resume undoes 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.