1ANNOCHECK(1) RPM Development Tools ANNOCHECK(1)
2
3
4
6 annocheck - Analysing an application's compilation.
7
9 annocheck
10 [--help]
11 [--version]
12 [--verbose]
13 [--quiet]
14 [--ignore-unknown]
15 [--report-unknown]
16 [--debug-rpm=file]
17 [--dwarf-dir=dir]
18 [--prefix=text]
19 file...
20
21 annocheck
22 [--skip-bind-now]
23 [--skip-cf-protection]
24 [--skip-dynamic-segment]
25 [--skip-fortify]
26 [--skip-glibcxx-assertions]
27 [--skip-gnu-relro]
28 [--skip-gnu-stack]
29 [--skip-optimization]
30 [--skip-pic]
31 [--skip-pie]
32 [--skip-property-note]
33 [--skip-run-path]
34 [--skip-rwx-seg]
35 [--skip-short-enum]
36 [--skip-stack-clash]
37 [--skip-stack-prot]
38 [--skip-stack-realign]
39 [--skip-textrel]
40 [--skip-threads]
41 [--skip-writeable-got]
42 [--ignore-gaps]
43 [--disable-hardened]
44 [--enable-hardened]
45 file...
46
47 annocheck
48 [--disable-hardened]
49 --enable-builtby
50 [--all]
51 [--tool=name]
52 [--nottool=name]
53 file...
54
55 annocheck
56 [--disable-hardened]
57 --section-size=name
58 [--human]
59 file...
60
61 annocheck
62 --enable-timing
63 file...
64 [--sec]
65 [--usec]
66 [--nsec]
67
69 The annocheck program can analyse programs and report information about
70 them. It is designed to be modular, with a set of self-contained tools
71 providing the checking functionality. Currently the following tools
72 are implemented:
73
74 The annocheck program is able to scan inside rpm files and libraries.
75 It will automatically recurse into any directories that are specified
76 on the command line. In addition annocheck knows how to find debug
77 information held in separate debug files, and it will search for these
78 whenever it needs the resources that they contain.
79
80 New tools can be added to the annocheck framework by creating a new
81 source file and including it in the Makefile used to build annocheck.
82 The modular nature of annocheck means that nothing else needs to be
83 updated.
84
85 New tools must fill out a "struct checker" structure (defined in
86 annocheck.h) and they must define a constructor function that calls
87 "annocheck_add_checker" to register their presence at program start-up.
88
89 The annocheck program supports some generic command line options that
90 are used regardless of which tools are enabled.
91
92 "--debug-rpm=file"
93 Look in file for separate dwarf debug information.
94
95 "--dwarf-dir=dir"
96 Look in dir for separate dwarf debug information files.
97
98 "--help"
99 Display this message & exit.
100
101 "--report-unknown"
102 "--ignore-unknown"
103 Report file types not recognised by annocheck. The default
104 behaviour can be restored by the --ignore-unknown option.
105
106 "--prefix=text"
107 Include text in the output description.
108
109 "--quiet"
110 Do not print anything, just return an exit status.
111
112 "--verbose"
113 Produce informational messages whilst working. Repeat for more
114 information.
115
116 "--version"
117 Report the version of the tool and then exit.
118
119 The hardened tool checks that the specified files were compiled with
120 the required security hardening options, as outlined in the elf-policy
121 document. It runs a series of tests checking compilation options and
122 link time options. These tests are outlined below, along with the
123 command line option that can be used to disable each test.
124
125 New tests can be added to the hardened checker by adding an entry in
126 the tests array defined in hardened.c and then creating the necessary
127 code to support the test.
128
129 "BIND_NOW"
130 Lazy binding must not have been enabled via the linker option -z
131 now. Disabled by --skip-bind-now.
132
133 "Non executable stack"
134 The program must not have a stack in an executable region of
135 memory. Disabled by --skip-gnu-stack.
136
137 "Safe GOT relocations"
138 The relocations for the GOT table must be read only. Disabled by
139 --skip-writeable-got.
140
141 "No RWX segments."
142 No program segment should have all three of the read, write and
143 execute permission bits set. Disabled by --skip-rwx-seg.
144
145 "No text relocations"
146 The should be no relocations against executable code. Disabled by
147 --skip-textrel.
148
149 "Correct runpaths"
150 The runpath information used to locate shared libraries at runtime
151 must only include directories rooted at /usr. Disabled by
152 --skip-run-path.
153
154 "Missing annobin data"
155 The program must have been compiled with annobin notes enabled.
156 Disabled by --ignore-gaps.
157
158 "Strong stack protection"
159 The program must have been compiled with the
160 -fstack-protector-strong option enabled, and with
161 -D_FORTIFY_SOURCE=2 specified. It must also have been compiled at
162 at least optimization level 2. Disabled by --skip-stack-prot.
163
164 "Dynamic data present"
165 Dynamic executables must have a dynamic segment. Disabled by
166 --skip-dynamic-segment.
167
168 "Position Independent compilation"
169 Shared libraries must have been compiled with -fPIC or "-fPIE" but
170 not -static. This check can be disabled by --skip-pic.
171
172 Dynamic executables must have been compiled with -fPIE and linked
173 with -pie. This check can be disabled by --skip-pie.
174
175 "Safe exceptions"
176 Program which use exception handling must have been compiled with
177 -fexceptions enabled and with -D_GLIBCXX_ASSERTIONS specified.
178 Disabled by --skip-threads and/or --skip-glibcxx-assertions.
179
180 "Stack Clash protection"
181 If available the -fstack-clash-protection must have been used.
182 Disabled by --skip-stack-clash.
183
184 "Control Flow protection"
185 If available the -fcf-protection=full must have been used.
186 Disabled by --skip-cf-protection. If this option is disabled then
187 the check for GNU Property notes will also be disabled.
188
189 "Stack realignment"
190 For i686 binaries, the -mstackrealign option must have been
191 specified. Disabled by --skip-stack-realign.
192
193 "Source fortification"
194 The program must have been compiled with the -D_FORTIFY_SOURCE=2
195 command line option specified. Disabled by --skip-fortify.
196
197 "Optimization"
198 The program must have been compiled with at least -O2 optimization
199 enabled. Disabled by --skip-optimization.
200
201 "Read only relocations"
202 The program must not have any relocations that are held in a
203 writeable section. Disabled by --skip-gnu-relro.
204
205 "GNU Property Note"
206 For x86_64 binaries, check that a correctly formatted GNU Property
207 note is present. These notes are only generated with a program is
208 compiled with the -fcf-protection gcc option is enabled, so if
209 annocheck's --skip-cf-protection option is enabled then this test
210 will be skipped as well.
211
212 "Enum Size"
213 Check that the program makes consistent use of the -fshort-enum
214 option.
215
216 The tool does support a couple of other command line options as well:
217
218 "--enable-hardened"
219 Enable the tool if it was previously disabled. The option is the
220 default.
221
222 "--disable-hardened"
223 Disable the tool.
224
225 The built-by tool is disabled by default, but it can be enabled by the
226 command line option --enable-builtby. The tool checks the specified
227 files to see if any information is stored about how the file was built.
228
229 Since the hardening checker is enabled by default it may also be useful
230 to add the --disable-hardened option to the command line.
231
232 The tool supports a few command line options to customise its
233 behaviour:
234
235 "--all"
236 Report all builder identification strings. The tool has several
237 different heuristics for determining the builder. By default it
238 will report the information return by the first successful
239 heuristic. If the --all option is enabled then all successful
240 results will be returned.
241
242 "--tool=name"
243 This option can be used to restrict the output to only those files
244 which were built by a specific tool. This can be useful when
245 scanning a directory full of files searching for those built by a
246 particular compiler.
247
248 "--nottool=NAME"
249 This option can be used to restrict the output to only those files
250 which were not built by a specific tool. This can be useful when
251 scanning a directory full of files searching for those that were
252 not built by a particular compiler.
253
254 The section-size tool records the size of named sections within a list
255 of files and then reports the accumulated size at the end. Since it is
256 part of the annocheck framework, it is able to handle directories and
257 rpms files as well as ordinary binary files.
258
259 The --section-size=name option enables the tool and tells it to record
260 the size of section name. The option can be repeated multiple times to
261 record the sizes of multiple sections. It may also be useful to add
262 the --disable-hardened option to the command line as otherwise the
263 security hardening will be run at the same time.
264
265 If the --verbose option is enabled, then the tool will also report the
266 size of the named section(s) in each file it encounters. If the
267 --human option is enabled then sizes will be rounded down to the
268 nearest byte, kibibyte, mebibyte or gibibyte, as appropriate.
269
270 The timing tool reports on the time taken by other tools to scan the
271 list of files. The tool is disabled by default, but it can be enabled
272 by the command line option --enable-timing.
273
274 By default the tool will report times in microseconds, but you can
275 change this to reporting in seconds with the --sec or in nanoseconds
276 with the --nsec. The default can be restored with the --usec option.
277
280 Copyright (c) 2018 Red Hat.
281
282 Permission is granted to copy, distribute and/or modify this document
283 under the terms of the GNU Free Documentation License, Version 1.3 or
284 any later version published by the Free Software Foundation; with no
285 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
286 Texts. A copy of the license is included in the section entitled "GNU
287 Free Documentation License".
288
289
290
291annobin-1 2018-10-10 ANNOCHECK(1)