doc: migration to zensical

Signed-off-by: Eloïse Brocas <ebrocas@quarkslab.com>

Author: ebrocas

README.md

@@ -16,7 +16,12 @@
 </p>
 
 
-Pyrrha is a filesystem cartography and correlation software focusing on visualization. It currently focuses on the relationship between executable files but aims at enabling anyone to map and visualize any relationship types. It uses the open-source code source
+Pyrrha is a firmware cartography tool which provide three level of details: 
+- an overview of the import/export relationships between executables;
+-  a firmware-wide callgraph;
+- a complete map of a given decompiled binary.
+
+It uses the open-source code source
 explorer [NumbatUI](https://github.com/quarkslab/NumbatUI) to provide users with an easy way to navigate through and search for 
 path to function.
  <!-- # --8<-- [end:intro]-->

docs/index.md

@@ -1,3 +1,7 @@
+---
+title: Home
+---
+
 --8<-- "README.md:intro"
 
 <div class="grid cards" markdown>
@@ -10,7 +14,13 @@
 ## Installation
 
 
-??? code "Install Visualisation Tool"
+!!! note "Install Visualisation Tool"
+
+    === "NumbatUI (Ubuntu/Debian)"
+
+        For Debian like distribution, download the [`.deb`](https://github.com/quarkslab/NumbatUI/releases) package and install it on your system (`sudo dpkg -i numbatui.deb`)
+
+        For other systems, you can also compile it manually or use a Docker, check [NumbatUI documentation](https://quarkslab.github.io/NumbatUI/installation/) for further details.
 
     === "Sourcetrail"
 
@@ -39,34 +49,8 @@
 
             Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), and install it following [Sourcetrail documentation](https://github.com/CoatiSoftware/Sourcetrail/releases).
 
-
-    === "NumbatUI (Ubuntu/Debian)"
-
-        _Tested only for last Ubuntu/Debian._
-
-        Run the following script that will clone and build `NumbatUI` and install `Pyrrha`. `NumbatUI` executable will  be in `numbatui/build/Release/app`.
-
-        ```sh
-        # Prerequisites for Numbat UI
-        sudo apt-get update
-        sudo apt-get install -y \
-                    cmake \
-                    git \
-                    build-essential \
-                    libboost-filesystem-dev libboost-program-options-dev libboost-system-dev libboost-date-time-dev \
-                    qt6-svg-dev qt6-base-dev qt6-5compat-dev \
-                    unzip wget \
-                    libclang-17-dev clang-17
-
-        # Clone and Build NumbatUI
-        git clone https://github.com/quarkslab/NumbatUI.git numbatui 
-        cd numbatui
-        mkdir -p build/Release 
-        cd build/Release
-        cmake -DCMAKE_BUILD_TYPE="Release" -DBUILD_CXX_LANGUAGE_PACKAGE=ON -DBUILD_PYTHON_LANGUAGE_PACKAGE=ON ../.. && make NumbatUI -j $(nproc)
-        ```
-
-!!! code "Install Pyrrha"
+    
+!!! note "Install Pyrrha"
     === ":fontawesome-brands-python: Python Package"
         Require a local installation of **IDA Pro 9.1+** and/or **Ghidra 12.0+**  except for `fs` mapper.
         ```python
@@ -81,12 +65,12 @@
         ```
 
 
-!!! note
+!!! info
     Detailed instructions can be found on the [dedicated documentation page](installation.md).
 
 --8<-- "README.md:usage"
 
-!!! code "Run Pyrrha"
+!!! note "Run Pyrrha"
     === ":fontawesome-brands-python: Python Package"
         If your backend is not on  `PATH`, indicate its directory using the matching environment variable.
         ```sh
@@ -106,14 +90,14 @@
         docker run  --rm -t -v $PWD:/tmp/pyrrha ghcr.io/quarkslab/pyrrha:latest MAPPER [OPTIONS] ROOT_DIRECTORY
         ```
 
-!!! code "Visualize results"
+!!! note "Visualize results"
     You should have a `*.srctrlprj` file corresponding to the project file and a `*.srctrldb` file for the DB. 
     Run `NumbatUI` or `Sourcetrail` on the project file. You can now navigate into the results.
 
     The user interface is described in depth in the [NumbatUI documentation](https://github.com/quarkslab/NumbatUI/blob/main/DOCUMENTATION.md#user-interface).
     Do not hesitate to take a look at  all the possibilities offered by NumbatUI, especially [Custom Trails](https://github.com/quarkslab/NumbatUI/blob/main/DOCUMENTATION.md#custom-trail-dialog).
-!!! note
-    The detailed documentation of each mapper is available in the [documentation](mappers/mappers.md).
+!!! info
+    The detailed documentation of each mapper is available in the [documentation](mappers/index.md).
 
 --8<-- "README.md:publications"
 --8<-- "README.md:authors"

docs/installation.md

@@ -10,89 +10,72 @@ The installation is done in three parts:
 
 ## Pyrrha Installation
 
-=== ":fontawesome-brands-python: Python Package"
-    **Pyrrha** relies on a backend (IDA or Ghidra) to generate its results, except for the light mapper `fs`. This installation is not covered here, we consider the following prerequisites:
+!!! note ""
+    === ":fontawesome-brands-python: Python Package"
+        **Pyrrha** relies on a backend (IDA or Ghidra) to generate its results, except for the light mapper `fs`. This installation is not covered here, we consider the following prerequisites:
 
-    - Python **≥ 3.10**.
-    - A local installation of **IDA Pro 9.1+** and/or **Ghidra 12.0+** —
-        required by the InterCG mapper.
+        - Python **≥ 3.10**.
+        - A local installation of **IDA Pro 9.1+** and/or **Ghidra 12.0+** —
+            required by the InterCG mapper.
 
-    Then you can install **Pyrrha** Python package in a virtual environment with `pip`.
-    ```sh
-    # Do not forget to activate your virtualenv
-    pip install pyrrha-mapper 
-    ```
-    If you prefer using sources to install Pyrrha, do the following:
-    ```sh
-    # Do not forget to activate your virtualenv
-    pip install 'pyrrha @ git+https://github.com/quarkslab/pyrrha'
-    ```
-=== ":fontawesome-brands-docker: Docker Image"
-    **Pyrrha** can be used with a docker. It provides **Pyrrha** with a backend (**Ghidra**), but you still need to install NumbatUI on your system as described in the [**NumbatUI** Installation](#numbatui-installation) section.
+        Then you can install **Pyrrha** Python package in a virtual environment with `pip`.
+        ```sh
+        # Do not forget to activate your virtualenv
+        pip install pyrrha-mapper 
+        ```
+        If you prefer using sources to install Pyrrha, do the following:
+        ```sh
+        # Do not forget to activate your virtualenv
+        pip install 'pyrrha @ git+https://github.com/quarkslab/pyrrha'
+        ```
+    === ":fontawesome-brands-docker: Docker Image"
+        **Pyrrha** can be used with a docker. It provides **Pyrrha** with a backend (**Ghidra**), but you still need to install NumbatUI on your system as described in the [**NumbatUI** Installation](#numbatui-installation) section.
 
-    The docker image is directly available from our [Github registry](https://github.com/orgs/quarkslab/packages/container/package/pyrrha).
+        The docker image is directly available from our [Github registry](https://github.com/orgs/quarkslab/packages/container/package/pyrrha).
 
 
-    ```commandline
-    cd ROOT_DIRECTORY/..
-    docker run  --rm -t -v $PWD:/tmp/pyrrha ghcr.io/quarkslab/pyrrha:latest MAPPER [OPTIONS] ROOT_DIRECTORY
-    ```
+        ```commandline
+        cd ROOT_DIRECTORY/..
+        docker run  --rm -t -v $PWD:/tmp/pyrrha ghcr.io/quarkslab/pyrrha:latest MAPPER [OPTIONS] ROOT_DIRECTORY
+        ```
 
-    
+        
 
 
 ## Visualizer Installation
-=== "**Sourcetrail**"
-    === "Linux"
-        ```sh
-        SOURCETRAIL_URL='https://github.com/CoatiSoftware/Sourcetrail/releases/download/2021.4.19/Sourcetrail_2021_4_19_Linux_64bit.tar.gz'
-        CHECKSUM=""f65a401daad8e16f29f7b2ff062a559999b6a8d44606db36cdf803de0cd7816d
-        EXTRACTION_DIR="/tmp/Sourcetrail_2021_4_19_Linux_64bit"
-        DOWNLOAD_PATH="$EXTRACTION_PATH.tar.gz"
-
-        wget $SOURCETRAIL_URL -O $DOWNLOAD_PATH
-        echo $CHECKSUM $DOWNLOAD_PATH | sha256sum -c 
-
-        if [ $? == 0 ]; then
-            echo '==== Install Sourcetrail'
-            tar xf $DOWNLOAD_PATH -C $EXTRACTION_DIR
-            sudo $EXTRACTION_DIR/Sourcetrail/install.sh
-            rm -rf $DOWNLOAD_PATH $EXTRACTION_DIR
-        fi
-        ```
-    === "Windows"
-
-        Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), unzip it and run the `setup.exe`.
-
-    === "MacOS"
-
-        Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), and install it following [Sourcetrail documentation](https://github.com/CoatiSoftware/Sourcetrail/releases).
-
-=== "**NumbatUI**"
-    <a name="numbatui-installation"></a>**NumbatUI** should be compiled locally, as explained in its [README](https://github.com/quarkslab/NumbatUI/blob/main/README.md). For the moment it has only be tested on Ubuntu/Debian distributions. 
-    Here are the summarized compilation instructions:
-
-    **Prerequisites**
-    ```sh
-    apt-get update
-    apt-get install -y \
-            cmake \
-            git \
-            build-essential \
-            libboost-filesystem-dev libboost-program-options-dev libboost-system-dev libboost-date-time-dev \
-            qt6-svg-dev qt6-base-dev qt6-5compat-dev \
-            unzip wget \
-            libclang-17-dev clang-17
-    ```
-
-    **Compilation**
-    ```sh
-    git clone https://github.com/quarkslab/NumbatUI.git numbatui 
-    cd numbatui
-    mkdir -p build/Release 
-    cd build/Release
-    cmake -DCMAKE_BUILD_TYPE="Release" -DBUILD_CXX_LANGUAGE_PACKAGE=ON -DBUILD_PYTHON_LANGUAGE_PACKAGE=ON ../.. && make NumbatUI -j $(nproc)
-    ```
+
+!!! note ""
+    === "**NumbatUI**"
+        <a name="numbatui-installation"></a>
+        For Debian like distribution, download the [`.deb`](https://github.com/quarkslab/NumbatUI/releases) package and install it on your system (`sudo dpkg -i numbatui.deb`)
+
+        For other systems, you can also compile it manually or use a Docker, check [NumbatUI documentation](https://quarkslab.github.io/NumbatUI/installation/) for further details.
+        
+    === "**Sourcetrail**"
+        === "Linux"
+            ```sh
+            SOURCETRAIL_URL='https://github.com/CoatiSoftware/Sourcetrail/releases/download/2021.4.19/Sourcetrail_2021_4_19_Linux_64bit.tar.gz'
+            CHECKSUM=""f65a401daad8e16f29f7b2ff062a559999b6a8d44606db36cdf803de0cd7816d
+            EXTRACTION_DIR="/tmp/Sourcetrail_2021_4_19_Linux_64bit"
+            DOWNLOAD_PATH="$EXTRACTION_PATH.tar.gz"
+
+            wget $SOURCETRAIL_URL -O $DOWNLOAD_PATH
+            echo $CHECKSUM $DOWNLOAD_PATH | sha256sum -c 
+
+            if [ $? == 0 ]; then
+                echo '==== Install Sourcetrail'
+                tar xf $DOWNLOAD_PATH -C $EXTRACTION_DIR
+                sudo $EXTRACTION_DIR/Sourcetrail/install.sh
+                rm -rf $DOWNLOAD_PATH $EXTRACTION_DIR
+            fi
+            ```
+        === "Windows"
+
+            Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), unzip it and run the `setup.exe`.
+
+        === "MacOS"
+
+            Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), and install it following [Sourcetrail documentation](https://github.com/CoatiSoftware/Sourcetrail/releases).
 
 ## Documentation
 

docs/mappers/exe-decomp.md

@@ -11,6 +11,13 @@ the mapper will:
 
 ## Usage
 
+!!! tip
+    If your backend is not on  `PATH`, indicate its directory using the matching environment variable.
+    ```sh
+    export IDADIR=/opt/idapro 
+    export GHIDRA_INSTALL_DIR=/opt/ghidra_12.0.4_PUBLIC  
+    ```
+
 ```commandline
 Usage: pyrrha decomp [OPTIONS] EXECUTABLE
 
@@ -24,6 +31,9 @@ Options:
   -e, --export                Create a JSON export of the resulting decompilation mapping.
   -h, --help                  Show this message and exit.
 ```
+After firmware analysis, you can visualize and navigate into the results with `numbatui`. The user interface is described in depth in the [NumbatUI documentation](https://quarkslab.github.io/NumbatUI/interface/).
+
+Do not hesitate to take a look at  all the possibilities offered by NumbatUI, especially [Custom Trails](https://quarkslab.github.io/NumbatUI/interface/#custom-trail).
 
 ## JSON export
 
@@ -38,18 +48,3 @@ for func in result.iter_functions():
 ```
 
 An `ExportedDecompilation` stores the analysed binary identity (`path`, `id`, `name`) and its functions, keyed by their parser-space entry-point address. Each function is an `ExportedFunction` carrying its `Symbol`, its `FuncType`, the addresses it calls and is called by, its decompiled `source`, and the in-source locations of its declaration and call sites (`ExportedLocation`).
-
-!!! note 
-    This mapper create the Quokka export of the binary as well as a cache version of all the decompiled function of the analyzed binary.. If these files already exist, it loads them without regenerate them. Like that it also allowed to use `pyrrha` in systems without Quokka and/or IDA. 
-
-
-After firmware analysis, you can visualize and navigate into the results with `numbatui`. The user interface is described in depth in the [NumbatUI documentation](https://github.com/quarkslab/NumbatUI/blob/main/DOCUMENTATION.md#user-interface).
-    Do not hesitate to take a look at  all the possibilities offered by NumbatUI, especially [Custom Trails](https://github.com/quarkslab/NumbatUI/blob/main/DOCUMENTATION.md#custom-trail-dialog).
-
-<!-- ## JumpTo Disassembler Feature
-
-The mapper uses a NumbatUI feature to enable jumping from NumbatUI directly
-to the given function in a disassembler. This feature is useful if one need
-to perform more in-depth reverse-engineering of the given function. Such
-feature requires an IDA Pro plugin to be installed. It can be done by copying
-the ``numbatui_plugin.py`` in the IDA Pro plugin directory. -->

docs/mappers/fs-cg.md

@@ -10,7 +10,7 @@ anyone can follow control-flow between programs.
 
 The main drawback is that computing a program call graph requires disassembly
 and is thus more computationaly intensive. That task is currently done using
-the [Quokka exporter](https://github.com/quarkslab/quokka).
+either IDA Pro or Ghidra.
 
 
 
@@ -21,27 +21,36 @@ The dump should be provided on the command line. The `ROOT_DIRECTORY` should con
 the whole filesystem to be indexed. 
 
 !!! tip
-    You can use the environement variable `IDAPATH` to indicate in which directory `ida` binary is.
-
-```commandline
-Usage: pyrrha fs-cg [OPTIONS] ROOT_DIRECTORY
-
-  Map a the Inter-Image Call Graph of a whole filesystem into a NumbatUI db.It disassembles executables using a
-  disassembler and extract the call graph.It then results all call references across binaries.
-
-Options:
-  -d, --debug          Set log level to DEBUG
-  --db PATH            NumbatUI DB file path (.srctrldb).  [default: fs-cg.srctrldb]
-  -j, --jobs INT       Number of parallel jobs created (threads).  [default: 1; 1<=x<=11]
-  --ignore             When resolving duplicate imports, ignore them
-  --arbitrary          When resolving duplicate imports, select the first one available
-  --interactive        When resolving duplicate imports, user manually select which one to use=
-  -h, --help           Show this message and exit.
+    If your backend is not on  `PATH`, indicate its directory using the matching environment variable.
+    ```sh
+    export IDADIR=/opt/idapro 
+    export GHIDRA_INSTALL_DIR=/opt/ghidra_12.0.4_PUBLIC  
+    ```
+
+```bash            
+ Usage: pyrrha fs-cg [OPTIONS] ROOT_DIRECTORY                                                                           
+                                                                                                                        
+ Map the inter-image call graph of a whole filesystem into a NumbatUI db. It disassembles executables, extracts the     
+ call graph, and resolves all call references across binaries.                                                          
+                                                                                                                        
+╭─ Mapper Options ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --backend  -b  [ida|ghidra]    Backend to use. [default: 1]                                                          │
+│ --db           PATH            NumbatUI DB file path (.srctrldb). [default: fs-cg.srctrldb]                          │
+│ --jobs     -j  INT [1<=x<=11]  Number of parallel jobs. [default: 1]                                                 │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Resolution ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ When resolving duplicate imports:                                                                                    │
+│ --arbitrary    Select the first one available.                                                                       │
+│ --interactive  User manually selects which one to use.                                                               │
+│ --ignore       Ignore them.                                                                                          │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --debug  -d  Set log level to DEBUG.                                                                                 │
+│ --help   -h  Show this message and exit.                                                                             │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
-!!! note 
-    This mapper create the Quokka export of each binary nearby each executable file. If this file already exists, it loads it without regenerate it. Like that it also allowed to use `pyrrha` in systems without Quokka and/or IDA. 
 
+After firmware analysis, you can visualize and navigate into the results with `numbatui`. The user interface is described in depth in the [NumbatUI documentation](https://quarkslab.github.io/NumbatUI/interface/).
 
-After firmware analysis, you can visualize and navigate into the results with `numbatui`. The user interface is described in depth in the [NumbatUI documentation](https://github.com/quarkslab/NumbatUI/blob/main/DOCUMENTATION.md#user-interface).
-    Do not hesitate to take a look at  all the possibilities offered by NumbatUI, especially [Custom Trails](https://github.com/quarkslab/NumbatUI/blob/main/DOCUMENTATION.md#custom-trail-dialog).
+Do not hesitate to take a look at  all the possibilities offered by NumbatUI, especially [Custom Trails](https://quarkslab.github.io/NumbatUI/interface/#custom-trail).