Skip to content

Ghidra is a software reverse engineering (SRE) framework

16.9 KB
Raw Blame
/* ###
 * 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 utility.application;

import java.io.*;
import java.util.*;

import generic.jar.ResourceFile;
import ghidra.framework.*;
import ghidra.util.Msg;
import ghidra.util.SystemUtilities;
import utilities.util.FileUtilities;

/**
 * Utility class for default application things.
 */
public class ApplicationUtilities {

	/**
	 * Name of system property used to override the location of the user temporary directory
	 */
	public static final String PROPERTY_TEMP_DIR = "application.tempdir";

	/**
	 * Name of system property used to override the location of the user cache directory
	 */
	public static final String PROPERTY_CACHE_DIR = "application.cachedir";

	/**
	 * Name of system property used to override the location of the user settings directory
	 */
	public static final String PROPERTY_SETTINGS_DIR = "application.settingsdir";

	/**
	 * Searches for default application root directories.
	 * 
	 * @return A collection of discovered application root directories (could be empty).
	 */
	public static SequencedCollection<ResourceFile> findDefaultApplicationRootDirs() {
		List<ResourceFile> applicationRootDirs = new ArrayList<>();
		ResourceFile applicationRootDir = findPrimaryApplicationRootDir();
		if (applicationRootDir != null) {
			applicationRootDirs.add(applicationRootDir);
			if (SystemUtilities.isInTestingMode() || SystemUtilities.isInDevelopmentMode()) {
				applicationRootDirs.addAll(
					findApplicationRootDirsFromRepoConfig(applicationRootDir));
			}
		}
		return applicationRootDirs;
	}

	/**
	 * Finds the primary application root directory from the classpath.  The primary application
	 * root directory must contain an application.properties file.  No other application root
	 * directories may contain an application.properties file.
	 * 
	 * @return The primary application root directory, or null if it could not be found.
	 */
	private static ResourceFile findPrimaryApplicationRootDir() {
		String[] classpath = System.getProperty("java.class.path").split(File.pathSeparator);
		for (String pathEntry : classpath) {
			try {
				ResourceFile pathFile = new ResourceFile(new File(pathEntry).getCanonicalPath());
				while (pathFile != null && pathFile.exists()) {
					ResourceFile applicationPropertiesFile =
						new ResourceFile(pathFile, ApplicationProperties.PROPERTY_FILE);
					if (validateApplicationPropertiesFile(applicationPropertiesFile)) {
						return pathFile;
					}
					pathFile = pathFile.getParentFile();
				}
			}
			catch (IOException e) {
				Msg.error(ApplicationUtilities.class, "Invalid class path entry: " + pathEntry, e);
			}
		}
		return null;
	}

	/**
	 * Checks to make sure the given application properties file exists and is a valid format
	 * 
	 * @param applicationPropertiesFile The application properties file to validate
	 * @return true if the given application properties file exists and is a valid format;
	 *   otherwise, false
	 */
	private static boolean validateApplicationPropertiesFile(
			ResourceFile applicationPropertiesFile) {
		if (applicationPropertiesFile.isFile()) {
			try {
				ApplicationProperties applicationProperties =
					new ApplicationProperties(applicationPropertiesFile);
				if (!applicationProperties.getApplicationName().isEmpty()) {
					return true;
				}
			}
			catch (IOException e) {
				Msg.error(ApplicationUtilities.class,
					"Failed to read: " + applicationPropertiesFile, e);
			}
		}
		return false;
	}

	/**
	 * Finds all application root directories defined in the repository config file.
	 * 
	 * @param primaryApplicationRootDir The primary application root directory that may contain the
	 *   repository config file one directory up.
	 * @return A {@link SequencedCollection} of defined application repository root directories.
	 */
	private static SequencedCollection<ResourceFile> findApplicationRootDirsFromRepoConfig(
			ResourceFile primaryApplicationRootDir) {
		List<ResourceFile> repoApplicationRootDirs = new ArrayList<>();
		ResourceFile repoConfigFile =
			new ResourceFile(primaryApplicationRootDir.getParentFile(), "ghidra.repos.config");
		if (repoConfigFile.isFile()) {
			try (BufferedReader reader =
				new BufferedReader(new FileReader(repoConfigFile.getFile(false)))) {
				String line = null;
				while ((line = reader.readLine()) != null) {
					line = line.trim();
					if (line.isEmpty() || line.startsWith("#")) {
						continue;
					}
					ResourceFile potentialApplicationRootDir =
						new ResourceFile(repoConfigFile.getParentFile().getParentFile(),
							line + File.separator + "Ghidra");
					if (potentialApplicationRootDir.isDirectory()) {
						repoApplicationRootDirs.add(potentialApplicationRootDir);
					}
				}
			}
			catch (IOException e) {
				Msg.error(ApplicationUtilities.class, "Failed to read: " + repoConfigFile);
			}
		}
		return repoApplicationRootDirs;
	}

	/**
	 * Gets the application's default user temp directory.
	 * <p>
	 * NOTE: This method creates the directory if it does not exist.
	 * 
	 * @param applicationName The application name.
	 * @return The application's default user temp directory. The returned {@link File} will 
	 *   represent an absolute path.
	 * @throws FileNotFoundException if the absolute path of the user temp directory could not be 
	 *   determined.
	 * @throws IOException if the user temp directory could not be created.
	 */
	public static File getDefaultUserTempDir(String applicationName)
			throws FileNotFoundException, IOException {

		String appName = normalizeApplicationName(applicationName);

		// Look for Ghidra-specific system property
		File tempOverrideDir = getSystemPropertyFile(PROPERTY_TEMP_DIR, false);
		if (tempOverrideDir != null) {
			return createDir(
				new File(tempOverrideDir, getUserSpecificDirName(tempOverrideDir, appName)));
		}

		File javaTmpDir = getJavaTmpDir();
		return createDir(new File(getJavaTmpDir(), getUserSpecificDirName(javaTmpDir, appName)));
	}

	/**
	 * Gets the application's default user cache directory.
	 * <p>
	 * NOTE: This method creates the directory if it does not exist.
	 * 
	 * @param applicationProperties The application properties.
	 * @return The application's default user cache directory. The returned {@link File} will 
	 *   represent an absolute path.
	 * @throws FileNotFoundException if the absolute path of the user cache directory could not be 
	 *   determined.
	 * @throws IOException if the user cache directory could not be created.
	 */
	public static File getDefaultUserCacheDir(ApplicationProperties applicationProperties)
			throws FileNotFoundException, IOException {

		String appName = normalizeApplicationName(applicationProperties.getApplicationName());

		// Look for Ghidra-specific system property
		File cacheOverrideDir = getSystemPropertyFile(PROPERTY_CACHE_DIR, false);
		if (cacheOverrideDir != null) {
			return createDir(
				new File(cacheOverrideDir, getUserSpecificDirName(cacheOverrideDir, appName)));
		}

		// Look for XDG environment variable
		File xdgCacheHomeDir = getEnvFile(XdgUtils.XDG_CACHE_HOME, false);
		if (xdgCacheHomeDir != null) {
			return createDir(
				new File(xdgCacheHomeDir, getUserSpecificDirName(xdgCacheHomeDir, appName)));
		}
		
		// Use platform-specific default location
		String userDirName = SystemUtilities.getUserName() + "-" + appName;

		try {
			return createDir(switch (OperatingSystem.CURRENT_OPERATING_SYSTEM) {
				case WINDOWS -> new File(getEnvFile("LOCALAPPDATA", true), appName);
				case LINUX -> new File("/var/tmp/" + userDirName);
				case FREE_BSD -> new File("/var/tmp/" + userDirName);
				case OPEN_BSD -> new File("/var/tmp/" + userDirName);
				case MAC_OS_X -> new File("/var/tmp/" + userDirName);
				default -> throw new FileNotFoundException(
					"Failed to find the user cache directory: Unsupported operating system.");
			});
		}
		catch (IOException e) {
			// Failed to create desired cache directory...use temp directory instead
			return getDefaultUserTempDir(applicationProperties.getApplicationName());
		}
	}

	/**
	 * Gets the application's default user settings directory.
	 * <p>
	 * NOTE: This method creates the directory if it does not exist.
	 * 
	 * @param applicationProperties The application properties.
	 * @param installationDirectory The application installation directory.
	 * @return The application's default user settings directory. The returned {@link File} will
	 *   represent an absolute path.
	 * @throws FileNotFoundException if the absolute path of the user settings directory could not 
	 *   be determined.
	 * @throws IOException if the user settings directory could not be created.
	 */
	public static File getDefaultUserSettingsDir(ApplicationProperties applicationProperties,
			ResourceFile installationDirectory) throws FileNotFoundException, IOException {

		ApplicationIdentifier applicationIdentifier =
			new ApplicationIdentifier(applicationProperties);
		String appName = applicationIdentifier.getApplicationName();
		String versionedName = applicationIdentifier.toString();
		if (SystemUtilities.isInDevelopmentMode()) {
			// Add the application's installation directory name to this variable, so that each 
			// branch's project user directory is unique.
			versionedName += "_location_" + installationDirectory.getName();
		}

		// Look for Ghidra-specific system property
		File settingsOverrideDir = getSystemPropertyFile(PROPERTY_SETTINGS_DIR, false);
		if (settingsOverrideDir != null) {
			return createDir(new File(settingsOverrideDir,
				getUserSpecificDirName(settingsOverrideDir, appName) + "/" + versionedName));
		}

		// Look for XDG environment variable
		File xdgConfigHomeDir = getEnvFile(XdgUtils.XDG_CONFIG_HOME, false);
		if (xdgConfigHomeDir != null) {
			return createDir(new File(xdgConfigHomeDir,
				getUserSpecificDirName(xdgConfigHomeDir, appName) + "/" + versionedName));
		}

		File userHomeDir = getJavaUserHomeDir();
		String versionedSubdir = appName + "/" + versionedName;
		return createDir(switch (OperatingSystem.CURRENT_OPERATING_SYSTEM) {
			case WINDOWS -> new File(getEnvFile("APPDATA", true), versionedSubdir);
			case LINUX -> new File(userHomeDir, ".config/" + versionedSubdir);
			case FREE_BSD -> new File(userHomeDir, ".config/" + versionedSubdir);
			case OPEN_BSD -> new File(userHomeDir, ".config/" + versionedSubdir);
			case MAC_OS_X -> new File(userHomeDir, "Library/" + versionedSubdir);
			default -> throw new FileNotFoundException(
				"Failed to find the user settings directory: Unsupported operating system.");
		});
	}

	/**
	 * Gets the application's legacy (pre-Ghida 11.1) user settings directory.
	 * <p>
	 * NOTE: This method does not create the directory.
	 * 
	 * @param applicationProperties The application properties.
	 * @param installationDirectory The application installation directory.
	 * @return The application's legacy user settings directory. The returned {@link File} will 
	 *   represent an absolute path.
	 * @throws FileNotFoundException if the absolute path of the legacy user settings directory 
	 *   could not be determined.
	 */
	public static File getLegacyUserSettingsDir(ApplicationProperties applicationProperties,
			ResourceFile installationDirectory) throws FileNotFoundException {

		ApplicationIdentifier applicationIdentifier =
			new ApplicationIdentifier(applicationProperties);

		File userSettingsParentDir =
			new File(getJavaUserHomeDir(), "." + applicationIdentifier.getApplicationName());

		String userSettingsDirName = "." + applicationIdentifier;

		if (SystemUtilities.isInDevelopmentMode()) {
			// Add the application's installation directory name to this variable, so that each 
			// branch's project user directory is unique.
			userSettingsDirName += "_location_" + installationDirectory.getName();
		}

		return new File(userSettingsParentDir, userSettingsDirName);
	}

	/**
	 * Normalizes the application name by removing spaces and converting to lower case
	 * 
	 * @param applicationName The application name
	 * @return The normalized application name
	 */
	public static String normalizeApplicationName(String applicationName) {
		return applicationName.replaceAll("\\s", "").toLowerCase();
	}

	/**
	 * Gets Java's temporary directory in absolute form
	 * 
	 * @return Java's temporary directory in absolute form
	 * @throws FileNotFoundException if Java's temporary directory is not defined or it is not an
	 *   absolute path
	 */
	private static File getJavaTmpDir() throws FileNotFoundException {
		return getSystemPropertyFile("java.io.tmpdir", true);
	}

	/**
	 * Gets Java's user home directory in absolute form
	 * 
	 * @return Java's user home directory in absolute form
	 * @throws FileNotFoundException if Java's user home directory is not defined or it is not an
	 *   absolute path
	 */
	public static File getJavaUserHomeDir() throws FileNotFoundException {
		return getSystemPropertyFile("user.home", true);
	}

	/**
	 * Gets the absolute form {@link File} value of the system property by the given name
	 * 
	 * @param name The system property name
	 * @param required True if given system property is required to be set; otherwise, false
	 * @return The absolute form {@link File} value of the system property by the given name, or 
	 *   null if it isn't set
	 * @throws FileNotFoundException if the property value was not an absolute path, or if it is
	 *   required and not set
	 */
	private static File getSystemPropertyFile(String name, boolean required)
			throws FileNotFoundException {
		String path = System.getProperty(name);
		if (path == null || path.isBlank()) {
			if (required) {
				throw new FileNotFoundException(
					"Required system property \"%s\" is not set!".formatted(name));
			}
			return null;
		}
		path = path.trim();
		File file = new File(path);
		if (!file.isAbsolute()) {
			throw new FileNotFoundException(
				"System property \"%s\" is not an absolute path: \"%s\"".formatted(name, path));
		}
		return file;
	}

	/**
	 * Gets the absolute form {@link File} value of the environment variable by the given name
	 * 
	 * @param name The environment variable name
	 * @param required True if the given environment variable is required to be set; otherwise,
	 *   false
	 * @return The absolute form {@link File} value of the environment variable by the given name,
	 *   or null if it isn't set
	 * @throws FileNotFoundException if the property value was not an absolute path, or if it is
	 *   required and not set
	 */
	private static File getEnvFile(String name, boolean required) throws FileNotFoundException {
		String path = System.getenv(name);
		if (path == null || path.isBlank()) {
			if (required) {
				throw new FileNotFoundException(
					"Required environment variable \"%s\" is not set!".formatted(name));
			}
			return null;
		}
		path = path.trim();
		File file = new File(path);
		if (!file.isAbsolute()) {
			throw new FileNotFoundException(
				"Environment variable \"%s\" is not an absolute path: \"%s\"".formatted(name,
					path));
		}
		return file;
	}

	/**
	 * Gets a directory name that can be used to create a user-specific sub-directory in 
	 * {@code parentDir}. If the {@code parentDir} is contained within the user's home directory, 
	 * the given {@code appName} can simply be used since it will live in a user-specific location. 
	 * Otherwise, the user's name will get prepended to the {@code appName} so it does not collide 
	 * with other users' directories in the shared directory space.
	 * 
	 * @param parentDir The parent directory where we'd like to create a user-specific sub-directory
	 * @param appName The application name
	 * @return A directory name that can be used to create a user-specific sub-directory in 
	 *   {@code parentDir}.
	 * @throws FileNotFoundException if Java's user home directory is not defined or it is not an 
	 *   absolute path
	 */
	private static String getUserSpecificDirName(File parentDir, String appName)
			throws FileNotFoundException {
		String userSpecificDirName = appName;
		if (!FileUtilities.isPathContainedWithin(getJavaUserHomeDir(), parentDir)) {
			userSpecificDirName = SystemUtilities.getUserName() + "-" + appName;
		}
		return userSpecificDirName;
	}

	/**
	 * Creates the given {@link File directory} if it does not exist, and sets its permissions to
	 * owner-only
	 * 
	 * @param dir The directory to create
	 * @return The given directory
	 * @throws IOException if the directory failed to be created
	 */
	private static File createDir(File dir) throws IOException {
		if (dir != null) {
			if (!FileUtilities.mkdirs(dir)) {
				throw new IOException("Failed to create directory: " + dir);
			}
			FileUtilities.setOwnerOnlyPermissions(dir);
		}
		return dir;
	}
}