{"id":22165550,"url":"https://github.com/supermarsx/patcherjs","last_synced_at":"2025-08-02T12:09:10.160Z","repository":{"id":184869225,"uuid":"672600744","full_name":"supermarsx/patcherjs","owner":"supermarsx","description":"Atomic Binary Patching Utility and Library for Windows","archived":false,"fork":false,"pushed_at":"2025-07-31T21:17:45.000Z","size":949,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-31T23:58:17.774Z","etag":null,"topics":["application","binary","builder","command-line","filedrop","library","nodejs","patch","patcher","patching","script","typescript","x64dbg"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supermarsx.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","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,"zenodo":null}},"created_at":"2023-07-30T16:25:42.000Z","updated_at":"2025-07-31T21:17:49.000Z","dependencies_parsed_at":"2025-07-21T21:19:01.679Z","dependency_job_id":"28f60ed7-7950-4476-890e-27d629560977","html_url":"https://github.com/supermarsx/patcherjs","commit_stats":null,"previous_names":["whois-team/patcherjs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/supermarsx/patcherjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermarsx%2Fpatcherjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermarsx%2Fpatcherjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermarsx%2Fpatcherjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermarsx%2Fpatcherjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supermarsx","download_url":"https://codeload.github.com/supermarsx/patcherjs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermarsx%2Fpatcherjs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268385861,"owners_count":24242105,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["application","binary","builder","command-line","filedrop","library","nodejs","patch","patcher","patching","script","typescript","x64dbg"],"created_at":"2024-12-02T05:15:13.610Z","updated_at":"2025-08-02T12:09:10.148Z","avatar_url":"https://github.com/supermarsx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# patcherjs\n\nA small TypeScript binary patching utility. Originally built for Windows, it works both as a standalone application or library and will support Linux and macOS.\n\nThis tool/library is intended for patch developers and enthusiasts to streamline patch tool distribution.\n\n![screenshot-patcherjs-min](https://github.com/supermarsx/patcherjs/assets/17675589/4f156087-8a3b-4c53-a692-c249e3155efd)\n\n## Starting up\n\n### As a library\n\nInstall using npm\n```\n$ npm install patcherjs\n```\nSimple running example\n```\nimport { Patcher } from 'patcherjs';\n\nPatcher.runPatcher({});\nPatcher.runPatcher({ configFilePath: './my-config.json', waitForExit: false });\n```\n\n### Use as standalone application or development\n\n#### Capabilities and functions\n\nPatcherjs has 3 main functions on its own:\n- Patching binaries\n- Executing arbitrary commands\n    - Execute any basic command\n    - Executing kill, system service or task scheduler commands\n- Drop files in a directory\n\n#### Get started\n\nDownload from releases or clone the repository\n##### Use binaries from releases\n\n`patcherjs-predist` - Just extract and edit\n`patcherjs-dist` - Open as an archive with 7-zip extract files files and drop inside again\n\n##### Clone the repository\n```\n$ git clone https://github.com/supermarsx/patcherjs\n$ npm install\n$ npm run ts-build\n$ node dist/standalone/executable.js\n$ node dist/standalone/executable.js --config ./my-config.json\n$ node dist/standalone/executable.js -c ./my-config.json\n```\nThe `--config` (or `-c`) option allows you to specify a custom configuration file instead of the default `config.json`. You can also use the form `--config=\u003cpath\u003e`.\n\n#### Running on Linux/macOS\n\nOnce the project adds support for these platforms the steps are the same:\n\n```bash\nnpm run ts-build\nnode dist/standalone/executable.js --config ./my-config.json\nnode dist/standalone/executable.js --config=./my-config.json\n```\nThe build pipeline will skip the signing step on non-Windows systems.\n#### npm scripts\n\nThere are a collection of scripts that are used help manage the build process\n\n`package.json` scripts:\n```\n   \"scriptsComments\": {\n    \"#GENERAL SCRIPTS#\": \"#SECTION#\",\n    \"start\": \"Runs the patcher (executable.js)\",\n    \"#BUILD SCRIPTS#\": \"#SECTION#\",\n    \"ts-build-clean\": \"Typescript clean build to 'dist' folder\",\n    \"ts-build\": \"Typescript build to 'dist' folder\",\n    \"esbuild\": \"ESBuild the standalone executable into a JS file (executable.js) on the 'sea' folder\",\n    \"sea-build\": \"Executes the SEA (single executable application) building script (builder.js) according to nodes sea generation guidelines (needs ts-build to be ran first)\",\n    \"sea-pack\": \"Packs all files in 'patch_files_unpacked' and drops them into 'patch_files' to be used by the patcher\",\n    \"sea-copy\": \"Copies 'config.json', 'patch_files' folder contents and 7zip binaries from node_modules to 'predist' folder (needs npm install to be ran first)\",\n    \"sea-predist\": \"Compresses built SEA file and its additional files into a 7zip archive using predist script (predist.js) (needs ts-build to be ran first)\",\n    \"sea-dist\": \"Creates distribution executable using Node script\",\n    \"sea-dist-prompt\": \"Same as 'sea-dist' but uses the prompt SFX module\",\n    \"sea-build-full\": \"Run full SEA build process including SFX ready for distribution (runs 'ts-build-clean', 'esbuild', 'sea-build', 'sea-copy', 'sea-predist' and 'sea-dist')\",\n    \"sea-build-full-clean\": \"Same as 'sea-build-full' but executes 'sea-cleanup-full' first, serves as a full clean build\",\n    \"sea-cleanup-full\": \"Build Typescript files and fully clean up build space\",\n    \"sea-cleanup\": \"fully clean up build space\",\n    \"sea-copy-config\": \"Copies 'config.json' to 'predist' folder using Node script\",\n    \"sea-copy-patch_files\": \"Copies 'patch_files' folder contents to 'predist' folder using Node script\",\n    \"sea-copy-7z\": \"Copies 7-zip binaries from 'node_modules' to 'predist' folder using Node script\",\n    \"generate-docs\": \"Generates documentation using typedoc to 'docs' folder\"\n  },\n```\n\n#### Running tests\n\nRun the Jest suite with the provided npm script. It builds the TypeScript sources and then executes Jest.\n```sh\nnpm test\n```\n\n#### Example files\n\nThe project comes with an example `.patch` file and a `.dll` file to be packed, these files should be removed and you should add your own files.\n\n#### Build steps\n\nTheres two ways of using patcherjs as an applications, as multi file application which contains a nodejs SEA or a single SFX file.\n\n1. Run the following build script to do a full build\n```\n$ npm run sea-build-full-clean\n```\n2. Grab your file from `sea/dist` folder if you want a single executable otherwise grab all files from `sea/predist` if you prefer a multi file approach.\n\n\u003e **Note**\n\u003e The build pipeline expects a Windows environment and uses `signtool` to remove the signature from the copied Node binary. When running on other platforms this step is skipped and the resulting executable will remain unsigned.\n\n#### Project structure\n\n`Project folder`\n```\n| Project folder\n \\\n  | dist - Compiled Typescript files\n  | docs - Generate typedoc documentation\n  | misc_bin - Miscellaneous binaries, containing signtool that can be installed to %PATH% to be used in the build process\n  | node_modules - Typical node modules folder\n  | patch_files - Contains '.patch' files to be used by the script and packed '.pack' files to be dropped by the script\n  | patch_files_unpacked - Contains all the unpacked files to be packed by patcherjs and dropped into 'patch_files' folder\n  | sea - Contains all the files pertaining to SEA (single executable application) build process\n   \\\n    | sea/dist - Final build step folder which will contain the SEA SFX packed executable ready for distribution\n     \\\n      | patcherjs-min.exe - Built single file executable ready for distribution (unpacks itself and runs patcherjs.exe)\n    | sea/predist - A Intermediate build step folder containing all the working parts of the patcher that can work but is not contained into a SFX file\n     \\\n      | patch_files - Folder copied from root containing all patch files and filedrops\n      | win - Folder containing 7-zip binaries\n      | config.json - Application configuration copied from root\n      | patcherjs.exe - Nodejs SEA containing all the functions necessary to patchers execution (runs executable.ts)\n    | sea/sea-sfx.sfx - 7zip SFX module without prompt\n    | sea/sea-sfx-config.txt - 7zip SFX module script (only necessary for prompt)\n    | sea/sea-sfx-gui.sfx - 7zip SFX module with prompt\n  | source - Folder containing all source files for the project\n   \\\n    | source/buildscripts - Contains all scripts related to the build scripts described in package.json\n    | source/lib - All the source code for the patcher inner workings and its different parts\n     \\\n      | auxiliary - Folder containing all the auxiliary file, debug, uac and useful functions and operations\n      | build - Folder containing all the build, packaging and cleanup functions and routines\n      | commands - Folder containing all the command related functions and routines\n      | configuration - Folder containing all the configuration functions and routines, and also constants\n      | filedrops - Folder containing all the filedrops, encryption and packing functions and routines\n      | patches - Folder containing all the buffer, parser and patches functions and routines\n      | composites.ts - File containing the general 'runPatcher' function and related\n    | source/standalone - Folder containing 'executable.ts' that is used as the patcherjs standalone application\n  | config.json - File containing all the configurations used by patcherjs\n\n```\n\n#### config.json file\nPatcherjs functions with a configuration json file using the following structure, generally the provided default `config.json` are the recommended values but you can set them as preferred and/or needed.\n\n`config.json`\n```\n{\n  \"options\": { // OPTIONS\n    \"general\": { // OPTIONS \u003e GENERAL, General options\n      \"exitOnNonAdmin\": true, // Exit when current running user doesn't have administrative privileges, on `false` will continue\n      \"debug\": true, // Enable debug messages (recommended)\n      \"logging\": false, // Enable logging debug messages to file (untested)\n      \"runningOrder\": [ // An array that defines in which order will the patcher run its commands, commands can be repeated though\n        \"commands\", // Run commands\n        \"filedrops\", // Run filedrops\n        \"patches\" // Run binary patches\n      ],\n      \"commandsOrder\": [ // Within commands you can decide which type of command runs first\n        \"tasks\", // Task scheduler commands\n        \"services\", // System service commands\n        \"kill\",  // Kill commands\n        \"general\" // General arbitrary commands\n      ],\n      \"onlyPackingMode\": false // Use when you want to pack files using the SEA without access to source\n    },\n    \"patches\": { // OPTIONS \u003e PATCHES, Patches related options\n      \"runPatches\": true, // Set to false if you want to skip patches for some reason\n      \"forcePatch\": false, // Set to true if you don't want to check for the current value, bulldozer mode basically\n      \"fileSizeCheck\": true, // Check for file size before running patch\n      \"fileSizeThreshold\": 0, // File size check threshold\n      \"skipWritePatch\": false, // Skip writing patch (mostly for debug purposes, like simulate a patch but not actually patch)\n      \"bigEndian\": false, // Read and write multi-byte values using big-endian\n      \"failOnUnexpectedPreviousValue\": false, // Fail patches if an unexpected previous/current value is found\n      \"warnOnUnexpectedPreviousValue\": true, // Warn/throw a debug message that an unexpected previous/current value was found\n      \"nullPatch\": false, // Just patch the offsets to null (basically 0, mostly useful just for debug)\n      \"unpatchMode\": false, // Reverse previous/current with new value to basically reverse patch a file\n      \"verifyPatch\": true, // Verify patch (not implemented)\n      \"backupFiles\": true, // Create copy with '.bak' extension in the destination directory for every patched file\n      \"skipWritingBinary\": false // Skip writing the patched buffer to file\n    },\n    \"commands\": { // OPTIONS \u003e COMMANDS, Commands related options\n      \"runCommands\": true // Set to false to skip running any commands\n    },\n    \"filedrops\": { // OPTIONS \u003e FILEDROPS, Filedrops related options\n      \"runFiledrops\": true, // Set to false to skip filedrops\n      \"isFiledropPacked\": true, // Is file compressed in a password protected 7zip archive or not compressed at all (affects packing process)\n      \"isFiledropCrypted\": true, // Is file encrypted (affects packing process)\n      \"backupFiles\": true // Backup destination files with '.bak' before replacing them\n    }\n  },\n  \"patches\": [ // A patches array, every object is related to a single '.patch' file\n    {\n      \"name\": \"file.dll patch\", // Patch display name, not important\n      \"patchFilename\": \"file.dll.patch\", // .patch filename\n      \"fileNamePath\": \"${HOME}/Someapp/file.dll\", // File path to patch, using HOME for cross-platform support\n      \"enabled\": true // Is this specific patch enabled, set false to skip\n    }\n  ],\n  \"commands\": { // Contains all the arrays of the different command types\n    \"tasks\": [ // An array of task scheduler related commands\n      {\n        \"name\": \"TestTaskApp-1\", // Task scheduler name\n        \"command\": \"delete\", // Either 'delete' or 'stop' those are the two available options\n        \"enabled\": true // Set false to skip\n      }\n    ],\n    \"kill\": [ // An array of processes to kill\n      {\n        \"name\": \"testapp.exe\", // Name of the process to kill\n        \"enabled\": true // Set false to skip\n      }\n    ],\n    \"services\": [ // An array of system service commands to run\n      {\n        \"name\": \"TestService\", // Name of the service\n        \"command\": \"delete\", // Either 'stop', 'disable' or 'delete' the service\n        \"enabled\": true // Set false to skip\n      }\n    ],\n    \"general\": [ // An array of general commands to run\n      {\n        \"name\": \"echo test\", // Display name\n        \"command\": \"echo \\\"test\\\"\", // Command to run, escape your special characters like backslash and quotes\n        \"enabled\": true // Set false to skip\n      }\n    ]\n  },\n  \"filedrops\": [ // An array of file drops to run\n    {\n      \"name\": \"helloworld.dll\", // Display name\n      \"fileDropName\": \"helloworld.dll.pack\", // Packed filename inside 'patch_files' directory\n      \"packedFileName\": \"helloworld.dll\", // Original filename inside 'patch_files_unpacked' folder\n      \"fileNamePath\": \"${HOME}/Someapp/helloworld.dll\", // Destination filename, using HOME for cross-platform support\n      \"decryptKey\": \"ad4bc8a11481000e4d8daf28412f867a\", // Encryption/decryption password\n      \"enabled\": true // Set to false to skip\n    }\n  ]\n}\n\n```\n## On .patch files\n### .patch file format\n\nA .patch file should follow the following format.\nOffsets may exceed 32-bits and are parsed as BigInt:\n```\n0002EB40: 03 00\n0006AA00: 04 10\n```\nWhen patching binaries that require 64-bit addressing,\nuse 16-digit hexadecimal offsets. For example:\n```\n0000000012345678: 00 ff\n```\n`patcherjs` automatically switches to 64‑bit mode when a\npatch includes an offset longer than eight hex digits or the\ntarget file exceeds the `LARGE_FILE_THRESHOLD` (2\u0026nbsp;GB).\n```\nOFFSET: PREVIOUS_VALUE NEW_VALUE\n```\nThe value fields may contain 2, 4, 8 or 16 hex digits\n(representing 1, 2, 4 or 8 bytes respectively). `patcherjs`\nwill automatically use the correct width when applying\nthe patch.\n### Creating .patch files\n\nYou can create patch files by exporting patches from x64dbg or vbindiff applications.\n\n## Built with\n- NodeJS\n- Typescript\n\n## License\nDistributed under MIT License. See`license.md`for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermarsx%2Fpatcherjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupermarsx%2Fpatcherjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermarsx%2Fpatcherjs/lists"}