---
title: Chapter 12. Security
prev: books/porters-handbook/upgrading
next: books/porters-handbook/porting-dads
description: Security instructions when making a FreeBSD Port
tags: ["security", "porting", "ports", "VuXML"]
showBookMenu: true
weight: 12
params:
  path: "/books/porters-handbook/security/"
---

[[security]]
= Security
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumoffset: 12
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/porters-handbook/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[security-intro]]
== Why Security is So Important

Bugs are occasionally introduced to the software.
Arguably, the most dangerous of them are those opening security vulnerabilities.
From the technical viewpoint, such vulnerabilities are to be closed by exterminating the bugs that caused them.
However, the policies for handling mere bugs and security vulnerabilities are very different.

A typical small bug affects only those users who have enabled some combination of options triggering the bug.
The developer will eventually release a patch followed by a new version of the software,
free of the bug, but the majority of users will not take the trouble of upgrading immediately because the bug has never vexed them.
A critical bug that may cause data loss represents a graver issue.
Nevertheless, prudent users know that a lot of possible accidents, besides software bugs, are likely to lead to data loss, and so they make backups of important data; in addition, a critical bug will be discovered really soon.

A security vulnerability is all different.
First, it may remain unnoticed for years because often it does not cause software malfunction.
Second, a malicious party can use it to gain unauthorized access to a vulnerable system, to destroy or alter sensitive data;
and in the worst case the user will not even notice the harm caused.
Third, exposing a vulnerable system often assists attackers to break into other systems that could not be compromised otherwise.
Therefore closing a vulnerability alone is not enough: notify the audience of it in the most clear and comprehensive manner,
which will allow them to evaluate the danger and take appropriate action.

[[security-fix]]
== Fixing Security Vulnerabilities

While on the subject of ports and packages, a security vulnerability may initially appear in the original distribution or in the port files.
In the former case, the original software developer is likely to release a patch or a new version instantly.
Update the port promptly with respect to the author's fix.
If the fix is delayed for some reason, either crossref:porting-dads[dads-noinstall,mark the port as `FORBIDDEN`] or introduce a patch file to the port.
In the case of a vulnerable port, just fix the port as soon as possible.
In either case, follow crossref:port-upgrading[port-upgrading,the standard procedure for submitting changes] unless having rights to commit it directly to the ports tree.

[IMPORTANT]
====
Being a ports committer is not enough to commit to an arbitrary port.
Remember that ports usually have maintainers, who must be respected.
====

Please make sure that the port's revision is bumped as soon as the vulnerability has been closed.
That is how the users who upgrade installed packages on a regular basis will see they need to run an update.
Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one.
Bump `PORTREVISION` unless `DISTVERSION` has changed in the course of correcting the vulnerability.
That is, bump `PORTREVISION` if adding a patch file to the port, but do not bump it if updating the port to the latest software version and thus already touched `DISTVERSION`.
Please refer to the crossref:makefiles[makefile-naming-revepoch,corresponding section] for more information.

[[security-notify]]
== Keeping the Community Informed

[[security-notify-vuxml-db]]
=== The VuXML Database

A very important and urgent step to take as early as possible after a security vulnerability is discovered is to notify the community of port users about the jeopardy.
Such a notification serves two purposes.
First, if the danger is really severe it will be wise to apply an instant workaround.
For example, stop the affected network service or even deinstall the port completely until the vulnerability is closed.
Second, a lot of users tend to upgrade installed packages only occasionally.
They will know from the notification that they _must_ update the package without delay as soon as a corrected version is available.

Given the huge number of ports in the tree, a security advisory cannot be issued on each incident without creating a flood and losing the attention of the audience when it comes to really serious matters.
Therefore security vulnerabilities found in ports are recorded in https://vuxml.freebsd.org/[the FreeBSD VuXML database], which both Ports Security Team members and Security Team members also monitor for issues requiring their intervention.

Committers can update the VuXML database themselves, assisting the Security Team and delivering crucial information to the community more quickly.
Port maintainers can create VuXML entries for their vulnerable ports and file bugs requesting security/vuxml updates.
Those who are not committers or have discovered an exceptionally severe vulnerability should not hesitate to contact the link:https://www.freebsd.org/administration.html#t-ports-secteam[FreeBSD Ports Security Team] first.
If needed, also contact the link:https://www.freebsd.org/administration.html#t-secteam[FreeBSD Security Team] as described on the link:https://www.freebsd.org/security/#reporting[FreeBSD Security Information] page.

The VuXML database is an XML document.
Its source file [.filename]#vuln.xml# is kept right inside the port package:security/vuxml[].
Therefore the file's full pathname will be [.filename]#PORTSDIR/security/vuxml/vuln.xml#.
Each time a security vulnerability is discovered in a port, please add an entry for it to that file.
Until familiar with VuXML, the best thing to do is to find an existing entry fitting the case at hand, then copy it and use it as a template.

[[security-notify-vuxml-intro]]
=== A Short Introduction to VuXML

The full-blown XML format is complex, and far beyond the scope of this book.
However, to gain basic insight on the structure of a VuXML entry only the notion of tags is needed.
XML tag names are enclosed in angle brackets.
Each opening <tag> must have a matching closing </tag>.
Tags may be nested.
If nesting, the inner tags must be closed before the outer ones. There is a hierarchy of tags, that is, more complex rules of nesting them.
This is similar to HTML.
The major difference is that XML is e__X__tensible, that is, based on defining custom tags.
Due to its intrinsic structure XML puts otherwise amorphous data into shape.
VuXML is particularly tailored to mark up descriptions of security vulnerabilities.

Now consider a realistic VuXML entry:

[.programlisting]
....
<vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <.>
  <topic>Several vulnerabilities found in Foo</topic> <.>
  <affects>
    <package>
      <name>foo</name> <.>
      <name>foo-devel</name>
      <name>ja-foo</name>
      <range><ge>1.6</ge><lt>1.9</lt></range> <.>
      <range><ge>2.*</ge><lt>2.4_1</lt></range>
      <range><eq>3.0b1</eq></range>
    </package>
    <package>
      <name>openfoo</name> <.>
      <range><lt>1.10_7</lt></range> <.>
      <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range>
    </package>
  </affects>
  <description>
    <body xmlns="http://www.w3.org/1999/xhtml">
      <p>J. Random Hacker reports:</p> <.>
      <blockquote
        cite="http://j.r.hacker.com/advisories/1">
        <p>Several issues in the Foo software may be exploited
          via carefully crafted QUUX requests.  These requests will
          permit the injection of Bar code, mumble theft, and the
          readability of the Foo administrator account.</p>
      </blockquote>
    </body>
  </description>
  <references> <.>
    <freebsdsa>SA-10:75.foo</freebsdsa> <.>
    <freebsdpr>ports/987654</freebsdpr> <.>
    <cvename>CVE-2023-48795</cvename> <.>
    <certvu>740169</certvu> <.>
    <uscertta>SA10-99A</uscertta> <.>
    <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <.>
    <url>http://j.r.hacker.com/advisories/1</url> <.>
  </references>
  <dates>
    <discovery>2010-05-25</discovery> <.>
    <entry>2010-07-13</entry> <.>
    <modified>2010-09-17</modified> <.>
  </dates>
</vuln>
....

The tag names are supposed to be self-explanatory so we shall take a closer look only at fields which needs to be filled in:

<.> This is the top-level tag of a VuXML entry. It has a mandatory attribute, `vid`, specifying a universally unique identifier (UUID) for this entry (in quotes). Generate a UUID for each new VuXML entry (and do not forget to substitute it for the template UUID unless writing the entry from scratch).
Use man:uuidgen[1] to generate a VuXML UUID.

<.> This is a one-line description of the issue found.

<.> The names of packages affected are listed there. Multiple names can be given since several packages may be based on a single master port or software product. This may include stable and development branches, localized versions, and slave ports featuring different choices of important build-time configuration options.

<.> Affected versions of the package(s) are specified there as one or more ranges using a combination of `<lt>`, `<le>`, `<eq>`, `<ge>`, and `<gt>` elements. Check that the version ranges given do not overlap. +
In a range specification, `\*` (asterisk) denotes the smallest version number. In particular, `2.*` is less than `2.a`. Therefore an asterisk may be used for a range to match all possible `alpha`, `beta`, and `RC` versions. For instance, `<ge>2.*</ge><lt>3.*</lt>` will selectively match every `2.x` version while `<ge>2.0</ge><lt>3.0</lt>` will not since the latter misses `2.r3` and matches `3.b`. +
The above example specifies that affected are versions `1.6` and up to but not including `1.9`, versions `2.x` before `2.4_1`, and version `3.0b1`.

<.> Several related package groups (essentially, ports) can be listed in the `<affected>` section. This can be used if several software products (say FooBar, FreeBar and OpenBar) grow from the same code base and still share its bugs and vulnerabilities. Note the difference from listing multiple names within a single <package> section.

<.> The version ranges have to allow for `PORTEPOCH` and `PORTREVISION` if applicable. Please remember that according to the collation rules, a version with a non-zero `PORTEPOCH` is greater than any version without `PORTEPOCH`, for example, `3.0,1` is greater than `3.1` or even than `8.9`.

<.> This is a summary of the issue. XHTML is used in this field. At least enclosing `<p>` and `</p>` has to appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please.

<.> This section contains references to relevant documents. As many references as apply are encouraged.

<.> This is a https://www.freebsd.org/security/#adv[FreeBSD security advisory].

<.> This is a https://www.freebsd.org/support/[FreeBSD problem report].

<.> This is a https://cve.mitre.org/[MITRE CVE] identifier.

<.> This is a https://www.kb.cert.org/vuls/[US-CERT] vulnerability note.

<.> This is a https://www.cisa.gov/news-events/cybersecurity-advisories[US-CERT] Technical Cyber Security Alert.

<.> This is a URL to an archived posting in a mailing list. The attribute `msgid` is optional and may specify the message ID of the posting.

<.> This is a generic URL. Only it if none of the other reference categories apply.

<.> This is the date when the issue was disclosed (_YYYY-MM-DD_).

<.> This is the date when the entry was added (_YYYY-MM-DD_).

<.> This is the date when any information in the entry was last modified (_YYYY-MM-DD_). New entries must not include this field. Add it when editing an existing entry.

[[security-notify-vuxml-testing]]
=== Testing Changes to the VuXML Database

This example describes a new entry for a vulnerability in the package `dropbear` that has been fixed in version `dropbear-2013.59`.

As a prerequisite, install a fresh version of package:security/vuxml[] port.

First, check whether there already is an entry for this vulnerability.
If there were such an entry, it would match the previous version of the package, `2013.58`:

[source,shell]
....
% pkg audit dropbear-2013.58
....

If there is none found, add a new entry for this vulnerability.

[source,shell]
....
% cd ${PORTSDIR}/security/vuxml
% make newentry
....

If the vulnerability has a https://cve.mitre.org/[MITRE CVE] identifier, the
following command can be used instead:

[source,shell]
....
% cd ${PORTSDIR}/security/vuxml
% make newentry CVE_ID=CVE-YYYY-XXXXX
....

where `CVE-YYYYY-XXXX` is a valid CVE identifier.

If the vulnerability is a FreeBSD Security Advisory, the
following command can be used instead:

[source,shell]
....
% cd ${PORTSDIR}/security/vuxml
% make newentry SA_ID=FreeBSD-SA-YY-XXXXXX.asc
....

where `FreeBSD-SA-YY-XXXXXX.asc` is a published https://www.freebsd.org/security/advisories/[FreeBSD Security Advisory].

Verify its syntax and formatting:

[source,shell]
....
% make validate
....

The previous command generates the [.filename]#vuln-flat.xml# file.
It can also
be generated with:

[source,shell]
....
% make vuln-flat.xml
....

[NOTE]
====
At least one of these packages needs to be installed: package:textproc/libxml2[], package:textproc/jade[].
====

Verify that the `<affected>` section of the entry will match the correct packages:

[source,shell]
....
% pkg audit -f ${PORTSDIR}/security/vuxml/vuln-flat.xml dropbear-2013.58
....

Make sure that the entry produces no spurious matches in the output.

Now check whether the right package versions are matched by the entry:

[source,shell]
....
% pkg audit -f ${PORTSDIR}/security/vuxml/vuln-flat.xml dropbear-2013.58 dropbear-2013.59
dropbear-2012.58 is vulnerable:
dropbear -- exposure of sensitive information, DoS
CVE: CVE-2013-4434
CVE: CVE-2013-4421
WWW: https://portaudit.FreeBSD.org/8c9b48d1-3715-11e3-a624-00262d8b701d.html

1 problem(s) in the installed packages found.
....

The former version matches while the latter one does not.

[[security-xcheck-vuxml]]
=== VuXML new entry checklist

* Check the name of the port.
Sometimes the upstream project name is not exactly the same as the port name.
* Add all flavors.
When a port has flavors all the package names need to be added as a `<package>` in
the entry.
Use the following script to generate all flavored package names:
+
[source,shell]
....
% for flavor in $(make -V FLAVORS); do FLAVOR="${flavor}" make -VPKGNAME;done
....
+
* Check if the port has `PORTEPOCH`.
The above script snippet helps with that.
If the port uses `PORTEPOCH` it is mandatory to add it to the `<range>` tag.
* Double check ranges.
In the case of ranges limited on both sides, make sure that the `<ge>` and
`<lt>` elements are inside the same `<range>` tag.
Otherwise the entry might end up defining an overlapping range.
* Cross-check derivatives.
Check whether derivatives or forks of the project included in the ports tree are also affected.
For example, if a vulnerability is discovered in package:www/firefox[], assess
whether derivatives like package:www/librewolf[], package:www/waterfox[] or
other similar projects share the same vulnerability.
Include all affected derivatives in the VuXML entry, ensuring that users of these ports are informed.
Also check if there are Linux versions of the same port in the tree.
For instance, package:databases/sqlite3[] vulnerabilities most likely affect packages like
package:databases/linux-c7-sqlite3[] too.
* Do not commit an entry without running `make validate` first.
