Skip to content

Commit 6857a78

Browse files
mihaimaruseacmihaimaruseac
committed
Add SPEC 11 on vulnerability disclosure
I used SPEC 11 name as that was selected from the last year, but I am happy to switch to a different number if needed. This is to be paired with scientific-python#390 and currently a draft. Signed-off-by: Mihai Maruseac <mihaimaruseac@google.com>
1 parent eefb9ab commit 6857a78

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎spec-0011/index.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# SPEC-11: Vulnerability disclosure
2+
---
3+
title: "SPEC 11 — Vulnerability disclosure
4+
number: 11
5+
date: 2025-05-13
6+
author:
7+
- "Juanita Gomez <juanitagomezr2112@gmail.com>"
8+
- "Mihai Maruseac <mihai.maruseac@gmail.com>"
9+
is-draft: true
10+
endorsed-by:
11+
---
12+
13+
## Description
14+
15+
This SPEC outlines the process for vulnerability disclosure. It aims to
16+
provide clear guidelines for the identification, reporting, and remediation of
17+
security vulnerabilities within projects.
18+
19+
### Core Project Endorsement
20+
21+
22+
### Ecosystem Adoption
23+
24+
TODO: Risks in smaller projects vs risks in larger projects. This might change
25+
strict adherence to the implementation here.
26+
27+
## Implementation
28+
29+
Security vulnerabilities should be handled quickly, and sometimes privately.
30+
The primary goal of this process is to reduce the total time users are
31+
vulnerable to both publicly and privately known reports.
32+
33+
To achieve this goal, the project should provide well-defined ways to report
34+
vulnerabilities (e.g., special email address such as `security@<project>.com`,
35+
forum, GitHub private security reporting, vulnerability reward programs). All
36+
suspected vulnerabilities should be handled in accordance with
37+
[Responsible Disclosure model](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
38+
The project should provide a mechanism for researchers to submit GPG encrypted
39+
vulnerability reports, for vulnerabilities with a higher degree of
40+
sensitivity.
41+
42+
The project should ensure that a _Security Response Team_ (SRT) exists. This
43+
team could be shared with other projects in the same organization, or within
44+
the same ecosystem. SRT has the following responsibilities:
45+
46+
- Triage: assess the impact of any vulnerability. Can the vulnerability be
47+
replicated? Which projects are affected? What is the blast radius? Who is
48+
responsible for the fix? Is there a need for coordinated disclosure between
49+
multiple projects?
50+
- Infrastructure: create security advisories, ensure teams working on fixing a
51+
vulnerability can work in private, create tests for the vulnerability and
52+
its variants.
53+
- Disclosure: handle public messaging around the vulenrability by drafting an
54+
advisory to document the impact, how to upgrade, how to mitigate if upgrade
55+
is not possible.
56+
- Release: create patch releases containing the fix and notify the public.
57+
58+
For each vulnerability, the SRT should follow these steps:
59+
60+
1. **Acknowledge the report**: The SRT should respond to any report in at most
61+
24 hours. For this, there should be inventory of all the places where
62+
vulnerabilities can be reported, and SRT should monitor all of these (via
63+
automation and dashboards where possible). The SRT will handle
64+
communication with the reporter throughout the vulnerability fixing
65+
process, updating the reporter on the disclosure timeline.
66+
2. **Triage the vulnerability**: The SRT should attempt to reproduce the
67+
vulnerabiltiy and analyze its impact. The SRT should rate the impact and
68+
consider coordinated disclosure based on
69+
[the traffic light protocol (TLP)](https://www.cisa.gov/news-events/news/traffic-light-protocol-tlp-definitions-and-usage).
70+
3. **Assign the vulnerability fix to fixing team**: The SRT is not responsible
71+
for fixing all vulnerabilities themselves. They should delegate to a team
72+
that has the most accurate knowledge of the involved codebase. In general,
73+
the fixing team should be formed from maintainers of the affected projects.
74+
Depending on TLP level, other members of the project could be brought in,
75+
as needed, but only after consulting the SRT.
76+
4. **Prepare a disclosure timeline**: Judging based on severity, complexity of
77+
the code base, development time, release work, dependencies on upstream,
78+
the SRT should create a timeline for when the vulnerability fix should be
79+
released and the public would be notified about the vulnerability. If the
80+
vulnerability has a low severity, the timeline can be extended to slow the
81+
release process to account for holidays, developer bandwidth, etc.
82+
5. **Request and prepare a CVE**: The SRT would prepare a
83+
[security advisory](https://docs.github.com/en/code-security/security-advisories)
84+
in the affected repositories and obtain CVE numbers for the
85+
vulnerabilities. As many details as possible should be entered into the
86+
advisory. Each time new information is discovered, the advisory should be
87+
update. A vulnerability severity score, computed using
88+
[CVSS](https://www.first.org/cvss/) should be added. Members of the fixing
89+
team should be added to the advisory, to contribute details.
90+
6. **Create a private fork[^1]** for the fixing team to fix the vulnerability
91+
in private. This is a temporary fork and should be deleted once the
92+
vulnerability is fixed. It should only be created to ensure CI can run on
93+
code fixing the vulnerability without accidentally disclosing the
94+
vulnerability[^2].
95+
7. **Plan and perform the patch release**. Once the fixing team has submitted
96+
all necessary fixes for the vulnerability and its variants and the SRT has
97+
verified that the work is completed, the two teams agree on a release
98+
timeline and perform the release as well as announce the vulnerability to
99+
the public[^3].
100+
101+
On the release day, the SRT and the fixing team:
102+
103+
1. merge all the commits from the private fork into the project repository
104+
2. start patch releases for all affected versions in the supported range
105+
3. publish all release binaries and packages
106+
4. publish the security advisory
107+
5. publish an announcement that is actionable, contains mitigation steps for
108+
users that cannot upgrade to the newly released patched versions, and is
109+
distributed to a wide audience.
110+
111+
A template of the announcement could be:
112+
113+
```
114+
Subject: Security release of $PROJECT $VERSION is now available
115+
To: ...
116+
117+
Hello $PROJECT Community,
118+
119+
The Security Response Team and maintainers of $PROJECT would like
120+
to announce the availability of $PROJECT $VERSION.
121+
122+
This addresses the following CVE(s):
123+
124+
* CVE-YEAR-ABCDEF (CVSS score $CVSS): $CVESUMMARY
125+
...
126+
127+
Upgrading to $VERSION is encouraged to fix these issues.
128+
129+
**Am I vulnerable?**
130+
131+
Run `$PROJECT --version` and if it indicates a base version of $OLDVERSION or
132+
older that means it is a vulnerable version.
133+
134+
<!-- Update this for libraries that don't have a CLI capable of running
135+
`--version` to extract version information -->
136+
137+
<!-- Provide details on features, extensions, configuration that make it
138+
likely that a system is vulnerable in practice. -->
139+
140+
**How do I mitigate the vulnerability?**
141+
142+
<!-- This is an optional section. Remove if there are no mitigations. -->
143+
144+
**How do I upgrade?**
145+
146+
<!-- Outline upgrade steps (e.g., use `uv install`) -->
147+
148+
**Vulnerability Details**
149+
150+
<!-- For each CVE, provide some details of the vulnerability and link to the
151+
advisory. -->
152+
```
153+
154+
## Notes
155+
156+
A few days after the release, the SRT could write a retrospective of the
157+
vulnerability and fixing process, with details on everyone involved, links to
158+
PRs, and other relevant information. This is to encourage learning, preventing
159+
future similar vulnerabilities and providing opportunities for improving the
160+
disclosure process.
161+
162+
[^1]: All communication between the people involved in the fix must happen only on the advisory and the private fork, to prevent accidental disclosure.
163+
[^2]: The [`act`](https://github.com/nektos/act) project could be used to run CI locally if needed.
164+
[^3]: To ensure that the release and the announcement are seen in an adequate time-frame, it is recommend to use 4PM UTC on a non-Friday weekend as the disclosure time. This ensures that the announcement would be seen at morning time in APAC, early evening in EMEA and late evening in Asia.

0 commit comments

Comments
 (0)