Fixes to make the module work

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=<uid> --build-arg GROUP_ID=<guid> --tag aflplusplus -f docker/Dockerfile.aflplusplus .`, where `<uid>` and `<guid>` 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=<uid> --build-arg GROUP_ID=<guid> --tag aflplusplus -f docker/Dockerfile.aflplusplus .
+   ```
+   where `<uid>` and `<guid>` 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.

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"

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 *~

samples/stdin_bof.c

@@ -0,0 +1,10 @@
+#include <stdio.h>
+
+int main(void)
+{
+	char buf[8];
+
+	fgets(buf, 128, stdin);
+
+	return 0;
+}