{"id":13419381,"url":"https://github.com/ucsb-seclab/dr_checker","last_synced_at":"2025-03-15T05:31:06.397Z","repository":{"id":40636917,"uuid":"92881927","full_name":"ucsb-seclab/dr_checker","owner":"ucsb-seclab","description":"DR.CHECKER : A Soundy Vulnerability Detection Tool for Linux Kernel Drivers","archived":false,"fork":false,"pushed_at":"2022-04-30T02:34:23.000Z","size":1024,"stargazers_count":331,"open_issues_count":15,"forks_count":71,"subscribers_count":20,"default_branch":"speedy","last_synced_at":"2024-07-31T22:47:36.264Z","etag":null,"topics":["kernel","kernel-driver","llvm","vulnerability-detection","vulnerability-scanners"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ucsb-seclab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-30T22:34:02.000Z","updated_at":"2024-04-24T03:50:21.000Z","dependencies_parsed_at":"2022-07-20T13:48:02.433Z","dependency_job_id":null,"html_url":"https://github.com/ucsb-seclab/dr_checker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsb-seclab%2Fdr_checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsb-seclab%2Fdr_checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsb-seclab%2Fdr_checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsb-seclab%2Fdr_checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ucsb-seclab","download_url":"https://codeload.github.com/ucsb-seclab/dr_checker/tar.gz/refs/heads/speedy","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243690113,"owners_count":20331726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kernel","kernel-driver","llvm","vulnerability-detection","vulnerability-scanners"],"created_at":"2024-07-30T22:01:15.166Z","updated_at":"2025-03-15T05:31:06.392Z","avatar_url":"https://github.com/ucsb-seclab.png","language":"C++","funding_links":[],"categories":["TODO scan for Android support in followings","\u003ca id=\"683b645c2162a1fce5f24ac2abfa1973\"\u003e\u003c/a\u003e漏洞\u0026\u0026漏洞管理\u0026\u0026漏洞发现/挖掘\u0026\u0026漏洞开发\u0026\u0026漏洞利用\u0026\u0026Fuzzing","Starchart"],"sub_categories":["功能"],"readme":"DR.CHECKER : A Soundy Vulnerability Detection Tool for Linux Kernel Drivers\n===================\n\n[![License](https://img.shields.io/github/license/angr/angr.svg)](https://github.com/ucsb-seclab/dr_checker/blob/master/LICENSE)\n\n![warning](https://raw.githubusercontent.com/ucsb-seclab/dr_checker/speedy/images/warning.png)\n\nThis repo contains all the sources, including setup scripts. \nNow with an Amazing UI to view the warnings along with corresponding source files.\n### Tested on\nUbuntu \u003e= 14.04.5 LTS\n### Announcements\n**16 Feb 2018**:\n* DR.CHECKER has been dockerized. Refer [Docker Usage](https://github.com/ucsb-seclab/dr_checker/blob/speedy/docs/docker.md) on how to use it.\n\n## [Frequently Asked Questions](https://github.com/ucsb-seclab/dr_checker/blob/master/docs/faq.md)\n\n## 0. Using Dockerized Setup (Recommended)\nRefer the [Docker Usage](https://github.com/ucsb-seclab/dr_checker/blob/speedy/docs/docker.md) document for details on how to use DR.CHECKER in a pre-built docker container.\n\n## 1. Setup\nOur implementation is based on LLVM, specifically LLVM 3.8. We also need tools like `c2xml` to parse headers.\n\nFirst, make sure that you have cmake (used by setup/build scripts) and libxml (required for c2xml):\n```\nsudo apt-get install cmake libxml2-dev\n```\n\nNext, We have created a single script, which downloads and builds all the required tools.\n```\ncd helper_scripts\npython setup_drchecker.py --help\nusage: setup_drchecker.py [-h] [-b TARGET_BRANCH] [-o OUTPUT_FOLDER]\n\noptional arguments:\n  -h, --help        show this help message and exit\n  -b TARGET_BRANCH  Branch (i.e. version) of the LLVM to setup. Default:\n                    release_38 e.g., release_38\n  -o OUTPUT_FOLDER  Folder where everything needs to be setup.\n\n```\nExample:\n```\npython setup_drchecker.py -o drchecker_deps\n```\nTo complete the setup you also need modifications to your local `PATH` environment variable. The setup script will give you exact changes you need to do.\n## 2. Building\nThis depends on the successful completion of [Setup](#markdown-header-setup).\nWe have a single script that builds everything, you are welcome.\n```\ncd llvm_analysis\n./build.sh\n```\n## 3. Running\nThis depends on the successful completion of [Build](#markdown-header-building).\nTo run DR.CHECKER on kernel drivers, we need to first convert them into llvm bitcode.\n### 3.1 Building kernel\nFirst, we need to have a buildable kernel. Which means you should be able to compile the kernel using regular build setup. i.e., `make`.\nWe first capture the output of `make` command, from this output we extract the exact compilation command.\n#### 3.1.1 Generating output of `make` (or `makeout.txt`)\n\nJust pass `V=1` and redirect the output to the file.\nExample:\n```\nmake V=1 O=out ARCH=arm64 \u003e makeout.txt 2\u003e\u00261\n```\nNOTE: DO NOT USE MULTIPLE PROCESSES i.e., `-j`. Running in multi-processing mode will mess up the output file as multiple process try to write to the output file.\n\nThat's it. DR.CHECKER will take care from here.\n### 3.2 Running DR.CHECKER analysis\nThere are several steps to run DR.CHECKER analysis, all these steps are wrapped in a single script `helper_scripts/runner_scripts/run_all.py`\nHow to run:\n```\npython run_all.py --help\nusage: run_all.py [-h] [-l LLVM_BC_OUT] [-a CHIPSET_NUM] [-m MAKEOUT] [-g COMPILER_NAME] [-n ARCH_NUM] [-o OUT] [-k KERNEL_SRC_DIR] [-skb] [-skl] [-skp] [-ske] [-ski] [-f SOUNDY_ANALYSIS_OUT]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -l LLVM_BC_OUT        Destination directory where all the generated bitcode files should be stored.\n  -a CHIPSET_NUM        Chipset number. Valid chipset numbers are:\n                        1(mediatek)|2(qualcomm)|3(huawei)|4(samsung)\n  -m MAKEOUT            Path to the makeout.txt file.\n  -g COMPILER_NAME      Name of the compiler used in the makeout.txt, This is\n                        needed to filter out compilation commands. Ex: aarch64-linux-android-gcc\n  -n ARCH_NUM           Destination architecture, 32 bit (1) or 64 bit (2).\n  -o OUT                Path to the out folder. This is the folder, which\n                        could be used as output directory during compiling\n                        some kernels. (Note: Not all kernels needs a separate out folder)\n  -k KERNEL_SRC_DIR     Base directory of the kernel sources.\n  -skb                  Skip LLVM Build (default: not skipped).\n  -skl                  Skip Dr Linker (default: not skipped).\n  -skp                  Skip Parsing Headers (default: not skipped).\n  -ske                  Skip Entry point identification (default: not\n                        skipped).\n  -ski                  Skip Soundy Analysis (default: not skipped).\n  -f SOUNDY_ANALYSIS_OUT    Path to the output folder where the soundy analysis output should be stored.\n\n```\nThe script builds, links and runs DR.CHECKER on all the drivers, as such might take **considerable time(45 min-90 min)**. If you want to run DR.CHECKER manually on individual drivers, refer [standalone](https://github.com/ucsb-seclab/dr_checker/tree/master/docs/standalone.md)\n\nThe above script performs following tasks in a multiprocessor mode to make use of all CPU cores:\n#### 3.2.1. LLVM Build \n* Enabled by default.\n\nAll the bitcode files generated will be placed in the folder provided to the argument `-l`.\nThis step takes considerable time, depending on the number of cores you have. \nSo, if you had already done this step, You can skip this step by passing `-skb`. \n#### 3.2.2. Linking all driver bitcode files in s consolidated bitcode file.\n* Enabled by default\n\nThis performs linking, it goes through all the bitcode files and identifies the related bitcode files that need to be linked and links them (using `llvm-link`) in to a consolidated bitcode file (which will be stored along side corresponding bitcode file).\n\nSimilar to the above step, you can skip this step by passing `-skl`.\n#### 3.2.3.Parsing headers to identify entry function fields.\n* Enabled by default.\n\nThis step looks for the entry point declarations in the header files and stores their configuration in the file: `hdr_file_config.txt` under LLVM build directory.\n\nTo skip: `-skp`\n#### 3.2.4.Identify entry points in all the consolidated bitcode files.\n* Enabled by default\n\nThis step identifies all the entry points across all the driver consolidated bitcode files.\nThe output will be stored in file: `entry_point_out.txt` under LLVM build directory.\n\nExample of contents in the file `entry_point_out.txt`:\n```\nFileRead:hidraw_read:/home/drchecker/33.2.A.3.123/llvm_bc_out/drivers/hid/llvm_link_final/final_to_check.bc\nFileWrite:hidraw_write:/home/drchecker/33.2.A.3.123/llvm_bc_out/drivers/hid/llvm_link_final/final_to_check.bc\nIOCTL:hidraw_ioctl:/home/drchecker/33.2.A.3.123/llvm_bc_out/drivers/hid/llvm_link_final/final_to_check.bc\n```\nTo skip: `-ske`\n#### 3.2.5.Run Soundy Analysis on all the identified entry points.\n* Enabled by default.\n\nThis step will run DR.CHECKER on all the entry points in the file `entry_point_out.txt`. The output for each entry point will be stored in the folder provided for option `-f`.\n\nTo skip: `-ski`\n#### 3.2.6 Example:\nNow, we will show an example from the point where you have kernel sources to the point of getting vulnerability warnings.\n\nWe have uploaded a mediatek kernel [33.2.A.3.123.tar.bz2](https://drive.google.com/file/d/0B4XwT5D6qkNmLXdNTk93MjU3SWM/view?usp=sharing\u0026resourcekey=0-cb1ceDme5Fi2xugS7nYl7w). \nFirst download and extract the above file.\n\nLets say you extracted the above file in a folder called: `~/mediatek_kernel`\n\n##### 3.2.6.1 Building\n```\ncd ~/mediatek_kernel\nsource ./env.sh\ncd kernel-3.18\n# the following step may not be needed depending on the kernel\nmkdir out\nmake O=out ARCH=arm64 tubads_defconfig\n# this following command copies all the compilation commands to makeout.txt\nmake V=1 -j8 O=out ARCH=arm64 \u003e makeout.txt 2\u003e\u00261\n```\n##### 3.2.6.2 Running DR.CHECKER\n```\ncd \u003crepo_path\u003e/helper_scripts/runner_scripts\n\npython run_all.py -l ~/mediatek_kernel/llvm_bitcode_out -a 1 -m ~/mediatek_kernel/kernel-3.18/makeout.txt -g aarch64-linux-android-gcc -n 2 -o ~/mediatek_kernel/kernel-3.18/out -k ~/mediatek_kernel/kernel-3.18 -f ~/mediatek_kernel/dr_checker_out\n```\nThe above command takes quite **some time (30 min - 1hr)**.\n##### 3.2.6.3 Understanding the output\nFirst, all the analysis results will be in the folder: **`~/mediatek_kernel/dr_checker_out` (argument given to the option `-f`)**, for each entry point a `.json` file will be created which contains all the warnings in JSON format. These `json` files contain warnings organized by contexts. \n\nSecond, The folder **`~/mediatek_kernel/dr_checker_out/instr_warnings` (w.r.t argument given to the option `-f`)** contains warnings organized by instruction location.\n\nThese warnings could be analyzed using our [Visualizer](https://github.com/ucsb-seclab/dr_checker/tree/speedy/visualizer).\n\nFinally, a summary of all the warnings for each entry point organized by the type will be written to the output CSV file: **`~/mediatek_kernel/dr_checker_out/warnings_stats.csv` (w.r.t argument given to the option `-f`)**.\n\n#### 3.2.7 Things to note:\n##### 3.2.7.1 Value for option `-g`\nTo provide value for option `-g` you need to know the name of the `*-gcc` binary used to compile the kernel.\nAn easy way to know this would be to `grep` for `gcc` in `makeout.txt` and you will see compiler commands from which you can know the `*-gcc` binary name.\n\nFor our example above, if you do `grep gcc makeout.txt` for the example build, you will see lot of lines like below:\n```\naarch64-linux-android-gcc -Wp,-MD,fs/jbd2/.transaction.o.d  -nostdinc -isystem ...\n```\nSo, the value for `-g` should be `aarch64-linux-android-gcc`. \n\nIf the kernel to be built is 32-bit then the binary most likely will be `arm-eabi-gcc`\n\n##### 3.2.7.2 Value for option `-a`\nDepeding on the chipset type, you need to provide corresponding number.\n\n##### 3.2.7.3 Value for option `-o`\nThis is the path of the folder provided to the option `O=` for `make` command during kernel build.\n\nNot all kernels need a separate out path. You may build kernel by not providing an option `O`, in which case you SHOULD NOT provide value for that option while running `run_all.py`.\n\n### 3.3 Visualizing DR.CHECKER results :snowflake:\nWe provide a web-based UI to view all the warnings. Please refer [Visualization](https://github.com/ucsb-seclab/dr_checker/tree/speedy/visualizer).\n\n### 3.6 Disabling Vulnerability checkers\nYou can disable one or more vulnerability checkers by uncommenting the corresponding `#define DISABLE_*` lines in [BugDetectorDriver.cpp](https://github.com/ucsb-seclab/dr_checker/blob/speedy/llvm_analysis/MainAnalysisPasses/SoundyAliasAnalysis/src/bug_detectors/BugDetectorDriver.cpp#L19)\n\n### 3.5 Post-processing DR.CHECKER results\nTo your liking, we also provide a script to post-process the results. [Check it out](https://github.com/ucsb-seclab/dr_checker/blob/master/docs/postprocessing.md).\n\nHave fun!!\n\n## 4. Contact\n* Slack: [JOIN SLACK CHANNEL](https://join.slack.com/t/driverchecking/shared_invite/enQtNDI3NDgyOTI4MTM1LTk3NTc4OWIxZTQyZjljNzkzMGM4YjczZjI4OTY0ODgyMmY1MWZmM2ZhZGM2OWY0NTMwOWQ5MmZjNzExMTQwODQ)\n* Aravind Machiry (machiry@cs.ucsb.edu)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucsb-seclab%2Fdr_checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucsb-seclab%2Fdr_checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucsb-seclab%2Fdr_checker/lists"}