Skip to content

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.java
new file mode 100644
index 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.md
index 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", c
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())
+ load_results.save(pyghidra.monitor())
- # Analyze the windows decompiler program
+ # Analyze the windows decompiler program for a maximum of 10 seconds
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())
+ pyghidra.analyze(program, pyghidra.monitor(10))
+ program.save("Analyzed", pyghidra.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())
+ 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", c
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())
+ load_results.save(pyghidra.monitor())
# Run a GhidraScript
pyghidra.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__.py
index 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, started
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_programs
+from pyghidra.api import program_loader, monitor, walk_project, walk_programs
from pyghidra.launcher import DeferredPyGhidraLauncher, GuiPyGhidraLauncher, HeadlessPyGhidraLauncher
from pyghidra.script import get_current_interpreter
from 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.py
index 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 sys
import contextlib
-from typing import Union, TYPE_CHECKING, Tuple, List, Callable, Any
+from typing import Union, TYPE_CHECKING, Tuple, List, Callable, Any, Optional
from pyghidra.converters import * # pylint: disable=wildcard-import, unused-wildcard-import
if TYPE_CHECKING:
from pyghidra.launcher import PyGhidraLauncher
+ from ghidra.app.plugin.core.analysis import AutoAnalysisManager
from ghidra.program.model.listing import Program
from ghidra.program.util import GhidraProgramUtilities
from ghidra.framework.model import Project, DomainFile
@@ -30,10 +31,11 @@ if TYPE_CHECKING:
from ghidra.util.task import TaskMonitor
from ghidra.app.script import GhidraScript
from ghidra.app.util.importer import ProgramLoader
+ from ghidra.pyghidra import PyGhidraTaskMonitor
from generic.jar import ResourceFile
from 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 FlatProgramAPI
from 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 complete
GhidraProgramUtilities.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 ProgramLoader
return 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",