4f_doc.txt 09.09.2009 Krakow Labs Development [www.krakowlabs.com] 4f Documentation jbrown@KL (Jeremy Brown) [jbrown@krakowlabs.com] ------------------------------------------------------------------------------------------------------------------ WHAT IS IT? 4f is a file format fuzzing framework. 4f uses modules which are specifications of the targeted binary or text file format that tell it how to fuzz the target application. If 4f detects a crash, it will log crucial information important for allowing the 4f user to reproduce the problem and also debugging information important to deciding the severity of the bug and its exploitability. ------------------------------------------------------------------------------------------------------------------ PURPOSE 4f's purpose is to find vulnerabilities in code that parses file formats including configuration files. ------------------------------------------------------------------------------------------------------------------ HOW DOES IT WORK? 4f uses specialized modules for fuzzing code that interprets file formats. Several modules are included and more can be written to follow other file formats. If you would like to learn how to write modules for 4f, read the detailed section near the end (plus mod/example). ------------------------------------------------------------------------------------------------------------------ FEATURES A module system is in place for fuzzing any file format you like as long as you know its specification Custom debugger gathers crucial debugging information on crash, logs it, then continues fuzzing For example... *************************************************** * * PATH: [/usr/bin/program] * SIGNAL: 11 (SIGSEGV) * FILE: [/tmp/96.ext] * DATA: Overflow: A x 1100 * * EAX = 0xb7cc307a * ECX = 0x81bee38 * EDX = 0x41414141 * EBX = 0x81bee38 * ESP = 0x41414141 * EBP = 0x41414141 * ESI = 0xbfb48af8 * EDI = 0x0 * EIP = 0x41414141 * *************************************************** Its nice and neat and actually useful for fuzzing local applications and custom software if you know how it works ------------------------------------------------------------------------------------------------------------------ USAGE DETAILS USAGE: ./4f <-T /usr/bin/target> <-M #> [-N fuzz.conf] [-A ARGS] [-R /output] [-L log.txt] [-C] [-D] INFO: [-O Fuzzing Oracle] [-S Modules Available] -T = target application (full path please) -A = arguments for target application (all at once, example: "-a 1 -z 2") -M = module number (target file format) -N = configuration path (fuzzing config files), default should be specified in each module header -C = clean-up bit (on/off), default = off -D = time (microseconds) before killing process, default = 100000 -L = logging file, default = 4f.log -R = output directory, default = /tmp -O = list fuzzing oracle -S = list available modules There are 7 modules that come in this release. (1) Development - BASIC Source (2) Development - C Source (3) Development - PERL Source (4) Multimedia - Extended M3U (5) Multimedia - Extended PLS (6) Multimedia - PulseAudio CONF (7) Networking - Bittorrent METAINFO Check out their headers for more information. Using 4f is as simple as ./4f -T /usr/bin/program -M 5 ------------------------------------------------------------------------------------------------------------------ WRITING MODULES How To Write Modules for 4f This guide aims tell you and show you, by example, everything you need to know about how to write and implement modules in the file format fuzzing framework (4f). * When you plan on fuzzing a file format with 4f, you need to be able to write a specification up for it in code. It can be as comphrensive as you make it. Make friends with the RFCs and technical documentation of any file format you are writing a module to fuzz. * Create two files, a C source file (exa.c) and a C header file (exa.h). example.c should contain the main programming of the module, how it should work, and what it should fuzz, while example.h is for outlining the module and keeping definitions. Now, let us say for example you are writing a module for Example's file format. [BEGIN test.exa] #EXAMPLE-1.0 username = data password = data [END test.exa] By looking at Example's file format, we can see that.. * Example format is identified by #EXAMPLE-1.0 * There are at least two parameters we can fuzz * We can even fuzz a variable's position When our target reads the file, and its format, its going to be able to tell that it is in Example file format because of the format descriptor. Also it can parse the parameters from "username" and "password". Furthermore, it parses the names of the variables themselves (takes input behind and in front of the equal sign). So, if we want to fuzz all of that, its relatively easy: we stuff all that information into a 4f module and let it find the bugs for us! :) You should start with writing up definitions in exa.h first, then move on to the coding in exa.c. It is also important to separate each thing you want to fuzz into definitions to make things easy to move around and manipulate in every fuzzing case you want to make. [BEGIN exa.h] //////////////////////////////////////////////////////////////////////////////////////////////////// /* EXAMPLE (EXAMPLE File Format) [.exa] #EXAMPLE-1.0 --> format descriptor username = data --> username password = data --> password Notes: Place any notes that you feel are important here. */ #define EXA_FF1 "#EXAMPLE-1.0" #define EXA_FF2 "username" #define EXA_FF3 "password" //////////////////////////////////////////////////////////////////////////////////////////////////// [END exa.h] [BEGIN exa.c] #include "../include/core.h" #include "../include/oracle.h" #include "../include/mod/example/exa.h" void exa_prepare(char *tar, char *arg, int kb, char *lgf, char *dir) { char *ext = "exa"; // extension int c = 0, i; fzof_gen(); // generate fuzzing oracle overflow data for(i = 0; i <= FZTL; i++) { counter(&c); process(c, &fp, ext, dir); fprintf(fp, "#%s\n", fuzz[i].data); // fuzzing format descriptor fprintf(fp, "%s = data\n%s = data", EXA_FF2, EXA_FF3); // make file complete fclose(fp); execute(tar, arg, NULL, cb, tm, lgf, ffn, fuzz[i].desc); } for(i = 0; i <= FZTL; i++) { counter(&c); process(c, &fp, ext, dir); fprintf(fp, "%s\n", EXA_FF1); // format descriptor fprintf(fp, "%s = %s\n%s = data", EXA_FF2, fuzz[i].data, EXA_FF3); // fuzzing "username" fclose(fp); execute(tar, arg, NULL, cb, tm, lgf, ffn, fuzz[i].desc); } for(i = 0; i <= FZTL; i++) { counter(&c); process(c, &fp, ext, dir); fprintf(fp, "%s\n", EXA_FF1); // format descriptor fprintf(fp, "%s = data\n%s = %s", EXA_FF2, EXA_FF3, fuzz[i].data); // fuzzing "password" fclose(fp); execute(tar, arg, NULL, cb, tm, lgf, ffn, fuzz[i].desc); } for(i = 0; i <= FZTL; i++) { counter(&c); process(c, &fp, ext, dir); fprintf(fp, "%s\n", EXA_FF1); // format descriptor fprintf(fp, "%s = data\n%s = data", fuzz[i].data, EXA_FF3); // fuzzing variable position fclose(fp); execute(tar, arg, NULL, cb, tm, lgf, ffn, fuzz[i].desc); } } [END exa.c] We can now insert it into 4f. --> Add the choice to list_modules(): printf(" (8) Category - Description\n\n"); --> Add a line like this in core.c: if(mod == 5) exa_prepare(tar, arg, kb, lgf, dir); --> Add "mod/exa.c" to the Makefile Now "make" it again and if you did everything correctly you should be good to go. ------------------------------------------------------------------------------------------------------------------ NOTES I am not expecting everyone to jump on the band wagon and start writing modules for 4f, but you can, and they have a decent chance of finding bugs if you write them correctly. I know that theres probably a better way to write the modules, and good for you if you do it, but I'm just not a great C programmer and the way I did it works and seems efficient to me. If you do happen to be interested and write some modules that you would like to share, send them to me and they could end up in a future release if thats what you want and if thats where development heads. If you set the cleanup bit to "on", 4f will try to cleaup the temporary directory of files that did not make the target application crash. After a 4 months of development, the only issue I couldn't get to work right is attaching to a GUI process to get debugging information. If you know how to do this, it would be cool if you let me know. Writing up a debug_win32.c or just using another debugger for fuzzing on Windows systems is probably a good idea, I studied a while on win32 debugging but never got it exactly implemented. Maybe in a future release? If you got something please let me know. 4f could be one of the ideas that went something like, "Wow, that is a good idea but considering it fuzzes locally, how useful could it be, if at all?". Well considering file formats can be shared remotely, not to mention config files, I feel its pretty useful, or at least parts are useful enough to be shared. I would like to thank people around the world for sharing information. Shouts to those who aren't out to hurt other people, those who care about more than themselves, and those who make this world go around without hesitation. 4f can be freely distributed and modified in any way, shape, or form; it is public domain. 4f comes with no warrenty or guaranteed support, but I will try to respond to emails accordingly. Do good, not evil. Enjoy life. Writing documentation is important but time consuming and not always fun, if you have any questions that weren't answered here then feel free to contact me. ------------------------------------------------------------------------------------------------------------------ Associated Files & Information: http://www.krakowlabs.com/dev/fuz/4f/4f http://www.krakowlabs.com/dev/fuz/4f/4f.c.txt http://www.krakowlabs.com/dev/fuz/4f/core.c.txt http://www.krakowlabs.com/dev/fuz/4f/include/core.h.txt http://www.krakowlabs.com/dev/fuz/4f/debug_linux.c.txt http://www.krakowlabs.com/dev/fuz/4f/oracle.c.txt http://www.krakowlabs.com/dev/fuz/4f/include/oracle.h.txt http://www.krakowlabs.com/dev/fuz/4f/mod/dev/bas.c.txt http://www.krakowlabs.com/dev/fuz/4f/mod/dev/ccc.c.txt http://www.krakowlabs.com/dev/fuz/4f/mod/dev/per.c.txt http://www.krakowlabs.com/dev/fuz/4f/mod/mul/m3u.c.txt http://www.krakowlabs.com/dev/fuz/4f/mod/mul/pls.c.txt http://www.krakowlabs.com/dev/fuz/4f/mod/mul/pul.c.txt http://www.krakowlabs.com/dev/fuz/4f/mod/net/tor.c.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/dev/bas.h.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/dev/ccc.h.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/dev/per.h.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/mul/m3u.h.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/mul/pls.h.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/mul/pul.h.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/net/tor.h.txt http://www.krakowlabs.com/dev/fuz/4f/mod/example/exa.c.txt http://www.krakowlabs.com/dev/fuz/4f/include/mod/example/exa.h.txt http://www.krakowlabs.com/dev/fuz/4f/Makefile.txt http://www.krakowlabs.com/dev/fuz/4f/doc/4f_doc.txt http://www.krakowlabs.com/dev/fuz/4f/media/4f.jpeg http://www.krakowlabs.com/dev/fuz/4f/media/4f.avi http://www.krakowlabs.com/dev/fuz/4f/4f.tar.gz 4f_doc.txt