From a4caed21c79a4a9678b33e175b51aa66bfa817be Mon Sep 17 00:00:00 2001 From: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com> Date: Sun, 11 Oct 2026 15:02:14 +0200 Subject: [PATCH] State the support period and add a user information document SECURITY.md "Supported versions" replaces "only the latest release receives fixes" with the support rule: from 1.0.0, each major version is supported with security fixes for five years, delivered in the latest release of that major version; fixes stay available to people whose HodeiShield subscription has ended, since releases are public downloads. During 0.x, fixes go into the latest 0.x release, and 0.x has no end-of-support date until 1.0.0 is released. An end-of-support notice is published twelve months ahead in SECURITY.md, the README security notice block and the release notes. docs/user-information.md gathers the product and version identification, the manufacturer's address and contact, the two ways to report a vulnerability, the intended purpose, secure use and known limitations, how each install channel updates and uninstalls, how to turn off the new-version notice, how to remove the configuration, update-check record and keychain entries, and where the SBOM is published. Each release tag keeps the copy that applies to it. The README links to both and states the rule in one sentence. Refs #127 Refs #128 Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com> --- CHANGELOG.md | 5 ++ README.md | 5 ++ SECURITY.md | 21 ++++- docs/user-information.md | 181 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 211 insertions(+), 1 deletion(-) create mode 100644 docs/user-information.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 623fed4..4265079 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,11 @@ commands, `--json` output and exit codes. Each release's notes start with its se `SECURITY.md` now says what happens after a vulnerability report, where a notice about an affected release appears (the README has an empty place for it), and how advisories are published, from a template kept in `docs/` ([#120](https://github.com/Hodeitek/hodeishield-cli/issues/120)). + `SECURITY.md` now states the support period (from 1.0.0, five years of security fixes per major + version; until then, the latest 0.x release), and `docs/user-information.md` gathers the contact + details, secure use, updating, removal and where the SBOM is published + ([#127](https://github.com/Hodeitek/hodeishield-cli/issues/127), + [#128](https://github.com/Hodeitek/hodeishield-cli/issues/128)). ### Fixed diff --git a/README.md b/README.md index 19715a4..828be3a 100644 --- a/README.md +++ b/README.md @@ -536,6 +536,11 @@ or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public i advisories are published under [Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories). +From 1.0.0, each major version is supported with security fixes for five years; during 0.x, fixes go +into the latest 0.x release ([Supported versions](SECURITY.md#supported-versions)). +[docs/user-information.md](docs/user-information.md) gathers the manufacturer's contact details, the +support period, secure use, how to update and remove the CLI, and where the SBOM is published. + ## License Licensed under the [Apache License, Version 2.0](LICENSE). Copyright 2026 Hodeitek S.L.; see diff --git a/SECURITY.md b/SECURITY.md index c015cd6..7b0e321 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -122,7 +122,26 @@ advisory, with GitHub as the CVE Numbering Authority. ## Supported versions -Only the latest release receives fixes. +From 1.0.0, each major version of `hodeishield` is supported for five years, counted from the +release of its first version (1.0.0 for version 1). A supported major version receives security +fixes. They ship in a new release of that major version: to get them, update to the latest release +of your major version. + +Security fixes stay available to you while your version is supported, even if your HodeiShield +subscription has ended: every release is a public download, and installing or updating the CLI +never requires a subscription. + +**Before 1.0.** While the 0.x series is current, security fixes go into the latest 0.x release. +The 0.x series has no end-of-support date until 1.0.0 is released. + +| Version | Supported | Security fixes until | +|---|---|---| +| 0.x | Yes, in the latest 0.x release | No end date until 1.0.0 is released | + +The end-of-support date of each major version is published in this table and in the release +notes. Twelve months before a major version's support ends, an end-of-support notice is published +here, in the security notice block at the top of [README.md](README.md) (see +[Security notices](#security-notices)) and in the release notes. ## What is in scope diff --git a/docs/user-information.md b/docs/user-information.md new file mode 100644 index 0000000..67b202e --- /dev/null +++ b/docs/user-information.md @@ -0,0 +1,181 @@ +# User information + +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](../README.md) or [SECURITY.md](../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/docs/user-information.md`. Releases +up to 0.3.1 were published before this document existed; for them, the README and SECURITY.md in +their tag apply. + +## Product + +- **Name:** HodeiShield CLI. The command is `hodeishield` (`hodeishield.exe` on Windows); the + source repository is [Hodeitek/hodeishield-cli](https://github.com/Hodeitek/hodeishield-cli). +- **Version:** `hodeishield --version` prints the installed version. Versions follow + [Semantic Versioning](https://semver.org/) and each release is tagged `v`. +- **Releases:** every release, with its files and notes, is on the + [releases page](https://github.com/Hodeitek/hodeishield-cli/releases), at + `https://github.com/Hodeitek/hodeishield-cli/releases/tag/v`. The notes of every + release, with its date, are also in [CHANGELOG.md](../CHANGELOG.md). + +## Manufacturer and contact + +Hodeitek S.L., Markole 17, 20550 Aretxabaleta, Gipuzkoa, Spain. + +- Email: [info@hodeitek.com](mailto:info@hodeitek.com) +- Website: [hodeitek.com](https://hodeitek.com) +- Bug reports and documentation problems that are not about security: + [GitHub issues](https://github.com/Hodeitek/hodeishield-cli/issues), as described in + [CONTRIBUTING.md](../CONTRIBUTING.md). + +## Reporting a vulnerability + +The point of contact for vulnerabilities in `hodeishield` is the maintainers, through either of +these two means: + +- [GitHub private vulnerability reporting](https://github.com/Hodeitek/hodeishield-cli/security/advisories/new) + (the *Security* tab of the repository → *Report a vulnerability*); +- email to [security@hodeitek.com](mailto: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](../SECURITY.md#what-happens-after-you-report). Published +advisories are under +[Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories), and +[Security notices](../SECURITY.md#security-notices) lists where an affected release is announced. + +## Intended purpose + +`hodeishield` is a read-only command-line client for the public `/v1` API of +[HodeiShield](https://hodeishield.com). It reads one organisation's third-party inventory, +supply-chain alerts, risk register, compliance posture, evidence and endpoint agents, 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. + +## Security properties and secure use + +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](../SECURITY.md#what-the-cli-guarantees). To use it securely: + +- **Verify every download** before you run it: [Verify a download](../README.md#verify-a-download) + and [docs/verifying-releases.md](verifying-releases.md). For the container image, verify it and + pin its digest ([Container image](../README.md#container-image)). +- **Pick the right credential** ([Authenticate](../README.md#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. When + `HODEISHIELD_API_KEY` is 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](../README.md#configure)). +- **Treat output as your organisation's data.** `--json` and `--csv` output, and the request URLs + that `--verbose` logs, 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](../README.md#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](../README.md#networking-proxies-and-tls-inspection)). +- **Cut access you no longer need**: `hodeishield logout`, or revoke the CLI's access in the app + under **Account → Application access**; 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](https://github.com/Hodeitek/hodeishield-cli/issues/50)); the Sigstore signature is the + proof that it is genuine (see + [If macOS or Windows blocks the binary](../README.md#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](../README.md#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](#updating)). + +## Support period + +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](../SECURITY.md#supported-versions). + +## Updating + +`hodeishield` never updates itself. On an interactive terminal it tells you, at most once a day, +that a newer release exists ([New-version notice](../README.md#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](../README.md#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. + +## Decommissioning + +To stop using `hodeishield` on a machine and leave nothing behind: + +1. **Sign out of every profile you signed in to**: `hodeishield logout`, and + `hodeishield logout --profile ` 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 → Application access**. +2. **Revoke the tenant API keys** the machine used, in the app, and remove them from the + environment and secret stores that held them. +3. **Delete the configuration file and the update-check record.** `hodeishield config path` prints + where the configuration file is; `update-check.json` is 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.toml` and `update-check.json`. If you set `HODEISHIELD_CONFIG`, they are + that file and `update-check.json` in its directory. +4. **Uninstall the CLI** with the channel you installed it with: + + | Installed with | To uninstall | + |---|---| + | Release archive | Delete the `hodeishield` binary, and any man pages you copied. | + | Homebrew | `brew uninstall hodeishield` | + | Scoop | `scoop uninstall hodeishield` | + | `.deb` / `.rpm` | `sudo apt remove hodeishield` or `sudo dnf remove hodeishield` | + | MSI | **Settings → Apps**, or `msiexec /x` ([Windows installer](../README.md#windows-installer-msi)) | + | `install.sh` | Delete `hodeishield` from the directory it installed to (`/usr/local/bin` or `~/.local/bin`, or your `--dir`), and the `hodeishield*.1` man pages from the `share/man/man1` directory beside it (for example `/usr/local/share/man/man1`). | + | Container image | Remove the image, for example `docker image rm ghcr.io/hodeitek/hodeishield-cli:`. | + | `cargo install` | `cargo 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 → Application access**), 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 `, on Windows in Credential Manager +(*Windows Credentials*, named `.hodeishield-cli`), and on Linux with +`secret-tool clear service hodeishield-cli username `. + +## Software bill of materials + +From 0.2.0, each release publishes a [CycloneDX](https://cyclonedx.org) software bill of materials +(SBOM) for each archive, `.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](verifying-releases.md) and +[Container image](../README.md#container-image).