doc: Add fuzzing quickstart guides for libFuzzer and afl-fuzz #18342

practicalswift commented at 12:42 PM on March 13, 2020: contributor

Add fuzzing quickstart guide to make it trivial to start fuzzing Bitcoin Core.

Fuzzing is fun and having more people contributing coverage-increasing inputs to https://github.com/bitcoin-core/qa-assets would be awesome :)

practicalswift force-pushed on Mar 13, 2020

fanquake added the label Docs on Mar 13, 2020

kiminuo commented at 2:22 PM on March 13, 2020: contributor

@practicalswift This is very informative. 👍

After reading https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md, I was still a bit unclear what that AFL really is. Maybe add http://lcamtuf.coredump.cx/afl/ URL to make it super clear that it's just another fuzzer ("american fuzzy lop")?

in doc/fuzzing.md:5 in 1ef9506b7a outdated

   0 | @@ -1,9 +1,98 @@
   1 |  Fuzz-testing Bitcoin Core
   2 |  ==========================
   3 |  
   4 | -A special test harness in `src/test/fuzz/` is provided for each fuzz target to
   5 | -provide an easy entry point for fuzzers and the like. In this document we'll
   6 | -describe how to use it with AFL and libFuzzer.
   7 | +## Quickstart guide
   8 | +
   9 | +To quickly get started with fuzzing Bitcoin Core:

MarcoFalke commented at 2:58 PM on March 13, 2020:

should mention that this only works on linux

practicalswift commented at 3:12 PM on March 13, 2020:

I have only tested this under Linux. What part is Linux specific? I would assume these instructions should work for all users with a working and not too ancient Clang/LLVM installation?

Are you referring to the "macOS hints for libFuzzer" instructions later on in the document?

MarcoFalke commented at 3:24 PM on March 13, 2020:

Yes, I meant to say that this doesn't work on mac, even with the latest clang installed

practicalswift commented at 3:35 PM on March 13, 2020:

Added:

# macOS X users: If you have problem with this step then make sure to read "macOS hints for
# libFuzzer" on https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md#macos-hints-for-libfuzzer

See below :)

in doc/fuzzing.md:60 in 1ef9506b7a outdated

  68 | +# abort using ^C after fuzzing a few seconds
  69 | +$ ls process_message-seeded-from-thin-air/
  70 | +349ac589fc66a09abc0b72bb4ae445a7a19e2cd8 4df479f1f421f2ea64b383cd4919a272604087a7
  71 | +a640312c98dcc55d6744730c33e41c5168c55f09 b135de16e4709558c0797c15f86046d31c5d86d7
  72 | +c000f7b41b05139de8b63f4cbf7d1ad4c6e2aa7f fc52cc00ec1eb1c08470e69f809ae4993fa70082
  73 | +$ cat -v process_message-seeded-from-thin-air/349ac589fc66a09abc0b72bb4ae445a7a19e2cd8

MarcoFalke commented at 3:02 PM on March 13, 2020:

Pretty sure that throwing arbitrary bytes at bash will lead to random code execution; E.g. sends all your bitcoins to whoever created the seed

practicalswift commented at 3:06 PM on March 13, 2020:

I'm not sure I follow at all TBH. Who would throw arbitrary bytes at bash and why? :)

MarcoFalke commented at 3:21 PM on March 13, 2020:

https://unix.stackexchange.com/questions/283732/safe-execution-of-cat-command-without-executing-arbitrary-code

MarcoFalke commented at 3:26 PM on March 13, 2020:

Ah, sorry. I missed the -v. Maybe make it more clear that --show-nonprinting must be passed when looking at fuzz seeds?

practicalswift commented at 12:56 PM on March 14, 2020:

Good idea! Replaced -v with --show-nonprinting to make it super clear :)

practicalswift force-pushed on Mar 13, 2020

DrahtBot commented at 5:34 PM on March 13, 2020: member

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

No conflicts as of last run.

practicalswift force-pushed on Mar 14, 2020

practicalswift renamed this:
~~doc: Add fuzzing quickstart guide~~
doc: Add fuzzing quickstart guides for libFuzzer and afl-fuzz
on Mar 14, 2020

practicalswift commented at 5:11 PM on March 14, 2020: contributor

@kiminuo Very good point! I've now also added a quickstart guide for afl-fuzz. Let me know what you think about the current version :)

kiminuo commented at 9:07 PM on March 14, 2020: contributor

@practicalswift I find it very good. Thank you for the update!

practicalswift force-pushed on Mar 15, 2020

practicalswift commented at 8:27 PM on March 15, 2020: contributor

Updated by adding a link to a nice libFuzzer tutorial provided by Google :)

in doc/fuzzing.md:130 in 21fa6cb9c0 outdated

 218 | +$ make
 219 | +# For macOS you may need to ignore x86 compilation checks when running "make". If so,
 220 | +# try compiling using: AFL_NO_X86=1 make
 221 | +$ mkdir -p inputs/ outputs/
 222 | +$ echo A > inputs/thin-air-input
 223 | +$ afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/bech32

Thoragh commented at 1:49 PM on March 16, 2020:

$ afl/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/bech32

I needed to add afl/ to run the fuzzer. same on line 140.

practicalswift force-pushed on Mar 16, 2020

practicalswift commented at 2:43 PM on March 16, 2020: contributor

@Thoragh Oh, good catch! Now added afl/.

Thanks a lot for testing the instructions. That's great!

DrahtBot added the label Needs rebase on Mar 18, 2020

practicalswift commented at 10:15 PM on March 18, 2020: contributor

Rebased! :)

practicalswift force-pushed on Mar 18, 2020

doc: Add fuzzing quickstart guides for libFuzzer and afl-fuzz. Simplify instructions. 33dd764984

in doc/fuzzing.md:93 in 21e553d972 outdated

 210 | +## macOS hints for libFuzzer
 211 | +
 212 | +The default Clang/LLVM version supplied by Apple on macOS does not include
 213 |  fuzzing libraries, so macOS users will need to install a full version, for
 214 |  example using `brew install llvm`.
 215 | +>>>>>>> doc: Add fuzzing quickstart guides for libFuzzer and afl-fuzz. Simplify instructions.

MarcoFalke commented at 10:28 PM on March 18, 2020:

:eyes:

practicalswift commented at 10:32 PM on March 18, 2020:

Ouch! Fixed :)

Thanks friend!

practicalswift force-pushed on Mar 18, 2020

DrahtBot removed the label Needs rebase on Mar 18, 2020

practicalswift commented at 1:53 PM on March 24, 2020: contributor

Ready for merge? :)

MarcoFalke commented at 3:34 PM on March 24, 2020: member

ACK 33dd764984def9371f324d3add19ee894a0260bf

in doc/fuzzing.md:122 in 33dd764984

 121 | +```sh
 122 | +$ git clone https://github.com/bitcoin/bitcoin
 123 | +$ cd bitcoin/
 124 | +$ git clone https://github.com/google/afl
 125 | +$ make -C afl/
 126 | +$ make -C afl/llvm_mode/

fanquake commented at 7:24 AM on March 25, 2020:

macOS users will likely get stuck here (even using brew installed llvm). This will fail to link given afls usage of -znodelete. Dropping that flag leads to issues with undefined symbols.

fanquake approved

fanquake commented at 7:28 AM on March 25, 2020: member

ACK 33dd764984def9371f324d3add19ee894a0260bf - ran through the quick start and process message instructions. macOS users might see issues with afl-fuzz.

fanquake merged this on Mar 25, 2020

fanquake closed this on Mar 25, 2020

sidhujag referenced this in commit 58cb6be29b on Mar 28, 2020

practicalswift deleted the branch on Apr 10, 2021

DrahtBot locked this on Aug 18, 2022