マニュアル / Documentation

The English version is written after Japanese version.

環境構築

dockerをインストールし、dockerとdocker-composeコマンドが使えることを確認してください。

https://www.docker.com/products/docker-desktop/

eclipseを以下のURLからダウンロードしてください。

https://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/2022-06/R/eclipse-committers-2022-06-R-linux-gtk-x86_64.tar.gz

以下のURLからこのgitリポジトリをダウンロードしてください。

https://github.com/usaribbon/firmddle_docker/archive/refs/heads/main.zip
もしくはgit clone https://github.com/usaribbon/firmddle_docker.git

先程ダウンロードしたeclipseのtar.gzファイルを、firmddle_docker/raw_firmwares/eclipse/のディレクトリにコピーしてください。
ダウンロードしたgitリポジトリに移動し、以下のようなディレクトリ構造になっていることを確認してください。

.
├── docker-compose.yml
├── gui
│   └── Dockerfile
└── raw_firmwares   ←docker上では/mnt/raw_firmwares/としてマウントされます
    ├── eclipse
    │   └── eclipse-committers-2022-06-R-linux-gtk-x86_64.tar.gz
    ├── elf
    ├── extracted
    ├── ghidraprj
    ├── raw

gitリポジトリ内で以下のコマンドを実行し、dockerをビルド＆起動させてください。

docker-compose build
docker-compose up -d

(Windows)iptablesの関係でStep7,9で初回ビルドは失敗してしまいます。その際はdockerを再起動して、もう一度ビルドコマンドを実行してみてください。

ホストPCのWEBブラウザからhttp://127.0.0.1:8080/にアクセスしてdockerコンテナに入ってください。（環境によって接続までに数分〜数十分かかる場合があります）
ファイルマネージャーから/root/firmusa/ghidra_10.1.5_PUBLIC_20220726/ghidraRunにアクセスし、Ghidraを起動してください。

ファームウェアを分割する

分割したいファームウェアを、gitリポジトリのraw_firmwares/raw/に置いてください。dockerには/mnt/raw_firmwares/としてマウントされています。
docker上で/root/firmware-mod-kit/extract_elf.sh を実行してください。/mnt/raw_firmwares/に置かれているファームウェアの分割が始まります。
分割されたファームウェアは、/mnt/raw_firmwares/extracted/に置かれます。

Ghidraにファームウェアをインポートする

「ファームウェアを分割する」の手順を実行した後、/root/firmware-mod-kit/import_elf_ghidra.sh を実行してください。
分割したファームウェアがGhidraにインポートされていきます。ファームウェアのサイズが大きい場合、インポートに時間がかかる場合があります。
ファームウェアごとにGhidraプロジェクトが作成され、/mnt/raw_firmwares/ghidraprj/に保存されます。
ファイルマネージャーから/root/firmusa/ghidra_10.1.5_PUBLIC_20220726/ghidraRunにアクセスし、Ghidraを起動してください。
Ghidraから、File -> Open Projectを選択して/mnt/raw_firmwares/ghidraprj/好きなファームウェア名.gprを開きます。

（おまけ）Ghidraで新規プロジェクトを作成してELFをインポートする

/root/firmusa/ghidra_10.1.5_PUBLIC_20220726/ghidraRun を実行してGhidraを起動してください。
NewProjectを選択します。

3. Non-Shared Projectを選択します。

4. プロジェクトの保存先を指定します。

5. Import Fileを選択します。

6. 読み込ませるELFファイルを指定します。

7. OKを選択します。

8. OKを選択します。

9. Yesを選択します。

10. Analyzeを選択します。解析が完了するまでしばらく待ちます。

11. プロジェクト画面の左上の「SAVE」ボタンを押して解析結果を保存します。

HeadlessAnalyzerの使い方

プロジェクト内の全ファイルに対してスクリプトを適用したいときは、下記のコマンドを実行してください /root/firmusa/ghidra_10.1.5_PUBLIC/support/analyzeHeadless /mnt/raw_firmwares/ghidraprj binary2 -scriptPath /root/ghidra_scripts -postScript Yoda_API_Headless.java -process -recursive
スクリプトを適用した結果は、dockerの/mnt/raw_firmwares/logs/、またはホストPCのこのgitリポジトリ/raw_firmwares/logs/に保存されています。

Setup

Install docker and make sure docker and docker-compose commands are available.

https://www.docker.com/products/docker-desktop/

Download eclipse from the following URL

https://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/2022-06/R/eclipse-committers-2022-06-R-linux-gtk-x86_64.tar.gz

Download this git repository from the following URL

https://github.com/usaribbon/firmddle_docker/archive/refs/heads/main.zip
Or git clone https://github.com/usaribbon/firmddle_docker.git

Copy the eclipse tar.gz file you just downloaded to the directory firmddle_docker/raw_firmwares/eclipse/
Go to the git repository you downloaded and make sure the directory structure looks like this

.
├── docker-compose.yml
├── gui
│   └── Dockerfile
└── raw_firmwares   ←mounted as /mnt/raw_firmwares/ on docker
    ├── eclipse
    │   └── eclipse-committers-2022-06-R-linux-gtk-x86_64.tar.gz
    ├── elf
    ├── extracted
    ├── ghidraprj
    ├── raw

Execute the following command in the git repository to build and start docker.

docker-compose build
docker-compose up -d

(Windows) Due to iptables, the first build will fail in Step 7 and 9. In that case, restart docker and run the build command again.

Please access http://127.0.0.1:8080/ from a web browser on the host PC to enter the docker container. (It may take several minutes to several tens of minutes to connect depending on the environment.)
Access /root/firmusa/ghidra_10.1.5_PUBLIC_20220726/ghidraRun from the file manager and start Ghidra.

Split the firmware

Place the firmware you want to split in the git repository raw_firmwares/raw/. docker has it mounted as /mnt/raw_firmwares/
Run /root/firmware-mod-kit/extract_elf.sh on docker. The firmware placed in /mnt/raw_firmwares/ will start to be split.
The split firmware will be placed in /mnt/raw_firmwares/extracted/

Importing firmware into Ghidra

After performing the steps in "Splitting Firmware," run /root/firmware-mod-kit/import_elf_ghidra.sh.
The split firmware will be imported into Ghidra. If the firmware is large, the import may take some time.
A Ghidra project will be created for each firmware and saved in /mnt/raw_firmwares/ghidraprj/.
Access /root/firmusa/ghidra_10.1.5_PUBLIC_20220726/ghidraRun from the file manager and start Ghidra.
From Ghidra, select File -> Open Project and open /mnt/raw_firmwares/ghidraprj/firmware_name.gpr of your choice.

(extra) Create a new project in Ghidra and import the ELF

Run Ghidra by executing /root/firmusa/ghidra_10.1.5_PUBLIC_20220726/ghidraRun
Select NewProject.

3. Select Non-Shared Project

4. Choose a folder to save your project.

5. Select Import File

6. Select ELF files

7. Select OK

8. Select OK

9. Select Yes。

10. Select Analyze. Wait a moment for the analysis to complete.

11. Save the analysis results by pressing the "SAVE" button in the upper left corner of the project screen.

How to use HeadlessAnalyzer

If you want to apply the script to all files in the project, run the following command /root/firmusa/ghidra_10.1.5_PUBLIC/support/analyzeHeadless /mnt/raw_firmwares/ghidraprj binary2 -scriptPath /root/ghidra_scripts - postScript Yoda_API_Headless.java -process -recursive.
The results of applying the scripts are stored in /mnt/raw_firmwares/logs/ on docker or in this git repository/raw_firmwares/logs/ on the host PC. The results are stored in the host PC.

usaribbon/firmddle_docker