This document gathers in one place what you need to know to use hodeishield securely: who makes
it, how to reach us, how long it is supported, and how to update and remove it. Where the details
live in README.md or SECURITY.md, it links to them.
Each release keeps the copy of this document that applies to it, in that release's tag:
https://github.com/Hodeitek/hodeishield-cli/blob/v<version>/docs/user-information.md. Releases
from 0.4.2 also ship that copy with the product, as USER-INFORMATION.md: next to the binary in
every release archive, in /usr/share/doc/hodeishield/ from the .deb and .rpm packages, in
%ProgramFiles%\HodeiShield CLI from the MSI, and in $(brew --prefix)/share/doc/hodeishield from
Homebrew. The container image does not include it. The shipped copy's links to other files are
relative to the repository: open them in the same tag. Releases up to 0.3.1 were published before
this document existed; for them, the README and SECURITY.md in their tag apply.
- Name: HodeiShield CLI. The command is
hodeishield(hodeishield.exeon Windows); the source repository is Hodeitek/hodeishield-cli. - Version:
hodeishield --versionprints the installed version. Versions follow Semantic Versioning and each release is taggedv<version>. - Releases: every release, with its files and notes, is on the
releases page, at
https://github.com/Hodeitek/hodeishield-cli/releases/tag/v<version>. The notes of every release, with its date, are also in CHANGELOG.md. - EU declaration of conformity: a declaration is issued from 11 December 2027. The one for each
release is at
https://github.com/Hodeitek/hodeishield-cli/blob/v<version>/docs/declaration-of-conformity.md. Until then that file is a template, not a declaration.
Hodeitek S.L., Markole 17, 20550 Aretxabaleta, Gipuzkoa, Spain.
- Email: info@hodeitek.com
- Website: hodeitek.com
- Bug reports and documentation problems that are not about security: GitHub issues, as described in CONTRIBUTING.md.
The point of contact for vulnerabilities in hodeishield is the maintainers, through either of
these two means:
- GitHub private vulnerability reporting (the Security tab of the repository → Report a vulnerability);
- email to security@hodeitek.com.
Never report a vulnerability in a public issue. What to include, how quickly you get an answer and how a fix is disclosed are in SECURITY.md. Published advisories are under Security → Advisories, and Security notices lists where an affected release is announced.
hodeishield is a read-only command-line client for the public /v1 API of
HodeiShield. It reads one organisation's third-party inventory,
supply-chain alerts, risk register, compliance posture, evidence, endpoint agents and reports, from
a terminal or a script. Every command reads: its requests to the API are GET only, and it cannot
change data in your organisation. It needs a HodeiShield account to sign in with, or a tenant API
key.
What the CLI guarantees (read only, credentials never written to disk in clear text, printed or logged, HTTPS only, no redirects followed, signed releases) is in SECURITY.md, and the risk assessment behind them is in risk-assessment.md. To use it securely:
- Verify every download before you run it: Verify a download and docs/verifying-releases.md. For the container image, verify it and pin its digest (Container image).
- Pick the right credential (Authenticate). People sign in with
hodeishield login: the token is kept in the system keychain, covers one tenant and only reads. Scripts, CI and servers use a tenant API key with only the read scopes they need, kept in the CI's secret store and passed in the environment, not on a command line. WhenHODEISHIELD_API_KEYis set, it is used for every call, whatever else is configured. - Keep the configuration file free of credentials. It holds URLs and sign-in settings only,
and URLs must use HTTPS; plain HTTP is accepted only for
localhost(Configure). - Treat output as your organisation's data.
--jsonand--csvoutput, and the request URLs that--verboselogs, can contain identifiers and filter values from your organisation, but never the CLI's credential. Text from the API is cleaned of terminal control characters before it is printed, and CSV cells that a spreadsheet would run as a formula are prefixed with'(CSV output). - Behind a proxy or TLS inspection, the CLI trusts the operating system's certificate store and has no option to skip certificate verification: install your organisation's CA in that store (Networking).
- Cut access you no longer need:
hodeishield logout, or revoke the CLI's access in the app under Account → Applications; revoke an API key in the app as soon as it is not needed or may have been exposed.
Known limitations:
- The macOS binary is not yet signed with an Apple Developer ID or notarized (#50); the Sigstore signature is the proof that it is genuine (see If macOS or Windows blocks the binary).
- Use behind a TLS-inspecting proxy is verified on Linux only; macOS and Windows have not been verified yet.
- The new-version notice makes at most one unauthenticated request a day to GitHub's public API, so GitHub sees your IP address. It can be turned off (see Updating).
From 1.0.0, each major version is supported with security fixes for five years, and the fixes ship in the latest release of that major version. While a version is supported, security fixes stay available even after your HodeiShield subscription ends. How this applies to the current 0.x series, the end-of-support date of each major version and how end of support is announced are in SECURITY.md.
hodeishield never updates itself. On an interactive terminal it tells you, at most once a day,
that a newer release exists (New-version notice); update through
the channel you installed it with. Before you move to a new minor version while the CLI is at 0.x,
read Changed (scripting surface) in its release notes (Stability).
| Installed with | To update |
|---|---|
| Release archive | Download the new archive, verify it, and replace the binary. |
| Homebrew | brew upgrade hodeishield |
| Scoop | scoop update hodeishield |
.deb / .rpm |
Verify the newer package and install it with the same apt install or dnf install command. |
| MSI | Install the newer MSI; it upgrades the older one in place. |
install.sh |
Download and verify the new release's install.sh and run it with --version (and the same --dir, if you used one). |
| Container image | Pull the new exact-version tag (there is no latest tag), verify it and pin its digest. |
cargo install |
Run the same command with the new --tag. |
To turn off the new-version notice, set HODEISHIELD_NO_UPDATE_CHECK to any non-empty value, or
run hodeishield config set update_check false once for all profiles (config unset update_check
restores it). With either, the CLI makes no request to GitHub.
To stop using hodeishield on a machine and leave nothing behind:
-
Sign out of every profile you signed in to:
hodeishield logout, andhodeishield logout --profile <name>for each other profile. This revokes the token at the app and removes it from the system keychain. If the CLI warns that the app did not confirm the revocation, revoke the CLI's access in the app under Account → Applications. -
Revoke the tenant API keys the machine used, in the app, and remove them from the environment and secret stores that held them.
-
Delete the configuration file and the update-check record.
hodeishield config pathprints where the configuration file is;update-check.jsonis next to it. By default:System Directory Linux ~/.config/hodeishield/(or$XDG_CONFIG_HOME/hodeishield/)macOS ~/Library/Application Support/com.Hodeitek.HodeiShield/Windows %APPDATA%\Hodeitek\HodeiShield\config\The files are
config.tomlandupdate-check.json. If you setHODEISHIELD_CONFIG, they are that file andupdate-check.jsonin its directory. -
Uninstall the CLI with the channel you installed it with:
Installed with To uninstall Release archive Delete the hodeishieldbinary, and any man pages you copied.Homebrew brew uninstall hodeishieldScoop scoop uninstall hodeishield.deb/.rpmsudo apt remove hodeishieldorsudo dnf remove hodeishieldMSI Settings → Apps, or msiexec /x(Windows installer)install.shDelete hodeishieldfrom the directory it installed to (/usr/local/binor~/.local/bin, or your--dir), and thehodeishield*.1man pages from theshare/man/man1directory beside it (for example/usr/local/share/man/man1).Container image Remove the image, for example docker image rm ghcr.io/hodeitek/hodeishield-cli:<version>.cargo installcargo uninstall hodeishield-cli
If the CLI is already gone and a sign-in was left in the keychain, revoke the access in the app
(Account → Applications), then delete the entry, one per profile, whose service is
hodeishield-cli and whose account is the profile name: on macOS with Keychain Access or
security delete-generic-password -s hodeishield-cli -a <profile>, on Windows in Credential Manager
(Windows Credentials, named <profile>.hodeishield-cli), and on Linux with
secret-tool clear service hodeishield-cli username <profile>.
From 0.2.0, each release publishes a CycloneDX software bill of materials
(SBOM) for each archive, <archive-name>.cdx.json, attached to the release with its own Sigstore
signature and listed in SHA256SUMS. It lists every crate compiled into that binary, with its
version, licence and package URL. The .deb, .rpm and MSI packages contain the binary of a
matching archive, which that archive's SBOM describes. The container image carries the release's
CycloneDX SBOM as a signed attestation.
The SBOM is intended for users: use it to check which components a release contains and whether any of them has a known vulnerability. How to verify it is in docs/verifying-releases.md and Container image.