diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/headerparser_usage.md | 65 | ||||
| -rw-r--r-- | docs/syscall_descriptions.md | 2 |
2 files changed, 67 insertions, 0 deletions
diff --git a/docs/headerparser_usage.md b/docs/headerparser_usage.md new file mode 100644 index 000000000..3bea38dbd --- /dev/null +++ b/docs/headerparser_usage.md @@ -0,0 +1,65 @@ +## Headerparser + +headerparser is a tool that assists in writing device system call descriptions for syzkaller. + +In order to make syzkaller smarter when it comes to fuzzing a device node, you can provide it with +information about the ioctl argument struct types it expects. + +However, in certain cases the number of argument struct types might be high, increasing the amount of manual +effort that goes into writing the description files for the struct types. + +In order to ease the effort of writing ioctl argument type description files, headerlib does a best-effort job at generating them for you. You will still need to manually select the appropriate syzkaller data type from the list of types [here](https://github.com/google/syzkaller/blob/master/docs/syscall_descriptions_syntax.md). + +## Dependencies +Headerlib uses pycparser. You can install pycparser using pip. + +```shell +$ pip install pycparser +``` + +## Using headerparser +```shell +$ python headerparser.py --device th_b --filenames=./test_headers/th_b.h +B { + B1 len|fileoff|flags|intN #(unsigned long) + B2 len|fileoff|flags|intN #(unsigned long) +} +struct_containing_union { + something len|fileoff|flags|int32 #(int) + a_union.a_char ptr[in|out, string]|ptr[in, filename] #(char*) + a_union.B_ptr ptr|buffer|array #(struct B*) +} +``` + +You can copy paste the content underneath the `Structure Metadata` over to your syzkaller device description. + +## Something breaks +Let us try parsing `test_headers/th_a.h` header file to generate argument structs. + +```shell +$ python headerparser.py --device th_a --filenames=./test_headers/th_a.h +ERROR:root:HeaderFilePreprocessorException: /tmp/tmpW8xzty/source.o:36:2: before: some_type + +$ python headerparser.py --filenames=./test_headers/th_a.h --debug +DEBUG:GlobalHierarchy:load_header_files : ['./test_headers/th_a.h'] +DEBUG:HeaderFilePreprocessor:HeaderFilePreprocessor._mktempfiles: sourcefile=/tmp/tmpbBQYhR/source.cobjectfile=/tmp/tmpbBQYhR/source.o +DEBUG:HeaderFilePreprocessor:HeaderFilePreprocessor.execute: cp ./test_headers/th_a.h /tmp/tmpbBQYhR +DEBUG:HeaderFilePreprocessor:HeaderFilePreprocessor.execute: gcc -I. -E -P -c /tmp/tmpbBQYhR/source.c > /tmp/tmpbBQYhR/source.o +ERROR:root:HeaderFilePreprocessorException: /tmp/tmpbBQYhR/source.o:36:2: before: some_type +``` + +From the error message, we can see that the error occurs as pycparser is not aware of the type `some_type`. We can resolve this by making pycparser aware of the unknown type. In order to do this, we supply headerparser with a include file that contains C declarations and includes that can fix the parse error. + +```shell +$ cat > include_file +typedef int some_type; +$ python headerparser.py --filenames=./test_headers/th_a.h --include=./include_file +A { + B_item ptr|buffer|array #(struct B*) + char_ptr ptr[in|out, string]|ptr[in, filename] #(char*) + an_unsigned_int len|fileoff|int32 #(unsigned int) + a_bool _Bool #(_Bool) + another_bool _Bool #(_Bool) + var some_type #(some_type) +} +```
\ No newline at end of file diff --git a/docs/syscall_descriptions.md b/docs/syscall_descriptions.md index 0c0041343..3fd5de919 100644 --- a/docs/syscall_descriptions.md +++ b/docs/syscall_descriptions.md @@ -64,3 +64,5 @@ Then, run `make generate` which will update generated code. Rebuild syzkaller (`make clean all`) to force use of the new system call definitions. Optionally, adjust the `enable_syscalls` configuration value for syzkaller to specifically target the new system calls. + +In order to partially auto-generate system call descriptions you can use [headerparser](headerparser_usage.md). |