1.. _reporting:
2
3Security Vulnerability Reporting
4################################
5
6Introduction
7============
8
9Vulnerabilities to the Zephyr project may be reported via email to the
10vulnerabilities@zephyrproject.org mailing list.  These reports will be
11acknowledged and analyzed by the security response team within 1 week.
12Each vulnerability will be entered into the Zephyr Project security
13advisory GitHub_.  The original submitter will be granted permission to
14view the issues that they have reported.
15
16.. _GitHub: https://github.com/zephyrproject-rtos/zephyr/security
17
18Security Issue Management
19=========================
20
21Issues within this bug tracking system will transition through a
22number of states according to this diagram:
23
24.. graphviz::
25
26   digraph {
27      node [style = rounded];
28      init [shape = point];
29      New [shape = box];
30      Triage [shape = box];
31      {
32        rank = same;
33        rankdir = LR;
34        Assigned [shape = box];
35        Rejected [shape = box];
36      }
37      Review [shape = box];
38      Accepted [shape = box];
39      Public [shape = box];
40
41      init -> New;
42      New -> Triage;
43      Triage -> Rejected [dir = both];
44      Triage -> Assigned;
45      Assigned -> Review [dir = both];
46      Review -> Accepted;
47      Review -> Rejected;
48      Accepted -> Public;
49
50   }
51
52- New: This state represents new reports that have been entered
53  directly by a reporter.  When entered by the response team in
54  response to an email, the issue shall be transitioned directly to
55  Triage.
56
57- Triage: This issue is awaiting Triage by the response team.  The
58  response team will analyze the issue, determine a responsible
59  entity, assign it to that individual, and move the
60  issue to the Assigned state.  Part of triage will be to set the
61  issue's priority.
62
63- Assigned: The issue has been assigned, and is awaiting a fix by the
64  assignee.
65
66- Review: Once there is a Zephyr pull request for the issue, the PR
67  link will be added to a comment in the issue, and the issue moved to
68  the Review state.
69
70- Accepted: Indicates that this issue has been merged into the
71  appropriate branch within Zephyr.
72
73- Public: The embargo period has ended.  The issue will be made
74  publicly visible, the associated CVE updated, and the
75  vulnerabilities page in the docs updated to include the detailed
76  information.
77
78The security advisories created are kept private, due to the
79sensitive nature of security reports.  The issues are only visible to
80certain parties:
81
82- Members of the PSIRT mailing list
83
84- the reporter
85
86- others, as proposed and ratified by the Zephyr Security
87  Subcommittee.  In the general case, this will include:
88
89  - The code owner responsible for the fix.
90
91  - The Zephyr release owners for the relevant releases affected by
92    this vulnerability.
93
94The Zephyr Security Subcommittee shall review the reported
95vulnerabilities during any meeting with more than three people in
96attendance.  During this review, they shall determine if new issues
97need to be embargoed.
98
99The guideline for embargo will be based on: 1. Severity of the issue,
100and 2. Exploitability of the issue.  Issues that the subcommittee
101decides do not need an embargo will be reproduced in the regular
102Zephyr project bug tracking system.
103
104.. _vulnerability_timeline:
105
106Security sensitive vulnerabilities shall be made public after an
107embargo period of at most 90 days.  The intent is to allow 30 days
108within the Zephyr project to fix the issues, and 60 days for external
109parties building products using Zephyr to be able to apply and
110distribute these fixes.
111
112.. _vulnerability_fix_recommendations:
113
114Fixes to the code shall be made through pull requests PR in the Zephyr
115project github.  Developers shall make an attempt to not reveal the
116sensitive nature of what is being fixed, and shall not refer to CVE
117numbers that have been assigned to the issue.  The developer instead
118should merely describe what has been fixed.
119
120The security subcommittee will maintain information mapping embargoed
121CVEs to these PRs (this information is within the Github security
122advisories), and produce regular reports of the state of security
123issues.
124
125Each issue that is considered a security vulnerability shall be
126assigned a CVE number.  As fixes are created, it may be necessary to
127allocate additional CVE numbers, or to retire numbers that were
128assigned.
129
130Vulnerability Notification
131==========================
132
133Each Zephyr release shall contain a report of CVEs that were fixed in
134that release.  Because of the sensitive nature of these
135vulnerabilities, the release shall merely include a list of CVEs that
136have been fixed.  After the embargo period, the vulnerabilities page
137shall be updated to include additional details of these
138vulnerabilities.  The vulnerability page shall give credit to the
139reporter(s) unless a reporter specifically requests anonymity.
140
141The Zephyr project shall maintain a vulnerability-alerts mailing list.
142This list will be seeded initially with a contact from each project
143member.  Additional parties can request to join this list by filling
144out the form at the `Vulnerability Registry`_.  These parties will be
145vetted by the project director to determine that they have a
146legitimate interest in knowing about security vulnerabilities during
147the embargo period.
148
149.. _Vulnerability Registry: https://www.zephyrproject.org/vulnerability-registry/ 
150
151Periodically, the security subcommittee will send information to this
152mailing list describing known embargoed issues, and their backport
153status within the project.  This information is intended to allow them
154to determine if they need to backport these changes to any internal
155trees.
156
157When issues have been triaged, this list will be informed of:
158
159- The Zephyr Project security advisory link (GitHub).
160
161- The CVE number assigned.
162
163- The subsystem involved.
164
165- The severity of the issue.
166
167After acceptance of a PR fixing the issue (merged), in addition to the
168above, the list will be informed of:
169
170- The association between the CVE number and the PR fixing it.
171
172- Backport plans within the Zephyr project.
173
174Backporting of Security Vulnerabilities
175=======================================
176
177Each security issue fixed within zephyr shall be backported to the
178following releases:
179
180- The current Long Term Stable (LTS) release.
181
182- The most recent two releases.
183
184The developer of the fix shall be responsible for any necessary
185backports, and apply them to any of the above listed release branches,
186unless the fix does not apply (the vulnerability was introduced after
187this release was made). All recommendations for
188:ref:`vulnerability fixes <vulnerability_fix_recommendations>` apply
189for backport pull requests (and associated issues). Additionally, it is
190recommended that the developer privately informs the responsible
191release manager that the backport pull request and issue are addressing
192a vulnerability.
193
194Backports will be tracked on the security advisory.
195
196Need to Know
197============
198
199Due to the sensitive nature of security vulnerabilities, it is
200important to share details and fixes only with those parties that have
201a need to know.  The following parties will need to know details about
202security vulnerabilities before the embargo period ends:
203
204- Maintainers will have access to all information within their domain
205  area only.
206
207- The current release manager, and the release manager for historical
208  releases affected by the vulnerability (see backporting above).
209
210- The Project Security Incident Response (PSIRT) team will have full
211  access to information.  The PSIRT is made up of representatives from
212  platinum members, and volunteers who do work on triage from other
213  members.
214
215- As needed, release managers and maintainers may be invited to attend
216  additional security meetings to discuss vulnerabilities.
217