Skip to content

Ghidra is a software reverse engineering (SRE) framework

13.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 agent.dbgeng.rmi;

import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.greaterThan;
import static org.hamcrest.Matchers.instanceOf;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

import java.util.*;

import org.junit.Ignore;
import org.junit.Test;

import ghidra.app.plugin.core.debug.utils.ManagedDomainObject;
import ghidra.debug.api.tracermi.RemoteMethod;
import ghidra.program.model.address.AddressSpace;
import ghidra.trace.database.ToyDBTraceBuilder;
import ghidra.trace.model.Lifespan;
import ghidra.trace.model.Trace;
import ghidra.trace.model.memory.TraceMemorySpace;
import ghidra.trace.model.memory.TraceMemoryState;
import ghidra.trace.model.target.TraceObject;
import ghidra.trace.model.target.path.*;
import ghidra.trace.model.time.TraceSnapshot;

public class DbgEngHooksTest extends AbstractDbgEngTraceRmiTest {
	private static final long RUN_TIMEOUT_MS = 5000;
	private static final long RETRY_MS = 500;

	record PythonAndTrace(PythonAndConnection conn, ManagedDomainObject<Trace> mdo)
			implements AutoCloseable {
		public void execute(String cmd) {
			conn.execute(cmd);
		}

		public String executeCapture(String cmd) {
			return conn.executeCapture(cmd);
		}

		@Override
		public void close() throws Exception {
			conn.close();
			mdo.close();
		}
	}

	@SuppressWarnings("resource")
	protected PythonAndTrace startAndSyncPython(String exec) throws Exception {
		PythonAndConnection conn = startAndConnectPython();
		try {
			ManagedDomainObject<Trace> mdo;
			conn.execute("from ghidradbg.commands import *");
			conn.execute(
				"util.set_convenience_variable('ghidra-language', 'x86:LE:64:default')");
			if (exec != null) {
				start(conn, exec);
				mdo = waitTrace("/New Traces/pydbg/" + exec);
			}
			else {
				conn.execute("ghidra_trace_start()");
				mdo = waitTrace("/New Traces/pydbg/noname");
			}
			tb = new ToyDBTraceBuilder(mdo.get());
			return new PythonAndTrace(conn, mdo);
		}
		catch (Exception e) {
			conn.close();
			throw e;
		}
	}

	protected long lastSnap(PythonAndTrace conn) {
		return conn.conn.connection().getLastSnapshot(tb.trace);
	}

	static final int INIT_NOTEPAD_THREAD_COUNT = 4; // This could be fragile

	@Test
	public void testOnNewThread() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			conn.execute("from ghidradbg.commands import *");
			txPut(conn, "processes");

			waitForPass(() -> {
				TraceObject proc = tb.objAny0("Sessions[].Processes[]");
				assertNotNull(proc);
				assertEquals("STOPPED", tb.objValue(proc, lastSnap(conn), "_state"));
			}, RUN_TIMEOUT_MS, RETRY_MS);

			txPut(conn, "threads");
			waitForPass(() -> assertEquals(INIT_NOTEPAD_THREAD_COUNT,
				tb.objValues(lastSnap(conn), "Sessions[].Processes[].Threads[]").size()),
				RUN_TIMEOUT_MS, RETRY_MS);

			// Via method, go is asynchronous
			RemoteMethod go = conn.conn.getMethod("go");
			TraceObject proc = tb.objAny0("Sessions[].Processes[]");
			go.invoke(Map.of("process", proc));

			waitForPass(() -> assertThat(
				tb.objValues(lastSnap(conn), "Sessions[].Processes[].Threads[]").size(),
				greaterThan(INIT_NOTEPAD_THREAD_COUNT)),
				RUN_TIMEOUT_MS, RETRY_MS);
		}
	}

	@Test
	public void testOnThreadSelected() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			txPut(conn, "processes");

			waitForPass(() -> {
				TraceObject proc = tb.obj("Sessions[0].Processes[0]");
				assertNotNull(proc);
				assertEquals("STOPPED", tb.objValue(proc, lastSnap(conn), "_state"));
			}, RUN_TIMEOUT_MS, RETRY_MS);

			txPut(conn, "threads");
			waitForPass(() -> assertEquals(4,
				tb.objValues(lastSnap(conn), "Sessions[0].Processes[0].Threads[]").size()),
				RUN_TIMEOUT_MS, RETRY_MS);

			// Now the real test
			conn.execute("print('Selecting 1')");
			conn.execute("util.select_thread(1)");
			waitForPass(() -> {
				String tnum = conn.executeCapture("print(util.selected_thread())").strip();
				assertEquals("1", tnum);
				String threadIndex = threadIndex(traceManager.getCurrentObject());
				assertEquals("1", threadIndex);
			}, RUN_TIMEOUT_MS, RETRY_MS);

			conn.execute("util.select_thread(2)");
			waitForPass(() -> {
				String tnum = conn.executeCapture("print(util.selected_thread())").strip();
				assertEquals("2", tnum);
				String threadIndex = threadIndex(traceManager.getCurrentObject());
				assertEquals("2", threadIndex);
			}, RUN_TIMEOUT_MS, RETRY_MS);

			conn.execute("util.select_thread(0)");
			waitForPass(() -> {
				String tnum = conn.executeCapture("print(util.selected_thread())").strip();
				assertEquals("0", tnum);
				String threadIndex = threadIndex(traceManager.getCurrentObject());
				assertEquals("0", threadIndex);
			}, RUN_TIMEOUT_MS, RETRY_MS);
		}
	}

	protected String getIndex(TraceObject object, String pattern, int n) {
		if (object == null) {
			return null;
		}
		PathPattern pat = PathFilter.parse(pattern).getSingletonPattern();
//		if (pat.countWildcards() != 1) {
//			throw new IllegalArgumentException("Exactly one wildcard required");
//		}
		KeyPath path = object.getCanonicalPath();
		if (path.size() < pat.asPath().size()) {
			return null;
		}
		List<String> matched = pat.matchKeys(path, false);
		if (matched == null) {
			return null;
		}
		if (matched.size() <= n) {
			return null;
		}
		return matched.get(n);
	}

	protected String threadIndex(TraceObject object) {
		return getIndex(object, "Sessions[].Processes[].Threads[]", 2);
	}

	protected String frameIndex(TraceObject object) {
		return getIndex(object, "Sessions[].Processes[].Threads[].Stack.Frames[]", 3);
	}

	@Test
	@Ignore
	public void testOnSyscallMemory() throws Exception {
		// TODO: Need a specimen
		// FWIW, I've already seen this getting exercised in other tests.
	}

	/**
	 * dbgeng has limited support via DEBUG_CDS_DATA. It tells us what space has changed, but not
	 * the address(es). We have some options:
	 * 
	 * 1) Ignore it. This puts the onus of refreshing on the user. The upside is that past
	 * observations are preserved. The downside is we can't be certain of their accuracy.
	 * 
	 * 2) Invalidate the entire space. This will ensure the UI either updates automatically or
	 * indicates the possible staleness. The downside is that we lose past observations.
	 * 
	 * 3) Remember what addresses have been fetched since last BREAK, and refresh them all. This is
	 * better than refreshing the entire space (prohibitive), but we could get right back there if
	 * the user has captured the full space and then modifies a single byte.
	 * 
	 * For the moment, we favor option (2), as we'd prefer never to display inaccurate data,
	 * especially as non-stale. The lost observations are a small price to pay, since they're not
	 * particularly important for the interactive use case.
	 * 
	 * @throws Exception because
	 */
	@Test
	public void testOnMemoryChanged() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {

			long address = getAddressAtOffset(conn, 0);

			conn.execute("ghidra_trace_txstart('Tx')");
			conn.execute("ghidra_trace_putmem(%d, 10)".formatted(address));
			conn.execute("ghidra_trace_txcommit()");

			waitForPass(() -> {
				assertEquals(TraceMemoryState.KNOWN,
					tb.trace.getMemoryManager().getState(lastSnap(conn), tb.addr(address)));
			}, RUN_TIMEOUT_MS, RETRY_MS);

			conn.execute("util.dbg.write(%d, b'\\x7f')".formatted(address));

			waitForPass(() -> {
				assertEquals(TraceMemoryState.UNKNOWN,
					tb.trace.getMemoryManager().getState(lastSnap(conn), tb.addr(address)));
			}, RUN_TIMEOUT_MS, RETRY_MS);
		}
	}

	@Test
	public void testOnRegisterChanged() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {

			conn.execute("ghidra_trace_txstart('Tx')");
			conn.execute("ghidra_trace_putreg()");
			conn.execute("ghidra_trace_txcommit()");
			conn.execute("util.dbg.cmd('r rax=0x1234')");

			String path = "Sessions[].Processes[].Threads[].Registers";
			TraceObject registers = Objects.requireNonNull(tb.objAny(path, Lifespan.at(0)));
			AddressSpace space = tb.trace.getBaseAddressFactory()
					.getAddressSpace(registers.getCanonicalPath().toString());
			TraceMemorySpace regs = tb.trace.getMemoryManager().getMemorySpace(space, false);
			waitForPass(() -> assertEquals("1234",
				regs.getValue(lastSnap(conn), tb.reg("RAX")).getUnsignedValue().toString(16)));
		}
	}

	@Test
	public void testOnCont() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			txPut(conn, "processes");

			// WaitForEvents is not required for this test to pass. 
			conn.execute("""
					@util.dbg.eng_thread
					def go_no_wait():
					    util.dbg._base._control.SetExecutionStatus(DbgEng.DEBUG_STATUS_GO)

					go_no_wait()
					""");
			waitRunning("Missed running after go");

			TraceObject proc = waitForValue(() -> tb.objAny0("Sessions[].Processes[]"));
			waitForPass(() -> {
				assertEquals("RUNNING", tb.objValue(proc, lastSnap(conn), "_state"));
			}, RUN_TIMEOUT_MS, RETRY_MS);
		}
	}

	@Test
	public void testOnStop() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			txPut(conn, "processes");

			TraceObject proc = waitForValue(() -> tb.objAny0("Sessions[].Processes[]"));
			waitForPass(() -> {
				assertEquals("STOPPED", tb.objValue(proc, lastSnap(conn), "_state"));
			}, RUN_TIMEOUT_MS, RETRY_MS);
		}
	}

	@Test
	public void testOnExited() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("netstat.exe")) {
			txPut(conn, "processes");
			waitStopped("Missed initial stop");

			// Do the synchronous wait here, since netstat should terminate
			conn.execute("util.dbg.go()");

			waitForPass(() -> {
				TraceSnapshot snapshot =
					tb.trace.getTimeManager().getSnapshot(lastSnap(conn), false);
				assertNotNull(snapshot);
				assertEquals("Exited with code 0", snapshot.getDescription());

				TraceObject proc = tb.objAny0("Sessions[].Processes[]");
				assertNotNull(proc);
				Object val = tb.objValue(proc, lastSnap(conn), "_exit_code");
				assertThat(val, instanceOf(Number.class));
				assertEquals(0, ((Number) val).longValue());
			}, RUN_TIMEOUT_MS, RETRY_MS);
		}
	}

	@Test
	public void testOnBreakpointCreated() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			txPut(conn, "breakpoints");
			assertEquals(0,
				tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]").size());

			conn.execute("pc = util.get_pc()");
			conn.execute("util.dbg.bp(expr=pc)");

			waitForPass(() -> {
				List<Object> brks =
					tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]");
				assertEquals(1, brks.size());
			});
		}
	}

	@Test
	public void testOnBreakpointModified() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			txPut(conn, "breakpoints");
			assertEquals(0,
				tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]").size());

			conn.execute("pc = util.get_pc()");
			conn.execute("util.dbg.bp(expr=pc)");

			TraceObject brk = waitForPass(() -> {
				List<Object> brks =
					tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]");
				assertEquals(1, brks.size());
				return (TraceObject) brks.get(0);
			});

			assertEquals(true, tb.objValue(brk, lastSnap(conn), "Enabled"));
			conn.execute("util.dbg.bd(0)");
			assertEquals(false, tb.objValue(brk, lastSnap(conn), "Enabled"));

			/* Not currently enabled
			assertEquals("", tb.objValue(brk, lastSnap(conn), "Command"));
			conn.execute("util.dbg.bp(expr=pc, windbgcmd='bl')");
			assertEquals("bl", tb.objValue(brk, lastSnap(conn), "Command"));
			*/
		}
	}

	@Test
	public void testOnBreakpointDeleted() throws Exception {
		try (PythonAndTrace conn = startAndSyncPython("notepad.exe")) {
			txPut(conn, "breakpoints");
			assertEquals(0,
				tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]").size());

			conn.execute("pc = util.get_pc()");
			conn.execute("util.dbg.bp(expr=pc)");

			TraceObject brk = waitForPass(() -> {
				List<Object> brks =
					tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]");
				assertEquals(1, brks.size());
				return (TraceObject) brks.get(0);
			});
			String id = brk.getCanonicalPath().index();
			assertEquals("0", id);

			// Causes access violation in pybag/comtypes during tear-down
			//conn.execute("util.dbg.bc(%s)".formatted(id));
			conn.execute("util.dbg.cmd('bc %s')".formatted(id));

			waitForPass(() -> assertEquals(0,
				tb.objValues(lastSnap(conn), "Sessions[].Processes[].Debug.Breakpoints[]").size()));
		}
	}

	private void start(PythonAndConnection conn, String obj) {
		conn.execute("from ghidradbg.commands import *");
		if (obj != null)
			conn.execute("ghidra_trace_create('" + obj + "', wait=True)");
		else
			conn.execute("ghidra_trace_create()");
		conn.execute("ghidra_trace_sync_enable()");
	}

	private void txPut(PythonAndTrace conn, String obj) {
		conn.execute("ghidra_trace_txstart('Tx" + obj + "')");
		conn.execute("ghidra_trace_put_" + obj + "()");
		conn.execute("ghidra_trace_txcommit()");
	}

	private long getAddressAtOffset(PythonAndTrace conn, int offset) {
		String inst = "print(util.get_inst(util.get_pc()+" + offset + "))";
		String ret = conn.executeCapture(inst);
		String[] split = ret.split("\\s+");  // get target
		return Long.decode(split[1]);
	}
}