Brad House
08b7692703
|
4 months ago | |
---|---|---|
.. | ||
fuzzinput | ||
fuzznames | ||
.gitignore | ||
CMakeLists.txt | ||
Makefile.am | ||
Makefile.inc | ||
Makefile.m32 | ||
Makefile.msvc | ||
README.md | ||
ares-fuzz.c | ||
ares-test-ai.h | ||
ares-test-fuzz-name.c | ||
ares-test-fuzz.c | ||
ares-test-init.cc | ||
ares-test-internal.cc | 4 months ago | |
ares-test-live.cc | ||
ares-test-main.cc | 4 months ago | |
ares-test-misc.cc | 4 months ago | |
ares-test-mock-ai.cc | ||
ares-test-mock-et.cc | 4 months ago | |
ares-test-mock.cc | 4 months ago | |
ares-test-ns.cc | ||
ares-test-parse-a.cc | ||
ares-test-parse-aaaa.cc | ||
ares-test-parse-caa.cc | ||
ares-test-parse-mx.cc | ||
ares-test-parse-naptr.cc | ||
ares-test-parse-ns.cc | ||
ares-test-parse-ptr.cc | 4 months ago | |
ares-test-parse-soa-any.cc | ||
ares-test-parse-soa.cc | ||
ares-test-parse-srv.cc | ||
ares-test-parse-txt.cc | ||
ares-test-parse-uri.cc | ||
ares-test-parse.cc | ||
ares-test.cc | 4 months ago | |
ares-test.h | 4 months ago | |
ares_queryloop.c | ||
dns-dump.cc | ||
dns-proto-test.cc | ||
dns-proto.cc | 4 months ago | |
dns-proto.h | 4 months ago | |
fuzzcheck.sh |
README.md
c-ares Unit Test Suite
This directory holds unit tests for the c-ares library. To build the tests:
- Build the main c-ares library first, in the directory above this. To
enable tests of internal functions, configure the library build to expose
hidden symbols with
./configure --disable-symbol-hiding
. - Generate a
configure
file by runningautoreconf -iv
(which requires a local installation of autotools). ./configure
make
- Run the tests with
./arestest
, or./arestest -v
for extra debug info.
Points to note:
- The tests are written in C++11, and so need a C++ compiler that supports this. To avoid adding this as a requirement for the library, the configuration and build of the tests is independent from the library.
- The tests include some live queries, which will fail when run on a machine
without internet connectivity. To skip live tests, run with
./arestest --gtest_filter=-*.Live*
. - The tests include queries of a mock DNS server. This server listens on port
5300 by default, but the port can be changed with the
-p 5300
option toarestest
.
Test Types
The test suite includes various different types of test.
- There are live tests (
ares-test-live.cc
), which assume that the current machine has a valid DNS setup and connection to the internet; these tests issue queries for real domains but don't particularly check what gets returned. The tests will fail on an offline machine. - There are some mock tests (
ares-test-mock.cc
) that set up a fake DNS server and inject its port into the c-ares library configuration. These tests allow specific response messages to be crafted and injected, and so are likely to be used for many more tests in future.- To make this generation/injection easier, the
dns-proto.h
file includes C++ helper classes for building DNS packets.
- To make this generation/injection easier, the
- Other library entrypoints that don't require network activity
(e.g.
ares_parse_*_reply
) are tested directly. - A couple of the tests use a helper method of the test fixture to
inject memory allocation failures, using a recent change to the
c-ares library that allows override of
malloc
/free
. - There are some tests of the internal entrypoints of the library
(
ares-test-internal.c
), but these are only enabled if the library was configured with--disable-symbol-hiding
and/or--enable-expose-statics
. - There is also an entrypoint to allow Clang's
libfuzzer to drive
the packet parsing code in
ares_parse_*_reply
, together with a standalone wrapper for it (./aresfuzz
) to allow use of command line fuzzers (such as afl-fuzz) for further fuzz testing.
Code Coverage Information
To generate code coverage information:
- Configure both the library and the tests with
./configure --enable-code-coverage
before building. This requires the relevant code coverage tools (gcov, lcov) to be installed locally. - Run the tests with
test/arestest
. - Generate code coverage output with
make code-coverage-capture
in the library directory (i.e. not intest/
).
Fuzzing
libFuzzer
To fuzz the packet parsing code with libFuzzer, follow the main libFuzzer instructions:
-
Configure the c-ares library and test suite with a recent Clang and a sanitizer, for example:
% export CFLAGS="-fsanitize=fuzzer-no-link,address" % export CC=clang % ./configure --disable-shared && make
-
Link each of the fuzzer entrypoints in with
ares-fuzz.cc
:% clang -I.. -c ares-test-fuzz.c % clang -I.. -c ares-test-fuzz-name.c % clang++ -fsanitize=fuzzer,address ares-test-fuzz.o ../.libs/libcares.a -o ares-libfuzzer % clang++ -fsanitize=fuzzer,address ares-test-fuzz-name.o ../.libs/libcares.a -o ares-libfuzzer-name
-
Run the fuzzer using the starting corpus with:
% ./ares-libfuzzer fuzzinput/ # OR % ./ares-libfuzzer-name fuzznames/
AFL
To fuzz using AFL, follow the AFL quick start guide:
-
Download and build AFL.
-
Configure the c-ares library and test tool to use AFL's compiler wrappers:
% export CC=$AFLDIR/afl-gcc % ./configure --disable-shared && make % cd test && ./configure && make aresfuzz aresfuzzname
-
Run the AFL fuzzer against the starting corpus:
% mkdir fuzzoutput % $AFLDIR/afl-fuzz -i fuzzinput -o fuzzoutput -- ./aresfuzz # OR % $AFLDIR/afl-fuzz -i fuzznames -o fuzzoutput -- ./aresfuzzname
AFL Persistent Mode
If a recent version of Clang is available, AFL can use its built-in compiler instrumentation; this configuration also allows the use of a (much) faster persistent mode, where multiple fuzz inputs are run for each process invocation.
-
Download and build a recent AFL, and run
make
in thellvm_mode
subdirectory to ensure thatafl-clang-fast
gets built. -
Configure the c-ares library and test tool to use AFL's clang wrappers that use compiler instrumentation:
% export CC=$AFLDIR/afl-clang-fast % ./configure --disable-shared && make % cd test && ./configure && make aresfuzz
-
Run the AFL fuzzer (in persistent mode) against the starting corpus:
% mkdir fuzzoutput % $AFLDIR/afl-fuzz -i fuzzinput -o fuzzoutput -- ./aresfuzz