{"id":13796632,"url":"https://github.com/daniel-araujo/proctal","last_synced_at":"2025-12-26T23:57:25.809Z","repository":{"id":102976408,"uuid":"219055610","full_name":"daniel-araujo/proctal","owner":"daniel-araujo","description":"A tool for modding programs on Linux at runtime. Scans memory for values and changes instructions.","archived":false,"fork":false,"pushed_at":"2020-12-20T01:33:11.000Z","size":814,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-02-14T22:33:59.816Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daniel-araujo.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-01T20:11:35.000Z","updated_at":"2024-08-03T23:07:09.895Z","dependencies_parsed_at":null,"dependency_job_id":"ea46386c-0b2c-42ea-bf57-f076197dfcb7","html_url":"https://github.com/daniel-araujo/proctal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-araujo%2Fproctal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-araujo%2Fproctal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-araujo%2Fproctal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daniel-araujo%2Fproctal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daniel-araujo","download_url":"https://codeload.github.com/daniel-araujo/proctal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225159873,"owners_count":17430201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T23:01:12.899Z","updated_at":"2025-12-26T23:57:25.758Z","avatar_url":"https://github.com/daniel-araujo.png","language":"C","funding_links":[],"categories":["CLI Utilities"],"sub_categories":[],"readme":"=========\n Proctal\n=========\n\nhttps://proctal.io\n\nA tool for modding programs on Linux at runtime. Provides a CLI and a C library.\n\n**Features:**\n\n- Reading and writing to memory\n\n- Searching for values and byte patterns\n\n- Pausing program execution\n\n- Watching for accesses to memory locations\n\n- Allocating and deallocating memory blocks\n\n- Assembling and disassembling instructions\n\n- Running your own code in the context of the program\n\n- Dumping contents in memory\n\n..\n\n\t**Note**\n\n\tThis is work in progress. It's currently only tested on x86-64 Linux.\n\n\n.. contents::\n\n\nExample\n=======\n\nThis example forces a program — whose Process ID (PID) is 15433 — to print\nHello, world!\n\n\t**Note**\n\n\tAccessing sensitive parts of other processes most likely requires you\n\tto have higher privileges. Try running as root.\n\n**CLI**\n\n.. code :: sh\n\n\t# Allocates memory to store Hello, world!\n\t$ proctal allocate --pid=15433 -rw 14\n\t7F78FDA9C000\n\n\t# Writes Hello, world! to memory.\n\t$ proctal write --pid=15433 --address=7F78FDA9C000 --type=text 'Hello, world!' $'\\n'\n\n\t# Executes code that will print Hello, world! to standard output.\n\t$ proctal execute --pid=15433\n\t\tmov\trsi, 0x7F78FDA9C000\n\t\tmov\trdx, 14\n\t\tmov\trdi, 1\n\t\tmov\trax, 1\n\t\tsyscall\n\n\t# Deallocates memory that was used to store Hello, world!\n\t$ proctal deallocate --pid=15433 7F78FDA9C000\n\n**API**\n\n.. code :: C\n\n\t#include \u003cstdlib.h\u003e\n\t#include \u003cstdint.h\u003e\n\t#include \u003cstdio.h\u003e\n\n\t#include \u003cproctal.h\u003e\n\n\tint main (int argc, char **argv)\n\t{\n\t\tconst char output[] = \"Hello, world!\\n\";\n\t\tchar code[] = {\n\t\t\t// mov rsi, \u003caddress\u003e\n\t\t\t0x48, 0xbe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\n\t\t\t// mov rax, 1\n\t\t\t0x48, 0xc7, 0xc0, 0x01, 0x00, 0x00, 0x00,\n\t\t\t// mov rdx, 14\n\t\t\t0x48, 0xc7, 0xc2, 0x0e, 0x00, 0x00, 0x00,\n\t\t\t// mov rdi, 1\n\t\t\t0x48, 0xc7, 0xc7, 0x01, 0x00, 0x00, 0x00,\n\t\t\t// syscall\n\t\t\t0x0f, 0x05\n\t\t};\n\n\t\tproctal_t proctal = proctal_open();\n\n\t\tif (proctal_error(proctal)) {\n\t\t\tfprintf(stderr, \"Failed to open Proctal.\\n\");\n\t\t\tproctal_close(proctal);\n\t\t\treturn EXIT_FAILURE;\n\t\t}\n\n\t\tproctal_pid_set(proctal, 15433);\n\n\t\tvoid *allocated_memory = proctal_allocate(proctal, sizeof output);\n\n\t\tif (proctal_error(proctal)) {\n\t\t\tfprintf(stderr, \"Failed to allocate memory in process %d.\\n\", proctal_pid(proctal));\n\t\t\tproctal_close(proctal);\n\t\t\treturn EXIT_FAILURE;\n\t\t}\n\n\t\tproctal_write(proctal, allocated_memory, output, sizeof output);\n\n\t\tif (proctal_error(proctal)) {\n\t\t\tfprintf(stderr, \"Failed to write to memory in process %d.\\n\", proctal_pid(proctal));\n\t\t\tproctal_deallocate(proctal, allocated_memory);\n\t\t\tproctal_close(proctal);\n\t\t\treturn EXIT_FAILURE;\n\t\t}\n\n\t\tcode[2] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 0 \u0026 0xFF);\n\t\tcode[3] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 1 \u0026 0xFF);\n\t\tcode[4] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 2 \u0026 0xFF);\n\t\tcode[5] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 3 \u0026 0xFF);\n\t\tcode[6] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 4 \u0026 0xFF);\n\t\tcode[7] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 5 \u0026 0xFF);\n\t\tcode[8] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 6 \u0026 0xFF);\n\t\tcode[9] = (char) ((uintptr_t) allocated_memory \u003e\u003e 8 * 7 \u0026 0xFF);\n\n\t\tproctal_execute(proctal, code, sizeof code);\n\n\t\tif (proctal_error(proctal)) {\n\t\t\tfprintf(stderr, \"Failed to execute code in process %d.\\n\", proctal_pid(proctal));\n\t\t\tproctal_deallocate(proctal, allocated_memory);\n\t\t\tproctal_close(proctal);\n\t\t\treturn EXIT_FAILURE;\n\t\t}\n\n\t\tproctal_deallocate(proctal, allocated_memory);\n\t\tproctal_close(proctal);\n\t\treturn EXIT_SUCCESS;\n\t}\n\n\nInstallation\n============\n\nYou need to have the following programs installed on your system:\n\n- GCC_\n- CMake_\n- sed_\n- m4_\n- php_\n\nOptionally:\n\n- Capstone_ - For disassembling instructions.\n- Keystone_ - For assembling instructions.\n\nThen run:\n\n.. code :: sh\n\n\t$ mkdir build\n\n\t$ cmake -DCMAKE_BUILD_TYPE=Release ..\n\n\t$ make\n\n\t$ make install\n\n\nUsage\n=====\n\n**CLI**\n\nThe command line tool is a program called ``proctal`` that takes commands, like\nso:\n\n.. code :: sh\n\n\t$ proctal COMMAND\n\nIf you execute ``proctal`` without a command, or pass it the ``-h`` option, it\nwill print help information which includes a list of all available commands.\n\nCommands can also take options. Every command recognizes the ``-h`` option,\nwhich will make it print help information related to it and then exit without\ndoing anything else.\n\nFor a complete overview of the functionality provided by the tool, you can read\nthe man page by running the following command:\n\n.. code :: sh\n\n\t$ man 1 proctal\n\n**API**\n\nThe C library can be used by linking to ``libproctal.so`` or ``libproctal.a``\nand including ``proctal.h``.\n\nThe header file contains comments that explain how functions and macros are\nmeant to be used.\n\n\nDocumentation\n=============\n\nYou will find a complete guide with examples and tutorials at `proctal.io\n\u003cDocumentation_\u003e`_. \n\n\nDevelopment\n===========\n\nProctal uses CMake_ to generate a suitable build system for your operating\nsystem. This section will not go into too much detail about that but will show\nyou what you need to get started.\n\nYou must have the following programs installed on your system:\n\n- Git_\n- GCC_\n- CMake_\n- sed_\n- m4_\n- php_\n- Python_\n\nHere's how you create a debug build of the latest version:\n\n.. code :: sh\n\n\t$ git clone https://github.com/daniel-araujo/proctal\n\n\t$ cd proctal\n\n\t$ mkdir -p build\n\n\t$ cd build\n\n\t$ cmake -DCMAKE_BUILD_TYPE=Debug ..\n\n\t$ make\n\nIf you modify a source file and run ``make`` again it will detect the change and\ncompile again.\n\nLibraries are automatically downloaded and installed locally in the project.\n\nYou can also run the test suite with ``ctest``.\n\n.. code :: sh\n\n\t$ ctest\n\nBeware that some test cases require higher privileges, which means that you will\nmost likely have to run that command as root in order for all tests to pass.\n\n\nContributing\n============\n\nFound a bug or want to contribute code? Feel free to create an issue or send a\npull request on GitHub_.\n\nBy submitting code as an individual you agree to the Individual Contributor\nLicense Agreement. By submitting code as an entity you agree to the Entity\nContributor License Agreement. Read the CONTRIBUTING file for more details.\n\nYou can also report bugs to bugs@proctal.io.\n\n\nCopying\n=======\n\nThis program is free software: you can redistribute it and/or modify it under\nthe terms of the GNU General Public License as published by the Free Software\nFoundation, either version 3 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT\nANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS\nFOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nA copy of the GNU General Public License is distributed in a file named\nCOPYING. If not, see `GNU licenses`_.\n\n\n.. References\n\n.. _Documentation: https://proctal.io/documentation\n.. _Download: https://proctal.io/download\n.. _`GNU software`: https://www.gnu.org/software/\n.. _`GNU licenses`: http://www.gnu.org/licenses/\n.. _GitHub: https://github.com/daniel-araujo/proctal\n.. _Capstone: http://www.capstone-engine.org/\n.. _Keystone: http://www.keystone-engine.org/\n.. _PHP: http://php.net/\n.. _CMake: https://cmake.org/cmake/help/v3.14/\n.. _GCC: https://gcc.gnu.org/\n.. _sed: https://www.gnu.org/software/sed/\n.. _m4: https://www.gnu.org/software/m4/\n.. _Python: https://www.python.org/\n.. _Git: https://git-scm.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-araujo%2Fproctal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-araujo%2Fproctal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-araujo%2Fproctal/lists"}