Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions tools/import/README.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,38 @@
# Import tools

The tools listed in this directory are for importing a Ghidra-SARIF file into src/OpenSHC as C++ header files.
The tools listed in this directory are for importing a Ghidra program into src/OpenSHC as C++ header files.

## Usage

0. Install `ghidra-skink`:
0. Install `ghidra-skink` and pyghidra, and set `GHIDRA_INSTALL_DIR` to your Ghidra installation (needed by pyghidra):

```py
python -m pip install -r requirements.txt
python -m pip install pyghidra
```

1. Export Data, Functions, and Symbols from Ghidra to a .sarif file.
2. Execute the following from PowerShell to cleanly convert the .sarif file into header files:
1. Export the program from Ghidra as a .gzf (File > Export Program..., format "Ghidra Zip File") to `Stronghold Crusader.exe.gzf`.
2. Execute the following from PowerShell to cleanly convert the .gzf file into header files:

```pwsh
& .\tools\import\reimport-ghidra.ps1 -ClearCache $true -OverwriteAll $true -Sarif "path/to/sarif/file.sarif
& .\tools\import\reimport-ghidra.ps1 -OverwriteAll $true
```

> By default, all .hpp files are backed up to the tmp\backup\ folder. When the .sarif file has not changed between calls of this script, use `-ClearCache $false` to speed up the conversion.

## Usage with a .gzf
Use `-Gzf "path/to/gzf/file.gzf"` to read a different .gzf file.

`ghidra-skink` can read the program straight from a Ghidra `.gzf` with pyghidra, so the SARIF export is not needed.
It generates the same header files in about half a minute instead of about ten minutes.
> By default, all .hpp files are backed up to the tmp\backup\ folder.

0. Install pyghidra (also used by `gzftosarif.py`), and set `GHIDRA_INSTALL_DIR` to your Ghidra installation:
## Usage with a .sarif

```pwsh
python -m pip install pyghidra
```
The headers can also be generated from a SARIF export of the program, which is slower (about ten minutes instead of
about half a minute) but gives the same header files.

1. Export the program from Ghidra as a .gzf (File > Export Program..., format "Ghidra Zip File").
1. Export Data, Functions, and Symbols from Ghidra to a .sarif file, or generate it from the .gzf with
`python .\tools\import\gzftosarif.py --gzf "Stronghold Crusader.exe.gzf" --sarif "Stronghold Crusader.exe.sarif"`.
2. Execute the following from PowerShell:

```pwsh
& .\tools\import\reimport-ghidra.ps1 -OverwriteAll $true -Gzf "path/to/gzf/file.gzf"
& .\tools\import\reimport-ghidra.ps1 -ClearCache $true -OverwriteAll $true -Sarif "path/to/sarif/file.sarif"
```

> When the .sarif file has not changed between calls of this script, use `-ClearCache $false` to speed up the conversion.
29 changes: 15 additions & 14 deletions tools/import/reimport-ghidra.ps1
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
param(
# Read the program straight from this .gzf with pyghidra
[Parameter(Mandatory = $false)]
[string]$Sarif = "Stronghold Crusader.exe.sarif",
# Read the program straight from a .gzf with pyghidra (no SARIF export, no cache)
[string]$Gzf = "",
[string]$Gzf = "Stronghold Crusader.exe.gzf",
# Read the program from this SARIF export instead of from the .gzf (see gzftosarif.py)
[string]$Sarif = "",
[string]$OutputDir = "src",
[bool]$ClearCache = $true,
[bool]$OverwriteAll = $true,
[bool]$VerboseLogging = $false,
[bool]$MakeBackup = $true,
[bool]$Interactive = $false,
[bool]$DryRun = $false,
[bool]$GenerateSarif = $false,
[string]$ScriptPath = "tools\import\ghidra-importer.py"
)

. .\tools\import\utils\backup-item.ps1

$InputFile = if ($Sarif) { $Sarif } else { $Gzf }
if (-not (Test-Path -PathType Leaf $InputFile)) {
Write-Error "Input file not found: $InputFile"
exit 1
}

$pyArgs = New-Object System.Collections.Generic.List[System.String]
if ($Interactive) {
# Useful for debugging purposes. Exit the interpreter to continue the export
Expand All @@ -24,12 +30,12 @@ if ($Interactive) {

$pyArgs += "$ScriptPath"

if ($Gzf) {
$pyArgs += "--gzf"
$pyArgs += $Gzf
} else {
if ($Sarif) {
$pyArgs += "--sarif"
$pyArgs += $Sarif
} else {
$pyArgs += "--gzf"
$pyArgs += $Gzf
}

$pyArgs += "--output-dir"
Expand Down Expand Up @@ -70,12 +76,7 @@ if ($DryRun) {
$hppFiles | Remove-Item
}

if($GenerateSarif -and -not $Gzf) {
Write-Output "Generating sarif file from gzf"
& python .\tools\import\gzftosarif.py --sarif $Sarif
}

Write-Output "Converting $(if ($Gzf) { $Gzf } else { $Sarif }) to .hpp files"
Write-Output "Converting $InputFile to .hpp files"
# Execute the export
& python $pyArgs

Expand Down
Loading