From fd03c64346ab3f63fc5ceafd891dee245121b5c9 Mon Sep 17 00:00:00 2001 From: Andrea Fioraldi Date: Mon, 3 Feb 2020 12:56:05 +0100 Subject: moar docs to markdown --- README.md | 8 +++---- docs/QuickStartGuide.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++ docs/QuickStartGuide.txt | 56 ------------------------------------------------ 3 files changed, 58 insertions(+), 60 deletions(-) create mode 100644 docs/QuickStartGuide.md delete mode 100644 docs/QuickStartGuide.txt diff --git a/README.md b/README.md index dbfdb2cc..e2e073ac 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ To compare notes with other users or get notified about major new features, send a mail to . - See [docs/QuickStartGuide.txt](docs/QuickStartGuide.txt) if you don't have time to + See [docs/QuickStartGuide.md](docs/QuickStartGuide.md) if you don't have time to read this file. @@ -250,7 +250,7 @@ automatically enable code hardening options that make it easier to detect simple memory bugs. Libdislocator, a helper library included with AFL (see [libdislocator/README.md](libdislocator/README.md)) can help uncover heap corruption issues, too. -PS. ASAN users are advised to review [docs/notes_for_asan.txt](docs/notes_for_asan.txt) +PS. ASAN users are advised to review [docs/notes_for_asan.md](docs/notes_for_asan.md) file for important caveats. @@ -278,7 +278,7 @@ your binary, then you can use afl-fuzz normally and it will have twice the speed compared to qemu_mode. A more comprehensive description of these and other options can be found in -[docs/binaryonly_fuzzing.txt](docs/binaryonly_fuzzing.txt) +[docs/binaryonly_fuzzing.md](docs/binaryonly_fuzzing.md) ## 5) Power schedules @@ -598,7 +598,7 @@ Here are some of the most important caveats for AFL: experimental/post_library/ (with AFL_POST_LIBRARY) - There are some unfortunate trade-offs with ASAN and 64-bit binaries. This - isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.txt](docs/notes_for_asan.txt) + isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.md](docs/notes_for_asan.md) for tips. - There is no direct support for fuzzing network services, background diff --git a/docs/QuickStartGuide.md b/docs/QuickStartGuide.md new file mode 100644 index 00000000..1e89a6ad --- /dev/null +++ b/docs/QuickStartGuide.md @@ -0,0 +1,54 @@ +# AFL quick start guide + +You should read docs/README.md - it's pretty short. If you really can't, here's +how to hit the ground running: + +1) Compile AFL with 'make'. If build fails, see docs/INSTALL for tips. + +2) Find or write a reasonably fast and simple program that takes data from + a file or stdin, processes it in a test-worthy way, then exits cleanly. + If testing a network service, modify it to run in the foreground and read + from stdin. When fuzzing a format that uses checksums, comment out the + checksum verification code, too. + If this is not possible (e.g. in -Q(emu) mode) then use AFL_POST_LIBRARY + to calculate the values with your own library. + + The program must crash properly when a fault is encountered. Watch out for + custom SIGSEGV or SIGABRT handlers and background processes. For tips on + detecting non-crashing flaws, see section 11 in docs/README.md . + +3) Compile the program / library to be fuzzed using afl-gcc. A common way to + do this would be: + + CC=/path/to/afl-gcc CXX=/path/to/afl-g++ ./configure --disable-shared + make clean all + + If program build fails, ping . + +4) Get a small but valid input file that makes sense to the program. When + fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described in + dictionaries/README.dictionaries, too. + +5) If the program reads from stdin, run 'afl-fuzz' like so: + + ./afl-fuzz -i testcase_dir -o findings_dir -- \ + /path/to/tested/program [...program's cmdline...] + + If the program takes input from a file, you can put @@ in the program's + command line; AFL will put an auto-generated file name in there for you. + +6) Investigate anything shown in red in the fuzzer UI by promptly consulting + docs/status_screen.txt. + +7) compile and use llvm_mode (afl-clang-fast/afl-clang-fast++) as it is way + faster and has a few cool features + +8) There is a basic docker build with 'docker build -t aflplusplus .' + +That's it. Sit back, relax, and - time permitting - try to skim through the +following files: + + - README.md - A general introduction to AFL, + - docs/perf_tips.txt - Simple tips on how to fuzz more quickly, + - docs/status_screen.txt - An explanation of the tidbits shown in the UI, + - docs/parallel_fuzzing.txt - Advice on running AFL on multiple cores. diff --git a/docs/QuickStartGuide.txt b/docs/QuickStartGuide.txt deleted file mode 100644 index 723611e3..00000000 --- a/docs/QuickStartGuide.txt +++ /dev/null @@ -1,56 +0,0 @@ -===================== -AFL quick start guide -===================== - -You should read docs/README.md - it's pretty short. If you really can't, here's -how to hit the ground running: - -1) Compile AFL with 'make'. If build fails, see docs/INSTALL for tips. - -2) Find or write a reasonably fast and simple program that takes data from - a file or stdin, processes it in a test-worthy way, then exits cleanly. - If testing a network service, modify it to run in the foreground and read - from stdin. When fuzzing a format that uses checksums, comment out the - checksum verification code, too. - If this is not possible (e.g. in -Q(emu) mode) then use AFL_POST_LIBRARY - to calculate the values with your own library. - - The program must crash properly when a fault is encountered. Watch out for - custom SIGSEGV or SIGABRT handlers and background processes. For tips on - detecting non-crashing flaws, see section 11 in docs/README.md . - -3) Compile the program / library to be fuzzed using afl-gcc. A common way to - do this would be: - - CC=/path/to/afl-gcc CXX=/path/to/afl-g++ ./configure --disable-shared - make clean all - - If program build fails, ping . - -4) Get a small but valid input file that makes sense to the program. When - fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described in - dictionaries/README.dictionaries, too. - -5) If the program reads from stdin, run 'afl-fuzz' like so: - - ./afl-fuzz -i testcase_dir -o findings_dir -- \ - /path/to/tested/program [...program's cmdline...] - - If the program takes input from a file, you can put @@ in the program's - command line; AFL will put an auto-generated file name in there for you. - -6) Investigate anything shown in red in the fuzzer UI by promptly consulting - docs/status_screen.txt. - -7) compile and use llvm_mode (afl-clang-fast/afl-clang-fast++) as it is way - faster and has a few cool features - -8) There is a basic docker build with 'docker build -t aflplusplus .' - -That's it. Sit back, relax, and - time permitting - try to skim through the -following files: - - - docs/README.md - A general introduction to AFL, - - docs/perf_tips.txt - Simple tips on how to fuzz more quickly, - - docs/status_screen.txt - An explanation of the tidbits shown in the UI, - - docs/parallel_fuzzing.txt - Advice on running AFL on multiple cores. -- cgit 1.4.1