1# postject 2 3[](https://dl.circleci.com/status-badge/redirect/gh/postmanlabs/postject/tree/main) 4[](https://npmjs.org/package/postject) 5 6Easily inject arbitrary read-only resources into executable formats 7(Mach-O, PE, ELF) and use it at runtime. 8 9## Install 10 11```sh 12npm i -g postject 13``` 14 15## Usage 16 17### Command line utility 18 19```sh 20$ postject -h 21Usage: postject [options] <filename> <resource_name> <resource> 22 23Inject arbitrary read-only resources into an executable for use at runtime 24 25Arguments: 26 filename The executable to inject into 27 resource_name The resource name to use (section name on Mach-O and ELF, resource name for PE) 28 resource The resource to inject 29 30Options: 31 --macho-segment-name <segment_name> Name for the Mach-O segment (default: "__POSTJECT") 32 --output-api-header Output the API header to stdout 33 --overwrite Overwrite the resource if it already exists 34 -h, --help display help for command 35``` 36 37### Using Programatically 38 39```js 40const { inject } = require('postject'); 41 42await inject('a.out', 'lol', Buffer.from('Hello, world!')); 43``` 44 45## Building 46 47### Prerequisites 48 49* CMake 50* Ninja 51* [Emscripten (emsdk)](https://emscripten.org/docs/getting_started/downloads.html) 52 53### Build Command 54 55```sh 56$ npm run build 57``` 58 59The final output is placed in `dist/`, with `main.js` being the 60entrypoint. 61 62### Testing 63 64```sh 65$ npm test 66``` 67 68## Design 69 70To ensure maximum capatibility and head off unforeseen issues, the 71implementation for each format tries to use that format's standard 72practices for embedding binary data. As such, it should be possible 73to embed the binary data at build-time as well. The CLI provides the 74ability to inject the resources into pre-built executables, with the 75goal that the end result should be as close as possible to what is 76obtained by embedding them at build-time. 77 78Note: Other runtime injection implementers should search the binary 79compiled with `postject-api.h` for the 80`POSTJECT_SENTINEL_fce680ab2cc467b6e072b8b5df1996b2:0` fuse and 81flip the last character to `1` to indicate that a resource has been 82injected. A different fuse can also be used by defining the 83`POSTJECT_SENTINEL_FUSE` macro before including `postject-api.h` and 84passing the same string to postject with 85`--sentinel-fuse <sentinel_fuse>`. 86 87### Windows 88 89For PE executables, the resources are added into the `.rsrc` section, 90with the `RT_RCDATA` (raw data) type. 91 92The build-time equivalent is adding the binary data as a resource in 93the usual manner, such as the Resource Compiler, and marking it as 94`RT_RCDATA`. 95 96The run-time lookup uses the `FindResource` and `LoadResource` APIs. 97 98### macOS 99 100For Mach-O executables, the resources are added as sections inside a 101new segment. 102 103The build-time equivalent of embedding binary data with this approach 104uses a linker flag: `-sectcreate,__FOO,__foo,content.txt` 105 106The run-time lookup uses APIs from `<mach-o/getsect.h>`. 107 108### Linux 109 110For ELF executables, the resources are added as notes. 111 112The build-time equivalent is to use a linker script. 113
){kind=link}
){kind=link}