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