From cb99d0b1c52349125cbbc58cdd8555f120fc4ae9 Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Thu, 4 Dec 2025 16:23:05 +0100 Subject: [PATCH] Add a new "Security" section The current security-related documentation is a bit hard to find and hidden within the development manual. However these are processes that are not part of a development task but is rather a vulnerability reporting process. Create a new "Security" section in the documentation to gather this information. This will be directly visible in the sidebar when opening the documentation. Split the previous security-subjects.rst document into 2 documents: - security-team.rst: defines the roles of the security teams and its members. - reporting-vulnerabilities.rst: guide to report vulnerabilities to the security team. The plan is to backport these documents to active releases. As a consequence, this section should be free of instructions and information that only make sense for a specific release. It should _not_ contain documents on how to enable security features with Yocto on target devices, this is unrelated and can be left in the development manual (for example: dev-manual/vulnerabilities.rst to deal with CVEs). (From yocto-docs rev: 3fd0f37d708d88534dd6dbb51dc264911c349352) Signed-off-by: Antonin Godard (cherry picked from commit 81e14ca2d5cff9e2104c556655144b069633790c) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/dev-manual/index.rst | 1 - .../dev-manual/security-subjects.rst | 194 ------------------ documentation/index.rst | 7 +- documentation/security-reference/index.rst | 14 ++ .../reporting-vulnerabilities.rst | 85 ++++++++ .../security-reference/security-team.rst | 110 ++++++++++ 6 files changed, 215 insertions(+), 196 deletions(-) delete mode 100644 documentation/dev-manual/security-subjects.rst create mode 100644 documentation/security-reference/index.rst create mode 100644 documentation/security-reference/reporting-vulnerabilities.rst create mode 100644 documentation/security-reference/security-team.rst diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst index ef0512d246..2a184ec731 100644 --- a/documentation/dev-manual/index.rst +++ b/documentation/dev-manual/index.rst @@ -41,7 +41,6 @@ Yocto Project Development Tasks Manual build-quality debugging licenses - security-subjects vulnerabilities sbom error-reporting-tool diff --git a/documentation/dev-manual/security-subjects.rst b/documentation/dev-manual/security-subjects.rst deleted file mode 100644 index 1ec7c8b385..0000000000 --- a/documentation/dev-manual/security-subjects.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -Dealing with Vulnerability Reports -********************************** - -The Yocto Project and OpenEmbedded are open-source, community-based projects -used in numerous products. They assemble multiple other open-source projects, -and need to handle security issues and practices both internal (in the code -maintained by both projects), and external (maintained by other projects and -organizations). - -This manual assembles security-related information concerning the whole -ecosystem. It includes information on reporting a potential security issue, -the operation of the YP Security team and how to contribute in the -related code. It is written to be useful for both security researchers and -YP developers. - -How to report a potential security vulnerability? -================================================= - -If you would like to report a public issue (for example, one with a released -CVE number), please report it using the -:yocto_bugs:`Security Bugzilla `. - -If you are dealing with a not-yet-released issue, or an urgent one, please send -a message to security AT yoctoproject DOT org, including as many details as -possible: the layer or software module affected, the recipe and its version, -and any example code, if available. This mailing list is monitored by the -Yocto Project Security team. - -For each layer, you might also look for specific instructions (if any) for -reporting potential security issues in the specific ``SECURITY.md`` file at the -root of the repository. Instructions on how and where submit a patch are -usually available in ``README.md``. If this is your first patch to the -Yocto Project/OpenEmbedded, you might want to have a look into the -Contributor's Manual section -":ref:`contributor-guide/submit-changes:preparing changes for submission`". - -Branches maintained with security fixes ---------------------------------------- - -See the -:ref:`Release process ` -documentation for details regarding the policies and maintenance of stable -branches. - -The :yocto_home:`Releases ` page contains a list of all -releases of the Yocto Project, grouped into current and previous releases. -Previous releases are no longer actively maintained with security patches, but -well-tested patches may still be accepted for them for significant issues. - -Security-related discussions at the Yocto Project -------------------------------------------------- - -We have set up two security-related emails/mailing lists: - - - Public Mailing List: yocto [dash] security [at] yoctoproject[dot] org - - This is a public mailing list for anyone to subscribe to. This list is an - open list to discuss public security issues/patches and security-related - initiatives. For more information, including subscription information, - please see the :yocto_lists:`yocto-security mailing list info page - `. - - This list requires moderator approval for new topics to be posted, to avoid - private security reports to be posted by mistake. - - - Yocto Project Security Team: security [at] yoctoproject [dot] org - - This is an email for reporting non-published potential vulnerabilities. - Emails sent to this address are forwarded to the Yocto Project Security - Team members. - - -What you should do if you find a security vulnerability -------------------------------------------------------- - -If you find a security flaw: a crash, an information leakage, or anything that -can have a security impact if exploited in any Open Source software built or -used by the Yocto Project, please report this to the Yocto Project Security -Team. If you prefer to contact the upstream project directly, please send a -copy to the security team at the Yocto Project as well. If you believe this is -highly sensitive information, please report the vulnerability in a secure way, -i.e. encrypt the email and send it to the private list. This ensures that -the exploit is not leaked and exploited before a response/fix has been generated. - -Security team -============= - -The Yocto Project/OpenEmbedded security team coordinates the work on security -subjects in the project. All general discussion takes place publicly. The -Security Team only uses confidential communication tools to deal with private -vulnerability reports before they are released. - -Security team appointment -------------------------- - -The Yocto Project Security Team consists of at least three members. When new -members are needed, the Yocto Project Technical Steering Committee (YP TSC) -asks for nominations by public channels including a nomination deadline. -Self-nominations are possible. When the limit time is -reached, the YP TSC posts the list of candidates for the comments of project -participants and developers. Comments may be sent publicly or privately to the -YP and OE TSCs. The candidates are approved by both YP TSC and OpenEmbedded -Technical Steering Committee (OE TSC) and the final list of the team members -is announced publicly. The aim is to have people representing technical -leadership, security knowledge and infrastructure present with enough people -to provide backup/coverage but keep the notification list small enough to -minimize information risk and maintain trust. - -YP Security Team members may resign at any time. - -Security Team Operations ------------------------- - -The work of the Security Team might require high confidentiality. Team members -are individuals selected by merit and do not represent the companies they work -for. They do not share information about confidential issues outside of the team -and do not hint about ongoing embargoes. - -Team members can bring in domain experts as needed. Those people should be -added to individual issues only and adhere to the same standards as the YP -Security Team. - -The YP security team organizes its meetings and communication as needed. - -When the YP Security team receives a report about a potential security -vulnerability, they quickly analyze and notify the reporter of the result. -They might also request more information. - -If the issue is confirmed and affects the code maintained by the YP, they -confidentially notify maintainers of that code and work with them to prepare -a fix. - -If the issue is confirmed and affects an upstream project, the YP security team -notifies the project. Usually, the upstream project analyzes the problem again. -If they deem it a real security problem in their software, they develop and -release a fix following their security policy. They may want to include the -original reporter in the loop. There is also sometimes some coordination for -handling patches, backporting patches etc, or just understanding the problem -or what caused it. - -When the fix is publicly available, the YP security team member or the -package maintainer sends patches against the YP code base, following usual -procedures, including public code review. - -What Yocto Security Team does when it receives a security vulnerability ------------------------------------------------------------------------ - -The YP Security Team team performs a quick analysis and would usually report -the flaw to the upstream project. Normally the upstream project analyzes the -problem. If they deem it a real security problem in their software, they -develop and release a fix following their own security policy. They may want -to include the original reporter in the loop. There is also sometimes some -coordination for handling patches, backporting patches etc, or just -understanding the problem or what caused it. - -The security policy of the upstream project might include a notification to -Linux distributions or other important downstream projects in advance to -discuss coordinated disclosure. These mailing lists are normally non-public. - -When the upstream project releases a version with the fix, they are responsible -for contacting `Mitre `__ to get a CVE number assigned and -the CVE record published. - -If an upstream project does not respond quickly ------------------------------------------------ - -If an upstream project does not fix the problem in a reasonable time, -the Yocto's Security Team will contact other interested parties (usually -other distributions) in the community and together try to solve the -vulnerability as quickly as possible. - -The Yocto Project Security team adheres to the 90 days disclosure policy -by default. An increase of the embargo time is possible when necessary. - -Current Security Team members ------------------------------ - -For secure communications, please send your messages encrypted using the GPG -keys. Remember, message headers are not encrypted so do not include sensitive -information in the subject line. - - - Ross Burton: `Public key `__ - - - Michael Halstead: - `Public key `__ - or `Public key `__ - - - Richard Purdie: `Public key `__ - - - Marta Rybczynska: `Public key `__ - - - Steve Sakoman: `Public key `__ diff --git a/documentation/index.rst b/documentation/index.rst index 3fef1704a4..adcb524df8 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -20,7 +20,6 @@ Welcome to the Yocto Project Documentation Yocto Project Software Overview Tips and Tricks Wiki - .. toctree:: :maxdepth: 1 :caption: Manuals @@ -37,6 +36,12 @@ Welcome to the Yocto Project Documentation Test Environment Manual bitbake +.. toctree:: + :maxdepth: 1 + :caption: Security + + Yocto Project Security Reference + .. toctree:: :maxdepth: 1 :caption: Release Manuals diff --git a/documentation/security-reference/index.rst b/documentation/security-reference/index.rst new file mode 100644 index 0000000000..c20a54d1a9 --- /dev/null +++ b/documentation/security-reference/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +================================ +Yocto Project Security Reference +================================ + +.. toctree:: + :caption: Table of Contents + :numbered: + + security-team + reporting-vulnerabilities + +.. include:: /boilerplate.rst diff --git a/documentation/security-reference/reporting-vulnerabilities.rst b/documentation/security-reference/reporting-vulnerabilities.rst new file mode 100644 index 0000000000..0c457278d5 --- /dev/null +++ b/documentation/security-reference/reporting-vulnerabilities.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Reporting Vulnerabilities +************************* + +The Yocto Project and OpenEmbedded are open-source, community-based projects +used in numerous products. They assemble multiple other open-source projects, +and need to handle security issues and practices both internal (in the code +maintained by both projects), and external (maintained by other projects and +organizations). + +This manual assembles security-related information concerning the whole +ecosystem. It includes information on reporting a potential security issue, +the operation of the YP Security team and how to contribute in the +related code. It is written to be useful for both security researchers and +YP developers. + +How to report a potential security vulnerability? +================================================= + +If you would like to report a public issue (for example, one with a released +CVE number), please report it using the +:yocto_bugs:`Security Bugzilla `. + +If you are dealing with a not-yet-released issue, or an urgent one, please send +a message to security AT yoctoproject DOT org, including as many details as +possible: the layer or software module affected, the recipe and its version, +and any example code, if available. This mailing list is monitored by the +Yocto Project Security team. + +For each layer, you might also look for specific instructions (if any) for +reporting potential security issues in the specific ``SECURITY.md`` file at the +root of the repository. Instructions on how and where submit a patch are +usually available in ``README.md``. If this is your first patch to the +Yocto Project/OpenEmbedded, you might want to have a look into the +Contributor's Manual section +":ref:`contributor-guide/submit-changes:preparing changes for submission`". + +Branches maintained with security fixes +--------------------------------------- + +See the +:ref:`Release process ` +documentation for details regarding the policies and maintenance of stable +branches. + +The :yocto_home:`Releases ` page contains a list of all +releases of the Yocto Project, grouped into current and previous releases. +Previous releases are no longer actively maintained with security patches, but +well-tested patches may still be accepted for them for significant issues. + +Security-related discussions at the Yocto Project +------------------------------------------------- + +We have set up two security-related emails/mailing lists: + + - Public Mailing List: yocto [dash] security [at] yoctoproject[dot] org + + This is a public mailing list for anyone to subscribe to. This list is an + open list to discuss public security issues/patches and security-related + initiatives. For more information, including subscription information, + please see the :yocto_lists:`yocto-security mailing list info page + `. + + This list requires moderator approval for new topics to be posted, to avoid + private security reports to be posted by mistake. + + - Yocto Project Security Team: security [at] yoctoproject [dot] org + + This is an email for reporting non-published potential vulnerabilities. + Emails sent to this address are forwarded to the Yocto Project Security + Team members. + + +What you should do if you find a security vulnerability +------------------------------------------------------- + +If you find a security flaw: a crash, an information leakage, or anything that +can have a security impact if exploited in any Open Source software built or +used by the Yocto Project, please report this to the Yocto Project Security +Team. If you prefer to contact the upstream project directly, please send a +copy to the security team at the Yocto Project as well. If you believe this is +highly sensitive information, please report the vulnerability in a secure way, +i.e. encrypt the email and send it to the private list. This ensures that +the exploit is not leaked and exploited before a response/fix has been generated. diff --git a/documentation/security-reference/security-team.rst b/documentation/security-reference/security-team.rst new file mode 100644 index 0000000000..b773653822 --- /dev/null +++ b/documentation/security-reference/security-team.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Security team +************* + +The Yocto Project/OpenEmbedded security team coordinates the work on security +subjects in the project. All general discussion takes place publicly. The +Security Team only uses confidential communication tools to deal with private +vulnerability reports before they are released. + +Security team appointment +========================= + +The Yocto Project Security Team consists of at least three members. When new +members are needed, the Yocto Project Technical Steering Committee (YP TSC) +asks for nominations by public channels including a nomination deadline. +Self-nominations are possible. When the limit time is +reached, the YP TSC posts the list of candidates for the comments of project +participants and developers. Comments may be sent publicly or privately to the +YP and OE TSCs. The candidates are approved by both YP TSC and OpenEmbedded +Technical Steering Committee (OE TSC) and the final list of the team members +is announced publicly. The aim is to have people representing technical +leadership, security knowledge and infrastructure present with enough people +to provide backup/coverage but keep the notification list small enough to +minimize information risk and maintain trust. + +YP Security Team members may resign at any time. + +Security Team Operations +======================== + +The work of the Security Team might require high confidentiality. Team members +are individuals selected by merit and do not represent the companies they work +for. They do not share information about confidential issues outside of the team +and do not hint about ongoing embargoes. + +Team members can bring in domain experts as needed. Those people should be +added to individual issues only and adhere to the same standards as the YP +Security Team. + +The YP security team organizes its meetings and communication as needed. + +When the YP Security team receives a report about a potential security +vulnerability, they quickly analyze and notify the reporter of the result. +They might also request more information. + +If the issue is confirmed and affects the code maintained by the YP, they +confidentially notify maintainers of that code and work with them to prepare +a fix. + +If the issue is confirmed and affects an upstream project, the YP security team +notifies the project. Usually, the upstream project analyzes the problem again. +If they deem it a real security problem in their software, they develop and +release a fix following their security policy. They may want to include the +original reporter in the loop. There is also sometimes some coordination for +handling patches, backporting patches etc, or just understanding the problem +or what caused it. + +When the fix is publicly available, the YP security team member or the +package maintainer sends patches against the YP code base, following usual +procedures, including public code review. + +What Yocto Security Team does when it receives a security vulnerability +======================================================================= + +The YP Security Team team performs a quick analysis and would usually report +the flaw to the upstream project. Normally the upstream project analyzes the +problem. If they deem it a real security problem in their software, they +develop and release a fix following their own security policy. They may want +to include the original reporter in the loop. There is also sometimes some +coordination for handling patches, backporting patches etc, or just +understanding the problem or what caused it. + +The security policy of the upstream project might include a notification to +Linux distributions or other important downstream projects in advance to +discuss coordinated disclosure. These mailing lists are normally non-public. + +When the upstream project releases a version with the fix, they are responsible +for contacting `Mitre `__ to get a CVE number assigned and +the CVE record published. + +If an upstream project does not respond quickly +=============================================== + +If an upstream project does not fix the problem in a reasonable time, +the Yocto's Security Team will contact other interested parties (usually +other distributions) in the community and together try to solve the +vulnerability as quickly as possible. + +The Yocto Project Security team adheres to the 90 days disclosure policy +by default. An increase of the embargo time is possible when necessary. + +Security Team Members +===================== + +For secure communications, please send your messages encrypted using the GPG +keys. Remember, message headers are not encrypted so do not include sensitive +information in the subject line. + +- Ross Burton: `Public key `__ + +- Michael Halstead: + `Public key `__ + or `Public key `__ + +- Richard Purdie: `Public key `__ + +- Marta Rybczynska: `Public key `__ + +- Steve Sakoman: `Public key `__