diff --git a/README.md b/README.md old mode 100755 new mode 100644 index b891321..56ef62e --- a/README.md +++ b/README.md @@ -8,10 +8,10 @@ - [Setup](#setup) - [Usage](#usage) - [As a CLI Tool](#as-a-cli-tool) - - [Fuzzing Files](#fuzzing-files) - - [Fuzzing Standard Input](#fuzzing-standard-input) - - [Fuzzing Arguments](#fuzzing-arguments) - - [Help](#help) + - [Fuzz Files](#fuzz-files) + - [Fuzz Standard Input](#fuzz-standard-input) + - [Fuzz Arguments](#fuzz-arguments) + - [Get Help](#get-help) - [As a Python Module](#as-a-python-module) --- @@ -27,27 +27,103 @@ ## How It Works -All implemented fuzzers automate AFL++, starting from the official Docker container. The standard input and the files one use the off-the-shelf functionality. +All implemented fuzzers automate AFL++, starting from the official Docker container. +The standard input and the files one use the off-the-shelf functionality. -The arguments fuzzer adapts the standard input fuzzer using a custom C adapter. The latter received the generated input and instantiate a format string that is passed as argument. The result is then injected in the `argv` of the fuzzed program. +The arguments fuzzer adapts the standard input fuzzer using a custom C adapter. +The latter received the generated input and instantiate a format string that is passed as argument. +The result is then injected in the `argv` of the fuzzed program. ## Setup -1. Ensure you have Docker installed. -2. Install the required Python 3 packages via `poetry install --no-dev`. -3. Build the Docker image: `sudo docker build --build-arg USER_ID= --build-arg GROUP_ID= --tag aflplusplus -f docker/Dockerfile.aflplusplus .`, where `` and `` are the individual and group IDs of the current user. -4. Ensure the Docker API is accessible by: + +1. Make sure you have set up the repositories and Python environment according to the [top-level instructions](https://github.com/open-crs#requirements). + That is: + + - Docker is installed and is properly running. + Check using: + + ```console + docker version + docker ps -a + docker run --rm hello-world + ``` + + These commands should run without errors. + + - The current module repository and all other module repositories (particularly the [`dataset` repository](https://github.com/open-crs/dataset) and the [`commons` repository](https://github.com/open-crs/commons)) are cloned in the same directory. + + - You are running all commands inside a Python virtual environment. + There should be `(.venv)` prefix to your prompt. + + - You have installed Poetry in the virtual environment. + If you run: + + ```console + which poetry + ``` + + you should get a path ending with `.venv/bin/poetry`. + +1. Disable the Python Keyring: + + ```console + export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring + ``` + + This is a problem that may occur in certain situations, preventing Poetry from getting packages. + +1. Install the required packages with Poetry (based on `pyprojects.toml`): + + ```console + poetry install --only main + ``` + +1. Build the Docker image: + + ```console + docker build --build-arg USER_ID= --build-arg GROUP_ID= --tag aflplusplus -f docker/Dockerfile.aflplusplus . + ``` + where `` and `` are the individual and group IDs of the current user. + +1. Ensure the Docker API is accessible by: + - Running the module as `root`; or - - Changing the Docker socket permissions (unsecure approach) via `chmod 777 /var/run/docker.sock`. -5. Build the arguments' adapter via `cd argv_adapter && make`. + - Changing the Docker socket permissions (unsecure approach) via: + + ```console + sudo chmod 777 /var/run/docker.sock + ``` + +1. Build the arguments adapter via: + + ```console + cd argv_adapter && make + ``` ## Usage +You can use the `vulnerability_detection` module either standalone, as a CLI tool, or integrated into Python applications, as a Python module. + ### As a CLI Tool -#### Fuzzing Files +As a CLI tool, you can either use the `cli.py` module: + +```console +vulnerability_detection/cli.py +``` + +or the Poetry interface: + +```console +poetry run vulnerability_detection +``` + +At the moment only `Fuzz Standard Input` works. + +#### Fuzz Files -```bash +```console ➜ poetry run vulnerability_detection fuzz --fuzzer FILES_AFLPLUSPLUS --stream FILES --elf file_bof.elf --samples samples --arguments "--file" New proof of vulnerability was generated with the following payloads: @@ -56,10 +132,10 @@ New proof of vulnerability was generated with the following payloads: 00000000: 79 80 80 y.. ``` -#### Fuzzing Standard Input +#### Fuzz Standard Input -```bash -➜ poetry run vulnerability_detection fuzz --fuzzer STDIN_AFLPLUSPLUS --stream STDIN --elf stdin_bof.elf --samples samples +```console +➜ poetry run vulnerability_detection fuzz --fuzzer STDIN_AFLPLUSPLUS --stream STDIN --elf stdin_bof.elf --samples samples New proof of vulnerability was generated with the following payloads: - For STDIN: @@ -68,9 +144,9 @@ New proof of vulnerability was generated with the following payloads: 00000010: 6B 6D km ``` -#### Fuzzing Arguments +#### Fuzz Arguments -```bash +```console ➜ poetry run vulnerability_detection fuzz --fuzzer ARGS_AFLPLUSPLUS --stream ARGUMENTS --elf argv_null_deref.elf --samples samples --arguments "--string %s" New proof of vulnerability was generated with the following payloads: @@ -79,10 +155,10 @@ New proof of vulnerability was generated with the following payloads: 00000000: 73 1D 0A AC 61 20 0A 00 s...a .. ``` -#### Help +#### Get Help -```bash -➜ poetry run vulnerability_detection +```console +➜ poetry run vulnerability_detection Usage: vulnerability_detection [OPTIONS] COMMAND [ARGS]... Discovers vulnerabilities in executables. diff --git a/pyproject.toml b/pyproject.toml old mode 100755 new mode 100644 index fdb67ed..96c945a --- a/pyproject.toml +++ b/pyproject.toml @@ -5,11 +5,13 @@ authors = ["OpenCRS"] version = "0.1.0" [tool.poetry.dependencies] +commons = { path = "../commons", develop = false } python = "^3.12" docker = "^6.1.2" hexdump = "^3.3" click = "^8.1.3" rich = "^12.5.1" +requests = "2.31.0" [tool.poetry.dev-dependencies] black = "^22.6.0" diff --git a/samples/Makefile b/samples/Makefile new file mode 100644 index 0000000..ca0965c --- /dev/null +++ b/samples/Makefile @@ -0,0 +1,12 @@ +TARGET = stdin_bof + +.PHONY: all clean + +all: $(TARGET) + +$(TARGET): $(TARGET).c + gcc -m32 -o $@ $^ + +clean: + -rm -f $(TARGET) + -rm -f *~ diff --git a/samples/stdin_bof b/samples/stdin_bof new file mode 100755 index 0000000..8bee398 Binary files /dev/null and b/samples/stdin_bof differ diff --git a/samples/stdin_bof.c b/samples/stdin_bof.c new file mode 100644 index 0000000..f4eefb4 --- /dev/null +++ b/samples/stdin_bof.c @@ -0,0 +1,10 @@ +#include + +int main(void) +{ + char buf[8]; + + fgets(buf, 128, stdin); + + return 0; +}