Proctal – Tool that Manipulates Address Space PID

by

Proctal 0.0.0

Proctal provides a command line interface and a C library to manipulate the address space of a running program on Linux. It can be used like a process memory editor or to provide the base functionality for building one that is domain-specific.

Currently only tested on x86-64 Linux.

Note: This is work in progress and as such the API is unstable and the documentation is done as an afterthought. This will change as the project matures.

DOWNLOAD Proctal

[sociallocker id=”968″]https://github.com/daniel-araujo/proctal[/sociallocker]

Features:

  • Reading and writing values in memory
  • Searching for values with a vast combination of filters
  • Writing a value to memory repeatedly fast, essentially freezing it
  • Temporarily freezing execution of a program’s main thread
  • Read, write and execution watch points on the main thread
  • Disassembling instructions from any memory location
  • Assembling instructions to write to any memory location

Planned:

  • Arbitrary instruction execution
  • Byte pattern search
  • Allocating and deallocating readable/writable/executable address spaces
  • Freezing all threads of execution
  • Watch points on all threads of execution

Example

CLI

Assuming 22002 is a Process ID (PID):

$ proctal search --pid=22002 > result

$ cat result
9a3654 40
acfa08 109
acfe90 394
b683f8 1055
b7d178 56
b84ab0 192
ba2e38 1264
[...]

$ wc -l result
1634

$ proctal search --pid=22002 --gt=31 --lt=110 -i < result
9a3654 40
acfa08 109
b7d178 56

$ proctal write --pid=22002 --address=b7d178 124

$ proctal read --pid=22002 --address=b7d178
124

C library

A program that takes a Process ID (PID) and an address to an integer value as arguments and reads the value then increments by 1 each time it’s run.

#include <stdio.h>
#include <sys/types.h>

// Declares proctal's functions.
#include <proctal.h>

int main (int argc, char **argv)
{
	if (argc == 1) {
		printf("Usage: %s <pid> <address>\n", argv[0]);
		return 0;
	} else if (argc != 3) {
		fprintf(stderr, "Incorrect number of arguments.\n");
		return 1;
	}

	pid_t pid;

	if (sscanf(argv[1], "%d", &pid) != 1) {
		fprintf(stderr, "Failed to parse process id.\n");
		return 1;
	}

	void *addr;

	if (sscanf(argv[2], "%lx", (unsigned long *) &addr) != 1) {
		fprintf(stderr, "Failed to parse address.\n");
		return 1;
	}

	proctal p = proctal_create();
	proctal_set_pid(p, pid);

	int read;

	// Attempts to read an int from an other process. May fail if
	// your program does not have permission to access the address
	// space of other processes.
	if (proctal_read_int(p, addr, &read) != 1) {
		fprintf(stderr, "Failed to read from %p of process %d.\n", addr, pid);
		return 1;
	}

	printf("Read %d from address %p of process %d.\n", read, addr, pid);

	// Just going to increment the read value.
	int write = read + 1;

	// Attempts to write an int to an other process. May fail if
	// your program does not have permission to access the address
	// space of other processes.
	if (proctal_write_int(p, addr, write) != 1) {
		fprintf(stderr, "Failed to write to %p of process %d.\n", addr, pid);
		return 1;
	}

	printf("Written %d to address %p of process %d.\n", write, addr, pid);

	return 0;
}

Usage

CLI

The command line interface can be used in the following ways:

proctal read [--type=<type>] --pid=<pid> --address=<address>

proctal write [--type=<type>] --pid=<pid> --address=<address> <value>

proctal search [--type=<type>] [--eq=<val>] [--gt=<val>] [--gte=<val>]
	[--lt=<val>] [--lte=<val>] [--inc=<val>] [--dec=<val>]
	[--changed] [--unchanged] [--increased] [--decreased]
	[--input] --pid=<pid> --address=<address>

proctal watch [--read] [--write] [--execute] --pid=<pid>
	--address=<address>

proctal freeze [--input] --pid=<pid>

For more details run proctal -h or read the man page:

man 1 proctal

C library

Can be used by linking to libproctal and including proctal.h

Functions, types and constants are documented in the header file.

Installation

Proctal provides a 3 step installation process employed by many C/C++ programs on Linux:

$ ./configure

$ make

$ make install

The configure script allows you to define how you want Proctal to be compiled and installed. For more information type ./configure -h.

Development

Proctal uses the autotools to generate build systems for UNIX like operating systems. I will provide instructions on how to get you quickly started to generate a development build.

To get the autotools ready for use, you will need to run autoreconf with the -i option:

$ autoreconf -i

You will notice that now there are new files and directories in the project. These were generated by autoreconf and can be ignored.

With the tools ready to use, you can now generate a build. I recommend using different build directories for different purposes. Here’s how you can create a build that suppresses optimizations and adds debugging symbols:

$ mkdir -p build/debug

$ cd build/debug

$ ../../configure 'CFLAGS=-g -O0'

So with a build system in place, you can now start compiling by running the make command in your build directory:

$ make

If you modify a source file and run make again it should detect the change and recompile again.

For tinkering with the source code this is the least you need to know about the build system. For more details on what you can do with the autotools read the manuals over at gnu.org [1].

Contributing

Found a bug or want to contribute code? Feel free to create an issue or send a pull request on GitHub [2].

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.