Overview

With text commands you can read, write and search for values, allocate memory, execute code, pause execution, dump memory and watch for memory accesses in programs that are running on your system.

• What it looks like
• Why use this
• Example

What it looks like

The proctal program accepts a set of commands that perform actions. Each command accepts a set of options and may require a set number of arguments.
Options are prefixed with -- (two dashes). This allows the program to distinguish them from positional arguments. Unlike positional arguments, options can be passed in any order.
The --help option is accepted by all commands. It will make the program print help information related to the command and exit without doing anything else.

$ proctal read --help
$ proctal write --help

Options may also take a value. The = (equals sign) is placed between the name of the option and the value.

$ proctal read --pid=12345 --address=ff00

Positional arguments come after the options.

$ proctal write --pid=12345 --address=ff00 1

If a positional argument starts with --, it will be mistaken for an option. You can pass -- as an argument to tell the program that any arguments coming after it should not be interpreted as options.

$ proctal write --pid=12345 --address=ff00 --type=text -- --text-that-starts-with-two-dashes

Why use this

The command line interface provides a simple way to introspect a program without attaching a dedicated debugger or using an integrated development environment.
This makes it easily scriptable.

Example

This is a bash script that can make a program print Hello, world!.

#!/usr/bin/env bash

set -e

pid="$1"

if [[ -z "$pid" ]]; then
	echo "Usage: $0 PID" 1>&2
	exit 1
fi

# Allocates memory to store Hello, world!
address="$(proctal allocate --pid="$pid" -rw 14)"

# Writes Hello, world! to memory.
proctal write --pid="$pid" --address="$address" --type=text 'Hello, world!' $'\n'

# Executes code that will print Hello, world! to standard output.
proctal execute --pid="$pid" <<EOD
	mov	rsi, 0x$address
	mov	rax, 1
	mov	rdi, 1
	mov	rdx, 14
	syscall
EOD

# Deallocates memory that was used to store Hello, world!
proctal deallocate --pid="$pid" "$address"