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