Checking the Target

First, we will do some validation. Check that we have an active session (trace):

Trace trace = getCurrentTrace();
if (trace == null) {
    throw new AssertionError("There is no active session");
}

Now, check that the current program is termmines:

if (!"termmines".equals(currentProgram.getName())) {
    throw new AssertionError("The current program must be termmines");
}

Checking the Module Map

Now, check that termmines is actually part of the current trace. There is not a great way to do this directly in the flat API, but we are going to need to map some symbols from the termmines module, anyway. In this step, we will both verify that the user has placed the required labels, as well as verify that those symbols can be mapped to the target:

List<Symbol> widthSyms = getSymbols("width", null);
if (widthSyms.isEmpty()) {
    throw new AssertionError("Symbol 'width' is required");
}
List<Symbol> heightSyms = getSymbols("height", null);
if (heightSyms.isEmpty()) {
    throw new AssertionError("Symbol 'height' is required");
}
List<Symbol> cellsSyms = getSymbols("cells", null);
if (cellsSyms.isEmpty()) {
    throw new AssertionError("Symbol 'cells' is required");
}

Address widthDyn = translateStaticToDynamic(widthSyms.get(0).getAddress());
if (widthDyn == null) {
    throw new AssertionError("Symbol 'width' is not mapped to target");
}
Address heightDyn = translateStaticToDynamic(heightSyms.get(0).getAddress());
if (heightDyn == null) {
    throw new AssertionError("Symbol 'height' is not mapped to target");
}
Address cellsDyn = translateStaticToDynamic(cellsSyms.get(0).getAddress());
if (cellsDyn == null) {
    throw new AssertionError("Symbol 'cells' is not mapped to target");
}

The getSymbols() method is part of the static flat API, so it returns symbols from the current static listing. The translateStaticToDynamic() is part of the dynamic flat API. This allows us to locate that symbol in the dynamic context.

Reading the Data

Now, we want to read the dimensions and the whole board from the target. You should know from earlier exercises that the board is allocated 32 cells by 32 cells, so we will want to read at least 1024 bytes. Note that this will implicitly capture the board to the trace:

byte[] widthDat = readMemory(widthDyn, 4, monitor);
byte[] heightDat = readMemory(heightDyn, 4, monitor);
byte[] cellsData = readMemory(cellsDyn, 1024, monitor);

Dumping the Board

Beyond this, everything is pretty standard Java / Ghidra scripting. We will need to do some quick conversion of the bytes to integers, and then we can iterate over the cells and print the mines’ locations:

int width = ByteBuffer.wrap(widthDat).order(ByteOrder.LITTLE_ENDIAN).getInt();
int height = ByteBuffer.wrap(heightDat).order(ByteOrder.LITTLE_ENDIAN).getInt();
for (int y = 0; y < height; y++) {
    for (int x = 0; x < width; x++) {
        if ((cellsData[(y + 1) * 32 + x + 1] & 0x80) == 0x80) {
            println("Mine at (%d,%d)".formatted(x, y));
        }
    }
}

Test the Script

To test, launch termmines in Ghidra using GDB. You will need to allow it to set up the first game board before running the script. The simplest way to do that is to resume and then interrupt the target while it waits for input. Now, run the script and examine its output. Resume and play the game. Once you win, check that the script output describes the actual board.

Exercise: Remove the Mines

Write a script that will remove the mines from the board. NOTE: The writeMemory() and related methods are all subject to the current Control Mode. If the mode is read-only, the script cannot modify the target’s machine state using those methods.

Exercise: Always Win in 0 Seconds

NOTE: The solution to this exercise is given as a tutorial below, but give it an honest try before peeking. If you are not already familiar with Eclipse’s searching and discovery features, try pressing CTRL-O twice in the editor for your script. You should now be able to type patterns, optionally with wildcards, to help you find applicable methods.

Your task is to write a script that will wait for the player to win then patch the machine state, so that the game always prints a score of 0 seconds. Some gotchas to consider up front:

• You may want to verify and/or correct the target’s execution state. See getExecutionState() and interrupt(). You will not likely be able to place or toggle breakpoints while the target is running.
• Methods like writeMemory() are subject to the current Control Mode. You may want to check and/or correct this at the top of your script.
• If you require the user to mark code locations with a label, note that those labels will likely end up in the containing function’s namespace. You will need to provide that namespace to getSymbols().
• If you need to set breakpoints, you should try to toggle an existing breakpoint at that location before adding a new one. Otherwise, you may generate a pile of breakpoints and/or needlessly increment GDB’s breakpoint numbers.

You are successful when you can attach to a running termmines and execute your script. Then, assuming you win the game, the game should award you a score of 0 seconds. It is okay if you have to re-execute your script after each win.

Solution: Always Win in 0 Seconds

As in the previous script, we will do some verifications at the top of the script. Your level of pedantry may vary.

Trace trace = getCurrentTrace();
if (trace == null) {
    throw new AssertionError("There is no active session");
}

if (!"termmines".equals(currentProgram.getName())) {
    throw new AssertionError("The current program must be termmines");
}

if (getExecutionState(trace).isRunning()) {
    monitor.setMessage("Interrupting target and waiting for STOPPED");
    interrupt();
    waitForBreak(3, TimeUnit.SECONDS);
}
flushAsyncPipelines(trace);

if (!getControlService().getCurrentMode(trace).canEdit(getCurrentDebuggerCoordinates())) {
    throw new AssertionError("Current control mode is read-only");
}

The first two blocks check that there is an active target with termmines as the current program. As before, the association of the current program to the current target will be implicitly verified when we map symbols. The second block will interrupt the target if it is running. We then allow everything to sync up before checking the control mode. We could instead change the control mode to Control Target (with edits), but I prefer to keep the user aware that the script needs to modify target machine state.

Next, we retrieve and map our symbols. This works pretty much the same as in the previous script, but with attention to the containing function namespace. The way termmines computes the score is to record the start time of the game. Then, when the player wins, it subtracts the recorded time from the current time. This script requires the user to label the start time variable timer, and to label the instruction that computes the score reset_timer. The function that prints the score must be named print_win.

List<Symbol> timerSyms = getSymbols("timer", null);
if (timerSyms.isEmpty()) {
    throw new AssertionError("Symbol 'timer' is required");
}
List<Function> winFuncs = getGlobalFunctions("print_win");
if (winFuncs.isEmpty()) {
    throw new AssertionError("Function 'print_win' is required");
}
List<Symbol> resetSyms = getSymbols("reset_timer", winFuncs.get(0));
if (resetSyms.isEmpty()) {
    throw new AssertionError("Symbol 'reset_timer' is required");
}

Address timerDyn = translateStaticToDynamic(timerSyms.get(0).getAddress());
if (timerDyn == null) {
    throw new AssertionError("Symbol 'timer' is not mapped to target");
}
Address resetDyn = translateStaticToDynamic(resetSyms.get(0).getAddress());
if (resetDyn == null) {
    throw new AssertionError("Symbol 'reset_timer' is not mapped to target");
}

ProgramLocation breakLoc =
    new ProgramLocation(currentProgram, resetSyms.get(0).getAddress());
Set<LogicalBreakpoint> breaks = breakpointsEnable(breakLoc);
if (breaks == null || breaks.isEmpty()) {
    breakpointSetSoftwareExecute(breakLoc, "reset timer");
}

while (true) {
    monitor.checkCancelled();

    TargetExecutionState execState = getExecutionState(trace);
    switch (execState) {
        case STOPPED:
            resume();
            break;
        case TERMINATED:
        case INACTIVE:
            throw new AssertionError("Target terminated");
        case ALIVE:
            println(
                "I don't know whether or not the target is running. Please make it RUNNING.");
            break;
        case RUNNING:
            /**
             * Probably timed out waiting for break. That's fine. Give the player time to
             * win.
             */
            break;
        default:
            throw new AssertionError("Unrecognized state: " + execState);
    }
    try {
        monitor.setMessage("Waiting for player to win");
        waitForBreak(1, TimeUnit.SECONDS);
    }
    catch (TimeoutException e) {
        // Give the player time to win.
        continue;
    }
    flushAsyncPipelines(trace);
    Address pc = getProgramCounter();
    println("STOPPED at pc = " + pc);
    if (resetDyn.equals(pc)) {
        break;
    }
}

int time = readRegister("ECX").getUnsignedValue().intValue();
if (!writeMemory(timerDyn,
    ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(time).array())) {
    throw new AssertionError("Could not write over timer. Does control mode allow edits?");
}

resume();