Ghidra is a software reverse engineering (SRE) framework
GP-5637: New PyGhidra API
Ryan Kurtzf5fd0171a2bd
diff --git a/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraProject.java b/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraProject.javanew file mode 100644index 0000000000..8f01041c06--- /dev/null+++ b/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraProject.java@@ -0,0 +1,29 @@+/* ###+ * IP: GHIDRA+ *+ * Licensed under the Apache License, Version 2.0 (the "License");+ * you may not use this file except in compliance with the License.+ * You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */+package ghidra.pyghidra;++import ghidra.framework.data.DefaultProjectData;+import ghidra.framework.main.AppInfo;+import ghidra.framework.model.ProjectData;+import ghidra.framework.project.DefaultProject;++public class PyGhidraProject extends DefaultProject {++ public PyGhidraProject(PyGhidraProjectManager projectManager, ProjectData projectData) {+ super(projectManager, (DefaultProjectData) projectData);+ AppInfo.setActiveProject(this);+ }+}diff --git a/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/interpreter/InterpreterGhidraScript.java b/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/interpreter/InterpreterGhidraScript.javaindex a1961aaf95..fb6f36d3ee 100644--- a/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/interpreter/InterpreterGhidraScript.java+++ b/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/interpreter/InterpreterGhidraScript.java@@ -17,7 +17,7 @@ package ghidra.pyghidra.interpreter;import java.io.PrintWriter;-import ghidra.app.script.*;+import ghidra.app.script.GhidraScript;import ghidra.program.model.address.Address;import ghidra.program.model.listing.Program;import ghidra.program.util.ProgramLocation;@@ -83,8 +83,4 @@ public final class InterpreterGhidraScript extends GhidraScript {currentHighlight = highlight;state.setCurrentHighlight(highlight);}-- public void set(GhidraState state, PrintWriter writer) {- set(state, new ScriptControls(writer, writer, new InterpreterTaskMonitor(writer)));- }}diff --git a/Ghidra/Features/PyGhidra/src/main/py/README.md b/Ghidra/Features/PyGhidra/src/main/py/README.mdindex 4550be5b4b..cb3df45fb8 100644--- a/Ghidra/Features/PyGhidra/src/main/py/README.md+++ b/Ghidra/Features/PyGhidra/src/main/py/README.md@@ -21,33 +21,28 @@ instructions in this document focus on this type of usage.To install the PyGhidra Python library:1. Download and install- [Ghidra 11.3 or later](https://github.com/NationalSecurityAgency/ghidra/releases) to a desired+ [Ghidra 12.0 or later](https://github.com/NationalSecurityAgency/ghidra/releases) to a desiredlocation.-2. Set the `GHIDRA_INSTALL_DIR` environment variable to point to the directory where Ghidra is- installed.-3. Install PyGhidra:+2. Install PyGhidra:* Online: `pip install pyghidra`* Offline: `python3 -m pip install --no-index -f<GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra`--Optionally, you can also install the Ghidra type stubs to improve your development experience-(assuming your Python editor supports it). The type stubs module is specific to each version of-Ghidra:-* Online: `pip install ghidra-stubs==<version>`-* Offline: `python3 -m pip install --no-index -f <GhidraInstallDir>/docs/ghidra_stubs ghidra-stubs`+3. Optionally install the Ghidra type stubs to improve your development experience (assuming your+ Python editor supports it). The type stubs module is specific to each version of Ghidra:+ * Online: `pip install ghidra-stubs==<version>`+ * Offline: `python3 -m pip install --no-index -f <GhidraInstallDir>/docs/ghidra_stubs ghidra-stubs`+4. Optionally point PyGhidra at your Ghidra installation by setting the `GHIDRA_INSTALL_DIR`+ environment variable. If not set, PyGhidra will point itself at the last used installation of+ Ghidra. Alternatively, you can point PyGhidra at a Ghidra installation with+ `pyghidra.start(install_dir=<GhidraInstallDir>)` (see below).## API-The current version of PyGhidra inherits an API from the original "Pyhidra" project that provides an-excellent starting point for interacting with a Ghidra installation. __NOTE:__ These functions are-subject to change in the future as more thought and feedback is collected on PyGhidra's role in the-greater Ghidra ecosystem:+The current version of PyGhidra introduces many new API methods with the goal of making the most+common Ghidra tasks quick and easy, such as opening a project, getting a program, running a+GhidraScript, etc. The inherited API from the original "Pyhidra" project is still available, but at+this point it will only receive bug fixes.### pyghidra.start()-To get a raw connection to Ghidra use the `start()` function. This will setup a JPype connection and-initialize Ghidra in headless mode, which will allow you to directly import `ghidra` and `java`.--__NOTE:__ No projects or programs get setup in this mode.-```pythondef start(verbose=False, *, install_dir: Path = None) -> "PyGhidraLauncher":"""@@ -60,38 +55,264 @@ def start(verbose=False, *, install_dir: Path = None) -> "PyGhidraLauncher":"""```-#### Example:+### pyghidra.started()```python-import pyghidra-pyghidra.start()+def started() -> bool:+ """+ Whether the PyGhidraLauncher has already started.+ """+```-import ghidra-from ghidra.app.util.headless import HeadlessAnalyzer-from ghidra.program.flatapi import FlatProgramAPI-from ghidra.base.project import GhidraProject-from java.lang import String+### pyghidra.open_project()+```python+def open_project(+ path: Union[str, Path],+ name: str,+ create: bool = False+) -> "Project": # type: ignore+ """+ Opens the Ghidra project at the given location, optionally creating it if it doesn't exist.-# do things+ :param path: Path of Ghidra project parent directory.+ :param name: Name of Ghidra project to open/create.+ :param create: Whether to create the project if it doesn't exist+ :return: A Ghidra "Project" object.+ :raises FileNotFoundError: If the project to open was not found and it shouldn't be created.+ """```-### pyghidra.started()-To check to see if PyGhidra has been started, use the `started()` function.+### pyghidra.open_filesystem()+```python+def open_filesystem(+ path: Union[str, Path]+ ) -> "GFileSystem":+ """+ Opens a filesystem in Ghidra.+ :param path: Path of filesystem to open in Ghidra.+ :return: A Ghidra "GFileSystem" object.+ :raises ValueError: If the filesystem to open is not supported by Ghidra.+ """+```++### pyghidra.consume_program()```python-def started() -> bool:+def consume_program(+ project: "Project",+ path: Union[str, Path],+ consumer: Any = None+ ) -> Tuple["Program", "Object"]:"""- Whether the PyGhidraLauncher has already started.+ Gets the Ghidra program from the given project with the given project path. The returned program+ must be manually released when it is no longer needed.++ :param project: The Ghidra project that has the program.+ :param path: The project path of the program (should start with "/")+ :param consumer: An optional reference to the Java object "consuming" the returned program, used+ to ensure the underlying DomainObject is only closed when every consumer is done with it. If+ a consumer is not provided, one will be generated by this function.+ :return: A 2-element tuple containing the program and a consumer object that must be used to+ release the program when finished with it (i.e., program.release(consumer). If a consumer+ object was provided, the same consumer object is returned. Otherwise, a new consumer object+ is created and returned.+ :raises FileNotFoundError: If the path does not exist in the project.+ :raises TypeError: If the path in the project exists but is not a Program."""```-#### Example:+### pyghidra.program_context()```python-import pyghidra+def program_context(+ project: "Project",+ path: Union[str, Path],+ ) -> "Program":+ """+ Gets the Ghidra program from the given project with the given project path. The returned+ program's resource cleanup is performed by a context manager.++ :param project: The Ghidra project that has the program.+ :param path: The project path of the program (should start with "/").+ :return: The Ghidra program.+ :raises FileNotFoundError: If the path does not exist in the project.+ :raises TypeError: If the path in the project exists but is not a Program.+ """+```-if pyghidra.started():- ...+### pyghidra.analyze()+```python+def analyze(program: "Program"):+ """+ Analyzes the given program.++ :param program: The Ghidra program to analyze.+ """+```++### pyghidra.ghidra_script()+```python+def ghidra_script(+ path: Union[str, Path],+ project: "Project",+ program: "Program" = None,+ echo_stdout = True,+ echo_stderr = True+ ) -> Tuple[str, str]:+ """+ Runs any type of GhidraScript (Java, PyGhidra, Jython, etc).++ :param path: The GhidraScript's path.+ :param project: The Ghidra project to run the GhidraScript in.+ :param program: An optional Ghidra program that the GhidraScript will see as its "currentProgram".+ :param echo_stdout: Whether or not to echo the GhidraScript's standard output.+ :param echo_stderr: Whether or not to echo the GhidraScript's standard error.+ :return: A 2 element tuple consisting of the GhidraScript's standard output and standard error.+ """+```++### pyghidra.transaction()+```python+def transaction(+ program: "Program",+ description: str = "Unnamed Transaction"+ ):+ """+ Creates a context for running a Ghidra transaction.++ :param program: The Ghidra program that will be affected.+ :param description: The transaction description+ :return: The transaction ID.+ """```+### pyghidra.analysis_properties()+```python+def analysis_properties(program: "Program") -> "Options":+ """+ Convenience function to get the Ghidra "Program.ANALYSIS_PROPERTIES" options.++ :return: the Ghidra "Program.ANALYSIS_PROPERTIES" options.+ """+```++### pyghidra.program_info()+```python+def program_info(program: "Program") -> "Options":+ """+ Convenience function to get the Ghidra "Program.PROGRAM_INFO" options.++ :return: the Ghidra "Program.PROGRAM_INFO" options.+ """+```++### pyghidra.program_loader()+```python+def program_loader() -> "ProgramLoader.Builder":+ """+ Convenience function to get a Ghidra "ProgramLoader.Builder" object.++ :return: A Ghidra "ProgramLoader.Builder" object.+ """+```++### pyghidra.dummy_monitor()+```python+def dummy_monitor() -> "TaskMonitor":+ """+ Convenience function to get the Ghidra "TaskMonitor.DUMMY" object.++ :return: The Ghidra "TaskMonitor.DUMMY" object.+ """+```++### pyghidra.walk_project()+```python+def walk_project(+ project: "Project",+ callback: Callable[["DomainFile"], None],+ start: Union[str, Path] = "/",+ file_filter: Callable[["DomainFile"], bool] = lambda _f: True+ ):+ """+ Walks the the given Ghidra project, calling the provided function when each domain file is+ encountered.++ :param project: The Ghidra project to walk.+ :param callback: The callback to process each domain file.+ :param start: An optional starting project folder path.+ :param file_filter: A filter used to limit what domain files get processed.+ :raises FileNotFoundError: If the starting folder is not found in the project.+ """+```++### pyghidra.walk_programs()+```python+def walk_programs(+ project: "Project",+ callback: Callable[["DomainFile", "Program"], None],+ start: Union[str, Path] = "/",+ program_filter: Callable[["DomainFile", "Program"], bool] = lambda _f, _p: True+ ):+ """+ Walks the the given Ghidra project, calling the provided function when each program is+ encountered. Non-programs in the project are skipped.++ :param project: The Ghidra project to walk.+ :param callback: The callback to process each program.+ :param start: An optional starting project folder path.+ :param program_filter: A filter used to limit what programs get processed.+ :raises FileNotFoundError: If the starting folder is not found in the project.+ """+```++## Example+The following example, while not very useful, showcases much of the API:+```python+import os, jpype, pyghidra+pyghidra.start()++# Open/create a project+with pyghidra.open_project(os.environ["GHIDRA_PROJECT_DIR"], "ExampleProject", create=True) as project:++ # Walk a Ghidra release zip file, load every decompiler binary, and save them to the project+ with pyghidra.open_filesystem(f"{os.environ['DOWNLOADS_DIR']}/ghidra_11.4_PUBLIC_20250620.zip") as fs:+ loader = pyghidra.program_loader().project(project)+ for f in fs.files(lambda f: "os/" in f.path and f.name.startswith("decompile")):+ loader.source(f.getFSRL()).projectFolderPath("/" + f.parentFile.name)+ with loader.load() as load_results:+ load_results.save(pyghidra.dummy_monitor())++ # Analyze the windows decompiler program+ with pyghidra.program_context(project, "/win_x86_64/decompile.exe") as program:+ analysis_props = pyghidra.analysis_properties(program)+ with pyghidra.transaction(program):+ analysis_props.setBoolean("Non-Returning Functions - Discovered", False)+ pyghidra.analyze(program)+ program.save("Analyzed", pyghidra.dummy_monitor())++ # Walk the project and set a propery in each decompiler program+ def set_property(domain_file, program):+ with pyghidra.transaction(program):+ program_info = pyghidra.program_info(program)+ program_info.setString("PyGhidra Property", "Set by PyGhidra!")+ program.save("Setting property", pyghidra.dummy_monitor())+ pyghidra.walk_programs(project, set_property, program_filter=lambda f, p: p.name.startswith("decompile"))++ # Load some bytes as a new program+ ByteArrayCls = jpype.JArray(jpype.JByte)+ my_bytes = ByteArrayCls(b"\xaa\xbb\xcc\xdd\xee\xff")+ loader = pyghidra.program_loader().project(project).source(my_bytes).name("my_bytes")+ loader.loaders("BinaryLoader").language("DATA:LE:64:default")+ with loader.load() as load_results:+ load_results.save(pyghidra.dummy_monitor())++ # Run a GhidraScript+ pyghidra.ghidra_script(f"{os.environ['GHIDRA_SCRIPTS_DIR']}/HelloWorldScript.java", project)+```++## Legacy API+### pyghidra.open_program()To have PyGhidra setup a binary file for you, use the `open_program()` function. This will setup aGhidra project and import the given binary file as a program for you.@@ -325,6 +546,10 @@ import pdb # imports Python's pdbimport pdb_ # imports Ghidra's pdb```## Change History+__3.0.0:__+* Introduced many new functions to the PyGhidra API. PyGhidra 3.0.0 requires Ghidra 12.0 or later+ to run.+__2.2.1:__* PyGhidra now launches with the current working directory removed from `sys.path` to preventthe potential for importing invalid modules from random `ghidra/` or `java/` directories that maydiff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.pyindex acff535673..713e00f538 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.py@@ -13,7 +13,7 @@# See the License for the specific language governing permissions and# limitations under the License.##-__version__ = "2.2.1"+__version__ = "3.0.0"# stub for documentation and typing# this is mostly to hide the function parameter@@ -55,6 +55,9 @@ debug_callback = _debug_callback# Expose APIfrom pyghidra.core import run_script, start, started, open_program+from pyghidra.api import open_project, open_filesystem, consume_program, program_context, analyze+from pyghidra.api import ghidra_script, transaction, analysis_properties, program_info+from pyghidra.api import program_loader, dummy_monitor, walk_project, walk_programsfrom pyghidra.launcher import DeferredPyGhidraLauncher, GuiPyGhidraLauncher, HeadlessPyGhidraLauncherfrom pyghidra.script import get_current_interpreterfrom pyghidra.version import ApplicationInfo, ExtensionDetails@@ -63,5 +66,8 @@ from pyghidra.version import ApplicationInfo, ExtensionDetails__all__ = ["debug_callback", "get_current_interpreter", "open_program", "run_script", "start","started", "ApplicationInfo", "DeferredPyGhidraLauncher", "ExtensionDetails",- "GuiPyGhidraLauncher", "HeadlessPyGhidraLauncher"+ "GuiPyGhidraLauncher", "HeadlessPyGhidraLauncher", "open_project", "open_filesystem",+ "consume_program", "program_conext", "analyze", "ghidra_script", "transaction",+ "analysis_properties", "program_info", "program_loader", "dummy_monitor", "walk_project",+ "walk_programs"]diff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/api.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/api.pynew file mode 100644index 0000000000..7bcd4e3798--- /dev/null+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/api.py@@ -0,0 +1,313 @@+## ###+# IP: GHIDRA+#+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+##+import sys+import contextlib+from typing import Union, TYPE_CHECKING, Tuple, Callable, Any++from pyghidra.converters import * # pylint: disable=wildcard-import, unused-wildcard-import++if TYPE_CHECKING:+ from ghidra.program.model.listing import Program+ from ghidra.program.util import GhidraProgramUtilities+ from ghidra.framework.model import Project, DomainFile+ from ghidra.framework.options import Options+ from ghidra.formats.gfilesystem import GFileSystem+ from ghidra.formats.gfilesystem import FSUtilities+ from ghidra.util.task import TaskMonitor+ from ghidra.app.script import GhidraScript+ from ghidra.app.util.importer import ProgramLoader+ from generic.jar import ResourceFile+ from java.lang import Object # type:ignore @UnresolvedImport++def open_project(+ path: Union[str, Path],+ name: str,+ create: bool = False+) -> "Project": # type: ignore+ """+ Opens the Ghidra project at the given location, optionally creating it if it doesn't exist.++ :param path: Path of Ghidra project parent directory.+ :param name: Name of Ghidra project to open/create.+ :param create: Whether to create the project if it doesn't exist+ :return: A Ghidra "Project" object.+ :raises FileNotFoundError: If the project to open was not found and it shouldn't be created.+ """+ from ghidra.framework.model import ProjectLocator+ from ghidra.pyghidra import PyGhidraProjectManager++ projectLocator = ProjectLocator(path, name);+ projectManager = PyGhidraProjectManager()+ if projectLocator.exists():+ return projectManager.openProject(projectLocator, False, True);+ elif create:+ return projectManager.createProject(projectLocator, None, True)+ raise FileNotFoundError(f'Project "{name}" not found at "{path}"!')++def open_filesystem(+ path: Union[str, Path]+ ) -> "GFileSystem":+ """+ Opens a filesystem in Ghidra.++ :param path: Path of filesystem to open in Ghidra.+ :return: A Ghidra "GFileSystem" object.+ :raises ValueError: If the filesystem to open is not supported by Ghidra.+ """+ from java.io import File # type:ignore @UnresolvedImport+ from ghidra.formats.gfilesystem import FileSystemService++ service = FileSystemService.getInstance()+ fsrl = service.getLocalFS().getLocalFSRL(File(path))+ fs = service.openFileSystemContainer(fsrl, dummy_monitor())+ if fs is None:+ raise ValueError(f'"{fsrl}" is not a supported GFileSystem!')+ return fs++def consume_program(+ project: "Project",+ path: Union[str, Path],+ consumer: Any = None+ ) -> Tuple["Program", "Object"]:+ """+ Gets the Ghidra program from the given project with the given project path. The returned program+ must be manually released when it is no longer needed.++ :param project: The Ghidra project that has the program.+ :param path: The project path of the program (should start with "/")+ :param consumer: An optional reference to the Java object "consuming" the returned program, used+ to ensure the underlying DomainObject is only closed when every consumer is done with it. If+ a consumer is not provided, one will be generated by this function.+ :return: A 2-element tuple containing the program and a consumer object that must be used to+ release the program when finished with it (i.e., program.release(consumer). If a consumer+ object was provided, the same consumer object is returned. Otherwise, a new consumer object+ is created and returned.+ :raises FileNotFoundError: If the path does not exist in the project.+ :raises TypeError: If the path in the project exists but is not a Program.+ """+ from ghidra.program.model.listing import Program+ from java.lang import Object # type:ignore @UnresolvedImport+ if consumer is None:+ consumer = Object()+ project_data = project.getProjectData()+ df = project_data.getFile(path)+ if df is None:+ raise FileNotFoundError(f'"{path}" does not exist in the Project')+ dobj = df.getDomainObject(consumer, True, False, dummy_monitor())+ program_cls = Program.class_+ if not program_cls.isAssignableFrom(dobj.getClass()):+ dobj.release(consumer)+ raise TypeError(f'"{path}" exists but is not a Program')+ return dobj, consumer++def program_context(+ project: "Project",+ path: Union[str, Path],+ ) -> "Program":+ """+ Gets the Ghidra program from the given project with the given project path. The returned+ program's resource cleanup is performed by a context manager.++ :param project: The Ghidra project that has the program.+ :param path: The project path of the program (should start with "/").+ :return: The Ghidra program.+ :raises FileNotFoundError: If the path does not exist in the project.+ :raises TypeError: If the path in the project exists but is not a Program.+ """+ program, consumer = consume_program(project, path)+ try:+ yield program+ finally:+ program.release(consumer)++def analyze(program: "Program"):+ """+ Analyzes the given program.++ :param program: The Ghidra program to analyze.+ """+ from ghidra.app.script import GhidraScriptUtil+ from ghidra.program.flatapi import FlatProgramAPI+ from ghidra.program.util import GhidraProgramUtilities+ with transaction(program, "Analyze"):+ GhidraScriptUtil.acquireBundleHostReference()+ try:+ FlatProgramAPI(program).analyzeAll(program)+ GhidraProgramUtilities.markProgramAnalyzed(program)+ finally:+ GhidraScriptUtil.releaseBundleHostReference()++def ghidra_script(+ path: Union[str, Path],+ project: "Project",+ program: "Program" = None,+ echo_stdout = True,+ echo_stderr = True+ ) -> Tuple[str, str]:+ """+ Runs any type of GhidraScript (Java, PyGhidra, Jython, etc).++ :param path: The GhidraScript's path.+ :param project: The Ghidra project to run the GhidraScript in.+ :param program: An optional Ghidra program that the GhidraScript will see as its "currentProgram".+ :param echo_stdout: Whether or not to echo the GhidraScript's standard output.+ :param echo_stderr: Whether or not to echo the GhidraScript's standard error.+ :return: A 2 element tuple consisting of the GhidraScript's standard output and standard error.+ """+ from generic.jar import ResourceFile+ from ghidra.app.script import GhidraScriptUtil, GhidraState, ScriptControls+ from java.io import File, PrintWriter, StringWriter # type:ignore @UnresolvedImport+ from java.lang import System # type:ignore @UnresolvedImport++ GhidraScriptUtil.acquireBundleHostReference()+ try:+ source_file = ResourceFile(File(path))+ if not source_file.exists():+ raise TypeError(f'"{str(source_file)}" was not found')+ provider = GhidraScriptUtil.getProvider(source_file)+ if provider is None:+ raise TypeError(f'"{path}" is not a supported GhidraScript')+ script = provider.getScriptInstance(source_file, PrintWriter(System.out))+ if script is None:+ raise TypeError(f'"{str(source_file)}" was not found')+ state = GhidraState(None, project, program, None, None, None)+ stdout_string_writer = StringWriter()+ stderr_string_writer = StringWriter()+ controls = ScriptControls(+ PrintWriter(stdout_string_writer, True),+ PrintWriter(stderr_string_writer, True),+ dummy_monitor()+ )+ script.execute(state, controls)+ stdout_str = str(stdout_string_writer)+ stderr_str = str(stderr_string_writer)+ if echo_stdout:+ sys.stdout.write(stdout_str)+ sys.stdout.flush()+ if echo_stderr:+ sys.stderr.write(stderr_str)+ sys.stderr.flush()+ return stdout_str, stderr_str+ finally:+ GhidraScriptUtil.releaseBundleHostReference()++def transaction(+ program: "Program",+ description: str = "Unnamed Transaction"+ ):+ """+ Creates a context for running a Ghidra transaction.++ :param program: The Ghidra program that will be affected.+ :param description: The transaction description+ :return: The transaction ID.+ """+ transaction_id = program.startTransaction(description)+ success = True+ try:+ yield transaction_id+ except:+ success = False+ finally:+ program.endTransaction(transaction_id, success)++def analysis_properties(program: "Program") -> "Options":+ """+ Convenience function to get the Ghidra "Program.ANALYSIS_PROPERTIES" options.++ :return: the Ghidra "Program.ANALYSIS_PROPERTIES" options.+ """+ from ghidra.program.model.listing import Program+ return program.getOptions(Program.ANALYSIS_PROPERTIES)++def program_info(program: "Program") -> "Options":+ """+ Convenience function to get the Ghidra "Program.PROGRAM_INFO" options.++ :return: the Ghidra "Program.PROGRAM_INFO" options.+ """+ from ghidra.program.model.listing import Program+ return program.getOptions(Program.PROGRAM_INFO)++def program_loader() -> "ProgramLoader.Builder":+ """+ Convenience function to get a Ghidra "ProgramLoader.Builder" object.++ :return: A Ghidra "ProgramLoader.Builder" object.+ """+ from ghidra.app.util.importer import ProgramLoader+ return ProgramLoader.builder()++def dummy_monitor() -> "TaskMonitor":+ """+ Convenience function to get the Ghidra "TaskMonitor.DUMMY" object.++ :return: The Ghidra "TaskMonitor.DUMMY" object.+ """+ from ghidra.util.task import TaskMonitor+ return TaskMonitor.DUMMY++def walk_project(+ project: "Project",+ callback: Callable[["DomainFile"], None],+ start: Union[str, Path] = "/",+ file_filter: Callable[["DomainFile"], bool] = lambda _f: True+ ):+ """+ Walks the the given Ghidra project, calling the provided function when each domain file is+ encountered.++ :param project: The Ghidra project to walk.+ :param callback: The callback to process each domain file.+ :param start: An optional starting project folder path.+ :param file_filter: A filter used to limit what domain files get processed.+ :raises FileNotFoundError: If the starting folder is not found in the project.+ """+ from ghidra.framework.model import ProjectDataUtils+ start_folder = project.projectData.getFolder(start)+ if start_folder is None:+ raise FileNotFoundError(f'Starting folder "{start}" does not exist in the Project')+ for file in ProjectDataUtils.DomainFileIterator(start_folder):+ if file_filter(file):+ callback(file)++def walk_programs(+ project: "Project",+ callback: Callable[["DomainFile", "Program"], None],+ start: Union[str, Path] = "/",+ program_filter: Callable[["DomainFile", "Program"], bool] = lambda _f, _p: True+ ):+ """+ Walks the the given Ghidra project, calling the provided function when each program is+ encountered. Non-programs in the project are skipped.++ :param project: The Ghidra project to walk.+ :param callback: The callback to process each program.+ :param start: An optional starting project folder path.+ :param program_filter: A filter used to limit what programs get processed.+ :raises FileNotFoundError: If the starting folder is not found in the project.+ """+ def process(file: "DomainFile"):+ try:+ with program_context(project, file.getPathname()) as program:+ if program_filter(file, program):+ callback(file, program)+ except TypeError:+ pass # skip over non-programs++ walk_project(project, process, start=start)diff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/core.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/core.pyindex e813fe41a2..3c426dd02b 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/core.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/core.py@@ -176,7 +176,7 @@ def _setup_script(project: "GhidraProject", program: "Program"):location = ProgramLocation(program, mem.getMinAddress())state = GhidraState(None, project, program, location, None, None)script = PyGhidraScript()- script.set(state, TaskMonitor.DUMMY, PrintWriter(System.out))+ script.set(state, TaskMonitor.DUMMY, PrintWriter(System.out), PrintWriter(System.err))return script@@ -187,10 +187,7 @@ def _analyze_program(flat_api, program):GhidraScriptUtil.acquireBundleHostReference()try:flat_api.analyzeAll(program)- if hasattr(GhidraProgramUtilities, "markProgramAnalyzed"):- GhidraProgramUtilities.markProgramAnalyzed(program)- else:- GhidraProgramUtilities.setAnalyzedFlag(program, True) # @UndefinedVariable+ GhidraProgramUtilities.markProgramAnalyzed(program)finally:GhidraScriptUtil.releaseBundleHostReference()diff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/internal/plugin/plugin.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/internal/plugin/plugin.pyindex 44bb9e8207..913b6e143e 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/internal/plugin/plugin.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/internal/plugin/plugin.py@@ -23,9 +23,11 @@ import threadingimport typesfrom code import InteractiveConsole+from ghidra.app.script import ScriptControlsfrom ghidra.framework import Applicationfrom ghidra.pyghidra import PyGhidraScriptProvider, PyGhidraPluginfrom ghidra.pyghidra.interpreter import PyGhidraConsole+from ghidra.util.task import TaskMonitorfrom java.io import BufferedReader, InputStreamReader # type:ignore @UnresolvedImportfrom java.lang import String # type:ignore @UnresolvedImportfrom java.lang import Thread as JThread # type:ignore @UnresolvedImport@@ -160,11 +162,12 @@ class PyConsole(InteractiveConsole):self._out = console.getOutWriter()self._err = console.getErrWriter()self._writer = self._out+ self._error_writer = self._errself._thread = Noneself._interact_thread = Noneself._script = self.locals._scriptstate = self._script.getState()- self._script.set(state, self._out)+ self._script.set(state, ScriptControls(console, TaskMonitor.DUMMY))self._state = ConsoleState.RESETself._completer = PythonCodeCompleter(self)diff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/script.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/script.pyindex 6609295689..70cadcd7c4 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/script.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/script.py@@ -205,12 +205,6 @@ class PyGhidraScript(dict):def get_static_view(self):return _StaticMap(self)- def set(self, state, monitor, writer):- """- see GhidraScript.set- """- self._script.set(state, monitor, writer)-def run(self, script_path: str = None, script_args: List[str] = None):"""Run this GhidraScriptdiff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/version.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/version.pyindex fbfd44342b..0f70b751cf 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/version.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/version.py@@ -19,7 +19,7 @@ from pathlib import Pathimport re-MINIMUM_GHIDRA_VERSION = "11.2"+MINIMUM_GHIDRA_VERSION = "12.0"_APPLICATION_PATTERN = re.compile(r"^application\.(\S+?)=(.*)$")