diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e38822..623fed4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,6 +56,9 @@ commands, `--json` output and exit codes. Each release's notes start with its se TLS inspection ([#25](https://github.com/Hodeitek/hodeishield-cli/issues/25), [#89](https://github.com/Hodeitek/hodeishield-cli/pull/89)); the beta programme and its terms ([#52](https://github.com/Hodeitek/hodeishield-cli/issues/52), [#90](https://github.com/Hodeitek/hodeishield-cli/pull/90)); defining a profile before signing in to it, and waiting for `msiexec` in a silent install ([#87](https://github.com/Hodeitek/hodeishield-cli/pull/87)). + `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)). ### Fixed diff --git a/README.md b/README.md index ffe8e0e..19715a4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ # HodeiShield CLI + + + [![Latest release](https://img.shields.io/github/v/release/Hodeitek/hodeishield-cli?sort=semver)](https://github.com/Hodeitek/hodeishield-cli/releases/latest) [![CI](https://github.com/Hodeitek/hodeishield-cli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Hodeitek/hodeishield-cli/actions/workflows/ci.yml?query=branch%3Amain) [![License: Apache-2.0](https://img.shields.io/github/license/Hodeitek/hodeishield-cli)](LICENSE) @@ -11,6 +14,8 @@ The official command-line client for [HodeiShield](https://hodeishield.com), by [Hodeitek](https://hodeitek.com). HodeiShield covers third-party risk, supply-chain security and compliance (NIS2, DORA, ISO 27001, ENS). +Security policy, how to report a vulnerability and where advisories appear: [SECURITY.md](SECURITY.md). + ## Quick start ```sh @@ -527,7 +532,9 @@ TLS-inspecting proxy; macOS and Windows have not been verified yet. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). To report a vulnerability, use [GitHub private reporting](https://github.com/Hodeitek/hodeishield-cli/security/advisories/new) -or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public issue. +or email [security@hodeitek.com](mailto:security@hodeitek.com), never a public issue. Security +advisories are published under +[Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories). ## License diff --git a/SECURITY.md b/SECURITY.md index 4ede4b2..c015cd6 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,7 +15,110 @@ what you expected, and a proof of concept if you have one. **Never include a rea if one was exposed, revoke it in the app first. We will acknowledge your report, keep you informed while we investigate, and credit you in the -advisory unless you prefer otherwise. +advisory if you want to be credited. + +- Encrypted email: not offered at the moment. +- Bug bounty: there is no bounty programme; we credit reporters publicly in the advisory. + +## What happens after you report + +A report made through GitHub opens a draft security advisory that only you and the maintainers can +see; we talk to you there. A report made by email is answered by email. + +| Step | What you get | When | +|---|---|---| +| Acknowledgement | Confirmation that we received the report | Within 3 business days | +| First assessment | Whether it is a vulnerability, its severity, and whether we know of it being exploited | Within 10 business days | +| Status updates | Progress on the fix and the expected release, until the advisory is published | At least every 14 days | +| Fix | A release that fixes it, and the published advisory | See the targets below | + +### Severity and fix targets + +We rate severity with [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) and use +its qualitative ratings. You can comment on the rating in the advisory or by email. The targets +below are for shipping a fixed release, counted from the first assessment. + +| Severity | CVSS v3.1 base score | Target to ship a fix | +|---|---|---| +| Critical | 9.0 – 10.0 | 7 days | +| High | 7.0 – 8.9 | 30 days | +| Medium | 4.0 – 6.9 | 90 days | +| Low | 0.1 – 3.9 | The next release | + +### Coordinated disclosure + +We ask you to keep the vulnerability confidential until the advisory is published, and we agree +the publication date with you. The coordinated disclosure period is 90 days from your report. If +a fix is not released by then, we publish the advisory with the workarounds we know of, unless we +agree a short extension with you. If the vulnerability is being actively exploited, +we may publish earlier, with workarounds (see [Security notices](#security-notices)). + +### Safe harbour + +We will not take legal action against you, or ask anyone else to, for research that follows this +policy in good faith: you report to us privately and give us reasonable time to fix the issue before +you disclose it; you access only the data you need to show the vulnerability, and do not keep, +change or share anyone else's data; you do not degrade the service or harm its users; and you test +only against accounts and tenants you own or are allowed to use. If in doubt, ask us first. + +## Security notices + +If a release is affected by a vulnerability that is being actively exploited, or by a severe +incident (for example a compromised release or release pipeline), we tell users in these places, +in this order: + +1. **The GitHub security advisory** for this repository, under + [Security → Advisories](https://github.com/Hodeitek/hodeishield-cli/security/advisories). It is + published or updated first, before a fix is available if necessary, and says which versions are + affected, what to do in the meantime, and whether a fix is in progress. +2. **A short notice at the top of [README.md](README.md)**, linking to the advisory. The README + keeps an empty block for it between the markers `` and + ``; the notice goes between them, as a quote with a blank line + before and after it: + + ```markdown + + + > **Security notice:** versions 0.x.y to 0.x.z are affected by GHSA-xxxx-xxxx-xxxx. Update to + > 0.x.w; until then, see the advisory for a workaround. + + + ``` + + The notice is updated when the fix ships and removed when it no longer applies, leaving the + block empty. The README inside a release archive is a copy taken when that release was built: + check the repository's README, not the copy you downloaded. +3. **The release notes of the release that fixes it**, under `### Security` in that release's + section of [CHANGELOG.md](CHANGELOG.md), which the release workflow uses as the release notes. + Each entry links to the advisory. + +To be told, watch this repository's releases on GitHub (*Watch → Custom → Releases*) or follow +[its releases feed](https://github.com/Hodeitek/hodeishield-cli/releases.atom), and check the +advisories page. The CLI's own [new-version notice](README.md#new-version-notice) tells you on an +interactive terminal that a newer release exists, but not whether it fixes a vulnerability. + +## How advisories are published + +Every fixed vulnerability gets a GitHub security advisory in this repository, written from +[docs/security-advisory-template.md](docs/security-advisory-template.md) so that every advisory has +the same fields: + +- a description of the vulnerability and its impact; +- who is affected: which commands, configurations and install channels; +- the affected versions and the fixed versions; +- the severity, with its CVSS v3.1 vector; +- workarounds, how to check whether you are affected, and how to update; +- the timeline (reported, fixed, published), the credit, and references. + +The advisory is published when the fixed release is out, or earlier as described in +[Security notices](#security-notices). + +Each advisory has a GHSA identifier. Its machine-readable form is the advisory record that GitHub's +REST API returns, for example +`https://api.github.com/repos/Hodeitek/hodeishield-cli/security-advisories?state=published`, which +lists the identifiers, affected and patched versions, CVSS vector and credits as JSON. Advisories +are published on GitHub. When a vulnerability needs a CVE identifier, we request it through the +advisory, with GitHub as the CVE Numbering Authority. ## Supported versions diff --git a/docs/security-advisory-template.md b/docs/security-advisory-template.md new file mode 100644 index 0000000..bfc890c --- /dev/null +++ b/docs/security-advisory-template.md @@ -0,0 +1,112 @@ +# Security advisory template + +Every security advisory for `hodeishield` is written from this template, as described in +[SECURITY.md](../SECURITY.md#how-advisories-are-published), so that every advisory has the same +fields in the same order. Copy everything below the line into a new GitHub security advisory for +this repository, fill in each field, and delete the parts in *italics*. Keep a heading and write +"None" rather than removing it, so readers and scripts find the same sections every time. + +The first table maps to the fields of GitHub's advisory form; the rest is the advisory's +description. + +--- + +| Advisory form field | Value | +|---|---| +| Title | *One line: the component, the flaw and its effect, e.g. "Sign-in token sent to a redirected host".* | +| Affected versions | *A range, e.g. `>= 0.2.0, < 0.3.2`.* | +| Patched versions | *e.g. `0.3.2`.* | +| Severity | *Critical, High, Medium or Low, from the CVSS v3.1 base score.* | +| CVSS v3.1 vector | *e.g. `CVSS:3.1/AV:N/AC:H/PR:N/UI:R/S:U/C:H/I:N/A:N`.* | +| Weakness | *CWE identifier, if one fits.* | +| Credits | *Reporter, as they asked to be credited, or "None" if they prefer not to be.* | + +## Summary + +*Two or three sentences: what is wrong, what an attacker can do, and what to do about it.* + +## Affected versions + +*Every release in the range, and every install channel that shipped them. Say if a channel was not +affected.* + +## Fixed versions + +*The first release with the fix, with a link to its release page.* + +## Severity + +*The rating and the CVSS v3.1 vector, with one sentence on why each metric that is not obvious was +chosen.* + +## Impact + +*What an attacker gains (for example a credential, the ability to hide terminal output, a tampered +download) and what they need first (network position, a crafted URL or identifier, local access, +the user running a particular command).* + +## Who is affected + +*The commands, flags, environment variables, configuration settings and platforms involved, e.g. +"anyone who signs in with `hodeishield login` on Windows", "scripts that set +`HODEISHIELD_API_KEY` together with a custom API URL". Say who is not affected.* + +## Workarounds + +*What to do until you can update, or "None: update". If a credential may have been exposed, say +which one and to revoke it in the app.* + +## How to check whether you are affected + +```sh +hodeishield --version +``` + +*Compare the version with the affected range above. Add any other check: a configuration value, a +file, an environment variable, a log line from `--verbose`. For the container image, check the tag +or digest your pipeline pins.* + +## How to update + +Verify every download as described in +[docs/verifying-releases.md](https://github.com/Hodeitek/hodeishield-cli/blob/main/docs/verifying-releases.md). +*Delete the channels that did not ship an affected version.* + +- **Release archive (Linux, macOS, Windows):** download the archive for your platform from the + release page of ``, verify it, and replace the `hodeishield` binary on your `PATH`. +- **Homebrew:** `brew update && brew upgrade hodeishield` +- **Scoop:** `scoop update` then `scoop update hodeishield` +- **Debian, Ubuntu (`.deb`) and Fedora, RHEL (`.rpm`):** download the `` package, + verify it, and install it with the same `sudo apt install ./...` or `sudo dnf install ./...` + command as the first time. +- **Windows installer (MSI):** install the `` MSI; it upgrades the installed version + in place. +- **Install script (Linux and macOS):** download and verify the `install.sh` of ``, + then run `sh install.sh --version `. +- **Container image:** pull `ghcr.io/hodeitek/hodeishield-cli:`, verify it with + `cosign verify`, and pin the new digest in your pipeline. +- **From source:** + `cargo install --locked --force --git https://github.com/Hodeitek/hodeishield-cli --tag v hodeishield-cli` + +## Timeline + +| Date (UTC) | Event | +|---|---| +| *YYYY-MM-DD* | Reported | +| *YYYY-MM-DD* | Fixed in `` | +| *YYYY-MM-DD* | Advisory published | + +*Add other dates that matter, such as when exploitation was first seen or when the first notice was +published.* + +## Credit + +*Who reported it and how they asked to be named, or "Reported privately; the reporter asked not to +be named".* + +## References + +- *The release notes of ``.* +- *The pull request or commit with the fix, once public.* +- *The CVE identifier, if one was assigned.* +- *Anything else a reader needs: related advisories, upstream issues.*