GLSA Coordinator Guide

1.  Prerequisites

Accounts

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 yourname@gentoo.org 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.

GPG key

You must create a GPG key for your yourname@gentoo.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 sent to devrel, 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.

Environment

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):

you@home you $ mkdir gentoo_cvs
you@home you $ cd gentoo_cvs
you@home gentoo_cvs $ export CVS_RSH="ssh"
you@home gentoo_cvs $ export CVSROOT="yourname@cvs.gentoo.org:/var/cvsroot"
you@home gentoo_cvs $ cvs checkout gentoo/xml/htdocs/security

Mailing-list subscriptions

To be able to post to the lists where we publish our GLSAs, you must subscribe your yourname@gentoo.org address to them:

As a security developer, you will be added to the gentoo-core list and security@gentoo.org alias. You should also subscribe to gentoo-announce, gentoo-dev and gentoo-security.

2.  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.

Vulnerability

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 Vulnerability.

Kernel

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 but have their own publication system (Gentoo KISS).

Default config

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.

Auditing

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 Vulnerability.

Restricted bugs

Sometimes a bug is communicated to us under the promise we'll keep it secret until a public release. Restricted bugs have the "Gentoo Security" checkbox checked and therefore can only be accessed by Gentoo Security Team members. External people (package maintainer, arch testers, Release Engineering) 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 should 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).

3.  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:

The following statuses are accepted:

The following extra information is admitted:

Examples:

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 the solution must be found amongst Gentoo developers, the bug is in [inhouse] status. If a fix is available, the bug is in [ebuild] status. If a fix ebuild is put in the portage tree, the bug is in [stable] status. When the fix ebuild is in portage with all required keywords set, the bug is in [glsa] status.

Bugs in [upstream] status

In [upstream] status, we wait for the fix version or a decent patch to appear. This status requires to regularly check upstream for information: development and announce mailing lists, websites, Bugs database, CVS when available, are all 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 [ebuild] status.

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 enhancement.

Bugs in [ebuild] status

In [ebuild] status, we must identify the maintainer of the package, and summon him to commit a fix 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/or maintainer responsible for the package on the bug and ask him to provide an ebuild for the fix 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 [stable] status.

If the maintainer doesn't show up, we enter [ebuild+] status. In cases of fix version, you should test if a simple version bump (renaming the ebuild to the latest version and emerging it) works. In cases of patch, you should test if it applies cleanly. Then you should find a security bug wrangler with x86 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 masked and/or tempglsa keywords and bug severity set to enhancement.

Bugs in [stable] status

In [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:

Once 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 ~ accordingly. The arches alias are archname@gentoo.org (x86@gentoo.org, ppc@gentoo.org...). 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 bug for all supported arches, the bug enters [glsa] status.

During a release preparation period you should also Cc: Release Engineering (release@gentoo.org) on all bugs with [stable] status.

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, 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

In [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. It's the case when the assigned GLSA coordinator did not draft and/or made peer-reviewed and/or sent his GLSA. Other members of the Security Team should take the lead at this point and finalize the GLSA.

4.  Confidential vulnerability bug management

Status whiteboard rules

Confidential bugs should be following this pattern: "RATING [status] coordinator / Release_date CLASSIFIED", where:

The following extra statuses are accepted in confidential bugs:

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 portage CVS, 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 the issue goes public.

5.  GLSA drafting with GLSAMaker

General rules

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 allow to clearly identify the vulnerability, 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:

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:

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, Severity

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 the 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 "<= last affected version" as vulnerable. You should double-check that there was no ebuild between the last affected version and the first fixed version. When in doubt, you should use ">= first fixed version" as unaffected and "< first fix version" as vulnerable.

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:

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 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 Impact section describes the global impact of the vulnerabilities described in the Description section, when exploited. It should focus on the maximum risk. Good examples:

Workaround, Resolution

The workaround describes if there is any simple way (other than upgrading to the fix version) of avoiding to be vulnerable. Good examples include:

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:

All Heimdal users should upgrade to the latest stable version:
<code>
# emerge --sync
# emerge --ask --oneshot --verbose ">=app-crypt/heimdal-0.6.2"

If there are multiple architectures, it should look like this:

OpenOffice.org users on the SPARC architecture should:
<code>
# emerge --sync
# emerge --ask --oneshot --verbose ">=app-office/openoffice-1.1.0-r3"
</code>
</p>
<p>
OpenOffice.org users on the PPC architecture should:
</p>
<code>
# emerge --sync
# emerge --ask --oneshot --verbose ">=app-office/openoffice-1.0.3-r1"

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:

References

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.

6.  GLSA publication

Peer reviewing

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:

you@home you $ cd gentoo_cvs
you@home gentoo_cvs $ cvs update -dP gentoo/xml/htdocs/security

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:

you@home gentoo_cvs $ cd gentoo/xml/htdocs/security/en/glsa
you@home glsa $ cvs add glsa-YYYYMM-NN.xml
you@home glsa $ cvs commit -m "GLSA YYYYMM-NN" glsa-YYYYMM-NN.xml

E-mail announcement

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 yourname@gentoo.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 yourname@gentoo.org address

Bug closing

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.

Errata/Update publication

An errata 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)

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 200405-25 ] tla: Multiple vulnerabilities in included libneon (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.

7.  GLSA Coordinators Tools

Information gathering

• 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.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.