summaryrefslogtreecommitdiffstats
path: root/doc/python-format.txt
blob: ef6711fc8b36f3b4190ecda7f08c87c98ed064a8 (plain) (blame)
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
NOTE: THIS DOES NOT DESCRIBE THE CURRENT IMPLEMENTATION

# Layout of major internal data structures

Most data structures use named tuples, as provided by
collections.namedtuples.

Due to the way unpickling works, you need to import the "parsers"
package.

The data structures described here are supposed to be fairly stable,
except for the addition of additional attributes and changes in the
internal order of named tuples (so you really should not rely on
that).

# Source packages

The dictionary returned by sectracker.parsers.sourcepackages()
contains the source package name as the key, and as values named
tuples with the following field:

* pkg.name: the name of the source package

* pkg.version: the source version

* pkg.binary: a list of binary package names compiled from this source
  package

# Individual bug information

The data/*/list files are parsed as lists of bugs.  A line which does
not start with whitespace is called a "header", and the following
intended lines are called "annotations".

The top-level named tuple contains two elements:

* list: the list of bug objects (see below)

* messages: the list of messages from the parser (see below)

All lists are sorted by file position of the contained objects.

## bug objects

* bug.file: path to the file containing this bug

* bug.header: header object (see below)

* bug.annotations: list of all annotations of this bug (see below)

## header objects

* header.line: line number

* header.name: bug name (auto-generated for temporary issues)

* header.description: string, can be empty or None

## message objects

* msg.file: file name

* msg.line: line number

* msg.level: "error" or "warning"

* msg.contents: free-text message

## Errors 

## annotation objects

All annotation objects have these fields:

* ann.line: the line number

* ann.type: code value to determine the  structure

Additional fields are described below, depending on the ann.type
value.

### types "NOT-FOR-US", "NOTE", "TODO"

* ann.description: user-supplied string

### types "RESERVED", "REJECTED"

These act just as flags; no additional data is present.

### type "xref"

* ann.bugs: list of bugs being referenced

### type "package"

* ann.release: applicable release, or None for unstable

* ann.package: name of the package

* ann.kind: one of "fixed" (version was supplied), "unfixed", "removed",
  "itp", "no-dsa", "not-affected", "undetermined"

* ann.version: fixed version number, or "None" for unfixed/not applicable

* ann.urgency: one of None, undetermined, low, medium, high

* ann.debian_bugs: set of numbers of Debian bugs

* ann.description: free-text information, or None if not applicable

# Derived vulnerability information

sectracker.analyzers.fixedversions() computes fixed versions for
bug/package pairs.  These are returned in a list of vulnerability
objects:

* vuln.bug: name of the bug (potentially auto-generated)

* vuln.package: name of the package

* vuln.fixed: fixed version in unstable (a string), or None (no fix
  available) or True (all versions fixed)

* vuln.fixed_other: a tuple, containing other fixed versions (which
  are less than the unfixed unstable version, but nevertheless known
  not to be vulnerable)

In itself, this data is not very illuminating, but comparision with
other information sources can be used to detect vulnerable installed
packages, generate bug and distribution overview pages etc.

This computation is in a separate pass because packages are sometimes
propagated between releases/distributions in the Debian archive.  The
returned data only contains plain versions, disregarding the source,
so further processing can correctly handle package propagation (in the
sense that if a bug was fixed in one place, all propagated copies are
also fixed).

© 2014-2024 Faster IT GmbH | imprint | privacy policy