ghidra: initial capa explorer extension MVP

capa/ghidra/plugin/extension/README.md

@@ -0,0 +1 @@
+# CapaExplorer

capa/ghidra/plugin/extension/build.gradle

@@ -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/**'

capa/ghidra/plugin/extension/extension.properties

@@ -0,0 +1,5 @@
+name=@extname@
+description=Finds capabilities in programs, as detected by capa.
+author=Mandiant
+createdOn=2026-01-26
+version=@extversion@

capa/ghidra/plugin/extension/src/main/help/help/TOC_Source.xml

@@ -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>

capa/ghidra/plugin/extension/src/main/help/help/topics/capaexplorer/help.html

@@ -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>

capa/ghidra/plugin/extension/src/main/java/capa/ghidra/CapaPlugin.java

@@ -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);
+    }
+}
+

capa/ghidra/plugin/extension/src/main/java/capa/ghidra/CapaProvider.java

@@ -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());
+        }
+    }
+}

capa/ghidra/plugin/extension/src/main/java/capa/ghidra/CapaPythonBridge.java

@@ -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();
+
+        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();
+    }
+}

capa/ghidra/plugin/extension/src/main/resources/images/README.txt

@@ -0,0 +1,2 @@
+The "src/resources/images" directory is intended to hold all image/icon files used by
+this module.