.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "BLHC 1p" .TH BLHC 1p "2020-08-03" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" blhc \- build log hardening check, checks build logs for missing hardening flags .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBblhc\fR [\fIoptions\fR] \fI..\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" blhc is a small tool which checks build logs for missing hardening flags. It's licensed under the \s-1GPL 3\s0 or later. .PP It's designed to check build logs generated by Debian's dpkg-buildpackage (or tools using dpkg-buildpackage like pbuilder or sbuild (which is used for the official buildd build logs)) to help maintainers detect missing hardening flags in their packages. .PP Only gcc is detected as compiler at the moment. If other compilers support hardening flags as well, please report them. .PP If there's no output, no flags are missing and the build log is fine. .PP See \fI\s-1README\s0\fR for details about performed checks, auto-detection and limitations. .SH "FALSE POSITIVES" .IX Header "FALSE POSITIVES" To suppress false positives you can embed the following string in the build log: .PP .Vb 1 \& blhc: ignore\-line\-regexp: REGEXP .Ve .PP All lines fully matching \s-1REGEXP\s0 (see \fB\-\-ignore\-line\fR for details) will be ignored. .PP Please use this feature sparingly so that missing flags are not overlooked. If you find false positives which affect more packages please report a bug. .PP To generate this string simply use echo in \f(CW\*(C`debian/rules\*(C'\fR; make sure to use @ to suppress the echo command itself as it could also trigger a false positive. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-all\fR" 8 .IX Item "--all" Force check for all +all (+pie, +bindnow) hardening flags. By default it's auto detected. .IP "\fB\-\-arch\fR \fIarchitecture\fR" 8 .IX Item "--arch architecture" Set the specific architecture (e.g. amd64, armel, etc.), automatically disables hardening flags not available on this architecture. Is detected automatically if dpkg-buildpackage is used. .IP "\fB\-\-bindnow\fR" 8 .IX Item "--bindnow" Force check for all +bindnow hardening flags. By default it's auto detected. .IP "\fB\-\-buildd\fR" 8 .IX Item "--buildd" Special mode for buildds when automatically parsing log files. The following changes are in effect: .RS 8 .IP "\(bu" 2 Print tags instead of normal warnings, see \*(L"\s-1BUILDD TAGS\*(R"\s0 for a list of possible tags. .IP "\(bu" 2 Don't check hardening flags in old log files (if dpkg-dev << 1.16.1 is detected). .IP "\(bu" 2 Don't require Term::ANSIColor. .IP "\(bu" 2 Return exit code 0, unless there was a error (\-I, \-W messages don't count as error). .RE .RS 8 .RE .IP "\fB\-\-debian\fR" 8 .IX Item "--debian" Apply Debian-specific settings. At the moment this only disables checking for \&\s-1PIE\s0 which is automatically applied by Debian's \s-1GCC\s0 and no longer requires a compiler command line argument. .IP "\fB\-\-color\fR" 8 .IX Item "--color" Use colored (\s-1ANSI\s0) output for warning messages. .IP "\fB\-\-line\-numbers\fR" 8 .IX Item "--line-numbers" Display line numbers. .IP "\fB\-\-ignore\-arch\fR \fIarch\fR" 8 .IX Item "--ignore-arch arch" Ignore build logs from architectures matching \fIarch\fR. \fIarch\fR is a string. .Sp Used to prevent false positives. This option can be specified multiple times. .IP "\fB\-\-ignore\-arch\-flag\fR \fIarch\fR:\fIflag\fR" 8 .IX Item "--ignore-arch-flag arch:flag" Like \fB\-\-ignore\-flag\fR, but only ignore flag on \fIarch\fR. .IP "\fB\-\-ignore\-arch\-line\fR \fIarch\fR:\fIline\fR" 8 .IX Item "--ignore-arch-line arch:line" Like \fB\-\-ignore\-line\fR, but only ignore line on \fIarch\fR. .IP "\fB\-\-ignore\-flag\fR \fIflag\fR" 8 .IX Item "--ignore-flag flag" Don't print an error when the specific flag is missing in a compiler line. \&\fIflag\fR is a string. .Sp Used to prevent false positives. This option can be specified multiple times. .IP "\fB\-\-ignore\-line\fR \fIregex\fR" 8 .IX Item "--ignore-line regex" Ignore lines matching the given Perl regex. \fIregex\fR is automatically anchored at the beginning and end of the line to prevent false negatives. .Sp \&\fB\s-1NOTE\s0\fR: Not the input lines are checked, but the lines which are displayed in warnings (which have line continuation resolved). .Sp Used to prevent false positives. This option can be specified multiple times. .IP "\fB\-\-pie\fR" 8 .IX Item "--pie" Force check for all +pie hardening flags. By default it's auto detected. .IP "\fB\-h \-? \-\-help\fR" 8 .IX Item "-h -? --help" Print available options. .IP "\fB\-\-version\fR" 8 .IX Item "--version" Print version number and license. .PP Auto detection for \fB\-\-pie\fR and \fB\-\-bindnow\fR 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. .SH "EXAMPLES" .IX Header "EXAMPLES" Normal usage, parse a single log file. .PP .Vb 1 \& blhc path/to/log/file .Ve .PP If there's no output, no flags are missing and the build log is fine. .PP Parse multiple log files. The exit code is ORed over all files. .PP .Vb 1 \& blhc path/to/directory/with/log/files/* .Ve .PP Don't treat missing \f(CW\*(C`\-g\*(C'\fR as error: .PP .Vb 1 \& blhc \-\-ignore\-flag \-g path/to/log/file .Ve .PP Don't treat missing \f(CW\*(C`\-pie\*(C'\fR on kfreebsd\-amd64 as error: .PP .Vb 1 \& blhc \-\-ignore\-arch\-flag kfreebsd\-amd64:\-pie path/to/log/file .Ve .PP Ignore lines consisting exactly of \f(CW\*(C`./script gcc file\*(C'\fR which would cause a false positive. .PP .Vb 1 \& blhc \-\-ignore\-line \*(Aq\e./script gcc file\*(Aq path/to/log/file .Ve .PP Ignore lines matching \f(CW\*(C`./script gcc file\*(C'\fR somewhere in the line. .PP .Vb 1 \& blhc \-\-ignore\-line \*(Aq.*\e./script gcc file.*\*(Aq path/to/log/file .Ve .PP Use blhc with pbuilder. .PP .Vb 2 \& pbuilder path/to/package.dsc | tee path/log/file \& blhc path/to/file || echo flags missing .Ve .PP Assume this build log was created on a Debian system and thus don't warn about missing \s-1PIE\s0 flags if the current architecture injects them automatically (this is enabled in buildd mode per default). \f(CW\*(C`\-\-arch\*(C'\fR is necessary if the build log contains no architecture information as written by dpkg-buildpackage. .PP .Vb 1 \& blhc \-\-debian \-\-all \-\-arch=amd64 path/to/log/file .Ve .SH "BUILDD TAGS" .IX Header "BUILDD TAGS" The following tags are used in \fI\-\-buildd\fR mode. In braces the additional data which is displayed. .IP "\fBI\-hardening-wrapper-used\fR" 2 .IX Item "I-hardening-wrapper-used" 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. .IP "\fBW\-compiler-flags-hidden\fR (summary of hidden lines)" 2 .IX Item "W-compiler-flags-hidden (summary of hidden lines)" Build log contains lines which hide the real compiler flags. For example: .Sp .Vb 4 \& CC test\-a.c \& CC test\-b.c \& CC test\-c.c \& LD test .Ve .Sp Most of the time either \f(CW\*(C`export V=1\*(C'\fR or \f(CW\*(C`export verbose=1\*(C'\fR in \&\fIdebian/rules\fR fixes builds with hidden compiler flags. Sometimes \f(CW\*(C`.SILENT\*(C'\fR in a \fIMakefile\fR must be removed. And as last resort the \fIMakefile\fR must be patched to remove the \f(CW\*(C`@\*(C'\fRs hiding the real compiler commands. .IP "\fBW\-dpkg-buildflags-missing\fR (summary of missing flags)" 2 .IX Item "W-dpkg-buildflags-missing (summary of missing flags)" \&\s-1CPPFLAGS, CFLAGS, CXXFLAGS, LDFLAGS\s0 missing. .IP "\fBI\-invalid-cmake-used\fR (version)" 2 .IX Item "I-invalid-cmake-used (version)" By default CMake ignores \s-1CPPFLAGS\s0 thus missing those hardening flags. Debian patched CMake in versions 2.8.7\-1 and 2.8.7\-2 to respect \s-1CPPFLAGS,\s0 but this patch was rejected by upstream and later reverted in Debian. Thus those two versions show correct usage of \s-1CPPFLAGS\s0 even if the package doesn't correctly handle them (for example by passing them to \s-1CFLAGS\s0). To prevent false negatives just blacklist those two versions. .IP "\fBI\-no-compiler-commands\fR" 2 .IX Item "I-no-compiler-commands" 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). .SH "EXIT STATUS" .IX Header "EXIT STATUS" The exit status is a \*(L"bit mask\*(R", each listed status is ORed when the error condition occurs to get the result. .IP "\fB0\fR" 4 .IX Item "0" Success. .IP "\fB1\fR" 4 .IX Item "1" No compiler commands were found. .IP "\fB2\fR" 4 .IX Item "2" Invalid arguments/options given to blhc. .IP "\fB4\fR" 4 .IX Item "4" Non verbose build. .IP "\fB8\fR" 4 .IX Item "8" Missing hardening flags. .IP "\fB16\fR" 4 .IX Item "16" Hardening wrapper detected, no tests performed. .IP "\fB32\fR" 4 .IX Item "32" Invalid CMake version used. See \fBI\-invalid-cmake-used\fR under \*(L"\s-1BUILDD TAGS\*(R"\s0 for a detailed explanation. .SH "AUTHOR" .IX Header "AUTHOR" Simon Ruderich, .PP Thanks to to Bernhard R. Link and Jaria Alto for their valuable input and suggestions. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (C) 2012\-2020 by Simon Ruderich .PP This program is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program. If not, see . .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBhardening\-check\fR\|(1), \fBdpkg\-buildflags\fR\|(1)