+ GhidraGo is a mechanism to cause Ghidra to display a previously imported program within a + local or multi-user project using a ghidraURL hyperlink similar to an http reference. In + practice ghidraURL's work very similarly to selecting a URL reference which displays a PDF. + Once setup correctly, GhidraURL links can be placed in web pages, external project + documentation files, or any other place a URL hyperlink can be placed. +
++ When a GhidraURL is selected, GhidraGo will startup Ghidra if it isn't already running as + well as prompt to login to the multi-user project if necessary. The program is displayed in + the default tool, usually the codebrowser, and can be configured to re-use an open default + tool or to use a new default tool. The GhidraURL must currently be locating a DomainFile + that is either in a Remote, Shared project, or a local project. +
++ GhidraGo is a combination of a command line program to send a link, a plugin running within + the Ghidra project manager, and the configuration of the default handling for the ghidraURL + within the user environment. The ghidraURL is sent as the first and only parameter to the + ghidraGo command line interface. +
++ GhidraGo passes information through a simple filesystem mechanism vice an open port for + security and simplicity. GhidraGo works on Windows, Linux, and MacOS. +
++
GhidraURL's have the format:
++ Remote Ghidra Server File: + ghidra://<host>[:<port>]/<repository-name>/<program-path> + [#<address-or-symbol-ref>] +
+Example: ghidra://hostname/Repo/notepad.exe#main
+ ++ Local Ghidra Project File: + ghidra:/[<project-path>/]<project-name>?/<program-path> + [#<address-or-symbol-ref>] +
+Example: ghidra:/share/MyProject?/notepad.exe#main
+ghidraGo ghidra://ghidra-server/project/myProgram#symbol
Executing this command will result in the program called myProgram being
+ opened in Ghidra's default tool with the cursor at symbol.
Ghidra is now configured to listen to GhidraGo Requests. You can execute a GhidraGo request
+ using the "ghidraGo" shell/batch script in
+ /path/to/ghidra/support/GhidraGo/ghidraGo
+ Configuring your platform to handle the protocol is what + enables the ghidraGo command line interface to be associated with a ghidraURL. Once + configured, clicking hyperlinks that start with the protocol + will execute the ghidraGo CLI with that hyperlink as the first argument. The + configuration is platform specific. +
++ *NOTE: changes to your path to ghidra, such as upgrading ghidra to a new version, + will require the path you set in this configuration to be updated. +
+regeditC:\Path\To\Ghidra\support\GhidraGo\ghidraGo "%1"
+ In Linux, when you click a browser link with an href value to a GhidraURL,
+ you'll be prompted to use xdg-open.
ghidra.desktop in ~/.local/share/applications
+ [Desktop Entry]
+ Name=ghidra Client
+ Exec=/path/to/ghidra/support/GhidraGo/ghidraGo "%u"
+ Type=Application
+ Terminal=false
+ MimeType=x-scheme-handler/ghidra;
+
+ ~/.local/share/applications
+ [Default Applications]
+ x-scheme-handler/ghidra=ghidra.desktop
+ ...
+
+ After the steps above, you should be able to click a GhidraURL href, get the same + xdg-open prompt, and upon clicking "Open xdg-open" GhidraGo should execute and open + Ghidra to the given GhidraURL.
+Script Editor and past the following into the editor.
+ on open location schemeUrl
+ set ghidraUrl to quoted form of schemeUrl
+ do shell script "/path/to/ghidraGo " & ghidraUrl
+ end open location
+
+ /Applications or ~/Applications<string>com.apple.ScriptEditor.id.GhidraGo</string>
+ paste the following:
+ <key>CFBundleURLTypes</key>
+ <array>
+ <dict>
+ <key>CFBundleURLName</key>
+ <string>Ghidra Scheme</string>
+ <key>CFBundleURLSchemes</key>
+ <array>
+ <string>ghidra</string>
+ </array>
+ </dict>
+ </array>
+
+ The first argument is expected to be non-null and a valid {@link GhidraURL}
+ *If the {@link GhidraURL} is valid, the URL is processed in an existing Ghidra, or + * a new Ghidra is started and used to process the URL.
+ *A valid {@link GhidraURL} in this case must be pointing to a remote (shared project) + * Program.
+ *In the event that a Ghidra is running and does not have an active project, the URL cannot be + * processed.
+ */ +public class GhidraGo implements GhidraLaunchable { + + private GhidraGoSender sender; + + /** + * Initializes a new GhidraGoSender and processes the {@link GhidraURL} + * @param layout the layout passed from main.Ghidra + * @param args the CLI args passed to GhidraGo. args should contain a single {@link GhidraURL}. + * @throws Exception in the event of an error + */ + @Override + public void launch(GhidraApplicationLayout layout, String[] args) throws Exception { + try { + ApplicationConfiguration configuration = null; + if (!Application.isInitialized()) { + System.setProperty(ApplicationProperties.APPLICATION_NAME_PROPERTY, "GhidraGo"); + configuration = new DockingApplicationConfiguration(); + Application.initializeApplication(layout, configuration); + } + if (args != null && args.length > 0) { + ghidra.framework.protocol.ghidra.Handler.registerHandler(); + sender = new GhidraGoSender(); + + startGhidraIfNeeded(layout); + + sender.send(args[0]); + // if configuration is null, probably running inside a test + if (configuration != null) { + // calling System.exit explicitly is necessary, otherwise the Loading... screen + // persists instead of closing when complete. + System.exit(0); + } + } + else { + throw new IllegalArgumentException( + "A valid GhidraURL locating a program, program name, or path to a program name " + + "must be specified as the first command line argument."); + } + } + catch (FailedToStartGhidraException e) { + logOrShowError("GhidraGo Start Ghidra Exception", + "Failed to start Ghidra from GhidraGo", e); + System.exit(-1); + } + catch (StopWaitingException e) { + System.exit(-1); + } + catch (Exception e) { + logOrShowError("GhidraGo Exception", "An unexpected exception occurred in GhidraGo", e); + // calling System.exit explicitly is necessary, otherwise the Loading... screen + // persists instead of closing when complete. + System.exit(-1); + } + } + + private void logOrShowError(String errorTitle, String errorMessage, Exception e) { + if (SystemUtilities.isInHeadlessMode()) { + Msg.error(this, errorMessage, e); + } + else { + Swing.runNow(() -> Msg.showError(this, null, errorTitle, errorMessage, e)); + } + } + + private void startGhidraIfNeeded(GhidraApplicationLayout layout) + throws StopWaitingException, FailedToStartGhidraException { + // if there is no listening Ghidra + if (!sender.isGhidraListening()) { + + // attempt to start a Ghidra within a locked action + // do not wait for the lock if another GhidraGo has been started. + try { + boolean success = sender.doLockedAction(false, () -> { + try { + Process ghidraProcess = startGhidra(layout); + sender.waitForListener(ghidraProcess); + return true; + } + catch (StopWaitingException e) { + return true; + } + catch (StartedGhidraProcessExitedException | IOException e) { + return false; + } + }); + if (!success) { + // GhidraGo attempted to start ghidra and failed + throw new FailedToStartGhidraException(); + } + } + catch (UnableToGetLockException e) { + // When another GhidraGo has the lock, + // wait for there to be a listener without starting the process + sender.waitForListener(); + } + } + } + + /** + * Determines the execution platform and executes the appropriate shell/bash script to start + * Ghidra. + * @throws IOException in the event that the execution failed + */ + private Process startGhidra(GhidraApplicationLayout layout) throws IOException { + ResourceFile file = layout.getApplicationInstallationDir(); + Path ghidraRunPath; + + if (SystemUtilities.isInDevelopmentMode()) { + if (Platform.CURRENT_PLATFORM.getOperatingSystem() == OperatingSystem.WINDOWS) { + ghidraRunPath = Path.of(file.getAbsolutePath(), + "/ghidra/Ghidra/RuntimeScripts/Windows/ghidraRun.bat"); + } + else { + ghidraRunPath = Path.of(file.getAbsolutePath(), + "/ghidra/Ghidra/RuntimeScripts/Linux/ghidraRun"); + } + } + else { + if (Platform.CURRENT_PLATFORM.getOperatingSystem() == OperatingSystem.WINDOWS) { + ghidraRunPath = Path.of(file.getAbsolutePath(), "/ghidraRun.bat"); + } + else { + ghidraRunPath = Path.of(file.getAbsolutePath(), "/ghidraRun"); + } + } + + Msg.info(this, "Starting new Ghidra using ghidraRun script at " + ghidraRunPath); + return Runtime.getRuntime().exec(ghidraRunPath.toString()); + } +} diff --git a/Ghidra/Features/GhidraGo/src/main/java/ghidra/app/plugin/core/go/GhidraGoPlugin.java b/Ghidra/Features/GhidraGo/src/main/java/ghidra/app/plugin/core/go/GhidraGoPlugin.java new file mode 100644 index 0000000000..70d8647115 --- /dev/null +++ b/Ghidra/Features/GhidraGo/src/main/java/ghidra/app/plugin/core/go/GhidraGoPlugin.java @@ -0,0 +1,106 @@ +/* ### + * 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.app.plugin.core.go; + +import java.io.IOException; +import java.net.URL; + +import ghidra.app.CorePluginPackage; +import ghidra.app.plugin.PluginCategoryNames; +import ghidra.app.plugin.core.go.ipc.GhidraGoListener; +import ghidra.framework.main.AppInfo; +import ghidra.framework.main.ApplicationLevelOnlyPlugin; +import ghidra.framework.model.ToolServices; +import ghidra.framework.plugintool.*; +import ghidra.framework.plugintool.util.PluginStatus; +import ghidra.framework.protocol.ghidra.GhidraURL; +import ghidra.util.Msg; +import ghidra.util.SystemUtilities; + +//@formatter:off +@PluginInfo( + category = PluginCategoryNames.COMMON, + status = PluginStatus.UNSTABLE, + packageName = CorePluginPackage.NAME, + shortDescription = "Listens for new GhidraURL's to launch using ToolServices", + description = "Polls the ghidraGo directory for any url files written by the GhidraGoClient and " + + "processes them in Ghidra", + eventsConsumed = {ProjectPluginEvent.class}) +//@formatter:on +public class GhidraGoPlugin extends Plugin implements ApplicationLevelOnlyPlugin { + private GhidraGoListener listener; + + public GhidraGoPlugin(PluginTool tool) { + super(tool); + } + + @Override + protected void init() { + super.init(); + } + + @Override + protected void dispose() { + if (this.listener != null) { + listener.dispose(); + listener = null; + } + super.dispose(); + } + + @Override + public void processEvent(PluginEvent event) { + if (event instanceof ProjectPluginEvent) { + if (((ProjectPluginEvent) event).getProject() == null) { + dispose(); + } + else { + try { + listener = new GhidraGoListener((url) -> { + processGhidraURL(url); + }); + } + catch (IOException e) { + Msg.showError(this, null, "GhidraGoPlugin Exception", + "Unable to create Listener", e); + } + } + } + } + + /** + * If the active project is null, do nothing. + * Otherwise, try and open the url using {@link ToolServices} launchDefaultToolWithURL function. + * @param ghidraURL the GhidraURL to open. + */ + private void processGhidraURL(URL ghidraURL) { + + Msg.info(GhidraGoPlugin.class, "GhidraGo processing " + ghidraURL); + + try { + Msg.info(GhidraGoPlugin.class, + "Accepting the resource at " + GhidraURL.getProjectURL(ghidraURL)); + SystemUtilities.runSwingNow(() -> { + AppInfo.getFrontEndTool().toFront(); + AppInfo.getFrontEndTool().getToolServices().launchDefaultToolWithURL(ghidraURL); + }); + } + catch (IllegalArgumentException e) { + Msg.showError(GhidraGoPlugin.class, null, "GhidraGo Unable to process GhidraURL", + "GhidraGo could not process " + ghidraURL, e); + } + } +} diff --git a/Ghidra/Features/GhidraGo/src/main/java/ghidra/app/plugin/core/go/GhidraGoSender.java b/Ghidra/Features/GhidraGo/src/main/java/ghidra/app/plugin/core/go/GhidraGoSender.java new file mode 100644 index 0000000000..c06550d83d --- /dev/null +++ b/Ghidra/Features/GhidraGo/src/main/java/ghidra/app/plugin/core/go/GhidraGoSender.java @@ -0,0 +1,151 @@ +/* ### + * 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.app.plugin.core.go; + +import java.io.FileOutputStream; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.UUID; +import java.util.concurrent.TimeUnit; +import java.util.function.Supplier; + +import org.apache.commons.lang3.StringUtils; + +import ghidra.app.plugin.core.go.exception.*; +import ghidra.app.plugin.core.go.ipc.*; +import ghidra.framework.protocol.ghidra.GhidraURL; +import ghidra.util.Msg; +import ghidra.util.Swing; + +public class GhidraGoSender extends GhidraGoIPC { + + public GhidraGoSender() throws IOException { + super(); + } + + @Override + public void dispose() { + // empty + } + + /** + * performs the given action once the sender lock has been acquired. Using this method ensures + * only one sender will perform the given action. + * @param waitForLock whether to block until the lock is available + * @param action the action to be performed once a lock is acquired. Returns true if successful. + * @return true if action was successfully performed; false otherwise. + * @throws UnableToGetLockException if the lock was unobtainable + */ + public boolean doLockedAction(boolean waitForLock, Supplier+ GhidraGo is a mechanism to cause Ghidra to display a previously imported program within a + local or multi-user project using a ghidraURL hyperlink similar to an http reference. In + practice ghidraURL's work very similarly to selecting a URL reference which displays a PDF. + Once setup correctly, GhidraURL links can be placed in web pages, external project + documentation files, or any other place a URL hyperlink can be placed. +
++ When a GhidraURL is selected, GhidraGo will startup Ghidra if it isn't already running as + well as prompt to login to the multi-user project if necessary. The program is displayed in + the default tool, usually the codebrowser, and can be configured to re-use an open default + tool or to use a new default tool. The GhidraURL must currently be locating a DomainFile + that is either in a Remote, Shared project, or a local project. +
++ GhidraGo is a combination of a command line program to send a link, a plugin running within + the Ghidra project manager, and the configuration of the default handling for the ghidraURL + within the user environment. The ghidraURL is sent as the first and only parameter to the + ghidraGo command line interface. +
++ GhidraGo passes information through a simple filesystem mechanism vice an open port for + security and simplicity. GhidraGo works on Windows, Linux, and MacOS. +
++
GhidraURL's have the format:
++ Remote Ghidra Server File: + ghidra://<host>[:<port>]/<repository-name>/<program-path> + [#<address-or-symbol-ref>] +
+Example: ghidra://hostname/Repo/notepad.exe#main
+ ++ Local Ghidra Project File: + ghidra:/[<project-path>/]<project-name>?/<program-path> + [#<address-or-symbol-ref>] +
+Example: ghidra:/share/MyProject?/notepad.exe#main
+ghidraGo ghidra://ghidra-server/project/myProgram#symbol
Executing this command will result in the program called myProgram being
+ opened in Ghidra's default tool with the cursor at symbol.
Ghidra is now configured to listen to GhidraGo Requests. You can execute a GhidraGo request
+ using the "ghidraGo" shell/batch script in
+ /path/to/ghidra/support/GhidraGo/ghidraGo
+ Configuring your platform to handle the protocol is what + enables the ghidraGo command line interface to be associated with a ghidraURL. Once + configured, clicking hyperlinks that start with the protocol + will execute the ghidraGo CLI with that hyperlink as the first argument. The + configuration is platform specific. +
++ *NOTE: changes to your path to ghidra, such as upgrading ghidra to a new version, + will require the path you set in this configuration to be updated. +
+regeditC:\Path\To\Ghidra\support\GhidraGo\ghidraGo "%1"
+ In Linux, when you click a browser link with an href value to a GhidraURL,
+ you'll be prompted to use xdg-open.
ghidra.desktop in ~/.local/share/applications
+ [Desktop Entry]
+ Name=ghidra Client
+ Exec=/path/to/ghidra/support/GhidraGo/ghidraGo "%u"
+ Type=Application
+ Terminal=false
+ MimeType=x-scheme-handler/ghidra;
+
+ ~/.local/share/applications
+ [Default Applications]
+ x-scheme-handler/ghidra=ghidra.desktop
+ ...
+
+ After the steps above, you should be able to click a GhidraURL href, get the same + xdg-open prompt, and upon clicking "Open xdg-open" GhidraGo should execute and open + Ghidra to the given GhidraURL.
+Script Editor and past the following into the editor.
+ on open location schemeUrl
+ set ghidraUrl to quoted form of schemeUrl
+ do shell script "/path/to/ghidraGo " & ghidraUrl
+ end open location
+
+ /Applications or ~/Applications<string>com.apple.ScriptEditor.id.GhidraGo</string>
+ paste the following:
+ <key>CFBundleURLTypes</key>
+ <array>
+ <dict>
+ <key>CFBundleURLName</key>
+ <string>Ghidra Scheme</string>
+ <key>CFBundleURLSchemes</key>
+ <array>
+ <string>ghidra</string>
+ </array>
+ </dict>
+ </array>
+
+