Project:Security/GLSA Coordinator Guide
This document contains procedures, tips and tricks applying to the GLSA Coordinator job.
- 1 Prerequisites
- 2 Security bug types and Bugzilla components
- 3 Public vulnerability bug management
- 4 Confidential vulnerability bug management
- 5 GLSA drafting with GLSAMaker
- 6 GLSA publication
- 7 GLSA Coordinators Tools
- 8 Acknowledgements
A certain number of accounts must be established before working as a GLSA coordinator. To draft GLSAs you must get a GLSAMaker account. To manage security bugs you need to have a Bugzilla account, which will be upgraded to
editbugs privileges. To send GLSA announcements you need to have a email@example.com address (i.e. to be a Gentoo developer). This address should be allowed to send to gentoo-announce. To commit XML GLSAs you need your developer account to be upgraded with commit access to the GLSA directory in the
gentoo CVS repository. Finally you need an IRC name. You will be required to hang out in the #gentoo-security channel whenever you're available online.
You must create a GPG key for your firstname.lastname@example.org email address. You can either create a specific key or add the gentoo.org address to an existing key. The key ID should be set in the LDAP , and you should check that your name and key ID appears on the developer list . It is very important that the key is published at least on the subkeys.pgp.net keyserver. It can also be submitted on other keyservers.
You must setup a CVS environment on your home machine to be able to commit your GLSAs to the tree. This is done by checking out a part of the
gentoo CVS repository to a given directory (for example ~/gentoo_cvs):
To be able to post to the lists where we publish our GLSAs, you must subscribe your email@example.com address to them:
As a security developer, you will be added to the gentoo-core list and firstname.lastname@example.org alias. You should also subscribe to gentoo-announce, gentoo-dev and gentoo-security.
Security bug types and Bugzilla components
All security bugs are located in the
Gentoo Security Bugzilla product. If you find a security bug which does not have the correct product name, please fix it immediately. There are several different types of security bugs, and each has its own component.
Vulnerabilities are security bugs in the upstream software or introduced in the Gentoo ebuild packaging. These bugs result in GLSAs. Kernel bugs have their own category and should not filed as
Kernel vulnerabilities are treated using a separate procedure. To easily distinguish them from the other bugs, they are filed under the
Kernel category. Kernel bugs do not result in GLSAs.
Gentoo packages should be as secure by default as possible. Default configuration bugs are filed when the default configuration shipped with the package can be improved in terms of security.
Default config bugs do not generate GLSAs.
Vulnerabilities that are found by Gentoo developers should be double-checked before going out in the open (to upstream developers or security lists). They are filed as Confidential Bugs (see below) and with the
Auditing component. When the finding has been verified they are switched to
Sometimes a bug is communicated to us under the promise we'll keep it secret until a public release, usually known as the embargo date or coordinated release date. Restricted bugs have the "Gentoo Security" checkbox checked and therefore can only be accessed by Gentoo Security Team members. External people (package maintainers, arch testers) may be added on a per-name basis, aliases should never be used (because they are too wide and won't allow bug comments).
There are three different types of restricted bugs. The first (and most secret) ones are the
CLASSIFIED bugs. A bug is classified when it contains information that should never be released. This includes quotes of personal emails sent to restricted mailing-lists or non-public intermediary patches. Classified bugs are identified by the
CLASSIFIED keyword in their Status Whiteboard. Once CLASSIFIED, a bug cannot go back to unclassified status unless at least two security managers agree to declassify it.
CLASSIFIED bugs should never be opened (unrestricted).
The second type of restricted bugs is
CONFIDENTIAL bugs. These are bugs that contain information that should be kept secret until an agreed-upon coordinated release date. No part of the bug (affected package name, description, proposed patch or whatever) should ever leak outside the bug. Patches must NOT be committed to portage CVS.
The third (and less secret) type of restricted bugs is the
SEMI-PUBLIC bugs. Semi-public bugs should be kept secret, but patches may be committed to portage. This is generally when the vulnerability is not known to the general public but could be accessed by anyone (patch in upstream CVS for example).
Public vulnerability bug management
Status whiteboard rules
The status whiteboard in Bugzilla lets us keep track of the security bug resolution steps. It should be following this pattern: "RATING [status] coordinator", where:
|RATING||The vulnerability rating, following current policy rules||B3|
|[status]||The bug status, with optional extra information||[ebuild+]|
The following statuses are accepted:
|upstream||Waiting for upstream developer to publish a new version or patch|
|upstream+||No response from upstream|
|ebuild||Waiting for the Gentoo package maintainer to provide a fixed ebuild|
|ebuild+||No response from the maintainer, considering a security bump|
|stable||Waiting for arches to mark the package with the appropriate keywords|
|stable+||Some arches are taking too long to mark the package appropriately|
|glsa?||Security must make a decision on whether a GLSA is needed|
|glsa||Waiting for the coordinator to send his GLSA|
|glsa+||The GLSA is late, any GLSA coordinator can correct and send it|
|cleanup||Waiting for the Gentoo package maintainer to remove vulnerable ebuilds from the tree|
|cleanup+||No response from the maintainer, the Security Team should remove vulnerable ebuilds as needed|
The following extra information is admitted:
|Extra information||Description||Corresponding statuses|
|tomask||When a package.mask has been requested against the package||upstream+, ebuild+|
|masked||if the package was masked as a temporary solution||upstream+, ebuild+|
|tempglsa||When a temporary GLSA was issued as a temporary solution||upstream+, ebuild+|
|blocked||When the bug is blocked by another bug||(any)|
|B1 [stable blocked]|
Determining original bug status
When the fix is not available from the upstream developer and/or there is no official patch to solve the problem, the bug is in
[upstream] status. If a fix is available, the bug is in
[ebuild] status. If a fixed ebuild is put in the Portage tree, the next step is stabilizing, so the bug is in
[stable] status. When the fixed ebuild is in Portage with all required keywords set and if the issue is severe enough to warrant a GLSA, the bug is in
[glsa] status. Is the bug not severe enough, GLSA voting is next, so the status would be
Bugs in [upstream] status
[upstream] status, we wait for the fixed version or a decent patch to appear. This status requires to regularly check upstream for information: development and announce mailing lists, websites, bugs database, VCS when available, are all other relevant sources of information. Unofficial patches must be taken into account only if the upstream developer does not react to the vulnerability, and they must be thoroughly double-checked to ensure they are not evil. When a fix version is announced or a patch is found, the bug enters
If there is no reaction from upstream and no patch, we enter
[upstream+] status. The only option here is to security-mask the vulnerable package and issue a temporary GLSA if needed. See the policy for more details on the security masking approval procedure. The status whiteboard should then be flagged with masked and/or tempglsa keywords and bug severity set to
Bugs in [ebuild] status
[ebuild] status, we must identify the maintainer of the package, and summon him to commit a fixed ebuild. Sources to identify the herd or developer responsible for maintaining a package are the metadata.xml file in the directory of the package in portage and the Changelog file showing who did the latest version bumps. You should Cc: the herd and maintainer responsible for the package on the bug and ask him to provide an ebuild for the fixed version. You should periodically check that an ebuild wasn't committed to Portage without any comment on the bug (it happens). When the ebuild appears, the bug enters
If the maintainer doesn't show up, we enter
[ebuild+] status. In case a fixed version is available, you should test if a simple version bump (renaming the ebuild to the needed/fixed version and emerging it) works. If only a patch is available, you should test if it applies cleanly. Then you should find a Security Team member with Portage tree commit rights to do the bump and mark the ebuild
~ for testing.
If the bump is not easy and/or any problem is detected with the bumped ebuild, the only option is to security-mask the unmaintained package and issue a temporary GLSA if needed. See the policy for more details on the security masking approval procedure. The status whiteboard should then be flagged with
tempglsa keywords and bug severity set to
Bugs in [stable] status
[stable] status, you have to determine what KEYWORDS the provided ebuild needs before the GLSA can go out. This can be tricky. You have to consider every version currently in portage so that the fix ebuild has equally or more stable keywords than any other packages in Portage. Here is an example:
|Affected||x86 ~ppc ~ia64|
|Affected||~x86 ~ppc ~ia64|
|Fix must have:||x86 ppc ~ia64|
Once you have determined (and noted for reference on the bug) the needed KEYWORDS, you should Cc: arch teams and ask them to mark the ebuild stable or testing accordingly. To make sure that the arch teams will pick the bug up, don't forget to add "STABLEREQ" to the bug's "Keywords" field. The arches alias are email@example.com (firstname.lastname@example.org, email@example.com...). All arches (including "unsupported" arches) must be called. But note that only "supported" arches (as defined in the policy) are needed before the bug can advance to
[glsa] status You should periodically check for new keywords in the ebuild, as sometimes they are changed without a comment in the bug. As soon as the required KEYWORDS are in the ebuild for all supported arches, the bug enters
If the arch teams take too much time testing and changing the KEYWORDS, or they refuse to mark stable a package due to outstanding problems, the bug enters
[stable+] status. We must track down arch maintainers to have them mark stable or help testing. You should also convince the arches that if they discover a bug in the ebuild that already was in previous "stable" versions, the ebuild should be marked "stable" anyway, even if it's not really stable, as specified in the policy. If the KEYWORDS can't be met, the only other option is to security-mask the package: there is no acceptable unaffected version, so it is like if no acceptable upstream fix was provided.
Bugs in [glsa] status
[glsa] status, the security bug is corrected. We need to issue the GLSA or close the bug without GLSA. The policy determines the cases where a GLSA is needed and where a GLSA is not needed. There are also cases where a GLSA vote must take place to decide if a GLSA is needed (
[glsa?] status). If at least two Security Team members vote for "no GLSA", then no GLSA should be issued. The bug remains in
[glsa] status until a GLSA is published.
When a GLSA is needed but nothing was sent, the bug enters
[glsa+] status. This is the case when there are delays during drafting, reviewing or sending the advisory. Any member of the Security Team should take the lead and finalize the GLSA.
Bugs in [cleanup] status
This status is not in order like the others. It is used to denote that the maintainer needs to remove vulnerable ebuild versions in the tree.
For example, the foo package has a vulnerability in versions earlier than 1.23. The version 1.24 was added to Portage and is stable already (i.e. the stabilization was done before the security impact of the release was known), only old ebuilds need to be removed. The next status in this case would be
[glsa?] depending on severity.
Another use case might be when a package was updated, and all steps are done (i.e. a GLSA was sent or the team decided against sending one), but the vulnerable ebuilds should really be removed to avoid users accidentally installing them, the bug could be left open and set to the
[cleanup] state. This is usually not needed tough, but may be used on a case-to-case base when the Security Team has an elevated interest in vulnerable ebuilds getting removed for whatever reasons.
Confidential vulnerability bug management
Status whiteboard rules
Confidential bugs should be following this pattern:
RATING [status] KEYWORD CRD , where:
|RATING||The vulnerability rating, following current policy rules||B3|
|[status]||The bug status, with optional extra information||[ebuild+]|
|KEYWORD||The confidentiality level of the bug, can be CLASSIFIED, CONFIDENTIAL, SEMI-PUBLIC||CLASSIFIED|
|CRD||The coordinated release date for the bugs disclosure. If no time is given, assume 14:00 UTC.||2009-01-06 18:00 UTC|
The following extra statuses are accepted in confidential bugs:
|preebuild||Specific package maintainer has been called to prepare an ebuild which must not be committed in the CVS tree, but attached to the bug|
|prestable||Specific arch testers has been called to test a not-yet-public ebuild|
Handling confidential bugs
Semi-public bugs should be handled as public bugs, except that no herd or arch alias should be CC-ed on the bug but rather specific developers.
Confidential and classified bugs need extra care. The ebuild and files fixing the vulnerability should NOT be committed to the Portage tree, and no part of those bugs should ever be discussed in public. Patches or Portage overlay tarballs can be attached to the bug, though. Testers will have to setup their own overlay to test it. The idea with those bugs is to prepare the ebuild and have it tested for the coordinated release date, so that it can be released with all needed KEYWORDS together with the GLSA at the same time or shortly after the issue goes public.
GLSA drafting with GLSAMaker
The GLSA should use the affected software name with proper capitalization, not the Gentoo package name. For example, you should use "MySQL" and not "mysql". Lowercase names should be used only if the software has an all-lowercase name or if the software is identified by its command name ("traceroute").
You should not copy any part of any existing advisory, but you may use them as sources of information for our GLSA. If you copy, for example a software description, from a website, please use a citation and quotes.
Title, Synopsis, Keywords
The title must be short (< 60 characters in most cases) and have the application name (not category) in front. It should clearly identify the impact, without getting into any details. Version should be left out, except in rare cases where it allows to identify the package more clearly. Multiple affected packages should be separated by a comma. Examples include:
|MySQL: Data loss|
|Exim: Denial of Service|
|Apache 1.3: Arbitrary code execution|
|MPlayer, xine-lib: Multiple vulnerabilities|
Synopsis is a short (< 160 characters), but complete, description of the vulnerability. People reading only the Synopsis should get a good idea what the vulnerability is and what impact it has. Examples include:
|Two MySQL utilities create temporary files with hardcoded paths, allowing an attacker to use a symlink to trick MySQL into overwriting important data.|
|Multiple vulnerabilities, including remotely exploitable buffer overflows, have been found in code common to MPlayer and the xine library.|
The GLSA keyword category is typically set to "Ebuild" and should contain the name of the main software vulnerable (for example, "MySQL"). Other keyword types include "Portage" (for portage bugs) and "Infrastructure" (for server compromises).
Access should be "Local" or "Remote". Local vulnerabilities can be carried out only by a local user of the system. For example it implies to run a specific executable to elevate privileges, or access to a temporary directory to run a symlink attack. Remote vulnerabilities are those that can be exploited by an attacker with or without an account on the system. Remote vulnerabilities can either be active (exploiting a listening server by sending malicious queries) or passive (enticing a user to connect client software to a malicious server or to open malicious files).
Severity is an indication of how deep the vulnerability is. It is defined in the Vulnerability Treatment Policy, in the table "Evaluate the vulnerability type". Note that it depends only on the maximum risk, not on the commonality of the configuration option at risk. A buffer overflow allowing arbitrary code execution in a rare client software, only when it uses a specific configuration option, theoretically remains a "High" severity. A denial of service on all configurations of Apache theoretically remains a "Normal" severity. In rare cases the severity may be adjusted, when several members of the Security Team agree, to a more relevant level. For example, a vulnerability allowing defacement of web sites on Apache and all configurations should probably be "High" rather than "Normal".
Unaffected, Vulnerable packages
This section provides information about versions of packages that are unaffected or vulnerable to the vulnerability described in this advisory. You should pay special attention to those numbers as they are one of the few areas where mistakes imply an errata publication.
There are the different fields composing an version entry. The package name field must list the category and package name ("net-mail/exim"). Regarding the "Architectures" field, you should put "*" in it when the version description applies to all the arches marked in the ebuild. You should use multiple entries for different arches if the version description is different from arch to arch. The "Auto" field must be set to true if the package is upgradeable by emerge.
For version fields, there are multiple cases:
The simple case is when the vulnerability is present in all old versions, and is fixed in all versions newer than a specific fix version. In this case, you should use ">= first fixed version" as unaffected and "< first fixed version" as vulnerable. You should double-check that there was no ebuild between the last affected version and the first fixed version.
A more complex case is when the vulnerability is present only in a few recent versions. Let's take the example of a package where 1.2.8-r2 was not affected, 1.2.9, 1.2.9-r1 and 1.2.9-r2 were affected, and 1.2.10 is fixed. In this case there are two possibilities:
|>=1.2.10||==1.2.9 ==1.2.9-r1 ==1.2.9-r2|
Another complex case is when the vulnerability is present in multiple slots for a package. For example, a package may have versions 1.5.x as SLOT="0" and versions 1.2.x as SLOT="1.2". If a vulnerability exists in 1.5.8 and 1.2.46 and was fixed in 1.5.9 and 1.2.47, the unaffected and vulnerable versions would look like this:
Finally, when the package has no fixed version, you should omit the "Unaffected" entry for that package and set "Auto" to "no".
Background, Description, Impact
The Background section gives information about the package at risk. It describes briefly what it is and gives any information that is helpful in understanding the part of the package vulnerable. The Background section should be shorter than the Description section or the Impact section. Good examples include:
|The K Desktop Environment (KDE) is a powerful Free Software graphical desktop environment. KDE makes use of URI handlers to trigger various programs when specific URLs are received.|
|CVS (Concurrent Versions System) is an open-source network-transparent version control system. It contains both a client utility and a server.|
|Metamail is a program that decodes MIME encoded mail. It is therefore often automatically called when an email is received or read.|
The Description section details what the vulnerability is, without telling what happens when it is exploited. It should be understandable by people without too much security background. Sometimes there is no information about the vulnerability at all, in which cases you should let the description short. Good examples include:
|The telnet URI handler in Opera does not check for leading '-' characters in the host name. Consequently, a maliciously-crafted telnet:// link may be able to pass options to the telnet program itself. One example would be "telnet://-nMyFile" If MyFile exists in the user's home directory and the user clicking on the link has write permissions to it, the contents of the file will be overwritten with the output of the telnet trace information. If MyFile does not exist, the file will be created in the user's home directory.|
|The MySQL bug reporting utility (mysqlbug) creates a temporary file to log bug reports to. A malicious local user with write access to the /tmp directory could create a symbolic link of the name mysqlbug-N pointing to a protected file, such as /etc/passwd, such that when mysqlbug creates the Nth log file, it would end up overwriting the target file. A similar vulnerability exists with the mysql_multi utility, which creates a temporary file called mysql_multi.log.|
|Multiple vulnerabilities have been found and fixed in the RTSP handling code common to recent versions of these two packages. These vulnerabilities include several remotely exploitable buffer overflows.|
The Impact section describes the global impact of the vulnerabilities described in the Description section, when exploited. It should focus on the maximum risk. Multiple impacts should be listed from highest to lowest severity. Good examples:
|A remote attacker, posing as a RTSP stream server, can execute arbitrary code with the rights of the user of the software playing the stream (MPlayer or any player using xine-lib). Another attacker may entice a user to use a maliciously crafted URL or playlist to achieve the same results.|
|This vulnerability has two possible impacts. First, it may create new files in the user's home directory. Second, and far more serious, it may overwrite existing files that the user has write permissions to. An attacker with some knowledge of a user's home directory might be able to destroy important files stored within.|
The workaround describes if there is any simple way (other than upgrading to the fix version) of avoiding to be vulnerable. Good examples include:
|For a temporary workaround, providing you do not require Kerberos 4 support, you may turn off Kerberos 4 kadmin by running kadmind with the --no-kerberos4 option.|
|There is no known workaround at this time.|
The Resolution section explains in human-readable terms what you have to do to be fully protected against the vulnerability. This section must look like this:
If there are multiple architectures, it should look like this:
If the GLSA is about a shared library, you should include the following paragraph at the end of the Resolution section to warn about the necessity to rebuild linked executables:
|Packages which depend on this library may need to be recompiled. Tools such as revdep-rebuild may assist in identifying some of these packages.|
The References section should provide links to reference information about the vulnerability. When a CVE number (CVE-XXXX-XXX) is available, it should be provided (with the complete CVE number in "Title"). You can also link an upstream developer advisory and/or announce email, when available. You should avoid links to other distribution advisories or non-official advisories from separate entities.
When the draft is finished, it must be submitted to the review of other members of the Security Team, by calling for a review on the #gentoo-security channel. The final version (after all corrections are made) must be approved by two Security Team members before being committed and sent out.
When reviewing a GLSA draft carefully check the correctness of the following things:
- Affected/unaffected versions (Check ChangeLog that versions are correct and make sure that there is no version not included by either affected or unaffected).
- Title correctness.
- Severity and Access (Don't just rely on the bug rating and for "Local" access a local account is needed otherwise it is "Remote").
- Finally do a sanity check: Is this a real vulnerability and not just a bug (like the Samba and Shadow non-vulnerabilities).
When the draft is approved, it must be assigned an official GLSA number. This is done by calling the "Move" function in GLSAMaker to move the draft from the pool to the official area.
GLSA XML commit
You need to commit the GLSA XML to the Gentoo CVS tree so that it automagically appears in the RDF feed, the GLSA list, and the portage updates. You should first update your GLSA directory in the gentoo CVS repository tree:
Then you should click
Fetch on the GLSA to download the XML version, and save it into your local gentoo_cvs/gentoo/xml/htdocs/security/en/glsa/ directory. Then you should add and commit the XML file:
Click on the Txt download to have a text version of the GLSA. Check that the affected/unaffected section looks good, then prepare an email with the following rules:
- From and Return-Path must be set to firstname.lastname@example.org
- To and Cc should be set according to policy
- Subject must be "[ GLSA XXXXYY-ZZ ] Your vulnerability here" (you should copy/paste from the title in the Txt file)
- the body of the mail should be the content of the Txt file, from the "Gentoo Linux Security Advisory" header to the end of the file
- email must be signed by the GPG key for your email@example.com address
You should check that the email got through to gentoo-announce, then you can close the related bug(s), by setting their status to RESOLVED/FIXED , with a comment pointing to the GLSA number.
An erratum is published when we made a mistake otherwise it is an update. When policy warrants a republication these guidelines should be followed:
- Revision should be correctly set in XML. This means that revision might need to be manually corrected in GLSAMaker data directory, if you do multiple changes using GLSAMaker ( ie. <revised>September 10, 2004: 02</revised>)
- If there is no vulnerability no affected packages should be listed in the XML
- Title can change ( ie. GLSA 200409-14 for Samba and GLSA 200411-01 for ppp)
- Not all Errata need republication. Policy details when republication is needed.
- For the text version GLSAmaker can add the relevant information to updates and erratas. Manually follow the instructions provided by GLSAmaker.
- Text version must contain an Errata or Update section (example shown below) and AFTER THAT only the sections changed (XML version does not have extra sections)
|This advisory incorrectly described ppp as being vulnerable to a remote denial of service. After further verifications, it appears that a remote user can only deny service to himself, so this bug does not induce any security issue at all. The corrected sections appear below.|
For two complete errata email examples see ERRATA: [ GLSA 200409-14 Samba: Remote printing non-vulnerability] (where there were no real vulnerability) and ERRATA: [ GLSA 200801-09 X.Org X server and Xfont library: Multiple vulnerabilities] (where the problem was not correctly fixed in the initial version). For an update example see UPDATE: [ GLSA 200410-30 GPdf, KPDF, KOffice: Vulnerabilities in included xpdf] (where the fix introduced another vulnerability).
Otherwise normal GLSA publication guidelines should be followed.
GLSA Coordinators Tools
- packageview is a tool that will open packages.gentoo.org and Gentoo ViewCVS at the right place for a given category and package name. It helps to determine what keywords are needed and to track changes to a package.
GLSA publication helpers
- glsacommit is a bash function handling GLSA commit. It features ssh-agent keyadding, glsa-check conformity doublecheck and has "Are you sure" functions. Edit it to suit your needs and directory locations.
Security Subversion repository
- The Security Subversion repository contains several tools to collaboratively assess whether we are affected by new CVE identifiers, and tools to determine target keywords. Most tools directly interact with Bugzilla, making manual copy-pasting unnecessary.
We would like to thank the following authors and editors for their contributions to this guide:
- Thierry Carrez
- Sune Kloppenborg Jeppesen
- Matthias Geerdsen
- Robert Buchholz
- Alex Legler