Skip to content

Ghidra is a software reverse engineering (SRE) framework

23.2 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 sarif.managers;

import java.io.*;
import java.lang.Exception;
import java.util.*;

import org.xml.sax.SAXException;

import com.contrastsecurity.sarif.*;
import com.google.gson.*;
import com.google.gson.stream.JsonWriter;

import ghidra.app.util.Option;
import ghidra.app.util.OptionException;
import ghidra.app.util.bin.ByteProvider;
import ghidra.app.util.importer.MessageLog;
import ghidra.app.util.opinion.*;
import ghidra.framework.Application;
import ghidra.program.database.module.TreeManager;
import ghidra.program.model.address.AddressFormatException;
import ghidra.program.model.address.AddressSetView;
import ghidra.program.model.lang.*;
import ghidra.program.model.listing.Listing;
import ghidra.program.model.listing.Program;
import ghidra.program.util.GhidraProgramUtilities;
import ghidra.util.Msg;
import ghidra.util.SystemUtilities;
import ghidra.util.exception.CancelledException;
import ghidra.util.exception.DuplicateNameException;
import ghidra.util.task.TaskMonitor;
import sarif.SarifController;
import sarif.SarifProgramOptions;
import sarif.export.SarifObject;
import sarif.io.SarifGsonIO;
import sarif.io.SarifIO;
import sarif.model.SarifDataFrame;

/**
 * The manager responsible for reading and writing a program in SARIF.
 */
public class ProgramSarifMgr {

	private static final String SARIF_URL = "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json";
	private static final String SARIF_VERSION = "2.1.0";
	private static final int N_MANAGERS = 16;

	private ProgramInfo info;
	private File file;
	private File tempFile;
	private String fileContents;
	private SarifSchema210 sarif;
	private SarifController controller;
	private SarifDataFrame df;
	private SarifMgr[] mgrs;
	private Boolean[] opts;
	private Program program;
	private MessageLog log;
	private SarifProgramOptions options;
	private Map<String, Boolean> keys = new HashMap<>();
	private Writer baseWriter;

	/**
	 * Constructs a new program SARIF manager for applying results to an existing
	 * program - used by the SarifPlugin
	 */
	public ProgramSarifMgr(Program program, MessageLog log) {
		this.program = program;
		this.log = log;
		options = new SarifProgramOptions();
		addManagers();
	}

	/**
	 * Constructs a new program SARIF manager using the specified file for export.
	 * The file should be an SARIF file.
	 * 
	 * @param file the SARIF file
	 */
	public ProgramSarifMgr(Program program, File file, MessageLog log) {
		this(program, log);
		this.file = file;
	}

	/**
	 * Constructs a new program SARIF manager using the specified file as import for
	 * creating a new program object
	 *
	 * @param bp byte provider
	 */
	public ProgramSarifMgr(ByteProvider bp, MessageLog log) {
		options = new SarifProgramOptions();
		this.file = (bp.getFSRL() != null && bp.getFSRL().getNestingDepth() == 1) ? new File(bp.getFSRL().getPath())
				: bp.getFile();
		this.log = log;
	}

	/**
	 * Returns the program info from the underlying file. T``his method does not
	 * make sense to invoke if a write is being performed to a new file.
	 * 
	 * @return the program info
	 * @throws IOException if an I/O error occurs
	 */
	public ProgramInfo getProgramInfo() throws IOException {
		if (info != null) {
			return info;
		}

		info = new ProgramInfo();

		SarifIO io = new SarifGsonIO();
		sarif = getSarif(io);
		controller = new SarifController(this);
		df = new SarifDataFrame(sarif, controller, true);
		List<Run> runs = sarif.getRuns();
		Set<Artifact> artifacts = runs.get(0).getArtifacts();
		Iterator<Artifact> iterator = artifacts.iterator();
		while(iterator.hasNext()) {
			Artifact next = iterator.next();
			Map<String, Object> props = next.getProperties().getAdditionalProperties();
			info.imageBase = (String) props.get("imageBase");
		}

		info.programName = "";
		info.exePath = "";
		info.exeFormat = "";
		info.user = "";
		info.setTool("");
		info.timestamp = "";
		info.version = "";
		info.languageID = new LanguageID(df.getSourceLanguage());
		info.compilerSpecID = new CompilerSpecID(df.getCompiler());
		info.processorName = "";
		info.family = "";
		info.addressModel = "";
		info.endian = "";

		return info;
	}

	private SarifSchema210 getSarif(SarifIO io) throws IOException {
		return file != null ? io.readSarif(file) : io.readSarif(getFileContents());
	}

	private Writer getWriter() throws IOException {
		return file != null ? new FileWriter(file) : new StringWriter(1000);
	}

	public void addManagers() {
		int mgrCount = 0;
		mgrs = new SarifMgr[N_MANAGERS+1];
		opts = new Boolean[N_MANAGERS+1];
		mgrs[mgrCount] = new DataTypesSarifMgr(program, log);
		opts[mgrCount++] = options.isData();
		mgrs[mgrCount] = new MemoryMapSarifMgr(this, program, log);
		opts[mgrCount++] = options.isMemoryBlocks();
		mgrs[mgrCount] = new RegisterValuesSarifMgr(program, log);
		opts[mgrCount++] = options.isRegisters();
		mgrs[mgrCount] = new CodeSarifMgr(program, log);
		opts[mgrCount++] = options.isInstructions();
		mgrs[mgrCount] = new DefinedDataSarifMgr(program, log);
		opts[mgrCount++] = options.isData();
		mgrs[mgrCount] = new EquatesSarifMgr(program, log);
		opts[mgrCount++] = options.isEquates();
		mgrs[mgrCount] = new CommentsSarifMgr(program, log);
		opts[mgrCount++] = options.isComments();
		mgrs[mgrCount] = new PropertiesSarifMgr(program, log);
		opts[mgrCount++] = options.isProperties();
		mgrs[mgrCount] = new BookmarksSarifMgr(program, log);
		opts[mgrCount++] = options.isBookmarks();
		mgrs[mgrCount] = new ProgramTreeSarifMgr(program, log);
		opts[mgrCount++] = options.isTrees();
		mgrs[mgrCount] = new ExtEntryPointSarifMgr(program, log);
		opts[mgrCount++] = options.isEntryPoints();
		mgrs[mgrCount] = new RelocationTableSarifMgr(program, log);
		opts[mgrCount++] = options.isRelocationTable();
		mgrs[mgrCount] = new SymbolTableSarifMgr(program, log, true);
		opts[mgrCount++] = options.isSymbols();
		mgrs[mgrCount] = new ExternalLibSarifMgr(program, log);
		opts[mgrCount++] = options.isExternalLibraries();
		mgrs[mgrCount] = new FunctionsSarifMgr(program, log);
		opts[mgrCount++] = options.isFunctions();
		mgrs[mgrCount] = new SymbolTableSarifMgr(program, log, false);
		opts[mgrCount++] = options.isSymbols();
		mgrs[mgrCount] = new MarkupSarifMgr(program, log);
		opts[mgrCount++] = options.isReferences();
		assert (mgrCount == N_MANAGERS+1);

		Map<String, Boolean> columnKeys = SarifMgr.getColumnKeys();
		for (String k : columnKeys.keySet()) {
			keys.put(k, columnKeys.get(k));
		}
	}

	public void setOptions(List<Option> optionList, boolean isAddToProgram) throws OptionException {
		options.setOptions(optionList);
		options.setAddToProgram(isAddToProgram);

		int mgrCount = 0;
		opts = new Boolean[N_MANAGERS + 1];
		opts[mgrCount++] = options.isData();
		opts[mgrCount++] = options.isMemoryBlocks();
		opts[mgrCount++] = options.isRegisters();
		opts[mgrCount++] = options.isInstructions();
		opts[mgrCount++] = options.isData();
		opts[mgrCount++] = options.isEquates();
		opts[mgrCount++] = options.isComments();
		opts[mgrCount++] = options.isProperties();
		opts[mgrCount++] = options.isBookmarks();
		opts[mgrCount++] = options.isTrees();
		opts[mgrCount++] = options.isEntryPoints();
		opts[mgrCount++] = options.isRelocationTable();
		opts[mgrCount++] = options.isSymbols();
		opts[mgrCount++] = options.isExternalLibraries();
		opts[mgrCount++] = options.isFunctions();
		opts[mgrCount++] = options.isSymbols();
		opts[mgrCount++] = options.isReferences();
		assert (mgrCount == N_MANAGERS + 1);
	}

	public Map<String, Boolean> getKeys() {
		return keys;
	}

	/**
	 * Reads from the underlying SARIF file and populates the specified program.
	 * 
	 * @param program the program to load the SARIF into
	 * @param monitor the task monitor
	 * @param options the SARIF options, which features to load and to ignore
	 * @return the message log containing any warning/error messages
	 * @throws SAXException           if an SARIF error occurs
	 * @throws IOException            if an I/O occurs
	 * @throws AddressFormatException if an invalid address is specified in the
	 *                                SARIF
	 */
	public MessageLog read(Program program, TaskMonitor monitor)
			throws IOException, AddressFormatException {

		if (mgrs == null || program != this.program) {
			this.program = program;
			addManagers();
		}
		if (df == null) {
			SarifIO io = new SarifGsonIO();
			sarif = getSarif(io);
			controller = new SarifController(this);
		}
		controller.setProgram(program);
		df = new SarifDataFrame(sarif, controller, false);

		Map<String, List<Map<String, Object>>> tableResults = getDataFrame().getTableResultsAsMap();

		readResults(monitor, options, tableResults);

		createDefaultTree(program, options);

		// if instructions were imported, then remove the "needs analyzed" property
		if (options.isInstructions()) {
			GhidraProgramUtilities.markProgramAnalyzed(program);
		}

		return null;
	}

	public void readResults(TaskMonitor monitor, SarifProgramOptions options,
			Map<String, List<Map<String, Object>>> tableResults) throws IOException {
		try {
			for (int i = 0; i < mgrs.length; i++) {
				if (opts[i]) {
					List<Map<String, Object>> list = tableResults.get(mgrs[i].getKey());
					mgrs[i].readResults(list, options, monitor);
				}
			}
		} catch (Exception e) {
			throw new IOException("SARIF Read Cancelled");
		}

	}

	/**
	 * Converts from a generic format name to standard Ghidra names;
	 *
	 * @param name the generic format name
	 * @return the equivalent Ghidra name
	 */
	public static String getStandardName(String name) {
		if (name == null) {
			return "Unknown";
		} else if (name.toLowerCase().indexOf("portable executable") >= 0 && name.toLowerCase().indexOf("(pe)") >= 0) {
			return PeLoader.PE_NAME;
		} else if (name.toLowerCase().indexOf("(elf)") != -1) {
			return ElfLoader.ELF_NAME;
		} else if (name.toLowerCase().indexOf("dos executable") >= 0) {
			return MzLoader.MZ_NAME;
		} else if (name.toLowerCase().indexOf("new executable") >= 0) {
			return NeLoader.NE_NAME;
		}
		return name;
	}

	private void createDefaultTree(Program program, SarifProgramOptions options) {

		if (options.isAddToProgram()) {
			return;
		}

		Listing listing = program.getListing();
		if (listing.getTreeNames().length == 0) {
			try {
				listing.createRootModule(TreeManager.DEFAULT_TREE_NAME);
			} catch (DuplicateNameException e) {
				// shouldn't happen since we checked the tree names above
				Msg.debug(this, "Unable to create default module", e);
			}
		}

	}

	/**
	 * Writes the specified program in SARIF into the underlying file.
	 * 
	 * @param program the program to write into SARIF
	 * @param addrSet an address set to limit areas of program that written, or null
	 *                for entire program
	 * @param monitor the task monitor
	 * @param options the SARIF options to limit what is and is not written out
	 * @return the message log containing any warning/error messages
	 * @throws IOException        if an I/O occurs
	 * @throws CancelledException if the user cancels the read
	 */
	public MessageLog write(Program program, AddressSetView addrSet, TaskMonitor monitor, SarifProgramOptions options)
			throws IOException, CancelledException {

		MessageLog log = new MessageLog();

		baseWriter = getWriter();
		JsonWriter writer = new JsonWriter(getBaseWriter());
		writer.setIndent("  ");
		Gson gson = new GsonBuilder().setPrettyPrinting().excludeFieldsWithoutExposeAnnotation().serializeNulls()
				.disableHtmlEscaping().create();
		try {
			if (SarifObject.SARIF) {
				JsonObject sarif = new JsonObject();
				JsonArray results = new JsonArray();
				writeSarifHeader(program, sarif, results);
				writeResults(program, addrSet, results, monitor, log, options);
			    monitor.setMessage("Results written...exporting to JSON");
				gson.toJson(sarif, writer);
			    monitor.setMessage("JSON completed");
			} else {
				JsonObject json = new JsonObject();
				json.addProperty("name", program.getDomainFile().getName());
				json.addProperty("exe_path", program.getExecutablePath());
				json.addProperty("exe_format", program.getExecutableFormat());
				json.addProperty("image_base", program.getImageBase().toString());
				writeInfoSource(json, monitor);
				writeProcessor(program, json, monitor);
				JsonArray results = new JsonArray();
				json.add("results", results);
				writeResults(program, addrSet, results, monitor, log, options);
			    monitor.setMessage("Results written...exporting to JSON");
				gson.toJson(json, writer);
			    monitor.setMessage("JSON completed");
			}
		} finally {
			writer.flush();
			writer.close();
		}

		return log;
	}

	private void writeSarifHeader(Program program, JsonObject sarif, JsonArray results) {
		sarif.addProperty("$schema", SARIF_URL);
		sarif.addProperty("version", SARIF_VERSION);
		sarif.add("properties", new JsonObject());
		JsonArray runs = new JsonArray();
		sarif.add("runs", runs);
		JsonObject run = new JsonObject();
		runs.add(run);
		writeToolInfo(program, run);
		run.add("results", results);
	}

	private void writeToolInfo(Program program, JsonObject run) {
		JsonObject tool = new JsonObject();
		run.add("tool", tool);
		JsonObject driver = new JsonObject();
		tool.add("driver", driver);
		driver.addProperty("name", Application.getName());
		driver.addProperty("version", Application.getApplicationVersion());
		driver.addProperty("informationUri", "https://github.com/NationalSecurityAgency/ghidra");
		
		JsonArray artifacts = new JsonArray();
		run.add("artifacts", artifacts);
		JsonObject artifact = new JsonObject();
		artifacts.add(artifact);
		JsonObject location = new JsonObject();
		artifact.add("location", location);
		location.addProperty("uri", program.getExecutablePath());
		
		JsonObject properties = new JsonObject();
		artifact.add("properties", properties);
		JsonObject additionalProperties = new JsonObject();
		properties.add("additionalProperties", additionalProperties);
		additionalProperties.addProperty("imageBase", program.getImageBase().toString());
		
		artifact.addProperty("sourceLanguage", program.getLanguageID().getIdAsString());
		
		JsonObject description = new JsonObject();
		artifact.add("description", description);
		// JsonObject message = new JsonObject();
		// description.add("message", message);
		description.addProperty("text", program.getMetadata().get("Compiler ID"));
	}

	private void writeResults(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		writeCodeBlocks(program, addrSet, results, monitor, log, options);
		writeComments(program, addrSet, results, monitor, log, options);
		writeDataTypes(program, addrSet, results, monitor, log, options);
		writeMemoryMap(program, addrSet, results, monitor, log, options);
		writeRegisters(program, addrSet, results, monitor, log, options);
		writeDefinedData(program, addrSet, results, monitor, log, options);
		writeEquates(program, addrSet, results, monitor, log, options);
		writeProperties(program, addrSet, results, monitor, log, options);
		writeBookmarks(program, addrSet, results, monitor, log, options);
		writeTrees(program, addrSet, results, monitor, log, options); 
		writeEntryPoints(program, addrSet, results, monitor, log, options);
		writeRelocations(program, addrSet, results, monitor, log, options);
		writeFunctions(program, addrSet, results, monitor, log, options);
		writeSymbols(program, addrSet, results, monitor, log, options);
		writeReferences(program, addrSet, results, monitor, log, options);
		writeExtLibraries(program, addrSet, results, monitor, log, options);
	}

	private void writeCodeBlocks(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isInstructions()) {
			CodeSarifMgr mgr = new CodeSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeComments(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isComments()) {
			CommentsSarifMgr mgr = new CommentsSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeDataTypes(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isData()) {
			DataTypesSarifMgr mgr = new DataTypesSarifMgr(program, log);
			mgr.write(results, monitor);
		}
	}

	private void writeMemoryMap(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isMemoryBlocks()) {
			MemoryMapSarifMgr mgr = new MemoryMapSarifMgr(this, program, log);
			String path = file != null ? file.getAbsolutePath() : tempFile.getAbsolutePath();
			mgr.write(results, addrSet, monitor, options.isMemoryContents(), path);
		}
	}

	private void writeEquates(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isEquates()) {
			EquatesSarifMgr mgr = new EquatesSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeProperties(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isProperties()) {
			PropertiesSarifMgr mgr = new PropertiesSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeBookmarks(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isBookmarks()) {
			BookmarksSarifMgr mgr = new BookmarksSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeRegisters(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isRegisters()) {
			RegisterValuesSarifMgr mgr = new RegisterValuesSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeTrees(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isTrees()) {
			ProgramTreeSarifMgr mgr = new ProgramTreeSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeEntryPoints(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isEntryPoints()) {
			ExtEntryPointSarifMgr mgr = new ExtEntryPointSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeRelocations(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isRelocationTable()) {
			RelocationTableSarifMgr mgr = new RelocationTableSarifMgr(program, log);
			mgr.write(results, monitor);
		}
	}

	private void writeDefinedData(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isData()) {
			DefinedDataSarifMgr mgr = new DefinedDataSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeFunctions(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isFunctions()) {
			FunctionsSarifMgr mgr = new FunctionsSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeSymbols(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isSymbols()) {
			SymbolTableSarifMgr mgr = new SymbolTableSarifMgr(program, log, true);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeReferences(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isReferences()) {
			MarkupSarifMgr mgr = new MarkupSarifMgr(program, log);
			mgr.write(results, addrSet, monitor);
		}
	}

	private void writeExtLibraries(Program program, AddressSetView addrSet, JsonArray results, TaskMonitor monitor,
			MessageLog log, SarifProgramOptions options) throws IOException, CancelledException {
		if (options.isExternalLibraries()) {
			ExternalLibSarifMgr mgr = new ExternalLibSarifMgr(program, log);
			mgr.write(results, monitor);
		}
	}

	private void writeInfoSource(JsonObject json, TaskMonitor monitor) {
		monitor.setMessage("Writing INFO SOURCE ...");

		JsonObject attrs = new JsonObject();
		String user = SystemUtilities.getUserName();
		if (user != null) {
			attrs.addProperty("USER", user);
		}
		attrs.addProperty("TOOL", "Ghidra " + Application.getApplicationVersion());
		attrs.addProperty("TIMESTAMP", new Date().toString());

		json.add("INFO_SOURCE", attrs);
	}

	private void writeProcessor(Program program, JsonObject json, TaskMonitor monitor) {
		monitor.setMessage("Writing PROCESSOR ...");

		JsonObject attrs = new JsonObject();
		Language language = program.getLanguage();
		CompilerSpec compilerSpec = program.getCompilerSpec();

		attrs.addProperty("NAME", language.getProcessor().toString());
		attrs.addProperty("LANGUAGE_PROVIDER",
				language.getLanguageID().getIdAsString() + ":" + compilerSpec.getCompilerSpecID().getIdAsString());
		attrs.addProperty("ENDIAN", language.isBigEndian() ? "big" : "little");

		json.add("PROCESSOR", attrs);
	}

	public File getFile() {
		return file;
	}

	public String getDirectory() {
		return file != null ? file.getParent() : tempFile.getParent();
	}
	
	public SarifDataFrame getDataFrame() {
		return df;
	}

	public SarifProgramOptions getOptions() {
		return options;
	}

	public String getFileContents() {
		return fileContents;
	}

	public void setFileContents(String fileContents) {
		this.fileContents = fileContents;
	}

	public Writer getBaseWriter() {
		return baseWriter;
	}
	
	// FOR TESTING
	public void useTempFileForBytes(String tempDir) throws IOException {
		File dir = new File(tempDir);
		String fileName = "SARIF_TEST";
		String suffixName = ".sarif.bytes";
		String filename = fileName + '.';
		tempFile = File.createTempFile(filename, suffixName, dir);
		tempFile.deleteOnExit();	
	}

}