Metadata-Version: 2.4
Name: pyrrha-mapper
Version: 2.0.0
Summary: A mapper collection for firmware analysis
Author-email: Eloïse Brocas <ebrocas@quarkslab.com>, Robin David <rdavid@quarkslab.com>
License: Apache License 2.0
Project-URL: Homepage, https://github.com/quarkslab/pyrrha
Project-URL: Source, https://github.com/quarkslab/pyrrha
Project-URL: Tracker, https://github.com/quarkslab/pyrrha/issues
Project-URL: Changelog, https://github.com/quarkslab/pyrrha/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Security
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.2.0
Requires-Dist: coloredlogs
Requires-Dist: lief>=0.17.0
Requires-Dist: numbat>=0.2.6
Requires-Dist: pydantic
Requires-Dist: rich-click
Requires-Dist: rich
Requires-Dist: ida_domain
Requires-Dist: pyghidra
Provides-Extra: doc
Requires-Dist: black; extra == "doc"
Requires-Dist: pymdown-extensions; extra == "doc"
Requires-Dist: zensical; extra == "doc"
Provides-Extra: linting
Requires-Dist: ruff; extra == "linting"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: typechecking
Requires-Dist: mypy; extra == "typechecking"
Dynamic: license-file

# Pyrrha: A mapper collection for firmware analysis
 <!-- # --8<-- [start:intro]-->

<p align="center">
  <a href="https://github.com/quarkslab/pyrrha/pypi">
    <img src="https://img.shields.io/pypi/v/pyrrha-mapper.svg">
  </a>
  <a href="https://github.com/quarkslab/pyrrha/releases">
    <img src="https://img.shields.io/github/actions/workflow/status/quarkslab/pyrrha/release.yml">
  </a>
  <a href="https://pypi.org/project/pyrrha-mapper/">
    <img src="https://img.shields.io/pypi/pyversions/pyrrha-mapper">
  </a>
  <img src="https://img.shields.io/pypi/dm/pyrrha-mapper"/>
  <img src="https://img.shields.io/github/license/quarkslab/pyrrha"/>
</p>


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/img/imports.png)
<p align="center">
<b>An example of the symbols and libraries imported by <code>libgcc_s.so.1</code> and of the symbols which reference this library.</b>
</p>

![](docs/img/symlinks.png)
<p align="center">
<b>An example of the symlinks which point on <code>busybox</code>.</b>
</p>

## Installation

The installation is done in two parts:

1. Install `Pyrrha` itself.
1. Install [`NumbatUI`](https://github.com/quarkslab/NumbatUI) (or [`Sourcetrail`](https://github.com/CoatiSoftware/Sourcetrail)) to be able to visualize Pyrrha's results. 
1. _(Optional)_ Install Ghidra or IDA if you want to use `fs-cg` or `decomp` mappers.
> [!NOTE]
> A quick start installation is available on [Pyrrha documentation](https://quarkslab.github.io/pyrrha/#installation).

 <!-- # --8<-- [start:usage]-->
## Usage

The usage workflow is composed of two steps which allow you to separate DB creation and result visualization.
 <!-- # --8<-- [end:usage] -->

1. Run Pyrrha to obtain NumbatUI compatible files (`*.srctrlprj` for the project file and `*.srctrldb` for the DB file). With the python package, you can just launch the command `pyrrha`.
2. Visualize your results with Sourcetrail/NumbatUI. 

> [!NOTE]
> The detailed documentation of each mapper is available in the [documentation](https://quarkslab.github.io/pyrrha/mappers/mappers/).

 <!-- # --8<-- [start:publications]-->
## Publications

Pyrrha presentations, including live demos:

- **Pyrrha & Friends: Diving into Firmware Cartography**, Eloïse Brocas & Robin David, *SSTIC*, Rennes, France, 2025. [[slides]](https://www.sstic.org/media/SSTIC2025/SSTIC-actes/pyrrha_diving_into_firmware_cartography/SSTIC2025-Slides-pyrrha_diving_into_firmware_cartography-brocas_david.pdf) [[video]](https://static.sstic.org/videos2025/1080p/pyrrha_diving_into_firmware_cartography.mp4) 

- **Pyrrha: navigate easily into your system binaries**, Eloïse Brocas, *Hack.lu*, Luxembourg, 2023. [[slides]](https://github.com/quarkslab/conf-presentations/blob/master/Confs/HackLu23/pyrrha.pdf) [[video]](https://www.youtube.com/watch?v=-dMl-SvQl4k) 

- **Map your Firmware!**, Eloïse Brocas, *Pass The SALT*, Lille, France, 2023. [[slides]](https://github.com/quarkslab/conf-presentations/blob/master/Confs/PTS23/PTS2023-Talk-14-Pyrrha-map-your-firmware.pdf) [[video]](https://passthesalt.ubicast.tv/videos/2023-map-your-firmware/) 

Theory behind implementations

- **Streamlining Firmware Analysis with Inter-Image Call Graphs and Decompilation**, Robin David, *RE//verse.io*, USA, 2025. [[slides]](https://github.com/quarkslab/conf-presentations/blob/master/Confs/REverse-25/REverse_firmware_analysis_2025.pdf) [[video]](https://www.youtube.com/watch?v=LsDnrfZt_Xs)

 <!-- # --8<-- [end:publications] -->

 <!-- # --8<-- [start:authors] -->
## Authors
- Eloïse Brocas (@ebrocas), Quarkslab
- Robin David (@RobinDavid), Quarkslab


### Past Contributors
- Pascal Wu (@pwu42), during his internship at Quarkslab
<!-- # --8<-- [end:authors] -->
