# Vulnerability Runbook
This document outlines how Wasmtime maintainers should respond to a security
vulnerability found in Wasmtime. This is intended to be a Wasmtime-specific
variant of the [runbook
RFC](https://github.com/bytecodealliance/rfcs/blob/main/accepted/vulnerability-response-runbook.md)
originally created. More details are available in the RFC in some specific steps.
Vulnerabilities and advisories are all primarily coordinated online through
GitHub Advisories on the Wasmtime repository. Anyone can make an advisory on
Wasmtime, and once created anyone can be added to an advisory. Once an advisory
is created these steps are followed:
1. An **Incident Manager** is selected. By default this is the Wasmtime
maintainer that opened the advisory. If a contributor opened the advisory
then it's by default the first responder on the advisory. The incident
manager can, at any time, explicitly hand off this role to another
maintainer.
2. **Fill out the advisory details**. This step involves filling out all the
fields on the GitHub Advisory page such as:
* Description - the description field's initial placeholder has the various
sections to fill out. At this point at least a brief description of the
impact should be filled out. This will get fleshed out more later too.
* Affected versions - determine which previously released versions of
Wasmtime are affected by this issue.
* Severity - use the CVSS calculator to determine the severity of this
vulnerability.
3. **Collaborate on a fix**. This should be done in a private fork created for
the security advisory. This is also when any collaborators who can help with
the development of the fix should also be invited. At this time only the
`main` branch needs to have a fix.
4. **Finalize vulnerability details and patched versions**. After a fix has been
developed and the vulnerability is better understood at this point the
description of the advisory should be fully filled out and be made ready to
go to the public. This is also when the incident manager should determine the
number of versions of Wasmtime to patch. All [supported releases
documented](./stability-release.md) must be patched, but the incident manager
may also elect to patch more releases if desired.
5. **Request a CVE**. Use the Big Green Button on the advisory to request a CVE
number from GitHub staff.
6. **Send advanced disclosure email**. The incident manager will decide on a
disclosure date, typically no more than a week away, and send mail to
sec-announce@bytecodealliance.org about the upcoming security release. An
example mail [looks like
this](https://groups.google.com/a/bytecodealliance.org/g/sec-announce/c/7SjEU_qSE4U/m/Y6baLYkhAgAJ)
7. **Add more stakeholders** (optional). Users interested in getting advanced
notice about this vulnerability may respond to the mailing list post. The
incident manager will add them to the security advisory.
8. **Prepare PRs for patch releases**. This will involve creating more pull
requests in the private fork attached to the advisory. Each version of
Wasmtime being patched should have a PR ready-to-go which cleanly applies.
Be sure to write release notes on the PR for each release branch.
9. **The full test suite should be run locally for `main`**. Locally try to run
as much of the CI matrix as you can. You probably won't be able to run all of
it, and that's ok, but try to get the ones that may have common failures.
This is required because CI doesn't run on private forks.
10. **Release day: Open version bump PRs on the public repository**. Use the
[online trigger] for this workflow to open PRs for all versions that are
going to be patched. Patch notes should be included with the private PRs, so
no need to worry about that. Plan on merging these PRs after the PRs below
are merged. Note that CI should be green as we test that it's green weekly
for all supported branches, but if it's not you'll need to fix that. GitHub
Actions has a nontrivial chance of having an outage during a release. If
this is the case all that can be done is waiting for the outage to be
resolved.
[online trigger]: https://github.com/bytecodealliance/wasmtime/actions/workflows/release-process.yml
11. **Release day: Manually make PRs to affected branches**. DO NOT merge via
the security advisory. This has generally not worked well historically
because there's too many CI failures and branch protections. On the day of
the release make public PRs from all of the previously-created PRs on the
private fork. You'll need to push the changes to your own personal
repository for this, but that's ok since it's time to make things public
anyway. Merge all PRs (including to `main`) once CI passes.
12. **Release day: Merge version bump PRs**. Once the fixes have all been merged
and CI is green merge all the version bump PRs. That will trigger the
automatic release process which will automatically publish to crates.io and
publish the release.
13. **Release day: Publish the GitHub Advisories**. Delete the private forks and
hit that Big Green Button to publish the advisory.
14. **Release day: Send mail about the security release**. Send another around
of mail to sec-announce@bytecodealliance.org describing the security
release. This mail looks [like
this](https://groups.google.com/a/bytecodealliance.org/g/sec-announce/c/7SjEU_qSE4U/m/zjW9fWlcAAAJ).
14. **Add the advisory to the [RustSec
database](https://github.com/rustsec/advisory-db)**. We mirror our
advisories into the RustSec database for projects using Cargo-based tooling
to check for security issue with their dependencies. An example of this is
[RUSTSEC-2024-0440]. File a PR with the
[RustSec/advisory-db](https://github.com/rustsec/advisory-db) repository
adding a new file in the `crates/wasmtime` directory. You'll use the file
name `RUSTSEC-0000-0000.md` and can copy metadata from a previous advisory.
The description should just point to the GitHub advisory published prior.
[RUSTSEC-2024-0440]: https://github.com/rustsec/advisory-db/blob/4584ad9a5ea16ce196317cf4d3593e974fb4a8a1/crates/wasmtime/RUSTSEC-2024-0440.md
You'll want to pay close attention to CI on release day. There's likely going to
be CI failures with the fix for the vulnerability for some build configurations
or platforms and such. It should be easy to fix though so mostly try to stay on
top of it. Additionally be sure to carefully watch the publish process to
crates.io. It's possible to hit rate limits in crate publication which
necessitates a retry of the job later. You can also try publishing locally too
from the release branch, but it's best to do it through CI.
