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