bytepatch
A Haskell library and CLI tool for writing declarative patches over streams.
Write patchscripts (in-place edits to a file) using a configurable YAML
schema, and apply them with a safe patching algorithm. On the library side,
define patches of various forms over any type, apply them to pure/impure
streams, and write further patch data types and streams to extend as you like.
bytepatch works with many data types:
- read pretty binary
00 FF 1234, parse to bytes
- read text, re-encode, null-terminate to generate a C-style string
- read assembly, assemble down to machine code
The schema itself is highly configurable:
- align: add a value (set in patch file) to each patch offset
- compare: bytepatch can check expected data against actual during patching,
to assert that you're patching the expected file. You can select how this
check works: compare equality (exact, or match prefix), hashes
- seek type: what the patch offsets mean. You'll likely want absolute
offsets - but you may also write them as linear offsets, forward from the
previous.
You may also ask bytepatch to compile a patchscript, which reads it and then
outputs a YAML file with a simplified schema: pre-aligned, compare via hashes,
forward seeks.
The bytepatch executable aims to be a general tool for reverse engineers, hoping
to make simple binary & assembly editing more manageable. The Haskell library is
quite sprawling, and has personally made for a fun investigation into type-level
Haskell.
What?
If you're modifying binaries, you often end up needing to make edits in a hex
editor. This is fun for a very short while, then you realise how easy it is to
mess up.
bytepatch is primarily intended as a developer tool for writing a
human-friendly static patchscript. It provides a nice schema for defining
edits to a binary file, so that developers can read and write patches in a
structured, readable format. If one wanted, they could very easily read the
patch file and use it to make the changes manually (though bytepatch wants to do
this for you).
bytepatch is not aimed at replacing binary patch tools such as IPS, BPS: these
take an input and a result file, and generate a patch file that can be applied
to the input in order to recreate the result. You need the result file in the
first place. These tools both generate the patch file and apply it; bytepatch
only applies the patch file, and leaves the writing to the user.
When might I want to use this?
You might find bytepatch useful if you want to define edits to be made on binary
files (especially executables) that are static and in-place. Examples are:
- instruction patching (via assembly)
- string patching (via text)
Less relevant use cases
You can't use bytepatch directly for edits which are dynamic in nature (e.g.
you need to read a file header in order to know what to change). (You could
have a patch preparer that does the dynamic work and emits a bytepatch patch,
but this tool is largely focused the patch representation, so you wouldn't be
gaining much.)
You can't use bytepatch to make edits that aren't in-place. Edits are located
using stream offsets. Allowing edits to change the length of the segment they
replace would introduce issues for following edits: do we use the original
offset, or do we implicitly shift them so they still write to the "same place"?
There is some support in the library for such edits, however, and it would be
interesting to explore.
License
Provided under the MIT license. Please see LICENSE for the full license text.
