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 --param=ssp-buffer-size=4 -Wformat -Wformat-security -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 (Ada and hardening-wrapper at the moment) check the build
 105 dependencies for certain packages. The following lines are used to get the
 106 build dependencies. The first is used in buildd build logs, the second by
 107 pbuilder logs, both are detected:
 108
 109     Build-Depends: ...
 110     Depends: ...
 111
 112
 113 LIMITATIONS
 114 -----------
 115
 116 The build log must contain the following line which marks the beginning of the
 117 real compile process (output of dpkg-buildpackage):
 118
 119     dpkg-buildpackage: ...
 120
 121 If it's not present no compiler commands are detected. In case you don't use
 122 dpkp-buildpackage but still want to check a build log, adding it as first line
 123 should work fine.
 124
 125 The following non-verbose builds can't be detected:
 126
 127     gcc -o test
 128
 129 This is not detected because `test` has no file extension. A file extension is
 130 required on a compiler line to prevent many false positives. As the build will
 131 most likely contain other non-verbose build commands (e.g. `gcc test.c`) which
 132 are correctly detected as non-verbose this shouldn't be a problem.
 133
 134 Some CMake non-verbose linker commands are also not correctly detected at the
 135 moment.
 136
 137 blhc still creates a few false positives. Patches to fix them are very welcome
 138 as long as they won't cause any false negatives.
 139
 140
 141 BUILDD MODE
 142 -----------
 143
 144 Buildd mode is enabled if '--buildd' is used. It's designed to check build
 145 logs from Debian's buildds.
 146
 147 Instead of normal warning messages only tags are printed at the end of the
 148 check. See the man page for possible tags.
 149
 150
 151 BUGS
 152 ----
 153
 154 If you find any bugs not mentioned in this document please report them to
 155 <simon@ruderich.org> with blhc in the subject.
 156
 157
 158 AUTHORS
 159 -------
 160
 161 Written by Simon Ruderich <simon@ruderich.org>.
 162
 163 Thanks to Bernhard R. Link <brlink@debian.org> and Jaria Alto
 164 <jari.aalto@cante.net> for their valuable input and suggestions.
 165
 166
 167 LICENSE
 168 -------
 169
 170 blhc is licensed under GPL version 3 or later.
 171
 172 Copyright (C) 2012-2013  Simon Ruderich
 173
 174 This program is free software: you can redistribute it and/or modify
 175 it under the terms of the GNU General Public License as published by
 176 the Free Software Foundation, either version 3 of the License, or
 177 (at your option) any later version.
 178
 179 This program is distributed in the hope that it will be useful,
 180 but WITHOUT ANY WARRANTY; without even the implied warranty of
 181 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 182 GNU General Public License for more details.
 183
 184 You should have received a copy of the GNU General Public License
 185 along with this program.  If not, see <http://www.gnu.org/licenses/>.