Package ghidra.framework.plugintool.dialog

Class ExtensionUtils

java.lang.Object
ghidra.framework.plugintool.dialog.ExtensionUtils
public class ExtensionUtils extends Object
Utility class for managing Ghidra Extensions.

Extensions are defined as any archive or folder that contains an extension.properties file. This properties file can contain the following attributes:

  • name (required)
  • description
  • author
  • createdOn (format: mm/dd/yyyy)
Extensions may be installed/uninstalled by users at runtime, using the ExtensionTableProvider. Installation consists of unzipping the extension archive to an installation folder, currently Ghidra/Extensions. To uninstall, the unpacked folder is simply removed.

  • Field Details

    • PROPERTIES_FILE_NAME

      public static String PROPERTIES_FILE_NAME

    • PROPERTIES_FILE_NAME_UNINSTALLED

      public static String PROPERTIES_FILE_NAME_UNINSTALLED

  • Constructor Details

    • ExtensionUtils

      public ExtensionUtils()

  • Method Details

    • getExtensions

      public static Set<ExtensionDetails> getExtensions() throws ExtensionException
      Returns a set of all extensions known to Ghidra, represented by ExtensionDetails objects. This will include all installed AND archived extensions.

      Note that this method will only look in the known extension folder locations:

      If users install extensions from other locations, the installed version of the extension will be known, but the source archive location will not be retained.
      Returns:
      list of unique extensions
      Throws:
      ExtensionException - if extensions cannot be retrieved

    • getInstalledExtensions

      public static Set<ExtensionDetails> getInstalledExtensions(boolean includeUninstalled) throws ExtensionException
      Returns all installed extensions. These are all the extensions found in ApplicationLayout.getExtensionInstallationDirs().
      Parameters:
      includeUninstalled - if true, include extensions that have been marked for removal
      Returns:
      set of installed extensions
      Throws:
      ExtensionException - if the extension details cannot be retrieved

    • getArchivedExtensions

      public static Set<ExtensionDetails> getArchivedExtensions() throws ExtensionException
      Returns all archived extensions. These are all the extensions found in ApplicationLayout.getExtensionArchiveDir().
      Returns:
      set of archived extensions
      Throws:
      ExtensionException - if the extension details cannot be retrieved

    • isInstalled

      public static boolean isInstalled(String extensionName)
      Returns true if an extension with the given name exists in the install folder.
      Parameters:
      extensionName - the name of the extension
      Returns:
      true if installed

    • install

      public static boolean install(ResourceFile rFile)
      Installs the given extension file. This can be either an archive (zip) or a directory that contains an extension.properties file.
      Parameters:
      rFile - the extension to install
      Returns:
      true if the extension was successfully installed

    • install

      public static boolean install(ExtensionDetails extension, boolean overwrite)
      Installs the given extension.
      Parameters:
      extension - the extension to install
      overwrite - if true, any existing extension will be overwritten
      Returns:
      true if the install was successful

    • uninstall

      public static boolean uninstall(ExtensionDetails extension)
      Uninstalls a given extension.
      Parameters:
      extension - the extension to uninstall
      Returns:
      true if successfully uninstalled

    • validateExtensionVersion

      public static boolean validateExtensionVersion(String extensionVersion)
      Compares the given extension version to the current Ghidra version. If they are different, then the user will be prompted to confirm the installation. This method will return true if the versions match or the user has chosen to install anyway.
      Parameters:
      extensionVersion - the extension version
      Returns:
      true if the versions match or the user has chosen to install anyway

    • isExtension

      public static boolean isExtension(ResourceFile rFile) throws ExtensionException
      Returns true if the given file or directory is a valid ghidra extension.

      Note: This means that the zip or directory contains an extension.properties file.

      Parameters:
      rFile - the resource zip or directory to inspect
      Returns:
      true if the given file represents a valid extension
      Throws:
      ExtensionException - if there's an error processing a zip file

    • isZip

      public static boolean isZip(File file) throws ExtensionException
      Returns true if the given file is a valid .zip archive.
      Parameters:
      file - the file to test
      Returns:
      true if file is a valid zip
      Throws:
      ExtensionException - if there's an error reading the zip file

    • findExtensionPropertyFiles

      public static List<ResourceFile> findExtensionPropertyFiles(ResourceFile sourceFile, boolean includeUninstalled)
      Returns a list of files representing all the extension.properties files found under a given directory. This will ONLY search the given directory and its immediate children. The conops are as follows:
      • If sourceFile is a directory and it contains an extension.properties file, then that file is returned
      • If sourceFile does not contain an extension.properties file, then any immediate directories are searched (ignoring Skeleton directory)

      Note: This will NOT search zip files. If you have a zip, call getPropertiesFromArchive(File) instead.

      Parameters:
      sourceFile - the directory to inspect
      includeUninstalled - if true, include extensions that have been marked for removal
      Returns:
      list of extension.properties files

    • removeStateFiles

      public static boolean removeStateFiles(ExtensionDetails extension)
      Recursively searches a given directory for any module manifest and extension properties files that are in an installed state and converts them to an uninstalled state. Specifically, the following will be renamed:
      • Module.manifest to Module.manifest.uninstalled
      • extension.properties = extension.properties.uninstalled
      Parameters:
      extension - the extension to modify
      Returns:
      false if any renames fail

    • restoreStateFiles

      public static boolean restoreStateFiles(File rootDir)
      Recursively searches a given directory for any module manifest and extension properties files that are in an uninstalled state and restores them. Specifically, the following will be renamed:
      • Module.manifest.uninstalled to Module.manifest
      • extension.properties.uninstalled = extension.properties
      Parameters:
      rootDir - the directory to search
      Returns:
      false if any renames fail

    • findFilesWithName

      public static void findFilesWithName(File root, String fileName, List<File> foundFiles)
      Parameters:
      root - the starting directory to search recursively
      fileName - the file name search for
      foundFiles - list of all matching files

    • getPropertiesFromArchive

      public static Properties getPropertiesFromArchive(File file) throws ExtensionException
      Given a zip file, returns the Properties defined in the embedded extension.properties file.
      Parameters:
      file - the extension archive file
      Returns:
      the properties file, or null if doesn't exist
      Throws:
      ExtensionException - if there's a problem unpacking the zip file

    • createExtensionDetailsFromPropertyFile

      public static ExtensionDetails createExtensionDetailsFromPropertyFile(File file)
      Extracts information from a Java Properties file to create an ExtensionDetails object.
      Parameters:
      file - the file to parse
      Returns:
      a new extension details object

    • getExtensionsInstalledSinceLastToolLaunch

      public static Set<ExtensionDetails> getExtensionsInstalledSinceLastToolLaunch(PluginTool tool)
      Finds any extensions that have been installed since the last time a given tool was launched.
      Parameters:
      tool - the tool to check
      Returns:
      set of new extensions

    • createExtensionDetailsFromPropertyFile

      public static ExtensionDetails createExtensionDetailsFromPropertyFile(ResourceFile resourceFile)
      Extracts information from a Java Properties file to create an ExtensionDetails object.
      Parameters:
      resourceFile - the resource file file to parse
      Returns:
      a new extension details object

    • cleanupUninstalledExtensions

      public static void cleanupUninstalledExtensions()
      Attempts to delete any extension directories that do not contain a Module.manifest file. This indicates that the extension was slated to be uninstalled by the user.
      See Also:

    • createExtensionDetailsFromProperties

      public static ExtensionDetails createExtensionDetailsFromProperties(Properties props)
      Extracts properties from a Java Properties file to create an ExtensionDetails object.
      Parameters:
      props - the java properties object
      Returns:
      a new extension details object