■ ■ ■ ■ ■ ■
detail/BinAbsInspector.md
| | 1 | + | ## BinAbsInspector <https://github.com/KeenSecurityLab/BinAbsInspector> |
| | 2 | + | <!--auto_detail_badge_begin_0b490ffb61b26b45de3ea5d7dd8a582e--> |
| | 3 | + |  |
| | 4 | + |  |
| | 5 | + |  |
| | 6 | + |  |
| | 7 | + |  |
| | 8 | + | <!--auto_detail_badge_end_fef74f2d7ea73fcc43ff78e05b1e7451--> |
| | 9 | + | |
| | 10 | + | # What is BinAbsInspector? |
| | 11 | + | |
| | 12 | + | BinAbsInspector (Binary Abstract Inspector) is a static analyzer for automated reverse engineering and scanning vulnerabilities in binaries, which is a long-term research project incubated at [Keenlab](https://keenlab.tencent.com/). It is based on abstract interpretation with the support from Ghidra. It works on Ghidra's Pcode instead of assembly. Currently it supports binaries on x86,x64, armv7 and aarch64. |
| | 13 | + | |
| | 14 | + | # Installation |
| | 15 | + | + Install Ghidra according to [Ghidra's documentation](https://github.com/NationalSecurityAgency/ghidra#install) |
| | 16 | + | + Install [Z3](https://github.com/Z3Prover/z3) (tested version: 4.8.15) |
| | 17 | + | + Note that generally there are two parts for Z3 library: one is Java package, the other one is native library. The Java package is already included in "/lib" directory, but we suggest that you replace it with your own Java package for version compatibility. |
| | 18 | + | + For Windows, download a pre-built package from [here](https://github.com/Z3Prover/z3/releases), extract the zip file and add a PATH environment variable pointing to `z3-${version}-win/bin` |
| | 19 | + | + For Linux, install with package manager is NOT recommended, there are two options: |
| | 20 | + | 1. You can download suitable pre-build package from [here](https://github.com/Z3Prover/z3/releases), extract the zip file and copy `z3-${version}-win/bin/*.so` to `/usr/local/lib/` |
| | 21 | + | 2. or you can build and install z3 according to [Building Z3 using make and GCC/Clang](https://github.com/Z3Prover/z3#building-z3-using-make-and-gccclang) |
| | 22 | + | + For MacOS, it is similar to Linux. |
| | 23 | + | + Download the extension zip file from [release page](https://github.com/KeenSecurityLab/BinAbsInspector/releases) |
| | 24 | + | + Install the extension according to [Ghidra Extension Notes](https://ghidra-sre.org/InstallationGuide.html#GhidraExtensionNotes) |
| | 25 | + | |
| | 26 | + | # Building |
| | 27 | + | Build the extension by yourself, if you want to develop a new feature, please refer to [development guide](https://github.com/KeenSecurityLab/BinAbsInspector/wiki/Developer-Guide). |
| | 28 | + | + Install Ghidra and Z3 |
| | 29 | + | + Install [Gradle 7.x](https://gradle.org/releases/) (tested version: 7.4) |
| | 30 | + | + Pull the repository |
| | 31 | + | + Run `gradle buildExtension` under repository root |
| | 32 | + | + The extension will be generated at `dist/${GhidraVersion}_${date}_BinAbsInspector.zip` |
| | 33 | + | |
| | 34 | + | # Usage |
| | 35 | + | You can run BinAbsInspector in headless mode, GUI mode, or with docker. |
| | 36 | + | |
| | 37 | + | + With Ghidra headless mode. |
| | 38 | + | ``` |
| | 39 | + | $GHIDRA_INSTALL_DIR/support/analyzeHeadless <projectPath> <projectName> -import <file> -postScript BinAbsInspector "@@<scriptParams>" |
| | 40 | + | ``` |
| | 41 | + | `<projectPath>` -- Ghidra project path. |
| | 42 | + | `<projectName>` -- Ghidra project name. |
| | 43 | + | `<scriptParams>` -- The argument for our analyzer, provides following options: |
| | 44 | + | |
| | 45 | + | | Parameter | Description | |
| | 46 | + | | ----------------------------------------- | --------------------------------------| |
| | 47 | + | | `[-K <kElement>]` | KSet size limit [K](https://github.com/KeenSecurityLab/BinAbsInspector/wiki/Technical-Details#kset) | |
| | 48 | + | | `[-callStringK <callStringMaxLen>]` | Call string maximum length [K](https://github.com/KeenSecurityLab/BinAbsInspector/wiki/Technical-Details#context)| |
| | 49 | + | | `[-Z3Timeout <timeout>]` | Z3 timeout | |
| | 50 | + | | `[-timeout <timeout>]` | Analysis timeout | |
| | 51 | + | | `[-entry <address>]` | Entry address | |
| | 52 | + | | `[-externalMap <file>]` | External function model config | |
| | 53 | + | | `[-json]` | Output in json format | |
| | 54 | + | | `[-disableZ3]` | Disable Z3 | |
| | 55 | + | | `[-all]` | Enable all checkers | |
| | 56 | + | | `[-debug]` | Enable debugging log output | |
| | 57 | + | | `[-check "<cweNo1>[;<cweNo2>...]"]` | Enable specific checkers | |
| | 58 | + | |
| | 59 | + | + With Ghidra GUI |
| | 60 | + | 1. Run Ghidra and import the target binary into a project |
| | 61 | + | 2. Analyze the binary with default settings |
| | 62 | + | 3. When the analysis is done, open `Window -> Script Manager` and find `BinAbsInspector.java` |
| | 63 | + | 4. Double-click on `BinAbsInspector.java` entry, set the parameters in configuration window and click OK |
| | 64 | + | 5. When the analysis is done, you can see the CWE reports in console window, double-click the addresses from the report can jump to corresponding address |
| | 65 | + | |
| | 66 | + | + With Docker |
| | 67 | + | |
| | 68 | + | ```shell |
| | 69 | + | git clone [email protected]:KeenSecurityLab/BinAbsInspector.git |
| | 70 | + | cd BinAbsInspector |
| | 71 | + | docker build . -t bai |
| | 72 | + | docker run -v $(pwd):/data/workspace bai "@@<script parameters>" -import <file> |
| | 73 | + | ``` |
| | 74 | + | |
| | 75 | + | # Implemented Checkers |
| | 76 | + | So far BinAbsInspector supports following checkers: |
| | 77 | + | |
| | 78 | + | + [CWE78](https://cwe.mitre.org/data/definitions/78.html) (OS Command Injection) |
| | 79 | + | + [CWE119](https://cwe.mitre.org/data/definitions/119.html) (Buffer Overflow (generic case)) |
| | 80 | + | + [CWE125](https://cwe.mitre.org/data/definitions/125.html) (Buffer Overflow (Out-of-bounds Read)) |
| | 81 | + | + [CWE134](https://cwe.mitre.org/data/definitions/134.html) (Use of Externally-Controlled Format string) |
| | 82 | + | + [CWE190](https://cwe.mitre.org/data/definitions/190.html) (Integer overflow or wraparound) |
| | 83 | + | + [CWE367](https://cwe.mitre.org/data/definitions/367.html) (Time-of-check Time-of-use (TOCTOU)) |
| | 84 | + | + [CWE415](https://cwe.mitre.org/data/definitions/415.html) (Double free) |
| | 85 | + | + [CWE416](https://cwe.mitre.org/data/definitions/416.html) (Use After Free) |
| | 86 | + | + [CWE426](https://cwe.mitre.org/data/definitions/426.html) (Untrusted Search Path) |
| | 87 | + | + [CWE467](https://cwe.mitre.org/data/definitions/467.html) (Use of sizeof() on a pointer type) |
| | 88 | + | + [CWE476](https://cwe.mitre.org/data/definitions/476.htmll) (NULL Pointer Dereference) |
| | 89 | + | + [CWE676](https://cwe.mitre.org/data/definitions/676.html) (Use of Potentially Dangerous Function) |
| | 90 | + | + [CWE787](https://cwe.mitre.org/data/definitions/787.html) (Buffer Overflow (Out-of-bounds Write)) |
| | 91 | + | |
| | 92 | + | # Project Structure |
| | 93 | + | The structure of this project is as follows, please refer to [technical details](https://github.com/KeenSecurityLab/BinAbsInspector/wiki/Technical-Details) for more details. |
| | 94 | + | ``` |
| | 95 | + | ├── main |
| | 96 | + | │ ├── java |
| | 97 | + | │ │ └── com |
| | 98 | + | │ │ └── bai |
| | 99 | + | │ │ ├── checkers checker implementatiom |
| | 100 | + | │ │ ├── env |
| | 101 | + | │ │ │ ├── funcs function modeling |
| | 102 | + | │ │ │ │ ├── externalfuncs external function modeling |
| | 103 | + | │ │ │ │ └── stdfuncs cpp std modeling |
| | 104 | + | │ │ │ └── region memory modeling |
| | 105 | + | │ │ ├── solver analyze core and grpah module |
| | 106 | + | │ │ └── util utilities |
| | 107 | + | │ └── resources |
| | 108 | + | └── test |
| | 109 | + | ``` |
| | 110 | + | You can also build the javadoc with `gradle javadoc`, the API documentation will be generated in `./build/docs/javadoc`. |
| | 111 | + | |
| | 112 | + | # Acknowledgement |
| | 113 | + | We employ [Ghidra](https://ghidra-sre.org/) as our foundation and frequently leverage [JImmutable Collections](http://brianburton.github.io/java-immutable-collections/) for better performance. |
| | 114 | + | Here we would like to thank them for their great help! |
| | 115 | + | |
| | 116 | + | |
| | 117 | + | |
| | 118 | + | <!--auto_detail_active_begin_e1c6fb434b6f0baf6912c7a1934f772b--> |
| | 119 | + | ## 项目相关 |
| | 120 | + | |
| | 121 | + | |
| | 122 | + | ## 最近更新 |
| | 123 | + | |
| | 124 | + | <!--auto_detail_active_end_f9cf7911015e9913b7e691a7a5878527--> |
| | 125 | + | |
