Improve README instructions

Signed-off-by: Amalia Ionescu <[email protected]>

Author: AmaliaI12

README.md

@@ -1,4 +1,4 @@
-# `automatic_exploit_generation` 💎
+:# `automatic_exploit_generation` 💎
 
 ---
 
@@ -9,9 +9,9 @@
 - [Development](#development)
 - [Usage](#usage)
   - [As a CLI Tool](#as-a-cli-tool)
-    - [Recommending Exploiters to Use](#recommending-exploiters-to-use)
-    - [Exploiting a Binary](#exploiting-a-binary)
-    - [Help](#help)
+    - [Recommend Exploiters to Use](#recommend-exploiters-to-use)
+    - [Exploit a Binary](#exploit-a-binary)
+    - [Get Help](#get-help)
   - [As a Python Module](#as-a-python-module)
 
 ---
@@ -31,31 +31,80 @@ With the input streams, mitigations, and vulnerabilities for the executable to e
 
 ## Setup
 
-1. Ensure you have Docker installed.
-2. Install the required Python 3 packages via `poetry install --no-dev`.
-3. Build the Docker image: `docker build --tag zeratool_lib -f docker/Dockerfile.zeratool_lib .`.
-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 [`zeratool_lib` repository](https://github.com/open-crs/zeratool_lib) 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 --tag zeratool_lib -f docker/Dockerfile.zeratool_lib .
+   ```
+
+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 others/argv_adapter && make`.
+   - Changing the Docker socket permissions (unsecure approach) via `sudo chmod 777 /var/run/docker.sock`.
+
+1. Build the arguments' adapter via `cd others/argv_adapter && make`.
 
 ## Development
 
-If you make modifications to the Protobuf definition, please regenerate the Python sources with `poetry run python3 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. ./automatic_exploit_generation/exploiters/zeratool/protobuf/exploit.proto`.
+If you make modifications to the Protobuf definition, please regenerate the Python sources with 
+    ```console
+        poetry run python3 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. 
+        ./automatic_exploit_generation/exploiters/zeratool/protobuf/exploit.proto
+    ```
 
 ## Usage
 
 ### As a CLI Tool
 
-#### Recommending Exploiters to Use
+#### Recommend Exploiters to Use
 
 ```bash
 ➜ poetry run automatic_exploit_generation recommend  --elf=key-manager.elf --stream=STDIN --mitigation=NX --weakness=STACK_OUT_OF_BOUND_WRITE
 Exploiters that can be used considering the context are:
 - ZERATOOL
 ```
 
-#### Exploiting a Binary
+#### Exploit a Binary
 
 ```bash
 ➜ poetry run automatic_exploit_generation exploit --exploiter=ZERATOOL --elf=key-manager.elf --stream=STDIN --mitigation=NX --weakness=STACK_OUT_OF_BOUND_WRITE
@@ -69,7 +118,7 @@ The exploiter could generate an exploit with the outcome of DENIAL_OF_SERVICE an
 00000000: 61 61 61 61 61 61 61 61                           aaaaaaaa
 ```
 
-#### Help
+#### Get help
 
 ```bash
 ➜ poetry run automatic_exploit_generation