Skip to content

Commit b14300a

Browse files
ebrocasebrocas
committed
doc: rewrite installation, home and README, details in other pages
1 parent 4620d10 commit b14300a

File tree

13 files changed

+354
-305
lines changed

13 files changed

+354
-305
lines changed

‎README.md‎

Lines changed: 37 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,60 @@
11
# Pyrrha: A mapper collection for firmware analysis
2+
<!-- # --8<-- [start:intro]-->
3+
4+
<p align="center">
5+
<a href="https://github.com/quarkslab/pyrrha/pypi">
6+
<img src="https://img.shields.io/pypi/v/pyrrha-mapper.svg">
7+
</a>
8+
<a href="https://github.com/quarkslab/pyrrha/releases">
9+
<img src="https://img.shields.io/github/actions/workflow/status/quarkslab/pyrrha/release.yml">
10+
</a>
11+
<a href="https://pypi.org/project/pyrrha-mapper/">
12+
<img src="https://img.shields.io/pypi/pyversions/pyrrha-mapper">
13+
</a>
14+
<img src="https://img.shields.io/pypi/dm/pyrrha-mapper"/>
15+
<img src="https://img.shields.io/github/license/quarkslab/pyrrha"/>
16+
</p>
17+
218

319
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
420
explorer [NumbatUI](https://github.com/quarkslab/NumbatUI) to provide users with an easy way to navigate through and search for
521
path to function.
22+
<!-- # --8<-- [end:intro]-->
623

7-
![](img/imports.png)
24+
![](docs/img/imports.png)
825
<p align="center">
926
<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>
1027
</p>
1128

12-
![](img/symlinks.png)
29+
![](docs/img/symlinks.png)
1330
<p align="center">
1431
<b>An example of the symlinks which point on <code>busybox</code>.</b>
1532
</p>
1633

17-
1834
## Installation
1935

2036
The installation is done in three parts:
2137

22-
- Installing mapper external dependencies:
23-
* IDA dissassembler (with the decompilation option for the `exe-decomp` mapper).
24-
* [`Quokka` IDA plugin](https://github.com/quarkslab/quokka/releases).
25-
- Installing `Pyrrha` as a Python module (`pip install pyrrha-mapper` or from the sources).
26-
- Installing [`NumbatUI`](https://github.com/quarkslab/NumbatUI) (or [`Sourcetrail`](https://github.com/CoatiSoftware/Sourcetrail)) to be able to visualize Pyrrha's results.
27-
28-
29-
!!! example "Quick Start"
30-
31-
=== "Sourcetrail"
32-
33-
1. Install Quokka plugin by downloaded the appropriate version from its [release](https://github.com/quarkslab/quokka/releases) page. Then follow the instructions according to your OS.
34-
35-
2. Install Sourcetrail and Pyrrha.
36-
37-
=== "Linux"
38-
```bash
39-
SOURCETRAIL_URL='https://github.com/CoatiSoftware/Sourcetrail/releases/download/2021.4.19/Sourcetrail_2021_4_19_Linux_64bit.tar.gz'
40-
CHECKSUM=""f65a401daad8e16f29f7b2ff062a559999b6a8d44606db36cdf803de0cd7816d
41-
EXTRACTION_DIR="/tmp/Sourcetrail_2021_4_19_Linux_64bit"
42-
DOWNLOAD_PATH="$EXTRACTION_PATH.tar.gz"
43-
44-
wget $SOURCETRAIL_URL -O $DOWNLOAD_PATH
45-
echo $CHECKSUM $DOWNLOAD_PATH | sha256sum -c
46-
47-
if [ $? == 0 ]; then
48-
echo '==== Install Sourcetrail'
49-
tar xf $DOWNLOAD_PATH -C $EXTRACTION_DIR
50-
sudo $EXTRACTION_DIR/Sourcetrail/install.sh
51-
rm -rf $DOWNLOAD_PATH $EXTRACTION_DIR
52-
fi
53-
54-
# Install pyrrha
55-
if [ $? == 0 ]; then
56-
echo '==== Install Pyrrha'
57-
pip install pyrrha-mapper
58-
fi
59-
```
60-
=== "Windows"
61-
62-
1. Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), unzip it and run the `setup.exe`.
63-
2. Install pyrrha: `pip install pyrrha-mapper`
64-
65-
=== "MacOS"
66-
67-
1. Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), and install it following [Sourcetrail documentation](https://github.com/CoatiSoftware/Sourcetrail/releases).
68-
2. Install pyrrha: `pip install pyrrha-mapper`
38+
1. Install mapper external dependencies: IDA dissassembler (with the decompilation option for the `exe-decomp` mapper) and [`Quokka` IDA plugin](https://github.com/quarkslab/quokka/releases).
39+
1. Install `Pyrrha` itself.
40+
1. Install [`NumbatUI`](https://github.com/quarkslab/NumbatUI) (or [`Sourcetrail`](https://github.com/CoatiSoftware/Sourcetrail)) to be able to visualize Pyrrha's results.
6941

42+
> [!NOTE]
43+
> A quick start installation is available on [Pyrrha documentation](https://quarkslab.github.io/pyrrha/#installation).
7044
71-
=== "NumbatUI (Ubuntu/Debian)"
72-
73-
_Tested only for last Ubuntu/Debian._
74-
75-
First install Quokka plugin by downloaded the appropriate version from its [release](https://github.com/quarkslab/quokka/releases) page.
76-
77-
Then run the following script that will clone and build `NumbatUI` and install `Pyrrha`. `NumbatUI` will in `numbatui/build/Release/app`.
78-
79-
```
80-
# Prerequisites for Numbat UI
81-
sudo apt-get update
82-
sudo apt-get install -y \
83-
cmake \
84-
git \
85-
build-essential \
86-
libboost-filesystem-dev libboost-program-options-dev libboost-system-dev libboost-date-time-dev \
87-
qt6-svg-dev qt6-base-dev qt6-5compat-dev \
88-
unzip wget \
89-
libclang-17-dev clang-17
90-
91-
# Clone and Build NumbatUI
92-
git clone https://github.com/quarkslab/NumbatUI.git numbatui
93-
cd numbatui
94-
mkdir -p build/Release
95-
cd build/Release
96-
cmake -DCMAKE_BUILD_TYPE="Release" -DBUILD_CXX_LANGUAGE_PACKAGE=ON -DBUILD_PYTHON_LANGUAGE_PACKAGE=ON ../.. && make NumbatUI -j $(nproc)
97-
98-
# Install pyrrha
99-
pip install pyrrha-mapper
100-
```
101-
102-
103-
104-
Detailed instructions can be found on the [dedicated documentation page](https://quarkslab.github.io/pyrrha/installation/).
105-
45+
<!-- # --8<-- [start:usage]-->
10646
## Usage
107-
The usage workflow is composed of two steps which allow you to separate DB creation and result visualization.
108-
109-
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:
110-
```
111-
> pyrrha
112-
Usage: pyrrha [OPTIONS] COMMAND [ARGS]...
11347

114-
Mapper collection for firmware analysis.
115-
116-
Options:
117-
-h, --help Show this message and exit.
118-
119-
Commands:
120-
exe-decomp Map an executable call graph with its decompiled code.
121-
fs Map PE and ELF files of a filesystem into a sourcetrail-compatible db.
122-
fs-cg Map the Call Graph of every firmware executable a sourcetrail-compatible db.
48+
The usage workflow is composed of two steps which allow you to separate DB creation and result visualization.
12349

124-
```
125-
2. Visualize your results with Sourcetrail
126-
```
127-
> numbatui PROJECT_NAME.srctrlprj
128-
```
50+
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`.
51+
2. Visualize your results with Sourcetrail/NumbatUI.
12952

130-
The detailed documentation of each mapper is available in the [documentation](https://quarkslab.github.io/pyrrha/mappers/mappers/).
53+
<!-- # --8<-- [end:usage] -->
54+
> [!NOTE]
55+
> The detailed documentation of each mapper is available in the [documentation](https://quarkslab.github.io/pyrrha/mappers/mappers/).
13156
57+
<!-- # --8<-- [start:publications]-->
13258
## Publications
13359

13460
Pyrrha has been presented by Eloïse Brocas at two conferences listed below. These talks include live demo of the `fs` parser which map links between libraries and executables files.
@@ -140,10 +66,14 @@ The theoritical details below the `fs-cg` and `exe-decomp` mappers implementatio
14066

14167
- Streamlining Firmware Analysis with Inter-Image Call Graphs and Decompilation, *RE/verse.io 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)
14268

69+
<!-- # --8<-- [end:publications] -->
70+
71+
<!-- # --8<-- [start:authors] -->
14372
## Authors
14473
- Eloïse Brocas (@ebrocas), Quarkslab
14574
- Robin David (@RobinDavid), Quarkslab
14675

14776

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

‎docs/.snippets/diffing_pyrrha_exports.py‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#!/usr/bin/env python3
2+
"""Diff two Pyrrha result JSON exports.It removes the kernel mangling."""
3+
4+
import argparse
5+
from pathlib import Path
6+
7+
from pyrrha_mapper import FileSystem
8+
9+
10+
def existing_file(raw_path: str) -> Path | None:
11+
"""Check if a path correspond to an existing file and transform it into a pathlib.Path object.
12+
13+
:param raw_path: the given path (as a string)
14+
:return: the corresponding pathlib.Path object
15+
"""
16+
if not Path(raw_path).exists():
17+
raise argparse.ArgumentTypeError('"{}" does not exist'.format(raw_path))
18+
elif not Path(raw_path).is_file():
19+
raise argparse.ArgumentTypeError('"{}" is not a file'.format(raw_path))
20+
return Path(raw_path)
21+
22+
23+
def main():
24+
"""Diff two exports of `fs` result."""
25+
parser = argparse.ArgumentParser()
26+
parser.add_argument("json1", type=existing_file, help="Path to old filesystem JSON.")
27+
parser.add_argument("json2", type=existing_file, help="Path to new filesystem JSON.")
28+
args = parser.parse_args()
29+
30+
old_fs = FileSystem.from_json_export(args.json1)
31+
new_fs = FileSystem.from_json_export(args.json2)
32+
33+
# Compute and display changes of binaries
34+
old_bins = {b.path for b in old_fs.iter_binaries()}
35+
new_bins = {b.path for b in new_fs.iter_binaries()}
36+
added_bin = new_bins - old_bins
37+
removed_bin = old_bins - new_bins
38+
for type, bin_set in [("no longer", removed_bin), ("added", added_bin)]:
39+
print(f"\nBinaries {type} in {args.json2}:")
40+
for b in bin_set:
41+
print(f"\t- {b}")
42+
43+
print("\nCommon binaries that have changed:")
44+
count = 0
45+
for b1, b2 in (
46+
(old_fs.get_binary_by_path(path), new_fs.get_binary_by_path(path))
47+
for path in old_bins.intersection(new_bins)
48+
):
49+
is_different = False
50+
old_libs, new_libs = set(b1.imported_library_names), set(b2.imported_library_names)
51+
if old_libs != new_libs:
52+
count += 1
53+
print(f"{b1.name} have changed:")
54+
is_different = True
55+
for type, bin_set in [("removed", old_libs - new_libs), ("added", new_libs - old_libs)]:
56+
for lib in bin_set:
57+
print(f"\t- lib {type}: {lib}")
58+
59+
old_symbs, new_symbs = set(b1.imported_symbol_names), set(b2.imported_symbol_names)
60+
if old_symbs != new_symbs:
61+
if not is_different:
62+
count += 1
63+
print(f"{b1.name} have changed:")
64+
is_different = True
65+
for type, bin_set in [
66+
("removed", old_symbs - new_symbs),
67+
("added", new_symbs - old_symbs),
68+
]:
69+
for lib in bin_set:
70+
print(f"\t- imported symbol {type}: {lib}")
71+
print(f"Total having changed: {count}")
72+
73+
74+
if __name__ == "__main__":
75+
main()

‎docs/img/example_sourcetrail.png‎

-42.7 KB
Loading

‎docs/index.md‎

Lines changed: 98 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,98 @@
1-
--8<-- "README.md"
1+
--8<-- "README.md:intro"
2+
3+
<div class="grid cards" markdown>
4+
5+
- ![](img/imports.png) <center> _Symbols and libraries imported by `libgcc_s.so.1`._</center>
6+
7+
- ![](img/symlinks.png) <center>_Symlinks pointing on `busybox`._</center>
8+
</div>
9+
10+
## Installation
11+
The installation is done in three parts:
12+
13+
1. Install mapper external dependencies: IDA dissassembler (with the decompilation option for the `exe-decomp` mapper) and [`Quokka` IDA plugin](https://github.com/quarkslab/quokka/releases).
14+
1. Install `Pyrrha` itself.
15+
1. Install [`NumbatUI`](https://github.com/quarkslab/NumbatUI) (or [`Sourcetrail`](https://github.com/CoatiSoftware/Sourcetrail)) to be able to visualize Pyrrha's results.
16+
17+
!!! example "Quick Start"
18+
19+
=== "Sourcetrail"
20+
21+
1. Install Quokka plugin by downloaded the appropriate version from its [release](https://github.com/quarkslab/quokka/releases) page. Then follow the instructions according to your OS.
22+
23+
2. Install Sourcetrail and Pyrrha.
24+
25+
=== "Linux"
26+
```bash
27+
SOURCETRAIL_URL='https://github.com/CoatiSoftware/Sourcetrail/releases/download/2021.4.19/Sourcetrail_2021_4_19_Linux_64bit.tar.gz'
28+
CHECKSUM=""f65a401daad8e16f29f7b2ff062a559999b6a8d44606db36cdf803de0cd7816d
29+
EXTRACTION_DIR="/tmp/Sourcetrail_2021_4_19_Linux_64bit"
30+
DOWNLOAD_PATH="$EXTRACTION_PATH.tar.gz"
31+
32+
wget $SOURCETRAIL_URL -O $DOWNLOAD_PATH
33+
echo $CHECKSUM $DOWNLOAD_PATH | sha256sum -c
34+
35+
if [ $? == 0 ]; then
36+
echo '==== Install Sourcetrail'
37+
tar xf $DOWNLOAD_PATH -C $EXTRACTION_DIR
38+
sudo $EXTRACTION_DIR/Sourcetrail/install.sh
39+
rm -rf $DOWNLOAD_PATH $EXTRACTION_DIR
40+
fi
41+
42+
# Install pyrrha
43+
if [ $? == 0 ]; then
44+
echo '==== Install Pyrrha'
45+
pip install pyrrha-mapper
46+
fi
47+
```
48+
=== "Windows"
49+
50+
1. Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), unzip it and run the `setup.exe`.
51+
2. Install pyrrha: `pip install pyrrha-mapper`
52+
53+
=== "MacOS"
54+
55+
1. Download last Sourcetrail [release](https://github.com/CoatiSoftware/Sourcetrail/releases), and install it following [Sourcetrail documentation](https://github.com/CoatiSoftware/Sourcetrail/releases).
56+
2. Install pyrrha: `pip install pyrrha-mapper`
57+
58+
59+
=== "NumbatUI (Ubuntu/Debian)"
60+
61+
_Tested only for last Ubuntu/Debian._
62+
63+
First install Quokka plugin by downloaded the appropriate version from its [release](https://github.com/quarkslab/quokka/releases) page.
64+
65+
Then run the following script that will clone and build `NumbatUI` and install `Pyrrha`. `NumbatUI` will in `numbatui/build/Release/app`.
66+
67+
```
68+
# Prerequisites for Numbat UI
69+
sudo apt-get update
70+
sudo apt-get install -y \
71+
cmake \
72+
git \
73+
build-essential \
74+
libboost-filesystem-dev libboost-program-options-dev libboost-system-dev libboost-date-time-dev \
75+
qt6-svg-dev qt6-base-dev qt6-5compat-dev \
76+
unzip wget \
77+
libclang-17-dev clang-17
78+
79+
# Clone and Build NumbatUI
80+
git clone https://github.com/quarkslab/NumbatUI.git numbatui
81+
cd numbatui
82+
mkdir -p build/Release
83+
cd build/Release
84+
cmake -DCMAKE_BUILD_TYPE="Release" -DBUILD_CXX_LANGUAGE_PACKAGE=ON -DBUILD_PYTHON_LANGUAGE_PACKAGE=ON ../.. && make NumbatUI -j $(nproc)
85+
86+
# Install pyrrha
87+
pip install pyrrha-mapper
88+
```
89+
90+
!!! note
91+
Detailed instructions can be found on the [dedicated documentation page](installation.md).
92+
93+
--8<-- "README.md:usage"
94+
!!! note
95+
The detailed documentation of each mapper is available in the [documentation](mappers/mappers.md).
96+
97+
--8<-- "README.md:publications"
98+
--8<-- "README.md:authors"

0 commit comments

Comments
 (0)