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