LearnPyhidra.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d44bd92f-23ae-4438-b5d0-7e8f3b6c6ba6",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Learn Pyhidra\n",
    "\n",
    "Pyhidra is a Python library that provides direct access to the Ghidra API within a native CPython interpreter using [jpype](https://jpype.readthedocs.io/en/latest). As well, Pyhidra contains some conveniences for setting up analysis on a given sample and running a Ghidra script locally. It also contains a Ghidra plugin to allow the use of CPython from the Ghidra user interface.\n",
    "\n",
    "In this script, we will learn how to use basic functions provided by pyhidra.\n",
    "Furthermore, we will discover the function related to binary analysis\n",
    "\n",
    "* **Task 1:** wirte a inherit launcher class to implement log service\n",
    "* **Task 2:** Create or open a project with given path and name \n",
    "* **Task 3:** import a program with path and name and get the flat api\n",
    "    * flat_api is a interface to export many useful functions without determine the class of it\n",
    "* **Task 4:** set the correct base address of the binary file\n",
    "* **Task 5:** create a function based on the vector table \n",
    "* **Task 6:** create a data as a pointer refer to a function\n",
    "* **Task 7:** Save the program and close the project"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c0cc26c3-5941-4501-acf6-1237e6f0c830",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# remember to set the GHIDRA_INSTALL_DIR first\n",
    "! pip install pyhidra > /dev/null\n",
    "# import launcher\n",
    "from pyhidra.launcher import PyhidraLauncher, GHIDRA_INSTALL_DIR"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "97a1a01c-2933-4ac6-a200-5f05d9fd8b44",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Task 1: wirte a inherit launcher class to implement log service\n",
    "# inherit PyhidraLauncher to save the log to file \n",
    "class HeadlessLoggingPyhidraLauncher(PyhidraLauncher):\n",
    "    \"\"\"\n",
    "    Headless pyhidra launcher\n",
    "    Slightly Modified from Pyhidra to allow the Ghidra log path to be set\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, verbose=False, log_path=None):\n",
    "        super().__init__(verbose)\n",
    "        self.log_path = log_path\n",
    "\n",
    "    def _launch(self):\n",
    "        from pyhidra.launcher import _silence_java_output\n",
    "        from ghidra.framework import Application, HeadlessGhidraApplicationConfiguration\n",
    "        from java.io import File\n",
    "        with _silence_java_output(not self.verbose, not self.verbose):\n",
    "            config = HeadlessGhidraApplicationConfiguration()\n",
    "            if self.log_path:\n",
    "                log = File(self.log_path)\n",
    "                config.setApplicationLogFile(log)\n",
    "            Application.initializeApplication(self._layout,config)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "debc3537-612e-4649-a1e7-cb9891698dd8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# start the Launcher \n",
    "launcher = HeadlessLoggingPyhidraLauncher(verbose=True, log_path='./launch.log')\n",
    "launcher.start()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eef7b382-92a8-409d-a22b-103288961501",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Task 2: Create or open a project with given path and name \n",
    "# Necessary imports for ghidra project \n",
    "from ghidra.base.project import GhidraProject\n",
    "from java.io import IOException\n",
    "from pathlib import Path \n",
    "\n",
    "# Create Project Dir and name \n",
    "project_location = Path('./ghidra_project')\n",
    "project_location.mkdir(exist_ok=True, parents=True)\n",
    "project_name = \"test_project\"\n",
    "\n",
    "# create or open project \n",
    "try:\n",
    "    project = GhidraProject.openProject(project_location, project_name, True)\n",
    "    print(f'Opened project: {project.project.name}')\n",
    "except IOException:\n",
    "    project = GhidraProject.createProject(project_location, project_name, False)\n",
    "    print(f'Created project: {project.project.name}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d95b347-04a3-46ec-8f04-5bf44e34d4e1",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Task 3: import a program with path and name and get the flat api\n",
    "program_name = \"STM32L1xxSmartGlass-V1.21-181016.bin\"\n",
    "program_path = Path(\"./\" + program_name)\n",
    "\n",
    "# helper funcs \n",
    "def _get_language(id: str) -> \"Language\":\n",
    "    from ghidra.program.util import DefaultLanguageService\n",
    "    from ghidra.program.model.lang import LanguageID, LanguageNotFoundException\n",
    "    try:\n",
    "        service: \"LanguageService\" = DefaultLanguageService.getLanguageService()\n",
    "        return service.getLanguage(LanguageID(id))\n",
    "    except LanguageNotFoundException:\n",
    "        # suppress the java exception\n",
    "        pass\n",
    "    raise ValueError(\"Invalid Language ID: \"+id)\n",
    "    \n",
    "def _get_compiler_spec(lang: \"Language\", id: str = None) -> \"CompilerSpec\":\n",
    "    if id is None:\n",
    "        return lang.getDefaultCompilerSpec()\n",
    "    from ghidra.program.model.lang import CompilerSpecID, CompilerSpecNotFoundException\n",
    "    try:\n",
    "        return lang.getCompilerSpecByID(CompilerSpecID(id))\n",
    "    except CompilerSpecNotFoundException:\n",
    "        # suppress the java exception\n",
    "        pass\n",
    "    lang_id = lang.getLanguageID()\n",
    "    raise ValueError(f\"Invalid CompilerSpecID: {id} for Language: {lang_id.toString()}\")\n",
    "    \n",
    "# import program  \n",
    "lang =  _get_language(\"ARM:LE:32:Cortex\")\n",
    "program = project.importProgram(program_path,lang , _get_compiler_spec(lang))\n",
    "\n",
    "# get the flat api \n",
    "from ghidra.program.flatapi import FlatProgramAPI\n",
    "flat_api = FlatProgramAPI(program)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ab3a250-5cd8-4979-bdef-77a59aeb2cee",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Task 4: set the correct base address of the binary file\n",
    "# set base address\n",
    "image_base = 0x8003000\n",
    "print(f'Original Image Base: {program.getImageBase()}')\n",
    "old_base = program.getImageBase()\n",
    "# setImageBase (Address base, boolean commit)\n",
    "program.setImageBase(old_base.getNewAddress(image_base), True)\n",
    "# test for the result\n",
    "print(hex(flat_api.getInt(flat_api.toAddr(image_base))))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "13b36acf-d6b7-43b6-962e-a2734fbffd1c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Task 5: create a function based on the vector table \n",
    "# raw program has no function \n",
    "list_ = program.getListing()\n",
    "funcs = list_.getFunctions(False)\n",
    "print(f'has func :{funcs.hasNext()}')\n",
    "# create one function \n",
    "entry_point = flat_api.toAddr(flat_api.getInt(flat_api.toAddr(image_base + 4)) - 1)\n",
    "print(f'Entry Point :{entry_point}')\n",
    "flat_api.createFunction(entry_point, 'Reset_Handler')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b945efc0-ac7c-4ccc-8d07-dfddef523db2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# create pointer for handler \n",
    "# TODO: the dword + reference is different from the original pointer data type, \n",
    "# For **may** the correct operation, see the ArmThumbFunctionTableScript.java in Script manager\n",
    "from ghidra.program.model.symbol import RefType\n",
    "addr_ = flat_api.toAddr(image_base +4)\n",
    "data_ = flat_api.createDWord(addr_)\n",
    "flat_api.createLabel(addr_, \"RESET\", False)\n",
    "flat_api.createMemoryReference(data_, entry_point, RefType.UNCONDITIONAL_CALL)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32605bf1-4097-4842-80aa-19ca59a670a6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Example: Create All labels and Functions based on the vector table \n",
    "# used for rename thunk function\n",
    "from ghidra.program.model.symbol import SourceType\n",
    "handler_name = ['MasterStackPointer', 'Reset_Handler', 'NMI_Handler', 'HardFault_Handler', \n",
    " 'MemManage_Handler', 'BusFault_Handler','UsageFault_Handler',\n",
    "    'Reserved1','Reserved2','Reserved3','Reserved4',\n",
    " 'SVC_Handler', 'Reserved5','Reserved6','PendSV_Handler','SysTick_Handler']\n",
    "i = 0\n",
    "program_len = int(program.getMaxAddress().subtract(program.getMinAddress()))\n",
    "while True:\n",
    "    i += 1\n",
    "    addr_ = flat_api.toAddr(image_base +4*i)\n",
    "    handler_address = flat_api.getInt(addr_) - 1\n",
    "    if handler_address == -1 or handler_address == 0xfffffffe:\n",
    "        flat_api.createDWord(addr_)\n",
    "        continue\n",
    "    elif handler_address > image_base and (handler_address - image_base) < program_len:\n",
    "        if i >= len(handler_name):\n",
    "            name_ = 'IRQ' + str(i-16)+ '_Handler'\n",
    "        else:\n",
    "            name_ = handler_name[i]\n",
    "        # create Data and reference \n",
    "        label_ = name_[:name_.find('_')]\n",
    "        data_ = flat_api.createDWord(addr_)\n",
    "        flat_api.createLabel(addr_, label_, True)\n",
    "        flat_api.createMemoryReference(data_, flat_api.toAddr(handler_address), RefType.UNCONDITIONAL_CALL)\n",
    "        # create Function \n",
    "        flat_api.disassemble(flat_api.toAddr(handler_address))\n",
    "        newfunc = flat_api.createFunction(flat_api.toAddr(handler_address), name_)\n",
    "        # rename thunk functions \n",
    "        if newfunc.getName()[:6] == 'thunk_':\n",
    "            newfunc.setName(name_, SourceType.USER_DEFINED)\n",
    "    else:\n",
    "        print(f'Add {i} handlers')\n",
    "        # not a correct handler \n",
    "        break\n",
    "   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f271a45e-0ee7-43a0-873c-f838b9797db3",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Auto Analyze for remaining functions \n",
    "flat_api.analyzeAll(program)\n",
    "# TODO: analyze the remaining addressed which cannot be handled by analyzeAll()\n",
    "# from ghidra.program.model.address import *\n",
    "# set_ = AddressSet(program.getMinAddress(), program.getMaxAddress())\n",
    "# undefinedset_ = program.getListing().getUndefinedRanges(set_, False, None)\n",
    "# print(f'Undefined Nums: {undefinedset_.getNumAddressRanges()}')\n",
    "# for range_ in undefinedset_:\n",
    "#     print(f' Min:{range_.getMinAddress()} Max:{range_.getMaxAddress()}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "036da10b-d354-49e3-95b3-11dac98843b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Task 6: Save the program and close the project\n",
    "project.saveAs(program, \"/\", program.getName(), True)\n",
    "project.save(program)\n",
    "project.close()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8398e0c3-4180-45e4-9a15-a06d5b8f189f",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}