5.8.5. Handling security-related bugs

Due to their sensitive nature, security-related bugs must be handled carefully. The Debian Security Team exists to coordinate this activity, keeping track of outstanding security problems, helping maintainers with security problems or fixing them themselves, sending security advisories, and maintaining security.debian.org.

When you become aware of a security-related bug in a Debian package, whether or not you are the maintainer, collect pertinent information about the problem, and promptly contact the security team by emailing team@security.debian.org. If desired, email can be encrypted with the Debian Security Contact key, see https://www.debian.org/security/faq#contact for details. DO NOT UPLOAD any packages for stable without contacting the team. Useful information includes, for example:

• Whether or not the bug is already public.

• Which versions of the package are known to be affected by the bug. Check each version that is present in a supported Debian release, as well as testing and unstable.

• The nature of the fix, if any is available (patches are especially helpful)

• Any fixed packages that you have prepared yourself (send the resulting debdiff or alternatively only the .diff.gz and .dsc files and read Preparing packages to address security issues first)

• Any assistance you can provide to help with testing (exploits, regression testing, etc.)

• Any information needed for the advisory (see Security Advisories)

As the maintainer of the package, you have the responsibility to maintain it, even in the stable release. You are in the best position to evaluate patches and test updated packages, so please see the sections below on how to prepare packages for the Security Team to handle.

5.8.5.1. Debian Security Tracker

The security team maintains a central database, the Debian Security Tracker. This contains all public information that is known about security issues: which packages and versions are affected or fixed, and thus whether stable, testing and/or unstable are vulnerable. Information that is still confidential is not added to the tracker.

You can search it for a specific issue, but also on package name. Look for your package to see which issues are still open. If you can, please provide more information about those issues, or help to address them in your package. Instructions are on the tracker web pages.

5.8.5.2. Confidentiality

Unlike most other activities within Debian, information about security issues must sometimes be kept private for a time. This allows software distributors to coordinate their disclosure in order to minimize their users’ exposure. Whether this is the case depends on the nature of the problem and corresponding fix, and whether it is already a matter of public knowledge.

There are several ways developers can learn of a security problem:

• they notice it on a public forum (mailing list, web site, etc.)

• someone files a bug report

• someone informs them via private email

In the first two cases, the information is public and it is important to have a fix as soon as possible. In the last case, however, it might not be public information. In that case there are a few possible options for dealing with the problem:

• If the security exposure is minor, there is sometimes no need to keep the problem a secret and a fix should be made and released.

• If the problem is severe, it is preferable to share the information with other vendors and coordinate a release. The security team keeps in contact with the various organizations and individuals and can take care of that.

In all cases if the person who reports the problem asks that it not be disclosed, such requests should be honored, with the obvious exception of informing the security team in order that a fix may be produced for a stable release of Debian. When sending confidential information to the security team, be sure to mention this fact.

Please note that if secrecy is needed you may not upload a fix to unstable (or anywhere else, such as a public VCS repository). It is not sufficient to obfuscate the details of the change, as the code itself is public, and can (and will) be examined by the general public.

There are two reasons for releasing information even though secrecy is requested: the problem has been known for a while, or the problem or exploit has become public.

The Security Team has a PGP-key to enable encrypted communication about sensitive issues. See the Security Team FAQ for details.

5.8.5.3. Security Advisories

Security advisories are only issued for the current, released stable distribution, and not for testing or unstable. When released, advisories are sent to the debian-security-announce@lists.debian.org mailing list and posted on the security web page. Security advisories are written and posted by the security team. However they certainly do not mind if a maintainer can supply some of the information for them, or write part of the text. Information that should be in an advisory includes:

• A description of the problem and its scope, including:

  • The type of problem (privilege escalation, denial of service, etc.)

  • What privileges may be gained, and by whom (if any)

  • How it can be exploited

  • Whether it is remotely or locally exploitable

  • How the problem was fixed

  This information allows users to assess the threat to their systems.

• Version numbers of affected packages

• Version numbers of fixed packages

• Information on where to obtain the updated packages (usually from the Debian security archive)

• References to upstream advisories, CVE identifiers, and any other information useful in cross-referencing the vulnerability

5.8.5.4. Preparing packages to address security issues

One way that you can assist the security team in their duties is to provide them with fixed packages suitable for a security advisory for the stable Debian release.

When an update is made to the stable release, care must be taken to avoid changing system behavior or introducing new bugs. In order to do this, make as few changes as possible to fix the bug. Users and administrators rely on the exact behavior of a release once it is made, so any change that is made might break someone’s system. This is especially true of libraries: make sure you never change the API (Application Program Interface) or ABI (Application Binary Interface), no matter how small the change.

This means that moving to a new upstream version is not a good solution. Instead, the relevant changes should be back-ported to the version present in the current stable Debian release. Generally, upstream maintainers are willing to help if needed. If not, the Debian security team may be able to help.

In some cases, it is not possible to back-port a security fix, for example when large amounts of source code need to be modified or rewritten. If this happens, it may be necessary to move to a new upstream version. However, this is only done in extreme situations, and you must always coordinate that with the security team beforehand.

Related to this is another important guideline: always test your changes. If you have an exploit available, try it and see if it indeed succeeds on the unpatched package and fails on the fixed package. Test other, normal actions as well, as sometimes a security fix can break seemingly unrelated features in subtle ways.

Do NOT include any changes in your package which are not directly related to fixing the vulnerability. These will only need to be reverted, and this wastes time. If there are other bugs in your package that you would like to fix, make an upload to proposed-updates in the usual way, after the security advisory is issued. The security update mechanism is not a means for introducing changes to your package which would otherwise be rejected from the stable release, so please do not attempt to do this.

Review and test your changes as much as possible. Check the differences from the previous version repeatedly (interdiff from the patchutils package and debdiff from devscripts are useful tools for this, see debdiff).

Be sure to verify the following items:

• Target the right distribution in your debian/changelog: codename-security (e.g. buster-security). Do not target distribution-proposed-updates or stable!

• The upload should have urgency=high.

• Make descriptive, meaningful changelog entries. Others will rely on them to determine whether a particular bug was fixed. Add closes: statements for any Debian bugs filed. Always include an external reference, preferably a CVE identifier, so that it can be cross-referenced. However, if a CVE identifier has not yet been assigned, do not wait for it but continue the process. The identifier can be cross-referenced later.

• Make sure the version number is proper. It must be greater than the current package, but less than package versions in later distributions. If in doubt, test it with dpkg --compare-versions. Be careful not to re-use a version number that you have already used for a previous upload, or one that conflicts with a binNMU. The convention is to append +debXu1 (where X is the major release number), e.g. 1:2.4.3-4+deb10u1, of course increasing 1 for any subsequent uploads.

• Unless the upstream source has been uploaded to security.debian.org before (by a previous security update), build the upload with full upstream source (dpkg-buildpackage -sa). If there has been a previous upload to security.debian.org with the same upstream version, you may upload without upstream source (dpkg-buildpackage -sd).

• Be sure to use the exact same ``*.orig.tar.{gz,bz2,xz}`` as used in the normal archive, otherwise it is not possible to move the security fix into the main archives later.

• Build the package on a clean system which only has packages installed from the distribution you are building for. If you do not have such a system yourself, you can use a debian.org machine (see Debian machines) or setup a chroot (see pbuilder and debootstrap).

5.8.5.5. Uploading the fixed package

Do NOT upload a package to the security upload queue (on *.security.upload.debian.org) without prior authorization from the security team. If the package does not exactly meet the team’s requirements, it will cause many problems and delays in dealing with the unwanted upload.

Do NOT upload your fix to proposed-updates without coordinating with the security team. Packages from security.debian.org will be copied into the proposed-updates directory automatically. If a package with the same or a higher version number is already installed into the archive, the security update will be rejected by the archive system. That way, the stable distribution will end up without a security update for this package instead.

Once you have created and tested the new package and it has been approved by the security team, it needs to be uploaded so that it can be installed in the archives. For security uploads, the place to upload to is ftp://ftp.security.upload.debian.org/pub/SecurityUploadQueue/.

Once an upload to the security queue has been accepted, the package will automatically be built for all architectures and stored for verification by the security team.

Uploads that are waiting for acceptance or verification are only accessible by the security team. This is necessary since there might be fixes for security problems that cannot be disclosed yet.

If a member of the security team accepts a package, it will be installed on security.debian.org as well as proposed for the proper distribution-proposed-updates on ftp-master.debian.org.