From d3b0b5c066e21ba3568448ad42e0b920e67d16ba Mon Sep 17 00:00:00 2001 From: "liang.he" Date: Tue, 8 Jul 2025 09:26:45 +0800 Subject: [PATCH] Add security issue runbook (#4450) This runbook provides step-by-step guidance on handling a security advisory --- doc/security_issue_runbook.md | 46 +++++++++++++++++++++++++++++++++++ doc/security_need_to_know.md | 2 +- 2 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 doc/security_issue_runbook.md diff --git a/doc/security_issue_runbook.md b/doc/security_issue_runbook.md new file mode 100644 index 000000000..1706b42c1 --- /dev/null +++ b/doc/security_issue_runbook.md @@ -0,0 +1,46 @@ +# Security Issue Runbook + +This runbook provides step-by-step guidance on handling a security advisory. Typically, it begins with a draft security advisory when we initiate the process outlined in this runbook. The draft security advisory is created by a contributor or a maintainer. + +For information on what types of issues are considered security vulnerabilities and require a security advisory for resolution, please refer to [identifying a security issue](./security_need_to_know.md#identifying-a-security-issue). + +## Step 1: Initial Response to Security Advisory + +- Receive Security Advisory: When a new security advisory is received, the Incident Manager, typically the maintainer who opened the advisory, becomes the first responder. If the advisory was opened by someone else, a maintainer should take on the role of Incident Manager. The Incident Manager can hand off this role to another maintainer if necessary. +- Acknowledge Receipt: The Incident Manager should promptly acknowledge receipt of the advisory and communicate that the investigation will begin immediately. Security issues are the highest priority. + +## Step 2: Investigating the Vulnerability + +- Identify the Vulnerability: Reproduce the issue to understand the vulnerability. Determine which versions and platforms are affected. Fill out the advisory details with this information. +- Accept the Report: Accept the security report and create a temporary private fork to collaborate on a fix. Invite necessary helpers and stakeholders to this fork, as their input can be valuable. + +## Step 3: Communication and Collaboration + +- Use Non-Public Channels: Communicate through non-public channels, preferably email, during the resolution process. Avoid filing issues or pull requests on third-party repositories if they are involved. +- Workaround for Third-Party Dependencies: If third-party dependencies are involved, consider a workaround to patch the issue quickly unless the third party can release a fix promptly. + +## Step 4: Finalizing and Preparing for Release + +- Finalize Details: Once a fix is developed and the vulnerability is fully understood, finalize the advisory details and prepare for public release. Ensure the security issues are resolved in the private fork. +- Request CVE: Use the Big Green Button on the advisory to request a CVE number from GitHub staff. +- Advanced Disclosure Email: Decide on a disclosure date, typically within a week, and send an email to sec-announce@bytecodealliance.org about the upcoming security release. Other ways are also available to communicate the disclosure date. + +## Step 5: Preparing and Testing Patch Releases + +- Prepare PRs for Patch Releases: Create pull requests in the private fork for each version being patched. Ensure each PR is ready to apply cleanly and includes release notes for each release branch. +- Run Full Test Suite: Run the full test suite locally for the main branch. Attempt to run as much of the CI matrix locally as possible. + +## Step 6: Public Release and Communication + +- Open Version Bump PRs: Open version bump pull requests on the public repository without including patch notes or release notes for the fix. +- Manually Make PRs from Private Fork: Transfer the necessary pull requests from the private fork to the public repository. +- Merge and Trigger Releases: Merge the version bump PRs and trigger the release process. +- Publish GitHub Advisories: Delete the private forks and use the Big Green Button to publish the advisory. +- Send Security Release Email: Send a follow-up email to sec-announce@bytecodealliance.org describing the security release. Other communication channels can also be used to inform users about the security release. + +By following these steps, you can effectively manage and resolve security issues for your open source project, ensuring timely communication and collaboration while maintaining the integrity and security of your software. + +## References + +- [Vulnerability Response Runbook](https://github.com/bytecodealliance/rfcs/blob/main/accepted/vulnerability-response-runbook.md) +- [Wasmtime Security Vulnerability Runbook](https://docs.wasmtime.dev/security-vulnerability-runbook.html) diff --git a/doc/security_need_to_know.md b/doc/security_need_to_know.md index b2b358983..b0d076d38 100644 --- a/doc/security_need_to_know.md +++ b/doc/security_need_to_know.md @@ -30,4 +30,4 @@ Before reporting an issue, particularly one related to crashing, consult [the ch Upon receiving an issue, thoroughly review [the cheat sheet](https://github.com/bytecodealliance/rfcs/blob/main/accepted/what-is-considered-a-security-bug.md#cheat-sheet-is-this-bug-considered-a-security-vulnerability) to assess and _Report a security vulnerability_ if the issue is indeed a security vulnerability. -Once a security issue is confirmed, please refer to [the runbook](https://github.com/bytecodealliance/rfcs/blob/main/accepted/vulnerability-response-runbook.md) for the subsequent steps to take. +Once a security issue is confirmed, please refer to [the runbook](./security_issue_runbook.md) for the subsequent steps to take.