Ghidra is a software reverse engineering (SRE) framework
GP-5637: More improvements to the PyGhidra API
Ryan Kurtzc18c7a8f50c3
diff --git a/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraTaskMonitor.java b/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraTaskMonitor.javanew file mode 100644index 0000000000..3511fa5cc2--- /dev/null+++ b/Ghidra/Features/PyGhidra/src/main/java/ghidra/pyghidra/PyGhidraTaskMonitor.java@@ -0,0 +1,176 @@+/* ###+ * 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 java.util.Timer;+import java.util.TimerTask;++import org.apache.commons.lang3.function.TriConsumer;++import ghidra.util.datastruct.WeakDataStructureFactory;+import ghidra.util.datastruct.WeakSet;+import ghidra.util.exception.CancelledException;+import ghidra.util.task.CancelledListener;+import ghidra.util.task.TaskMonitor;++/**+ * A {@link TaskMonitor} for use by PyGhidra, which features a cancellation timer and a change+ * callback mechanism+ */+public class PyGhidraTaskMonitor implements TaskMonitor {++ private String message;+ private long progress;+ private long maxProgress;+ private boolean isIndeterminate;+ private volatile boolean isCancelled;++ private Timer timer = new Timer();+ private WeakSet<CancelledListener> listeners =+ WeakDataStructureFactory.createCopyOnReadWeakSet();++ private TriConsumer<String, Long, Long> changeCallback;+++ public PyGhidraTaskMonitor(Integer timeoutSecs,+ TriConsumer<String, Long, Long> changeCallback) {+ isCancelled = false;+ if (timeoutSecs != null) {+ timer.schedule(new PyGhidraTimeOutTask(), timeoutSecs * 1000);+ }+ this.changeCallback = changeCallback;+ }++ @Override+ public void initialize(long maxValue) {+ setMaximum(maxValue);+ setProgress(0);+ setIndeterminate(false);+ }++ @Override+ public void setMessage(String message) {+ this.message = message;+ if (changeCallback != null) {+ changeCallback.accept(message, progress, maxProgress);+ }+ }++ @Override+ public String getMessage() {+ return message;+ }++ @Override+ public void incrementProgress(long incrementAmount) {+ setProgress(progress + incrementAmount);+ }++ @Override+ public void setProgress(long value) {+ progress = value;+ if (changeCallback != null) {+ changeCallback.accept(message, progress, maxProgress);+ }+ }++ @Override+ public long getProgress() {+ return progress;+ }++ @Override+ public boolean isCancelled() {+ return isCancelled;+ }++ @Override+ public void setMaximum(long max) {+ this.maxProgress = max;+ if (progress > max) {+ progress = max;+ }+ if (changeCallback != null) {+ changeCallback.accept(message, progress, maxProgress);+ }+ }++ @Override+ public long getMaximum() {+ return maxProgress;+ }++ @Override+ public void setIndeterminate(boolean indeterminate) {+ isIndeterminate = indeterminate;+ }++ @Override+ public boolean isIndeterminate() {+ return isIndeterminate;+ }++ @Override+ public void checkCanceled() throws CancelledException {+ if (isCancelled()) {+ throw new CancelledException();+ }+ }++ @Override+ public void clearCanceled() {+ isCancelled = false;+ }++ @Override+ public void cancel() {+ timer.cancel(); // Terminate the timer thread+ isCancelled = true;+ }++ @Override+ public void setCancelEnabled(boolean enable) {+ // stub+ }++ @Override+ public boolean isCancelEnabled() {+ return true;+ }++ @Override+ public void setShowProgressValue(boolean showProgressValue) {+ // stub+ }++ @Override+ public void addCancelledListener(CancelledListener listener) {+ listeners.add(listener);+ }++ @Override+ public void removeCancelledListener(CancelledListener listener) {+ listeners.remove(listener);+ }++ private class PyGhidraTimeOutTask extends TimerTask {+ @Override+ public void run() {+ PyGhidraTaskMonitor.this.cancel();+ }+ }+}+diff --git a/Ghidra/Features/PyGhidra/src/main/py/README.md b/Ghidra/Features/PyGhidra/src/main/py/README.mdindex 65e193e2c0..b3bd5f82c2 100644--- a/Ghidra/Features/PyGhidra/src/main/py/README.md+++ b/Ghidra/Features/PyGhidra/src/main/py/README.md@@ -216,13 +216,19 @@ def program_loader() -> "ProgramLoader.Builder":"""```-### pyghidra.dummy_monitor()+### pyghidra.monitor()```python-def dummy_monitor() -> "TaskMonitor":+def monitor(+ timeout: Optional[int] = None,+ change_callback: Callable[[str, int, int], None] = None+ ) -> "PyGhidraTaskMonitor":"""- Convenience function to get the Ghidra "TaskMonitor.DUMMY" object.+ Convenience function to get a "PyGhidraTaskMonitor" object.- :return: The Ghidra "TaskMonitor.DUMMY" object.+ :param timeout: An optional number of seconds to wait before canceling the monitor.+ :param change_callback: A optional function that gets called any time the monitor receives an+ update.+ :return: A "PyGhidraTaskMonitor" object."""```@@ -281,22 +287,22 @@ with pyghidra.open_project(os.environ["GHIDRA_PROJECT_DIR"], "ExampleProject", cfor 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())+ load_results.save(pyghidra.monitor())- # Analyze the windows decompiler program+ # Analyze the windows decompiler program for a maximum of 10 secondswith 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())+ pyghidra.analyze(program, pyghidra.monitor(10))+ program.save("Analyzed", pyghidra.monitor())# Walk the project and set a propery in each decompiler programdef 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())+ program.save("Setting property", pyghidra.monitor())pyghidra.walk_programs(project, set_property, program_filter=lambda f, p: p.name.startswith("decompile"))# Load some bytes as a new program@@ -305,7 +311,7 @@ with pyghidra.open_project(os.environ["GHIDRA_PROJECT_DIR"], "ExampleProject", cloader = 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())+ load_results.save(pyghidra.monitor())# Run a GhidraScriptpyghidra.ghidra_script(f"{os.environ['GHIDRA_SCRIPTS_DIR']}/HelloWorldScript.java", project)diff --git a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.py b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.pyindex 713e00f538..a1d38d9c59 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/__init__.py@@ -54,20 +54,21 @@ debug_callback = _debug_callback# Expose API-from pyghidra.core import run_script, start, started, open_program+from pyghidra.core import run_script, open_program+from pyghidra.api import start, startedfrom pyghidra.api import open_project, open_filesystem, consume_program, program_context, analyzefrom pyghidra.api import ghidra_script, transaction, analysis_properties, program_info-from pyghidra.api import program_loader, dummy_monitor, walk_project, walk_programs+from pyghidra.api import program_loader, monitor, walk_project, walk_programsfrom pyghidra.launcher import DeferredPyGhidraLauncher, GuiPyGhidraLauncher, HeadlessPyGhidraLauncherfrom pyghidra.script import get_current_interpreterfrom pyghidra.version import ApplicationInfo, ExtensionDetails__all__ = [- "debug_callback", "get_current_interpreter", "open_program", "run_script", "start",- "started", "ApplicationInfo", "DeferredPyGhidraLauncher", "ExtensionDetails",- "GuiPyGhidraLauncher", "HeadlessPyGhidraLauncher", "open_project", "open_filesystem",+ "debug_callback", "get_current_interpreter", "open_program", "run_script", "ApplicationInfo",+ "DeferredPyGhidraLauncher", "ExtensionDetails", "GuiPyGhidraLauncher",+ "HeadlessPyGhidraLauncher", "start", "started", "open_project", "open_filesystem","consume_program", "program_conext", "analyze", "ghidra_script", "transaction",- "analysis_properties", "program_info", "program_loader", "dummy_monitor", "walk_project",+ "analysis_properties", "program_info", "program_loader", "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.pyindex 41efff2346..0bb887e6fd 100644--- a/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/api.py+++ b/Ghidra/Features/PyGhidra/src/main/py/src/pyghidra/api.py@@ -15,12 +15,13 @@##import sysimport contextlib-from typing import Union, TYPE_CHECKING, Tuple, List, Callable, Any+from typing import Union, TYPE_CHECKING, Tuple, List, Callable, Any, Optionalfrom pyghidra.converters import * # pylint: disable=wildcard-import, unused-wildcard-importif TYPE_CHECKING:from pyghidra.launcher import PyGhidraLauncher+ from ghidra.app.plugin.core.analysis import AutoAnalysisManagerfrom ghidra.program.model.listing import Programfrom ghidra.program.util import GhidraProgramUtilitiesfrom ghidra.framework.model import Project, DomainFile@@ -30,10 +31,11 @@ if TYPE_CHECKING:from ghidra.util.task import TaskMonitorfrom ghidra.app.script import GhidraScriptfrom ghidra.app.util.importer import ProgramLoader+ from ghidra.pyghidra import PyGhidraTaskMonitorfrom generic.jar import ResourceFilefrom java.lang import Object # type:ignore @UnresolvedImport-def start(verbose=False, *, install_dir: Path = None) -> "PyGhidraLauncher":+def start(verbose=False, *, install_dir: Optional[Path] = None) -> "PyGhidraLauncher":"""Starts the JVM and fully initializes Ghidra in Headless mode.@@ -95,7 +97,7 @@ def open_filesystem(service = FileSystemService.getInstance()fsrl = service.getLocalFS().getLocalFSRL(File(path))- fs = service.openFileSystemContainer(fsrl, dummy_monitor())+ fs = service.openFileSystemContainer(fsrl, monitor())if fs is None:raise ValueError(f'"{fsrl}" is not a supported GFileSystem!')return fs@@ -103,7 +105,7 @@ def open_filesystem(def consume_program(project: "Project",path: Union[str, Path],- consumer: Any = None+ consumer: Optional[Any] = None) -> Tuple["Program", "Object"]:"""Gets the Ghidra program from the given project with the given project path. The returned program@@ -129,7 +131,7 @@ def consume_program(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())+ dobj = df.getDomainObject(consumer, True, False, monitor())program_cls = Program.class_if not program_cls.isAssignableFrom(dobj.getClass()):dobj.release(consumer)@@ -157,19 +159,33 @@ def program_context(finally:program.release(consumer)-def analyze(program: "Program"):+def analyze(+ program: "Program",+ monitor: Optional["TaskMonitor"] = None+ ):"""Analyzes the given program.:param program: The Ghidra program to analyze."""from ghidra.app.script import GhidraScriptUtil- from ghidra.program.flatapi import FlatProgramAPIfrom ghidra.program.util import GhidraProgramUtilities+ from ghidra.app.plugin.core.analysis import AutoAnalysisManager++ if monitor is None:+ monitor = monitor()+with transaction(program, "Analyze"):GhidraScriptUtil.acquireBundleHostReference()try:- FlatProgramAPI(program).analyzeAll(program)+ mgr: AutoAnalysisManager = AutoAnalysisManager.getAnalysisManager(program);+ mgr.initializeOptions();+ mgr.reAnalyzeAll(None);+ analysisTool = mgr.getAnalysisTool();+ if analysisTool is None or analysisTool.threadIsBackgroundTaskThread():+ mgr.startAnalysis(monitor, True); # yields to analysis+ else:+ mgr.waitForAnalysis(None, monitor); # waits for all analysis to completeGhidraProgramUtilities.markProgramAnalyzed(program)finally:GhidraScriptUtil.releaseBundleHostReference()@@ -177,7 +193,7 @@ def analyze(program: "Program"):def ghidra_script(path: Union[str, Path],project: "Project",- program: "Program" = None,+ program: Optional["Program"] = None,script_args: List[str] = [],echo_stdout = True,echo_stderr = True@@ -215,7 +231,7 @@ def ghidra_script(controls = ScriptControls(PrintWriter(stdout_string_writer, True),PrintWriter(stderr_string_writer, True),- dummy_monitor()+ monitor())script.setScriptArgs(script_args)script.execute(state, controls)@@ -279,14 +295,22 @@ def program_loader() -> "ProgramLoader.Builder":from ghidra.app.util.importer import ProgramLoaderreturn ProgramLoader.builder()-def dummy_monitor() -> "TaskMonitor":+def monitor(+ timeout: Optional[int] = None,+ change_callback: Callable[[str, int, int], None] = None+ ) -> "PyGhidraTaskMonitor":"""- Convenience function to get the Ghidra "TaskMonitor.DUMMY" object.+ Convenience function to get a "PyGhidraTaskMonitor" object.- :return: The Ghidra "TaskMonitor.DUMMY" object.+ :param timeout: An optional number of seconds to wait before canceling the monitor.+ :param change_callback: A optional function that gets called any time the monitor receives an+ update.+ :return: A "PyGhidraTaskMonitor" object."""- from ghidra.util.task import TaskMonitor- return TaskMonitor.DUMMY+ from ghidra.pyghidra import PyGhidraTaskMonitor+ from jpype.types import JInt+ t = None if timeout is None else JInt(timeout)+ return PyGhidraTaskMonitor(t, change_callback)def walk_project(project: "Project",