1# Vulnerability Runbook
2
3This document outlines how Wasmtime maintainers should respond to a security
4vulnerability found in Wasmtime. This is intended to be a Wasmtime-specific
5variant of the [runbook
6RFC](https://github.com/bytecodealliance/rfcs/blob/main/accepted/vulnerability-response-runbook.md)
7originally created. More details are available in the RFC in some specific steps.
8
9Vulnerabilities and advisories are all primarily coordinated online through
10GitHub Advisories on the Wasmtime repository. Anyone can make an advisory on
11Wasmtime, and once created anyone can be added to an advisory. Once an advisory
12is created these steps are followed:
13
141. An **Incident Manager** is selected. By default this is the Wasmtime
15   maintainer that opened the advisory. If a contributor opened the advisory
16   then it's by default the first responder on the advisory. The incident
17   manager can, at any time, explicitly hand off this role to another
18   maintainer.
19
202. **Fill out the advisory details**. This step involves filling out all the
21   fields on the GitHub Advisory page such as:
22
23   * Description - the description field's initial placeholder has the various
24     sections to fill out. At this point at least a brief description of the
25     impact should be filled out. This will get fleshed out more later too.
26   * Affected versions - determine which previously released versions of
27     Wasmtime are affected by this issue.
28   * Severity - use the CVSS calculator to determine the severity of this
29     vulnerability.
30
313. **Collaborate on a fix**. This should be done in a private fork created for
32   the security advisory. This is also when any collaborators who can help with
33   the development of the fix should also be invited. At this time only the
34   `main` branch needs to have a fix.
35
364. **Finalize vulnerability details and patched versions**. After a fix has been
37   developed and the vulnerability is better understood at this point the
38   description of the advisory should be fully filled out and be made ready to
39   go to the public. This is also when the incident manager should determine the
40   number of versions of Wasmtime to patch. All [supported releases
41   documented](./stability-release.md) must be patched, but the incident manager
42   may also elect to patch more releases if desired.
43
445. **Request a CVE**. Use the Big Green Button on the advisory to request a CVE
45   number from GitHub staff.
46
476. **Send advanced disclosure email**. The incident manager will decide on a
48   disclosure date, typically no more than a week away, and send mail to
49   [email protected] about the upcoming security release. An
50   example mail [looks like
51   this](https://groups.google.com/a/bytecodealliance.org/g/sec-announce/c/7SjEU_qSE4U/m/Y6baLYkhAgAJ)
52
537. **Add more stakeholders** (optional). Users interested in getting advanced
54   notice about this vulnerability may respond to the mailing list post. The
55   incident manager will add them to the security advisory.
56
578. **Prepare PRs for patch releases**. This will involve creating more pull
58   requests in the private fork attached to the advisory. Each version of
59   Wasmtime being patched should have a PR ready-to-go which cleanly applies.
60   Be sure to write release notes on the PR for each release branch.
61
629. **The full test suite should be run locally for `main`**. Locally try to run
63   as much of the CI matrix as you can. You probably won't be able to run all of
64   it, and that's ok, but try to get the ones that may have common failures.
65   This is required because CI doesn't run on private forks.
66
6710. **Open version bump PRs on the public repository**. Use the [online trigger]
68    for this workflow to open PRs for all versions that are going to be patched.
69    DO NOT include patch notes or release notes for this fix. Use this time to
70    fix CI by landing PRs to the release branches separate from the version bump
71    PR. DO NOT merge the version bump PR.
72
73[online trigger]: https://github.com/bytecodealliance/wasmtime/actions/workflows/release-process.yml
74
7511. **Manually make PRs on release day**. DO NOT merge via the security
76    advisory. This has generally not worked well historically because there's
77    too many CI failures and branch protections. On the day of the release make
78    public PRs from all of the previously-created PRs on the private fork.
79    You'll need to push the changes to your own personal repository for this,
80    but that's ok since it's time to make things public anyway. Merge all PRs
81    (including to `main`) once CI passes.
82
8312. **Merge version bump PRs**. Once the fixes have all been merged and CI is
84    green merge all the version bump PRs. That will trigger the automatic
85    release process which will automatically publish to crates.io and publish
86    the release.
87
8813. **Publish the GitHub Advisories**. Delete the private forks and hit that Big
89    Green Button to publish the advisory.
90
9114. **Send mail about the security release**. Send another around of mail to
92    [email protected] describing the security release. This mail
93    looks [like
94    this](https://groups.google.com/a/bytecodealliance.org/g/sec-announce/c/7SjEU_qSE4U/m/zjW9fWlcAAAJ).
95
9614. **Add the advisory to the [RustSec
97    database](https://github.com/rustsec/advisory-db)**. We mirror our
98    advisories into the RustSec database for projects using Cargo-based tooling
99    to check for security issue with their dependencies. An example of this is
100    [RUSTSEC-2024-0440]. File a PR with the
101    [RustSec/advisory-db](https://github.com/rustsec/advisory-db) repository
102    adding a new file in the `crates/wasmtime` directory. You'll use the file
103    name `RUSTSEC-0000-0000.md` and can copy metadata from a previous advisory.
104    The description should just point to the GitHub advisory published prior.
105
106[RUSTSEC-2024-0440]: https://github.com/rustsec/advisory-db/blob/4584ad9a5ea16ce196317cf4d3593e974fb4a8a1/crates/wasmtime/RUSTSEC-2024-0440.md
107
108You'll want to pay close attention to CI on release day. There's likely going to
109be CI failures with the fix for the vulnerability for some build configurations
110or platforms and such. It should be easy to fix though so mostly try to stay on
111top of it. Additionally be sure to carefully watch the publish process to
112crates.io. It's possible to hit rate limits in crate publication which
113necessitates a retry of the job later. You can also try publishing locally too
114from the release branch, but it's best to do it through CI.
115