aboutsummaryrefslogtreecommitdiff
path: root/0.4.0/doc/doc_security_advisories.doxygen
blob: 1f290f898121c4af4527121022eaef8f3f32c094 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
/* vim: set ft=cpp tw=80 sw=4 et spell spelllang=en : */

/**
\page SecurityAdvisoriesSpecs Handling of Security Advisories

\version 1
\author Danny van Dyk <kugelfang@gentoo.org>
\author Stefan Cornelius <dercorny@gentoo.org>


\section SecurityAdvisoriesSpecsAbstract Abstract

This specification describes how security advisory files should be named,
stored, structured and handled by Paludis.


\section SecurityAdvisoriesSpecsNaming Naming

The format of file names shall be
\code
    advisory-YYYYMM-XX.conf
\endcode
where XX is a unique ID that is increased with every GLSA in the month and
YYYYMM is the usual date notation.


\section SecurityAdvisoriesSpecsStorage Storage

Security advisories shall be stored as text files in
\code
    ${repo}/metadata/security
\endcode
by default. Files within subdirectories shall not be parsed by Paludis. However,
the user can change this path in the repository's configuration file. The key's
name shall be <code>securitydir</code>.

Once tree wide Manifest support (aka as Manifest2 support) will be implemented,
all advisories should be listed by a Manifest file and checked against this
manifest before parsing them.


\section SecurityAdvisoriesSpecsStructure Structure

The file format shall consist of a RFC 822 style header and a trailing text
body. This document describes specification <code>0</code>. The following keys shall be
understood by Paludis:

The following keys are mandatory and must be unique in the advisory.
Paludis shall throw an exception otherwise.

<table>
  <tr>
    <td>Id</td>
    <td>Unique identifier of this advisory. Must be in <code>YYYYMM-XX</code> format and
    reflect the suffix of the advisory's file name.</td>
  </tr>
  <tr>
    <td>Title</td>
    <td>A string that describes the kind of vulnerability indicated by the advisory.</td>
  </tr>
  <tr>
    <td>Access</td>
    <td>Describes if if the vulnerability can be exploited by <code>local</code> or
    <code>remote</code> users.</td>
  </tr>
  <tr>
    <td>Last-Modified</td>
    <td>A date string that describes when the advisory was changed.</td>
  </tr>
  <tr>
    <td>Revision</td>
    <td>The advisory's revision number. It must start with <code>1.0</code> and should be
    increased by <code>0.1</code> whenever the advisory's metadata was changed
    substantially.</td>
  <tr>
    <td>Severity</td>
    <td>The severity of the vulnerabilities described by the advisory.
    Supported values are <code>high</code>, <code>normal</code> and <code>low</code>.</td>
  </tr>
  <tr>
    <td>Spec-Version</td>
    <td>The version of the specification that the advisory applies to should be
    referenced here. As of this specification, the only valid value is <code>1</code>.</td>
  </tr>
</table>

\note The following keys can be specified more than once.

<table>
  <tr>
    <td>Affected</td>
    <td>A string of one dependency atom or two ranged dependency atoms. When two
    dependency atoms are given, their intersection must not describe and empty
    set of packages.</td>
  </tr>
  <tr>
    <td>Bug-Id</td>
    <td>Identifier of a bug report that is associated with this advisory.\n

    Must be in format <code>DISTRO#YY</code>, where <code>DISTRO</code> is a unique string
    describing the distribution that the bug report is filed against and <code>YY</code>
    is the bug's local identifier.

    There is no restriction on the values of <code>DISTRO</code> besides the uniqueness,
    but each used distribution identifier should be listed along a short
    description and/or URL of the associated bug tracker in the text file
\code
        ${repo}/metadata/security/bugtracker
\endcode </td>
  </tr>
  <tr>
    <td>CVE</td>
    <td>A string of one CVE IDs in the format <code>CVE-XXXX-XXXX</code>. Historically,
    there have been CVE references prefixed by CAN instead of CVE. These
    are explicitly permitted by this specification, but are to be treated as
    deprecated.</td>
  </tr>
  <tr>
    <td>Reference</td>
    <td>URL to a public web-based advisory, announcement or (possibly) exploit.
    Optionally, a descriptive string can be prepended.</td>
  </tr>
  <tr>
    <td>Restart</td>
    <td>The name of a service or init script that should be restarted by
    Paludis after the vulnerable package has been replaced.</td>
  </tr>
  <tr>
    <td>Unaffected</td>
    <td>A string of one dependency atom or two ranged dependency atoms. When two
    dependency atoms are given, their intersection must not describe and empty
    set of packages.</td>
  </tr>
</table>

The text body shall be separated from the aforementioned header by an empty
line. The contents of the text body is not subject of this advisory.

Paludis shall provide an eselect module to display advisory texts.


\section Handling Handling

Paludis will parse security advisories when it builds the built-in
package set <code>security</code> or when it is called with command line option
<code>--list-vulnerabilities</code>. The later shall support all modifiers, which are
respected by other <code>--list</code> actions.

All packages that match the contents of at least one <code>Affected</code> item and that
do not match any <code>Unaffected</code> item will be treated as vulnerable. Paludis shall
then search for a package in the same slot that matches at least one
<code>Unaffected</code> items and does not match any <code>Affected</code> item. If several
package versions match this criterion, Paludis shall select the highest version.
*/