Skip to content

Ghidra is a software reverse engineering (SRE) framework

10.8 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 pdb.symbolserver;

import java.io.File;
import java.io.IOException;
import java.util.*;
import java.util.stream.Collectors;

import org.apache.commons.io.FilenameUtils;
import org.apache.commons.lang3.StringUtils;

import ghidra.util.Msg;
import ghidra.util.exception.CancelledException;
import ghidra.util.task.TaskMonitor;
import pdb.PdbUtils;

/**
 * A (lowercase-'S') service that searches for and fetches symbol files
 * from a set of {@link SymbolServer symbolservers}. (not to be confused with a Plugin service)
 * <p>
 * Instances of this class are meant to be easily created when needed
 * and just as easily thrown away when not used or when the search 
 * path configuration changes.
 * <p>
 * A SymbolServerService instance requires a {@link SymbolStore} and
 * optionally a list of {@link SymbolServer}s.
 */
public class SymbolServerService {

	private static final int MAX_TRY_COUNT = 3;
	private SymbolStore symbolStore;	// also the first element of the symbolServers list
	private List<SymbolServer> symbolServers;

	/**
	 * Creates a new SymbolServerService instance.
	 * 
	 * @param symbolStore a {@link SymbolStore} - where all remote files are placed when 
	 * downloaded. Also treated as a SymbolServer and searched first
	 * @param symbolServers  a list of {@link SymbolServer symbol servers} - searched in order
	 */
	public SymbolServerService(SymbolStore symbolStore, List<SymbolServer> symbolServers) {
		this.symbolStore = symbolStore;
		this.symbolServers = new ArrayList<>();
		this.symbolServers.add(symbolStore);
		this.symbolServers.addAll(symbolServers);
	}

	/**
	 * Returns true if this SymbolServerService is fully valid.
	 * Will be false if the symbol storage location isn't a {@link LocalSymbolStore}.
	 * 
	 * @return boolean true if this instance is valid, false if not valid
	 */
	public boolean isValid() {
		return symbolStore instanceof LocalSymbolStore;
	}

	/**
	 * Returns the {@link SymbolStore}, which is the primary / first location queried and
	 * used to store any symbol files retrieved from a remote symbol server. 
	 * 
	 * @return the {@link SymbolStore}
	 */
	public SymbolStore getSymbolStore() {
		return symbolStore;
	}

	/**
	 * Returns the list of {@link SymbolServer}s.
	 * 
	 * @return the list of {@link SymbolServer}s
	 */
	public List<SymbolServer> getSymbolServers() {
		return new ArrayList<>(symbolServers.subList(1, symbolServers.size()));
	}

	/**
	 * Searches all {@link SymbolServer symbol servers} for a matching pdb symbol file.
	 * 
	 * @param symbolFileInfo {@link SymbolFileInfo} bag of information
	 *   about the file to search for
	 * @param monitor {@link TaskMonitor} to update with search progress and to
	 *   allow the user to cancel the operation
	 * @return a list of {@link SymbolFileLocation} instances
	 * @throws CancelledException if cancelled
	 */
	public List<SymbolFileLocation> find(SymbolFileInfo symbolFileInfo, TaskMonitor monitor)
			throws CancelledException {
		return find(symbolFileInfo, FindOption.NO_OPTIONS, monitor);
	}

	/**
	 * Searches all {@link SymbolServer symbol servers} for a matching pdb symbol file.
	 * <p>
	 * Returns a list of matches.
	 * <p>
	 * Use {@link SymbolFileLocation#isExactMatch(SymbolFileInfo)} to test elements in the
	 * result list for exactness.
	 * 
	 * @param symbolFileInfo Pdb file info to search for
	 * @param findOptions set of {@link FindOption} to control the search.
	 *  See {@link FindOption#NO_OPTIONS} or 
	 *  {@link FindOption#of(FindOption...) FindOptions.of(option1, option2...)}
	 * @param monitor {@link TaskMonitor}
	 * @return list of {@link SymbolFileLocation}s
	 * @throws CancelledException if operation canceled by user
	 */
	public List<SymbolFileLocation> find(SymbolFileInfo symbolFileInfo,
			Set<FindOption> findOptions, TaskMonitor monitor) throws CancelledException {

		if (StringUtils.isBlank(symbolFileInfo.getName())) {
			Msg.warn(this,
				logPrefix() + ": Unable to search for empty filename: " + symbolFileInfo);
			return List.of();
		}

		List<SymbolFileLocation> allFindResults = new ArrayList<>();
		Set<String> uniqueSymbolFilePaths = new HashSet<>();

		for_each_symbol_server_loop: for (SymbolServer symbolServer : symbolServers) {
			monitor.checkCancelled();
			if (!symbolServer.isTrusted() && !findOptions.contains(FindOption.ALLOW_UNTRUSTED)) {
				Msg.debug(this,
					logPrefix() + ": skipping untrusted symbol server " +
						symbolServer.getDescriptiveName());
				continue;
			}

			Msg.debug(this, logPrefix() + ": querying " + symbolServer.getDescriptiveName() +
				" for " + symbolFileInfo.getDescription());

			List<SymbolFileLocation> symbolServerFindResults =
				symbolServer.find(symbolFileInfo, findOptions, monitor);

			Msg.debug(this,
				logPrefix() + ": got " + symbolServerFindResults.size() + " results from " +
					symbolServer.getDescriptiveName());

			// only add unique file locations
			for (SymbolFileLocation symbolFileLocation : symbolServerFindResults) {
				if (uniqueSymbolFilePaths.add(symbolFileLocation.getLocationStr())) {
					allFindResults.add(symbolFileLocation);
					if (findOptions.contains(FindOption.ONLY_FIRST_RESULT)) {
						break for_each_symbol_server_loop;
					}
				}
			}
		}

		Msg.debug(this, logPrefix() + ": found " + allFindResults.size() + " matches");

		return allFindResults;

	}

	/**
	 * Returns the local file path of the symbol file specified by symbolFileLocation.
	 *  
	 * @param symbolFileLocation {@link SymbolFileLocation}, returned 
	 *  by {@link #find(SymbolFileInfo, Set, TaskMonitor) find()} 
	 * @param monitor {@link TaskMonitor}
	 * @return {@link File} path to the local pdb file, never null
	 * @throws CancelledException if user cancels operation
	 * @throws IOException if error or problem getting file
	 */
	public File getSymbolFile(SymbolFileLocation symbolFileLocation, TaskMonitor monitor)
			throws CancelledException, IOException {
		Msg.debug(this,
			logPrefix() + ": getting symbol file: " + symbolFileLocation.getLocationStr());

		SymbolFileLocation localSymbolFileLocation =
			ensureLocalUncompressedFile(symbolFileLocation, monitor);

		Msg.debug(this,
			logPrefix() + ": local file now: " + localSymbolFileLocation.getLocationStr());

		SymbolStore symbolStore = (SymbolStore) localSymbolFileLocation.getSymbolServer();

		return symbolStore.getFile(localSymbolFileLocation.getPath());
	}

	/**
	 * Converts a possibly remote {@link SymbolFileLocation} to a location that is local and
	 * uncompressed.
	 * 
	 * @param symbolFileLocation possibly remote {@link SymbolFileLocation}
	 * @param monitor {@link TaskMonitor} to display progress and allow canceling
	 * @return {@link SymbolFileLocation} that is local (possibly the same  instance if already
	 * local)
	 * @throws CancelledException if canceled
	 * @throws IOException if error
	 */
	public SymbolFileLocation getLocalSymbolFileLocation(SymbolFileLocation symbolFileLocation,
			TaskMonitor monitor) throws CancelledException, IOException {
		Msg.debug(this,
			logPrefix() + ": getting symbol file: " + symbolFileLocation.getLocationStr());

		SymbolFileLocation localSymbolFileLocation =
			ensureLocalUncompressedFile(symbolFileLocation, monitor);

		return localSymbolFileLocation;
	}

	private SymbolFileLocation ensureLocalUncompressedFile(SymbolFileLocation symbolFileLocation,
			TaskMonitor monitor) throws IOException, CancelledException {
		if (!(symbolFileLocation.getSymbolServer() instanceof SymbolStore)) {
			symbolFileLocation = copyRemoteToLocal(symbolFileLocation, monitor);
		}

		// symbolFileLocation now must be on a SymbolStore, so safe to cast
		SymbolStore localSymbolStore = (SymbolStore) symbolFileLocation.getSymbolServer();

		if (SymbolStore.isCompressedFilename(symbolFileLocation.getPath())) {
			File cabFile = localSymbolStore.getFile(symbolFileLocation.getPath());
			File adminDir = symbolStore.getAdminDir();
			if (!adminDir.isDirectory()) {
				// if the admin dir is missing, use the cab file's directory
				adminDir = cabFile.getParentFile();
			}
			File temporaryExtractFile =
				new File(adminDir, "ghidra_cab_extract_tmp_" + System.currentTimeMillis());

			Msg.debug(this, "%s: decompressing file %s".formatted(logPrefix(),
				symbolFileLocation.getLocationStr()));

			String originalName =
				PdbUtils.extractSingletonCabToFile(cabFile, temporaryExtractFile, monitor);
			String uncompressedPath =
				symbolStore.giveFile(symbolFileLocation.getFileInfo(), temporaryExtractFile,
					originalName, monitor);

			symbolFileLocation = new SymbolFileLocation(uncompressedPath, symbolStore,
				symbolFileLocation.getFileInfo());

			Msg.debug(this, "%s: new decompressed file %s".formatted(logPrefix(),
				symbolFileLocation.getLocationStr()));
		}

		return symbolFileLocation;
	}

	private SymbolFileLocation copyRemoteToLocal(SymbolFileLocation symbolFileLocation,
			TaskMonitor monitor) throws CancelledException, IOException {
		int tryCount = 0;
		while (true) {
			Msg.debug(this,
				"%s try[%d]: copying file %s from remote to local %s".formatted(logPrefix(),
					tryCount, symbolFileLocation.getLocationStr(), symbolStore.getName()));

			// copy from remote store to our main local symbol store
			String remoteFilename = FilenameUtils.getName(symbolFileLocation.getPath());
			try (SymbolServerInputStream symbolServerInputStream =
				symbolFileLocation.getSymbolServer()
						.getFileStream(symbolFileLocation.getPath(), monitor)) {
				String newPath = symbolStore.putStream(symbolFileLocation.getFileInfo(),
					symbolServerInputStream, remoteFilename, monitor);
				return new SymbolFileLocation(newPath, symbolStore,
					symbolFileLocation.getFileInfo());
			}
			catch (IOException e) {
				String msg = "%s: error copying file %s to %s: %s".formatted(logPrefix(),
					symbolFileLocation.getLocationStr(), symbolStore.getName(), e.getMessage());
				if (++tryCount >= MAX_TRY_COUNT) {
					Msg.error(this, msg);
					throw e; // failure
				}

				// allow retry
				Msg.warn(this, msg);
			}
		}
	}

	private String logPrefix() {
		return getClass().getSimpleName();
	}

	@Override
	public String toString() {
		return String.format(
			"SymbolServerService:\n\tsymbolStore: %s,\n\tsymbolServers:\n\t\t%s\n",
			symbolStore.toString(),
			symbolServers.subList(1, symbolServers.size())
					.stream()
					.map(SymbolServer::toString)
					.collect(Collectors.joining("\n\t\t")));
	}

}