ghidra: initial capa explorer extension MVP #2839
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| # CapaExplorer |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| /* ### | ||
| * 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. | ||
| */ | ||
| // Builds a Ghidra Extension for a given Ghidra installation. | ||
| // | ||
| // An absolute path to the Ghidra installation directory must be supplied either by setting the | ||
| // GHIDRA_INSTALL_DIR environment variable or Gradle project property: | ||
| // | ||
| // > export GHIDRA_INSTALL_DIR=<Absolute path to Ghidra> | ||
| // > gradle | ||
| // | ||
| // or | ||
| // | ||
| // > gradle -PGHIDRA_INSTALL_DIR=<Absolute path to Ghidra> | ||
| // | ||
| // Gradle should be invoked from the directory of the project to build. Please see the | ||
| // application.gradle.version property in <GHIDRA_INSTALL_DIR>/Ghidra/application.properties | ||
| // for the correction version of Gradle to use for the Ghidra installation you specify. | ||
|
|
||
| //----------------------START "DO NOT MODIFY" SECTION------------------------------ | ||
| def ghidraInstallDir | ||
|
|
||
| if (System.env.GHIDRA_INSTALL_DIR) { | ||
| ghidraInstallDir = System.env.GHIDRA_INSTALL_DIR | ||
| } | ||
| else if (project.hasProperty("GHIDRA_INSTALL_DIR")) { | ||
| ghidraInstallDir = project.getProperty("GHIDRA_INSTALL_DIR") | ||
| } | ||
| else { | ||
| ghidraInstallDir = "<REPLACE>" | ||
| } | ||
|
|
||
| task distributeExtension { | ||
| group = "Ghidra" | ||
|
|
||
| apply from: new File(ghidraInstallDir).getCanonicalPath() + "/support/buildExtension.gradle" | ||
| dependsOn ':buildExtension' | ||
| } | ||
| //----------------------END "DO NOT MODIFY" SECTION------------------------------- | ||
|
|
||
| repositories { | ||
| // Declare dependency repositories here. This is not needed if dependencies are manually | ||
| // dropped into the lib/ directory. | ||
| // See https://docs.gradle.org/current/userguide/declaring_repositories.html for more info. | ||
| // Ex: mavenCentral() | ||
| } | ||
|
|
||
| dependencies { | ||
| // Any external dependencies added here will automatically be copied to the lib/ directory when | ||
| // this extension is built. | ||
| } | ||
|
|
||
| // Exclude additional files from the built extension | ||
| // Ex: buildExtension.exclude '.idea/**' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| name=@extname@ | ||
| description=Finds capabilities in programs, as detected by capa. | ||
| author=Mandiant | ||
| createdOn=2026-01-26 | ||
| version=@extversion@ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| <?xml version='1.0' encoding='ISO-8859-1' ?> | ||
| <!-- | ||
|
|
||
| This is an XML file intended to be parsed by the Ghidra help system. It is loosely based | ||
| upon the JavaHelp table of contents document format. The Ghidra help system uses a | ||
| TOC_Source.xml file to allow a module with help to define how its contents appear in the | ||
| Ghidra help viewer's table of contents. The main document (in the Base module) | ||
| defines a basic structure for the | ||
| Ghidra table of contents system. Other TOC_Source.xml files may use this structure to insert | ||
| their files directly into this structure (and optionally define a substructure). | ||
|
|
||
|
|
||
| In this document, a tag can be either a <tocdef> or a <tocref>. The former is a definition | ||
| of an XML item that may have a link and may contain other <tocdef> and <tocref> children. | ||
| <tocdef> items may be referred to in other documents by using a <tocref> tag with the | ||
| appropriate id attribute value. Using these two tags allows any module to define a place | ||
| in the table of contents system (<tocdef>), which also provides a place for | ||
| other TOC_Source.xml files to insert content (<tocref>). | ||
|
|
||
| During the help build time, all TOC_Source.xml files will be parsed and validated to ensure | ||
| that all <tocref> tags point to valid <tocdef> tags. From these files will be generated | ||
| <module name>_TOC.xml files, which are table of contents files written in the format | ||
| desired by the JavaHelp system. Additionally, the genated files will be merged together | ||
| as they are loaded by the JavaHelp system. In the end, when displaying help in the Ghidra | ||
| help GUI, there will be on table of contents that has been created from the definitions in | ||
| all of the modules' TOC_Source.xml files. | ||
|
|
||
|
|
||
| Tags and Attributes | ||
|
|
||
| <tocdef> | ||
| -id - the name of the definition (this must be unique across all TOC_Source.xml files) | ||
| -text - the display text of the node, as seen in the help GUI | ||
| -target** - the file to display when the node is clicked in the GUI | ||
| -sortgroup - this is a string that defines where a given node should appear under a given | ||
| parent. The string values will be sorted by the JavaHelp system using | ||
| a javax.text.RulesBasedCollator. If this attribute is not specified, then | ||
| the text of attribute will be used. | ||
|
|
||
| <tocref> | ||
| -id - The id of the <tocdef> that this reference points to | ||
|
|
||
| **The URL for the target is relative and should start with 'help/topics'. This text is | ||
| used by the Ghidra help system to provide a universal starting point for all links so that | ||
| they can be resolved at runtime, across modules. | ||
|
|
||
|
|
||
| --> | ||
|
|
||
|
|
||
| <tocroot> | ||
| <!-- Uncomment and adjust fields to add help topic to help system's Table of Contents | ||
| <tocref id="Ghidra Functionality"> | ||
| <tocdef id="HelpAnchor" text="My Feature" target="help/topics/my_topic/help.html" /> | ||
| </tocref> | ||
| --> | ||
| </tocroot> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | ||
|
|
||
| <HTML> | ||
| <HEAD> | ||
| <META name="generator" content= | ||
| "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net"> | ||
| <META http-equiv="Content-Language" content="en-us"> | ||
| <META http-equiv="Content-Type" content="text/html; charset=windows-1252"> | ||
| <META name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| <META name="ProgId" content="FrontPage.Editor.Document"> | ||
|
|
||
| <TITLE>Skeleton Help File for a Module</TITLE> | ||
| <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css"> | ||
| </HEAD> | ||
|
|
||
| <BODY> | ||
| <H1><a name="HelpAnchor"></a>Skeleton Help File for a Module</H1> | ||
|
|
||
| <P>This is a simple skeleton help topic. For a better description of what should and should not | ||
| go in here, see the "sample" Ghidra extension in the Extensions/Ghidra directory, or see your | ||
| favorite help topic. In general, language modules do not have their own help topics.</P> | ||
| </BODY> | ||
| </HTML> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| package capa.ghidra; | ||
|
|
||
| import docking.ActionContext; | ||
| import docking.action.DockingAction; | ||
| import docking.action.MenuData; | ||
| import ghidra.app.plugin.PluginCategoryNames; | ||
| import ghidra.app.plugin.ProgramPlugin; | ||
| import ghidra.framework.plugintool.PluginInfo; | ||
| import ghidra.framework.plugintool.PluginTool; | ||
| import ghidra.framework.plugintool.util.PluginStatus; | ||
|
|
||
| @PluginInfo( | ||
| status = PluginStatus.STABLE, | ||
| packageName = "Capa", | ||
| category = PluginCategoryNames.ANALYSIS, | ||
| shortDescription = "Run capa analysis", | ||
| description = "Capa explorer MVP for Ghidra" | ||
| ) | ||
| public class CapaPlugin extends ProgramPlugin { | ||
|
|
||
| private CapaProvider provider; | ||
|
|
||
| public CapaPlugin(PluginTool tool) { | ||
| super(tool); | ||
|
|
||
| provider = new CapaProvider(tool); | ||
| createActions(); | ||
| } | ||
|
|
||
| private void createActions() { | ||
|
|
||
| DockingAction action = | ||
| new DockingAction("Run capa analysis", getName()) { | ||
|
|
||
| @Override | ||
| public void actionPerformed(ActionContext context) { | ||
| provider.runCapa(currentProgram); | ||
| } | ||
| }; | ||
|
|
||
| action.setMenuBarData( | ||
| new MenuData(new String[] { | ||
| "Tools", | ||
| "Run capa analysis" | ||
| }) | ||
| ); | ||
|
|
||
| tool.addAction(action); | ||
| } | ||
| } | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| package capa.ghidra; | ||
|
|
||
| import docking.ComponentProvider; | ||
| import ghidra.framework.plugintool.PluginTool; | ||
| import ghidra.program.model.listing.Program; | ||
| import ghidra.util.Msg; | ||
|
|
||
| import javax.swing.JScrollPane; | ||
| import javax.swing.JTextArea; | ||
| import javax.swing.JComponent; | ||
| import java.awt.Font; | ||
|
|
||
| import java.io.PrintWriter; | ||
| import java.io.StringWriter; | ||
|
|
||
| public class CapaProvider extends ComponentProvider { | ||
|
|
||
| private final PluginTool tool; | ||
| private final JTextArea output; | ||
|
|
||
| public CapaProvider(PluginTool tool) { | ||
| super(tool, "Capa Explorer", "CapaExplorer"); | ||
| this.tool = tool; | ||
|
|
||
| output = new JTextArea(); | ||
| output.setEditable(false); | ||
| output.setFont(new Font("Monospaced", Font.PLAIN, 12)); | ||
|
|
||
| tool.addComponentProvider(this, true); | ||
| tool.showComponentProvider(this, true); | ||
| } | ||
|
|
||
| @Override | ||
| public JComponent getComponent() { | ||
| return new JScrollPane(output); | ||
| } | ||
|
|
||
| public void runCapa(Program program) { | ||
|
|
||
| // Ensure panel is visible | ||
| tool.showComponentProvider(this, true); | ||
|
|
||
| if (program == null) { | ||
| output.setText("No program is currently open.\n"); | ||
| return; | ||
| } | ||
|
|
||
| output.setText("Running capa...\n"); | ||
|
|
||
| try { | ||
| String result = CapaPythonBridge.run(program); | ||
| output.append(result); | ||
| } | ||
| catch (Exception e) { | ||
| Msg.error(this, "Error running capa", e); | ||
|
|
||
| output.append("\nERROR:\n"); | ||
|
|
||
| StringWriter sw = new StringWriter(); | ||
| PrintWriter pw = new PrintWriter(sw); | ||
| e.printStackTrace(pw); | ||
|
|
||
| output.append(sw.toString()); | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| package capa.ghidra; | ||
|
|
||
| import generic.jar.ResourceFile; | ||
| import ghidra.framework.Application; | ||
| import ghidra.program.model.listing.Program; | ||
| import ghidra.util.Msg; | ||
|
|
||
| import java.io.BufferedReader; | ||
| import java.io.File; | ||
| import java.io.InputStreamReader; | ||
|
|
||
| public class CapaPythonBridge { | ||
| /** | ||
| * Execute capa analysis for the currently loaded program. | ||
| * | ||
| * NOTE: The Program parameter is intentionally unused in this MVP. | ||
| * In future iterations, program metadata (path, architecture, hashes, | ||
| * memory layout, etc.) will be passed to the Python capa runner. | ||
| */ | ||
|
|
||
| public static String run(Program program) throws Exception { | ||
|
|
||
| ResourceFile pythonDir = | ||
| Application.getModuleDataSubDirectory("python"); | ||
|
|
||
| File scriptFile = | ||
| new File( | ||
| pythonDir.getFile(false), | ||
| "capa_runner.py" | ||
| ); | ||
|
|
||
| String python = System.getenv("CAPA_PYTHON"); | ||
| if (python == null || python.isBlank()) { | ||
| python = "python3"; | ||
| } | ||
|
|
||
| Msg.info( | ||
| CapaPythonBridge.class, | ||
| "Using Python executable: " + python | ||
| ); | ||
|
|
||
| Process process = | ||
| new ProcessBuilder( | ||
| python, | ||
| scriptFile.getAbsolutePath() | ||
| ) | ||
| .redirectErrorStream(true) | ||
| .start(); | ||
|
Comment on lines
+42
to
+48
Collaborator
There was a problem hiding this comment. PyGhidra should serve as the Python <-> Java bridge. Running Python in a separate process doesn't count 🙂
Author
There was a problem hiding this comment. Thanks for the clarification @mike-hunhoff that makes sense. You're right: launching Python as a separate process is not the intended model here. The updated approach will be:
For this draft PR, my goal was to validate extension packaging and UI wiring. Thanks for pointing this out — I’ll push an update shortly. |
||
|
|
||
| StringBuilder output = new StringBuilder(); | ||
|
|
||
| try (BufferedReader reader = | ||
| new BufferedReader( | ||
| new InputStreamReader( | ||
| process.getInputStream()))) { | ||
|
|
||
| String line; | ||
| while ((line = reader.readLine()) != null) { | ||
| output.append(line).append('\n'); | ||
| } | ||
| } | ||
|
|
||
| int exit = process.waitFor(); | ||
| if (exit != 0) { | ||
| throw new RuntimeException( | ||
| "Python exited with code " + exit | ||
| ); | ||
| } | ||
|
|
||
| return output.toString(); | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| The "src/resources/images" directory is intended to hold all image/icon files used by | ||
| this module. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.