==========
CVE triage
==========

The Security and LTS teams cooperate to process the flow of new
security issues. Each is assigned a CVE number, so we often call this
"CVE triage".

.. _debian-security-tracker:

~~~~~~~~~~~~~~~~~~~~~~~
Debian Security Tracker
~~~~~~~~~~~~~~~~~~~~~~~

The Debian LTS team makes extensive use of the Debian Security
Tracker.  This is a database of all known security issues in Debian.

 * `Git repository <https://salsa.debian.org/security-tracker-team/>`_
   at Salsa. This is the central data and tooling. DDs automatically
   have commit access, others may `request
   <https://lts-team.pages.debian.net/wiki/Contact.html>`_ membership.
 * `Documentation <https://security-team.debian.org/security_tracker.html>`_:
   **important**, please do read, to understand the triage and
   update logic.
 * `Web interface <https://security-tracker.debian.org/tracker/>`_:
   reflects the changes every 30mn or so.
 * `Commit notifications
   <https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/debian-security-tracker-commits>`_.
 * `debian-security-tracker@l.d.o
   <https://lists.debian.org/debian-security-tracker/>`_: not useful
   in the context of LTS.
 * `CVE history <https://salsa.debian.org/lts-team/cvehist>`_: Git
   rewrite, 1 file per CVE, allowing fast git log and git blame;
   updated 4x/day by Freexian infrastructure (zeus)

LTS developers must keep the security tracker up-to-date. In
particular:

 * `data/CVE/list <#cve-status-list-for-lts>`_: large, single-file
   text-base database of all current and past CVEs, for non-LTS and
   LTS Debian dists. Includes links to related bug reports, upstream
   commits, fixing versions, exploits, and any information useful to
   the Security and LTS teams.

 * :ref:`data/dla-needed.txt <claim-package>`: LTS work queue.

 * :ref:`data/DLA/list <claim-dla>`: semi-automated reference list of
   DLAs with affected packages and CVEs.

To work on the security tracker, clone the repository.
::

 git clone git@salsa.debian.org:security-tracker-team/security-tracker.git
 cd security-tracker/
 sudo apt install jq python3-apt
 bin/setup-repo

.. note::

  The git repository is heavy and a first normal clone will easily
  take an hour. For occasional work, a shallow clone (with ``--depth
  1``) will only take a few minutes.

.. attention::

  Please run ``bin/setup-repo``, which installs a pre-commit hook to
  validate syntax (and avoid breaking web interface updates).

.. _cve-status-list:

~~~~~~~~~~~~~~~~~~~~~~~
CVE status list for LTS
~~~~~~~~~~~~~~~~~~~~~~~

.. important ::

  The reference documentation for ``data/CVE/list`` classification
  remains the `security tracker documentation
  <https://security-team.debian.org/security_tracker.html>`_. Do read
  it first.

There are some differences between LTS and Debian Security triaging:
 * LTS currently does not have any point releases.
 * The LTS Team prepares the vast majority of updates (few maintainers
   want to help with the LTS fixes).

In the context of LTS (currently ``[bullseye]``), here's a break-down of
each possible CVE status:

 * ``<postponed>`` when it's a minor issue that is not critical to
   address immediately, but may be fixed later.
 * ``<ignored>`` when there is a valid/strong reason *not* to fix it
   (e.g. it is only in sources neither compiled nor shipped in binary
   packages; it's non-critical and too long to backport or there's a
   high risk of regression; it's non-critical and requires an API
   change affecting reverse dependencies).
 * ``<not-affected>`` when LTS version is not affected (e.g. because
   the vulnerable code was introduced later). This needs solid
   evidence. Good practice: find and reference the related commit (in
   "NOTE: Introduced by ..."), because vulnerable code often gets
   moved around between upstream releases. If all versions are
   unaffected, tag at the package-level (e.g. ``- python3.7
   <not-affected>``, without ``[bullseye]``).
 * ``<end-of-life>`` when the package is not supported in the LTS
   release (bullseye unsupported packages are listed at
   `debian-security-support:security-support.deb11
   <https://salsa.debian.org/debian/debian-security-support/blob/master/security-support.deb11>`_). If
   needed, update that file and add debian-security-support to
   ``dla-needed.txt`` -- cf. `debian-security-support:README.source
   <https://salsa.debian.org/debian/debian-security-support/-/blob/master/debian/README.source>`_.)
 * *specific version*: any later version is considered fixed. Normally
   not used, in favor of the automated ``{DLA-XXXX-X}`` tags.
 * ``<undetermined>``: rare, set at the package level by secteam, we
   don't use this tag, but you can help find more information.

.. attention::

  <no-dsa> is often used by the Security Team to indicate a first
  level of triage: no immediate DSA (aka package update), *but* maybe
  a delayed fix in the next point release, or just deferring to the
  maintainer [`doc <https://security-team.debian.org/triage.html>`_].

  We decided to **stop using <no-dsa>** as of 2024-03, due to its
  vagueness and ambiguity in the context of LTS, in favor of its
  `sub-states
  <https://security-team.debian.org/security_tracker.html#issues-not-warranting-a-security-advisory>`_
  <postponed> and <ignored>. Old no-dsa LTS entries can be considered
  <postponed>.

.. note::

  LTS triage normally tags dist-level (bullseye) entries, while higher,
  package-level tagging is reserved to secteam. We only tag at the
  package level for LTS-specific packages. Contact secteam if you have
  a recommendation for other package-level entries.

`Severity levels
<https://security-team.debian.org/security_tracker.html#severity-levels>`_
are normally set by the Security Team, coordinate with them if
needed. A couple notes:

 * "minor": the Security Team tends to mark non-Internet-facing
   vulnerabilities as ``<some tag> (Minor)`` with default severity,
   because those are not directly exploitable. However they allow
   greater penetration when the attacker put one foot in the victim's
   infrastructure and are better fixed in the long run.
 * unimportant: caution, makes the CVE disappear from all our tooling.
 * other states: rarely used in practice.

Hint at your thought process through a comment or a NOTE:

.. code-block:: text

  [bullseye] - package <postponed> (Minor issue, local OOM DoS)

  NOTE: PoC doesn't trigger in bullseye.

You may expand your rationale in the Git commit message, this helps
secteam review your changes, but makes it harder for others to notice
or search it later.

.. _cve-bts:

~~~
BTS
~~~
If a vulnerability bug is unfixed in unstable and not reported in the
`BTS <https://wiki.debian.org/BTS>`_ yet, you can use `bin/report-vuln
<https://salsa.debian.org/security-tracker-team/security-tracker/raw/master/bin/report-vuln>`_
to open it. Discussions about severity and urgency are best done in
the bug report since all involved parties (LTS team, security team and
package maintainers) can get involved. Maintainers often know best how
severe an issue is and if an immediate update is actually needed.