From: Simon Ruderich Date: Tue, 10 Apr 2012 20:35:05 +0000 (+0200) Subject: README: Add. X-Git-Tag: 0.01~24 X-Git-Url: https://ruderich.org/simon/gitweb/?a=commitdiff_plain;ds=inline;h=2839b145ae987b823227ba569e140f413b84b303;p=blhc%2Fblhc.git README: Add. --- diff --git a/README b/README new file mode 100644 index 0000000..a2adcb8 --- /dev/null +++ b/README @@ -0,0 +1,155 @@ +README +====== + +blhc (build log hardening check) is a small tool which checks build logs for +missing hardening flags. It's licensed under the GPL 3 or later. + +It's designed to check build logs generated by Debian's dpkg-buildpackage (or +tools using dpkg-buildpackage like pbuilder or the official buildd build logs) +to help maintainers detect missing hardening flags in their packages. + +At the moment it works only on Debian and derivatives but it should be easily +extendable for other systems as well. + +For more information about hardening flags have a look at [1]. + +[1]: https://wiki.debian.org/Hardening + + +DEPENDENCIES +------------ + +- Perl + - Dpkg::Arch + - Dpkg::Version + + +USAGE +----- + + blhc path/to/log/file + +For more examples see the man page. + + +CHECKS +------ + +blhc checks all compiler lines (lines matching `gcc`) for hardening flags +(same as set by `dpkg-buildflags`). If a compiler flag is missing a warning +with the missing flags is printed. + +Consider the following compiler line: + + gcc -g -O2 -o test test.c + +blhc generates the following warnings because all hardening flags are missing: + + CFLAGS missing (-fstack-protector --param=ssp-buffer-size=4 -Wformat -Wformat-security -Werror=format-security): gcc -g -O2 -o test test.c + CPPFLAGS missing (-D_FORTIFY_SOURCE=2): gcc -g -O2 -o test test.c + LDFLAGS missing (-Wl,-z,relro): gcc -g -O2 -o test test.c + +Preprocessing, linking and compiling is automatically detected: + + gcc -MM test.c > test.d + gcc -E test.c + gcc -o test test.o + + CPPFLAGS missing (-D_FORTIFY_SOURCE=2): gcc -E test.c + LDFLAGS missing (-Wl,-z,relro): gcc -o test test.o + +blhc differentiates the following flags: + + - CPPFLAGS: preprocessor flags + - CFLAGS: C compiler flags + - CXXFLAGS: C++ compiler flags + - LDFLAGS: linker flags + +Both '-O2' and '-O3' are recognized as valid, even though only '-O2' is +printed in warnings. + +It handles all file extensions as documented by gcc regarding preprocessing, +linking, compiling. + +The architecture of the build log is automatically detected by looking for the +following line (output of dpkg-buildpackage): + + dpkg-buildpackage: host architecture + +The available hardening flags are adapted to the architecture because some +architectures don't support certain hardening options. + + +LIMITATIONS +----------- + +The build log must contain the following line which marks the beginning of the +real compile process (output of dpkg-buildpackage): + + dpkg-buildpackage: ... + +If it's not present no compiler commands are detected. In case you don't use +dpkp-buildpackage but still want to check a build log adding it as first line +should work fine. + +The following non-verbose builds can't be detected: + + gcc -o test + +This is not detected because `test` has no file extension. A file extension is +required on a compiler line to prevent many false positives. As the build will +most likely contain other non-verbose build commands (e.g. `gcc test.c`) which +are correctly detected as non-verbose this shouldn't be a problem. + +Some CMake non-verbose linker commands are also not correctly detected at the +moment. + +blhc still creates a few false positives. Patches to fix them are very welcome +as long as they won't cause any false negatives. + + +BUILDD MODE +----------- + +Buildd mode is enabled if '--buildd' is used. It's designed to check build +logs from Debian's buildds. + +Instead of normal warning messages only tags are printed at the end of the +check. See the man page for possible tags. + + +BUGS +---- + +If you find any bugs not mentioned in this document please report them to + with blhc in the subject. + + +AUTHORS +------- + +Written by Simon Ruderich . + +Thanks to Bernhard R. Link and Jaria Alto + for their valuable input and suggestions. + + +LICENSE +------- + +blhc is licensed under GPL version 3 or later. + +Copyright (C) 2012 Simon Ruderich + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see .