annocheck man page

annocheck — Analysing an application's compilation.

Synopsis

annocheck
 [--help]
 [--version]
 [--verbose]
 [--quiet]
 [--ignore-unknown]
 [--report-unknown]
 [--debug-rpm=file]
 [--dwarf-dir=dir]
 [--prefix=text]
 file...

annocheck
 [--disable-hardened]
 --enable-builtby
 [--all]
 [--tool=name]
 [--nottool=name]
 file...

annocheck
 [--skip-bind-now]
 [--skip-cf-protection]
 [--skip-dynamic-segment]
 [--skip-fortify]
 [--skip-glibcxx-assertions]
 [--skip-gnu-relro]
 [--skip-gnu-stack]
 [--skip-optimization]
 [--skip-pic]
 [--skip-pie]
 [--skip-property-note]
 [--skip-run-path]
 [--skip-rwx-seg]
 [--skip-short-enum]
 [--skip-stack-clash]
 [--skip-stack-prot]
 [--skip-stack-realign]
 [--skip-textrel]
 [--skip-threads]
 [--skip-writeable-got]
 [--ignore-gaps]
 [--disable-hardened]
 [--enable-hardened]
 file...

annocheck
 [--disable-hardened]
 --enable-notes
 file...

annocheck
 [--disable-hardened]
 [--size-sec=name]
 [--size-sec-flags=!WAX]
 [--size-seg-flags=!WRX]
 [--size-human]
 file...

annocheck
 --enable-timing
 file...
 [--sec]
 [--usec]
 [--nsec]

Description

The annocheck program can analyse programs and report information about them.  It is designed to be modular, with a set of self-contained tools providing the checking functionality. Currently the following tools are implemented:

The annocheck program is able to scan inside rpm files and libraries.  It will automatically recurse into any directories that are specified on the command line.  In addition annocheck knows how to find debug information held in separate debug files, and it will search for these whenever it needs the resources that they contain.

New tools can be added to the annocheck framework by creating a new source file and including it in the Makefile used to build annocheck.  The modular nature of annocheck means that nothing else needs to be updated.

New tools must fill out a struct checker structure (defined in annocheck.h) and they must define a constructor function that calls annocheck_add_checker to register their presence at program start-up.

The annocheck program supports some generic command line options that are used regardless of which tools are enabled.

--debug-rpm=file

Look in file for separate dwarf debug information.

--dwarf-dir=dir

Look in dir for separate dwarf debug information files.

--help

Display this message & exit.

--report-unknown
--ignore-unknown

Report file types not recognised by annocheck.  The default behaviour can be restored by the --ignore-unknown option.

--prefix=text

Include text in the output description.

--quiet

Do not print anything, just return an exit status.

--verbose

Produce informational messages whilst working.  Repeat for more information.

--version

Report the version of the tool and then exit.

The built-by tool is disabled by default, but it can be enabled by the command line option --enable-builtby.  The tool checks the specified files to see if any information is stored about how the file was built.

Since the hardening checker is enabled by default it may also be useful to add the --disable-hardened option to the command line.

The tool supports a few command line options to customise its behaviour:

--all

Report all builder identification strings.  The tool has several different heuristics for determining the builder.  By default it will report the information return by the first successful heuristic.  If the --all option is enabled then all successful results will be returned.

--tool=name

This option can be used to restrict the output to only those files which were built by a specific tool.  This can be useful when scanning a directory full of files searching for those built by a particular compiler.

--nottool=NAME

This option can be used to restrict the output to only those files which were not built by a specific tool.  This can be useful when scanning a directory full of files searching for those that were not built by a particular compiler.

The hardened tool checks that the specified files were compiled with the required security hardening options, as outlined in the elf-policy document.  It runs a series of tests checking compilation options and link time options.  These tests are outlined below, along with the command line option that can be used to disable each test.

New tests can be added to the hardened checker by adding an entry in the tests array defined in hardened.c and then creating the necessary code to support the test.

BIND_NOW

Lazy binding must not have been enabled via the linker option -z lazy.  Instead the -z now option must have been used. Disabled by --skip-bind-now.

Non executable stack

The program must not have a stack in an executable region of memory. Disabled by --skip-gnu-stack.

Safe GOT relocations

The relocations for the GOT table must be read only. Disabled by --skip-writeable-got.

No RWX segments.

No program segment should have all three of the read, write and execute permission bits set. Disabled by --skip-rwx-seg.

No text relocations

There should be no relocations against executable code. Disabled by --skip-textrel.

Correct runpaths

The runpath information used to locate shared libraries at runtime must only include directories rooted at /usr. Disabled by --skip-run-path.

Missing annobin data

The program must have been compiled with annobin notes enabled. Disabled by --ignore-gaps.

Strong stack protection

The program must have been compiled with the -fstack-protector-strong option enabled, and with -D_FORTIFY_SOURCE=2 specified.  It must also have been compiled at at least optimization level 2. Disabled by --skip-stack-prot.

Dynamic data present

Dynamic executables must have a dynamic segment. Disabled by --skip-dynamic-segment.

Position Independent compilation

Shared libraries must have been compiled with -fPIC or -fPIE but not -static. This check can be disabled by --skip-pic.

Dynamic executables must have been compiled with -fPIE and linked with -pie.  This check can be disabled by --skip-pie.

Safe exceptions

Program which use exception handling must have been compiled with -fexceptions enabled and with -D_GLIBCXX_ASSERTIONS specified. Disabled by --skip-threads and/or --skip-glibcxx-assertions.

Stack Clash protection

If available the -fstack-clash-protection must have been used. Disabled by --skip-stack-clash.

Control Flow protection

If available the -fcf-protection=full must have been used. Disabled by --skip-cf-protection.  If this option is disabled then the check for GNU Property notes will also be disabled.

Stack realignment

For i686 binaries, the -mstackrealign option must have been specified. Disabled by --skip-stack-realign.

Source fortification

The program must have been compiled with the -D_FORTIFY_SOURCE=2 command line option specified. Disabled by --skip-fortify.

Optimization

The program must have been compiled with at least -O2 optimization enabled. Disabled by --skip-optimization.

Read only relocations

The program must not have any relocations that are held in a writeable section. Disabled by --skip-gnu-relro.

GNU Property Note

For x86_64 binaries, check that a correctly formatted GNU Property note is present.  These notes are only generated with a program is compiled with the -fcf-protection gcc option is enabled, so if annocheck's --skip-cf-protection option is enabled then this test will be skipped as well.

Enum Size

Check that the program makes consistent use of the -fshort-enum option.

The tool does support a couple of other command line options as well:

--enable-hardened

Enable the tool if it was previously disabled.  The option is the default.

--disable-hardened

Disable the tool.

The notes tool displays the contents of any annobin notes inside the specified files.  It groups the notes by address range, which can help locate missing details.

The notes tool is disabled by default, but it can be enabled by the command line option --enable-notes.  Since the hardening checker is enabled by default it may also be useful to add the --disable-hardened option to the command line.

The section-size tool records the size of named sections within a list of files and then reports the accumulated size at the end. Since it is part of the annocheck framework, it is able to handle directories and rpms files as well as ordinary binary files.

The --size-sec=name option enables the tool and tells it to record the size of section name.  The option can be repeated multiple times to record the sizes of multiple sections.  It may also be useful to add the --disable-hardened option to the command line as otherwise the security hardening will be run at the same time.

Instead of searching for named sections, it is also possible to search for sections with specific flags.  The --size-sec-flags=<flags> option will search for any section that has all of the specified <flags> set.  Currently only W, A and X are recognised as flags, indicating that the section must have the Write, Alloc or Execute flags set respectively.  If the ! exclamation mark character is present then it negates the meaning of the following flags.  Thus --section-sec-flags=W option will search for any writeable section whereas the --size-sec-flags=W!A option will search only for sections that are writeable but not allocated.

Instead of searching for sections by flags it is also possible to search for segments by flags using the --size-seg-flags=<flags> option.  The flags recognised for segments are W for writeable, R for readable and X for executable.  Again the ! character can be used to invert the meaning of the flags that follow it.

If the --verbose option is enabled, then the tool will also report the size of the named section(s) in each file it encounters. If the --size-human option is enabled then sizes will be rounded down to the nearest byte, kibibyte, mebibyte or gibibyte, as appropriate.

The timing tool reports on the time taken by other tools to scan the list of files.  The tool is disabled by default, but it can be enabled by the command line option --enable-timing.

By default the tool will report times in microseconds, but you can change this to reporting in seconds with the --sec or in nanoseconds with the --nsec.  The default can be restored with the --usec option.

Options

Info

2019-02-01 annobin-1 RPM Development Tools