From: Simon Ruderich Date: Tue, 10 Apr 2012 22:30:01 +0000 (+0200) Subject: Update Pod documentation. X-Git-Tag: 0.01~15 X-Git-Url: https://ruderich.org/simon/gitweb/?a=commitdiff_plain;h=758fd27d99baec2f20e7ab4291e4aaa998ba338c;p=blhc%2Fblhc.git Update Pod documentation. --- diff --git a/bin/blhc b/bin/blhc index 88d1346..49640dd 100755 --- a/bin/blhc +++ b/bin/blhc @@ -963,8 +963,12 @@ B [I] Idpkg-buildpackage build log fileE..> =head1 DESCRIPTION -blhc is a small tool which checks build logs for missing hardening flags and -other important warnings. It's licensed under the GPL 3 or later. +blhc 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. =head1 OPTIONS @@ -994,8 +998,8 @@ changes are in effect: =item -Print tags instead of normal warnings, see README file for a list of possible -tags. +Print tags instead of normal warnings, see L for a list of +possible tags. =item @@ -1047,6 +1051,84 @@ Auto detection for B<--pie> and B<--bindnow> only works if at least one command uses the required hardening flag (e.g. -fPIE). Then it's required for all other commands as well. +=head1 EXAMPLES + +Normal usage, parse a single log file. + + blhc path/to/log/file + +Parse multiple log files. The exit code is ORed over all files. + + blhc path/to/directory/with/log/files/* + +Don't treat missing C<-g> as error: + + blhc --ignore-flag -g path/to/log/file + +Ignore lines consisting exactly of C<./script gcc file> which would cause a +false positive. + + blhc --ignore-line '\./script gcc file' path/to/log/file + +Ignore lines matching C<./script gcc file> somewhere in the line. + + blhc --ignore-line '.*\./script gcc file.*' path/to/log/file + +Use blhc with pbuilder. + + pbuilder path/to/package.dsc | tee path/log/file + blhc path/to/file || echo flags missing + +=head1 BUILDD TAGS + +The following tags are used in I<--buildd> mode. In braces the additional data +which is displayed. + +=over 2 + +=item + +B + +The package uses hardening-wrapper which intercepts calls to gcc and adds +hardening flags. The build log doesn't contain any hardening flags and thus +can't be checked by blhc. + +=item + +B (summary of hidden lines) + +Build log contains lines which hide the real compiler flags. For example: + + CC test-a.c + CC test-b.c + CC test-c.c + LD test + +Most of the time either C or C in +F fixes builds with hidden compiler flags. Sometimes C<.SILENT> +in a F must be removed. And as last resort the F must be +patched to remove the C<@>s hiding the real compiler commands. + +=item + +B (summary of missing flags) + +CPPFLAGS, CFLAGS, CXXFLAGS, LDFLAGS missing. + +=item + +B (version) + +=item + +B + +No compiler commands were detected. Either the log contains none or they were +not correctly detected by blhc (please report the bug in this case). + +=back + =head1 EXIT STATUS The exit status is a "bit mask", each listed status is ORed when the error @@ -1084,6 +1166,9 @@ Hardening wrapper detected, no tests performed. Simon Ruderich, Esimon@ruderich.orgE +Thanks to to Bernhard R. Link Ebrlink@debian.orgE and Jaria Alto +Ejari.aalto@cante.netE for their valuable input and suggestions. + =head1 COPYRIGHT AND LICENSE Copyright (C) 2012 by Simon Ruderich @@ -1101,4 +1186,8 @@ 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 . +=head1 SEE ALSO + +L, L + =cut