Package: pyrrha-mapper
PyrrhaIntroductionInstallationUsageDockerUsage ExampleAuthorsIntroductionPyrrha 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
explorerSourcetrailto provide users with an easy way to navigate through and search for
path to function.An example of the symbols and libraries imported bylibgcc_s.so.1and of the symbols which reference this library.An example of the symlinks which point onbusybox.InstallationThe installation is done in two parts:installingPyrrha(as a Python module);installingSourcetrailto be able to visualize Pyrrha's results.Sourcetrail installationSourcetrail can be installed usingits last releaseand itsdocumentation.Pyrrha installationPyrrha requires a Python version >= 3.10.
It is recommended to install the Python package inside a virtualenv. You can usepipto install it.pipinstallpyrrha-mapperIf you prefer using sources to install Pyrrha, do the following:# Do not forget to activate your virtualenv
$ pip install 'pyrrha @ git+https://github.com/quarkslab/pyrrha'

# If you prefer, you can manually clone the repository and then install the package
$ git clone https://github.com/quarkslab/pyrrha
$ cd pyrrha
$ pip install '.'Tested for Linux and Windows.For Windows systems, installation should be run from MSVC Developer shell to build the wheel.Dockerpyrrhacan be used with a docker. It provides Pyrrha but you still need to install Sourcetrail on your system as described in theSourcetrail Installationsection.$ cd ROOT_DIRECTORY/..
$ docker run  --rm -t -v $PWD:/tmp/pyrrha ghcr.io/quarkslab/pyrrha:latest fs [OPTIONS] ROOT_DIRECTORYA docker image is directly available from ourGithub registry, but you can also build it from the sources.$ git clone PYRRHA_URL && cd pyrrha
$ docker build -t pyrrha .UsageMapping with PyrrhaFirst, create your db withpyrrha. TheROOT_DIRECTORYshould contain the whole filesystem you want to map, it should be already extracted or mounted.ROOT_DIRECTORYwill be considered by Pyrrha as the filesystem root for all the symlink resolutions.Usage: pyrrha fs [OPTIONS] ROOT_DIRECTORY

  Map a filesystem into a sourcetrail-compatible db.

Options:
  --db PATH   Sourcetrail DB file path (.srctrldb).  [default: pyrrha.srctrldb]
  -e, --json  Create a JSON export of the resulting mapping.
  -h, --help  Show this message and exit.You can also export your Pyrrha results as a JSON file (option-j) to be able to postprocess them. For example, you can diff the results between two versions of the same system and list the binaries added/removed and which symbols has been added/removed (cfexample script inexample).Visualization with SourcetrailOpen the resulting project withsourcetrail. You can now navigate on the resulting cartography. The user interface is described in depth in theSourcetrail documentation.To match the Sourcetrail language, the binaries, the exported functions and symbols, and the symlinks are represented as follows in Sourcetrail.BinariesExported functionsExported symbolsSymlinksDo not hesitate to take a look atSourcetrail documentationto explore all the possibilities offered by Sourcetrail.Custom Trailscould be really useful in a lot of cases.Quick Start—Usage ExampleLet's take the example of an OpenWRT firmware which is a common Linux distribution for embedded targets like routers.First, download the firmware and extract its root-fs into a directory. Here we download the last OpenWRT version for generic x86_64 systems.$ wget https://downloads.openwrt.org/releases/22.03.5/targets/x86/64/openwrt-22.03.5-x86-64-rootfs.tar.gz -O openwrt_rootfs.tar.gz
$ mkdir openwrt_root_fs && cd openwrt_root_fs
$ tar -xf ../openwrt_rootfs.tar.gz
$ cd .. && rm openwrt_rootfs.tar.gzThen we can run Pyrrha on it. It will produce some logs indicating which symlinks or imports cannot be solved directly by the tool.(Do not forget to activate your virtualenv if you have created one for Pyrrha installation.)$ pyrrha fs --db openwrt_db openwrt_root_fs
$ ls 
openwrt_root_fs openwrt_db.srctrldb  openwrt_db.srctrlprjYou can now navigate into the resulting cartography with Sourcetrail.$ sourcetrail openwrt_db.srctrlprjPyrrha result opened with Sourcetrail.AuthorsEloïse Brocas (@ebrocas), Quarkslab