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