Skip to content

Commit 9f29643

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 #390 and currently a draft. Signed-off-by: Mihai Maruseac <mihaimaruseac@google.com>
1 parent eefb9ab commit 9f29643

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