Gorka Gonzalo (d0ubl3g) · Oct 11, 2026 · Oct 11, 2026
diff --git 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
@@ -2,6 +2,9 @@
 
 # HodeiShield CLI
 
+<!-- security-notice:start -->
+<!-- security-notice:end -->
+
 [![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
@@ -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 `<!-- security-notice:start -->` and
+   `<!-- security-notice:end -->`; the notice goes between them, as a quote with a blank line
+   before and after it:
+
+   ```markdown
+   <!-- security-notice:start -->
+
+   > **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.
+
+   <!-- security-notice:end -->
+   ```
+
+   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
@@ -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 `<fixed version>`, 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 `<fixed version>` 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 `<fixed version>` MSI; it upgrades the installed version
+  in place.
+- **Install script (Linux and macOS):** download and verify the `install.sh` of `<fixed version>`,
+  then run `sh install.sh --version <fixed version>`.
+- **Container image:** pull `ghcr.io/hodeitek/hodeishield-cli:<fixed version>`, 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<fixed version> hodeishield-cli`
+
+## Timeline
+
+| Date (UTC) | Event |
+|---|---|
+| *YYYY-MM-DD* | Reported |
+| *YYYY-MM-DD* | Fixed in `<fixed version>` |
+| *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 `<fixed version>`.*
+- *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.*