Skip to content

Commit f4abc91

Browse files
UlisesGasconbjohansebasctcpip
authored
docs: process to handle security reports (#56)
Co-authored-by: Sebastian Beltran <[email protected]> Co-authored-by: Chris de Almeida <[email protected]>
1 parent fb09621 commit f4abc91

File tree

1 file changed

+188
-0
lines changed

1 file changed

+188
-0
lines changed

‎docs/handle_security_reports.md

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Security Report Handling Process
2+
**Version:** 1.0
3+
**Last Updated:** March 2025
4+
**Maintainers:** Security Triage Team
5+
6+
## Introduction
7+
Security is a top priority for the Express project. This document outlines the **formal process** for handling **security reports**, including how to **triage**, **assess**, and **disclose** vulnerabilities responsibly.
8+
9+
## Scope
10+
11+
The Security Triage Team will use this document as a process guide when a security vulnerability is reported, from triage to resolution. This process must align with the project's [SECURITY policy](https://github.com/expressjs/.github/blob/master/SECURITY.md) and cannot diverge significantly.
12+
13+
14+
## Security Report Handling Flowchart
15+
The following diagram details the **decision-making process** for handling security reports:
16+
17+
```mermaid
18+
flowchart TD
19+
A[Security Report Received] --> B[Assign Security Report Coordinator]
20+
B --> E{Premature Disclosure?}
21+
22+
E -- No --> J[Proceed with Standard Private Process]
23+
E -- Yes --> F[Privatize Disclosure]
24+
F --> G[Handle Related PRs & Issues]
25+
G --> H[Request GitHub to Remove Public PR/Issues]
26+
H --> I[Create Public Placeholder Issue]
27+
I --> J[Acknowledge within 5 days to the Reporter]
28+
J --> K[Create Issue in Triage Repo for Visibility]
29+
30+
K --> L[Assess Report]
31+
L --> M{Enough Information?}
32+
33+
M -- No --> N[Request Additional Info]
34+
N --> L[Assess Report]
35+
36+
M -- Yes --> O{Valid Vulnerability?}
37+
O -- No --> X[Close Report as Invalid]
38+
X --> Y[Acknowledge within 10 days to the Reporter]
39+
40+
O -- Yes --> Q[Create Advisory]
41+
Q --> Q1[Calculate CVSS Score]
42+
Q1 --> Q2[Request a CVE]
43+
44+
Q2 --> R{Patch Required?}
45+
46+
R -- No --> Z[Public Disclosure]
47+
48+
R -- Yes --> T[Develop Patch]
49+
T --> U[Test Solution]
50+
U --> V[Add Regression Testing]
51+
V --> W[Create a Security Release with CVE Included]
52+
W --> Z[Public Disclosure]
53+
Z --> Z1[Notify Community]
54+
Z1 --> Z2[Official Blog Post]
55+
Z1 --> Z3[Social Media Announcements]
56+
```
57+
58+
## Roles & Responsibilities
59+
60+
### Finder
61+
62+
This person identifies a potential security vulnerability in the project. The Finder may or may not be the same person as the Reporter. If the Finder is not the Reporter, they may share the details with someone else who submits the report to the Security Triage Team.
63+
64+
**Responsibilities**
65+
- Identify potential security vulnerabilities in the project.
66+
- Share sufficient details about the vulnerability with the Reporter or directly with the Security Triage Team.
67+
68+
**Expectations**
69+
- Follow responsible disclosure guidelines by ensuring the vulnerability is reported privately before public disclosure.
70+
- Provide clear and accurate information about the vulnerability to facilitate the reporting process.
71+
72+
### Reporter
73+
74+
This person submits a security report to the Security Triage Team and provides detailed information about the suspected vulnerability. It is expected that the Reporter will cooperate with the Security Triage Team during this process and follow responsible disclosure guidelines.
75+
76+
**Responsibilities**
77+
- Submit a security report to the Security Triage Team.
78+
79+
**Expectations**
80+
- Provide detailed information about the suspected vulnerability.
81+
- Follow responsible disclosure guidelines (report privately before public disclosure).
82+
- Cooperate with the security team by providing additional details when needed.
83+
- Test and verify patches (when applicable).
84+
- Respect security timelines and avoid premature public disclosure.
85+
86+
### Coordinator
87+
88+
This person acts as the focal point for a specific security report and ensures the report follows all responsible disclosure guidelines. The SRC coordinates the remediation process if a vulnerability is confirmed and ensures that the security report follows the process and necessary actions are taken. While the SRC is not necessarily responsible for performing analysis, remediation, or patching, they may take on these tasks if they also hold the role of Analyst or Remediation Developer.
89+
90+
**Responsibilities**
91+
- Acknowledge receipt of security reports within the required timeframe.
92+
- Orchestrate the embargo and identify the minimum set of individuals involved.
93+
- Remind everyone involved that they must not notify/involve any other individuals. If someone else needs to be involved, that must go through the Coordinator.
94+
- Assign an Analyst to assess and validate the report.
95+
- Ensure communication with the reporter throughout the process.
96+
- Coordinate the remediation process if a vulnerability is confirmed.
97+
- Oversee the advisory & CVE request process if applicable.
98+
- Escalate critical vulnerabilities when necessary.
99+
- Track all security reports for visibility and reporting.
100+
101+
**Requirements**
102+
- Must be a member of the Security Triage Team.
103+
104+
105+
### Analyst
106+
107+
**Responsibilities**
108+
- Determine if the reported issue is a real vulnerability, and is in within the scope of our [threat model](https://github.com/expressjs/security-wg/blob/main/docs/ThreatModel.md)
109+
- Validate proof-of-concept exploits
110+
- Assess the security report and determine its severity (assist in CVSS).
111+
- Validate the reported vulnerability against best practices.
112+
- Identify potential mitigation strategies and workarounds.
113+
- Prepare a report for the Security Report Coordinator.
114+
115+
### Remediation Developer
116+
117+
**Responsibilities**
118+
- Develop a patch or solution based on the reported vulnerability.
119+
- Ensure the patch follows best practices and is testable.
120+
- Add test(s) to the existing test suite to confirm the vulnerability (pre-patch) and confirm the fix (post-patch).
121+
- Test the patch to ensure it works as expected.
122+
- Create a pull request to merge the patch into the project.
123+
124+
## Runbook
125+
126+
The following sections outline the **step-by-step process**, explaining each decision, scenario, and possible actions. In this guide we also include links that are private (limited to the security triage team), a general overview of the process in flowchart format can be found [here](#security-report-handling-flowchart).
127+
128+
### Step 0: Security Report Received
129+
130+
A security vulnerability report is received via [official channels](https://github.com/expressjs/.github/blob/master/SECURITY.md#reporting-a-bug) or otherwise (i.e. via third-party advisory services, blog post, social media, etc.).
131+
132+
Ideally, the report must contain **clear and detailed information** like (Affected versions, a small PoC/sample project demonstrating the issue, steps to reproduce, expected vs. actual behavior, potential impact...) but this might not be the case depending on the communication channel used. Later on we will try to collect this information and refine the report.
133+
134+
### Step 1: Assign Security Report Coordinator (SRC) and consolidate the report
135+
136+
1.1 One person from the Security Triage Team will volunteer and self-assign to oversee the case. It is expected that the person will remain assigned until the end of the process, so they effectively take the role of [the Security Report Coordinator (SRC)](#security-report-coordinator-src).
137+
138+
> [!Note]
139+
> While this document refers to a single SRC for simplicity, in practice, having two coordinators is acceptable and often beneficial. A second coordinator can assist with tasks such as reviewing the advisory content before it is published, ensuring accuracy and completeness.
140+
141+
1.2 If the report was created accidentally or intentionally in a public channel (e.g. GitHub issues), it is important to share this information ASAP in the private slack channel `#express-security-triage` so the Security triage team is aware of it. At this stage, our priority is to remove the report from public view as soon as possible and let the reporter know what happened next.
142+
143+
1.2.1 In the case of a report made public in a Pull request or issue under the Express organizations ownership the following process will be followed (by an Express TC member):
144+
145+
* Move the issue to the private repository called [expressjs/security-triage](https://github.com/expressjs/security-triage).
146+
* For any related pull requests, create an associated issue in [expressjs/security-triage](https://github.com/expressjs/security-triage) repository. Add a copy of the patch for the pull request to the issue. Add screenshots of discussion from the pull request to the issue.
147+
* [Open a ticket with GitHub](https://support.github.com/contact) to delete the pull request using Expressjs (team) as the account organization.
148+
* Force-push to the PR branch to overwrite the code with a placeholder commit (if "allow edits by maintainers" is enabled). This ensures sensitive information is removed immediately.
149+
* In the PR comments, notify the author about the force-push and explain the reason:
150+
> FYI @xxxx, we force-pushed to your branch to remove sensitive information while we work on releases in private.
151+
* Open a new issue in the public repository with the title `FYI - pull request deleted #YYYY`. Include an explanation for the user:
152+
> FYI @xxxx we asked GitHub to delete your pull request while we work on releases in private.
153+
* Update the team in the slack channel #express-security-triage`.
154+
155+
1.2.2 In the case that the report is made public in a different channel that we don't own/control, the TC will attempt to mitigate this by trying to remove the report from public view (reporting to support, asking the reporter to remove the report, etc...).
156+
157+
158+
1.3 At this stage the Security Report Coordinator (SRC) will create a (private) issue in [expressjs/security-triage](https://github.com/expressjs/security-triage) repository with the existing information from the security report (example: [expressjs/security-triage#14](https://github.com/expressjs/security-triage/issues/14)) unless it already exists (step 1.2.1). This issue will serve as the central discussion point for this particular report. At this stage is expected from the Security Report Coordinator (SRC) to acknowledge receipt of the security report to the reporter.
159+
160+
> [!Note]
161+
> It is expected that the issue will be assigned to the Security Report Coordinator (SRC) and will remain open until the end of the process.
162+
163+
### Step 2: Review the Report and determine its severity
164+
165+
2.1 It is expected from the security triage team to review the report and determine its severity, also evaluating the impact on the project(s). In some cases the report might be too vague to properly determine its severity. In this case the Security Report Coordinator (SRC) will need to reach out to the reporter for more information and refine the report.
166+
167+
2.2 At this stage we are capable of determining the severity of the report based on the information provided and also if the report is still relevant. In case that the team has considered the report to be irrelevant or not valid, the Security Report Coordinator (SRC) will need to close the issue and inform the reporter that the report has been dismissed, ideally we can provide a reason for dismissal to prevent the report from being resubmitted within the project(s) in the future.
168+
169+
2.3 If the report is considered relevant and valid, the Security Report Coordinator (SRC) will create an advisory and request a CVE number. The Security Report Coordinator (SRC) will also include the remediation developer(s), analyst(s) and potentially the reporter in the advisory, so they can start to work on private fork to fix the security issue (example: [GHSA-qw6h-vgh9-j6wx](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx)).
170+
171+
### Step 3: Patch and release
172+
173+
3.1 The security triage team will determine if this vulnerability will be patched and work on it. In case that the vulnerability won't be patched jump to step 4.
174+
175+
3.2 The mitigation team (remediation developer(s), analyst(s), reporter(s)) will work on the patch(es), re-evaluate the report once the patch is ready and include regression tests (when possible).
176+
177+
3.3 The Express TC will announce publicly (social media and public issues) that there is security path available and the plan to do a release with an specific date (ideally) and the versions affected without providing additional information to prevent early disclosure.
178+
179+
3.4 The security triage, along with the repo captain(s) and the TC team, will create the releases and publish them to npm. In some cases one vulnerability can affect multiple packages requiring several coordinated releases.
180+
181+
182+
### Step 4: Public disclosure
183+
184+
4.1 At this stage the Security Report Coordinator (SRC) will make the advisory public and close the coordination issue (opened in step 1).
185+
186+
4.2 The Security Report Coordinator (SRC) will also help to publish a blog post about the vulnerability and the patch (if applicable, example [September 2024 Security Releases](https://expressjs.com/2024/09/29/security-releases.html)).
187+
188+
4.3 The TC team will do social media announcements about the vulnerability and the patch (if applicable, example [Tweet post](https://x.com/UseExpressJS/status/1772300472730198037)).

0 commit comments

Comments
 (0)