Release 0.09
[blhc/blhc.git] / README
1 README
2 ======
3
4 blhc (build log hardening check) is a small tool which checks build logs for
5 missing hardening flags. It's licensed under the GPL 3 or later.
6
7 Hardening flags enable additional security features in the compiler to prevent
8 e.g. stack overflows, format string vulnerabilities, GOT overwrites, etc.
9
10 Because most build systems are quite complicated there are many places where
11 compiler flags from the environment might be ignored. The parser verifies that
12 all compiler commands use the correct hardening flags and thus all hardening
13 features are correctly used.
14
15 It's designed to check build logs generated by Debian's dpkg-buildpackage (or
16 tools using dpkg-buildpackage like pbuilder or sbuild (which is used for the
17 official buildd build logs)) to help maintainers detect missing hardening
18 flags in their packages.
19
20 At the moment it works only on Debian and derivatives but it should be easily
21 extendable to other systems as well. Patches are welcome.
22
23 Only gcc is detected as compiler at the moment. If other compilers support
24 hardening flags as well, please report them.
25
26 For more information about hardening flags have a look at [1].
27
28 [1]: https://wiki.debian.org/Hardening
29
30
31 DEPENDENCIES
32 ------------
33
34 - Perl
35   - Dpkg::Arch
36   - Dpkg::Version
37   - Term::ANSIColor >= 2.01
38     Bundled with perl. A recent version is only necessary for build logs with
39     ANSI colors which is rare, blhc works fine without if the build log
40     doesn't use colors. Not required for buildd mode.
41
42
43 USAGE
44 -----
45
46     blhc path/to/log/file
47
48 blhc can be run directly from the source tree (`bin/blhc`) or copied anywhere
49 on the system. It doesn't have to be explicitly installed. To read the man
50 page use `perldoc bin/blhc`.
51
52 If there's no output, no flags are missing and the build log is fine.
53
54 For more examples see the man page.
55
56
57 CHECKS
58 ------
59
60 blhc checks all compiler lines (lines matching `gcc`) for hardening flags
61 (same as set by `dpkg-buildflags`). If a compiler flag is missing a warning
62 with the missing flags is printed.
63
64 Consider the following compiler line:
65
66     gcc -g -O2 -o test test.c
67
68 blhc generates the following warnings because all hardening flags are missing:
69
70     CFLAGS missing (-fstack-protector-strong -Wformat -Werror=format-security): gcc -g -O2 -o test test.c
71     CPPFLAGS missing (-D_FORTIFY_SOURCE=2): gcc -g -O2 -o test test.c
72     LDFLAGS missing (-Wl,-z,relro): gcc -g -O2 -o test test.c
73
74 Preprocessing, linking and compiling is automatically detected:
75
76     gcc -MM test.c > test.d
77     gcc -E test.c
78     gcc -o test test.o
79
80     CPPFLAGS missing (-D_FORTIFY_SOURCE=2): gcc -E test.c
81     LDFLAGS missing (-Wl,-z,relro): gcc -o test test.o
82
83 blhc differentiates the following flags:
84
85     - CPPFLAGS: preprocessor flags
86     - CFLAGS:   C compiler flags
87     - CXXFLAGS: C++ compiler flags
88     - LDFLAGS:  linker flags
89
90 Both '-O2' and '-O3' are recognized as valid, even though only '-O2' is
91 printed in warnings.
92
93 It handles all file extensions as documented by gcc regarding preprocessing,
94 linking, compiling.
95
96 The architecture of the build log is automatically detected by looking for the
97 following line (output of dpkg-buildpackage):
98
99     dpkg-buildpackage: host architecture <architecture>
100
101 The available hardening flags are adapted to the architecture because some
102 architectures don't support certain hardening options.
103
104 Some checks check the build dependencies for certain packages. The following
105 lines are used to get the build dependencies. The first two are used in buildd
106 build logs (the second was used in older logs), the third by pbuilder logs,
107 all are detected:
108
109     Filtered Buildd-Depends: ...
110     Build-Depends: ...
111     Depends: ...
112
113
114 LIMITATIONS
115 -----------
116
117 The build log must contain the following line which marks the beginning of the
118 real compile process (output of dpkg-buildpackage):
119
120     dpkg-buildpackage: ...
121
122 If it's not present no compiler commands are detected. In case you don't use
123 dpkp-buildpackage but still want to check a build log, adding it as first line
124 should work fine.
125
126 To prevent false positives when checking debug builds, compiler lines
127 containing '-OO' or '-Og' are considered debug builds and are not checked for
128 '-O2', even though fortification doesn't work without '-O2'.
129
130 The following non-verbose builds can't be detected:
131
132     gcc -o test
133
134 This is not detected because `test` has no file extension. A file extension is
135 required on a compiler line to prevent many false positives. As the build will
136 most likely contain other non-verbose build commands (e.g. `gcc test.c`) which
137 are correctly detected as non-verbose this shouldn't be a problem.
138
139 Some CMake non-verbose linker commands are also not correctly detected at the
140 moment.
141
142 blhc still creates a few false positives. Patches to fix them are very welcome
143 as long as they won't cause any false negatives.
144
145
146 BUILDD MODE
147 -----------
148
149 Buildd mode is enabled if '--buildd' is used. It's designed to check build
150 logs from Debian's buildds.
151
152 Instead of normal warning messages only tags are printed at the end of the
153 check. See the man page for possible tags.
154
155
156 BUGS
157 ----
158
159 If you find any bugs not mentioned in this document please report them to
160 <simon@ruderich.org> with blhc in the subject.
161
162
163 AUTHORS
164 -------
165
166 Written by Simon Ruderich <simon@ruderich.org>.
167
168 Thanks to Bernhard R. Link <brlink@debian.org> and Jaria Alto
169 <jari.aalto@cante.net> for their valuable input and suggestions.
170
171
172 LICENSE
173 -------
174
175 blhc is licensed under GPL version 3 or later.
176
177 Copyright (C) 2012-2018  Simon Ruderich
178
179 This program is free software: you can redistribute it and/or modify
180 it under the terms of the GNU General Public License as published by
181 the Free Software Foundation, either version 3 of the License, or
182 (at your option) any later version.
183
184 This program is distributed in the hope that it will be useful,
185 but WITHOUT ANY WARRANTY; without even the implied warranty of
186 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
187 GNU General Public License for more details.
188
189 You should have received a copy of the GNU General Public License
190 along with this program.  If not, see <http://www.gnu.org/licenses/>.
191
192 // vim: ft=asciidoc