# BREWasm
BREWasm: A general purpose static binary rewriting framework for Wasm, which aims at reducing the complexity of the Wasm
binary format.
## Features
BREWasm consists of four key components: the Wasm Parser, section rewriter, semantics rewriter, and Wasm Encoder. The
Wasm parser and encoder are built using our abstraction of the Wasm binary, which is represented as a formal format
comprising a list of objects. The parser and encoder effectively convert the Wasm binary and an array of objects into
each other, with each object containing multiple attributes.
<div align=center>
<img src="doc/Definition.png" width="600">
<div style="margin-top: 10px; margin-bottom: 10px">
<b>Formal definition of sections, elements and fields in Wasm.</b>
</div>
</div>
- The section rewriter directly interacts with the formal definition, e.g., inserting/deleting a new object or modifying
attributes of existing objects. It packs these fine-grained rewriting functions into APIs.
- The semantics rewriter further combines the fine-grained APIs of section rewriter and offers another set of high-level
APIs, where each of them possesses rich semantics as following, like inserting a function, and append a piece of
linear memory.
- Global Variables
- Import & Export
- Linear Memory
- Function
- Custom Content
## Installation
### Python package
BREWasm is currently available on PIP repositories.
Install BREWasm::
```
pip install BREWasm
```
## Examples
### Section Rewriter
The basic operation of the section rewriter is `select`, `insert`, `update` and `delete`.
```python
from BREWasm import *
binary = BREWasm('a.wasm') # Open a Wasm binary file
# Initialize a section rewriter of the global section.
global_rewriter = SectionRewriter(binary.module, globalsec=binary.module.global_sec)
# Select all the items in global section
global_list = global_rewriter.select(Global())
# Get the attribute globalidx of a global item, whose index is one.
idx = global_list[1].globalidx
# Insert a new global item at the index idx of the global section
global_rewriter.insert(Global(idx), Global(valtype=I32, val=100))
# Delete the global item whose index is idx.
global_rewriter.delete(Global(idx))
# Emit a new binary file
binary.emit_binary('b.wasm')
```
### Semantics Rewriter
```python
from BREWasm import *
binary = BREWasm('a.wasm') # Open a Wasm binary file
# Initialize a semantics rewriter of the function semantics
function_rewriter = SemanticsRewriter.Function(binary.module)
# Define the instructions of function
func_body = [Instruction(LocalGet, 0), Instruction(LocalGet, 1), Instruction(I32Add, 0), Instruction(Nop)]
# Insert a internal function in the binary
function_rewriter.insert_internal_function(idx=1, params_type=[I32, I32], results_type=[I32], local_vec=[Local(0, I32), Local(1, I64)], func_body=func_body)
# Emit a new binary file
binary.emit_binary('b.wasm')
```
## Documentation
The complete documentation can be found [here](https://brewasm-project.readthedocs.io/en/latest/).
## Publications
Our work is accepted by SAS 2023. If you have used BREWasm in academic work, please cite our work by:
```
@article{cao2023general,
title={A General Static Binary Rewriting Framework for WebAssembly},
author={Cao, Shangtong and He, Ningyu and Guo, Yao and Wang, Haoyu},
journal={arXiv preprint arXiv:2305.01454},
year={2023}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/BREWasm/brewasm-project",
"name": "BREWasm",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "BINARY,REWRITER,WASM",
"author": "BREWasm",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/ad/37/4f057385640e841a8dfbbbd2be5b7222711a0909ae4277c0bb5005a47a01/BREWasm-1.0.8.tar.gz",
"platform": null,
"description": "\ufeff# BREWasm\n\nBREWasm: A general purpose static binary rewriting framework for Wasm, which aims at reducing the complexity of the Wasm\nbinary format.\n\n## Features\n\nBREWasm consists of four key components: the Wasm Parser, section rewriter, semantics rewriter, and Wasm Encoder. The\nWasm parser and encoder are built using our abstraction of the Wasm binary, which is represented as a formal format\ncomprising a list of objects. The parser and encoder effectively convert the Wasm binary and an array of objects into\neach other, with each object containing multiple attributes.\n\n<div align=center>\n<img src=\"doc/Definition.png\" width=\"600\">\n <div style=\"margin-top: 10px; margin-bottom: 10px\">\n <b>Formal definition of sections, elements and fields in Wasm.</b>\n </div>\n</div> \n\n- The section rewriter directly interacts with the formal definition, e.g., inserting/deleting a new object or modifying\n attributes of existing objects. It packs these fine-grained rewriting functions into APIs.\n- The semantics rewriter further combines the fine-grained APIs of section rewriter and offers another set of high-level\n APIs, where each of them possesses rich semantics as following, like inserting a function, and append a piece of\n linear memory.\n - Global Variables\n - Import & Export\n - Linear Memory\n - Function\n - Custom Content\n\n## Installation\n\n### Python package\n\nBREWasm is currently available on PIP repositories.\n\nInstall BREWasm::\n\n```\npip install BREWasm\n```\n\n\n## Examples\n\n### Section Rewriter\n\nThe basic operation of the section rewriter is `select`, `insert`, `update` and `delete`.\n\n```python\nfrom BREWasm import *\n\nbinary = BREWasm('a.wasm') # Open a Wasm binary file\n\n# Initialize a section rewriter of the global section. \nglobal_rewriter = SectionRewriter(binary.module, globalsec=binary.module.global_sec)\n\n# Select all the items in global section\nglobal_list = global_rewriter.select(Global())\n# Get the attribute globalidx of a global item, whose index is one.\nidx = global_list[1].globalidx\n# Insert a new global item at the index idx of the global section\nglobal_rewriter.insert(Global(idx), Global(valtype=I32, val=100))\n# Delete the global item whose index is idx.\nglobal_rewriter.delete(Global(idx))\n# Emit a new binary file\nbinary.emit_binary('b.wasm')\n```\n\n### Semantics Rewriter\n\n```python\nfrom BREWasm import *\n\nbinary = BREWasm('a.wasm') # Open a Wasm binary file\n\n# Initialize a semantics rewriter of the function semantics\nfunction_rewriter = SemanticsRewriter.Function(binary.module)\n# Define the instructions of function\nfunc_body = [Instruction(LocalGet, 0), Instruction(LocalGet, 1), Instruction(I32Add, 0), Instruction(Nop)]\n# Insert a internal function in the binary\nfunction_rewriter.insert_internal_function(idx=1, params_type=[I32, I32], results_type=[I32], local_vec=[Local(0, I32), Local(1, I64)], func_body=func_body)\n# Emit a new binary file\nbinary.emit_binary('b.wasm')\n```\n\n## Documentation\n\nThe complete documentation can be found [here](https://brewasm-project.readthedocs.io/en/latest/).\n\n## Publications\n\nOur work is accepted by SAS 2023. If you have used BREWasm in academic work, please cite our work by:\n```\n@article{cao2023general,\n title={A General Static Binary Rewriting Framework for WebAssembly},\n author={Cao, Shangtong and He, Ningyu and Guo, Yao and Wang, Haoyu},\n journal={arXiv preprint arXiv:2305.01454},\n year={2023}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A general purpose static binary rewriting framework for Wasm, which aims at reducing the complexity of the Wasm",
"version": "1.0.8",
"project_urls": {
"Homepage": "https://github.com/BREWasm/brewasm-project"
},
"split_keywords": [
"binary",
"rewriter",
"wasm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad374f057385640e841a8dfbbbd2be5b7222711a0909ae4277c0bb5005a47a01",
"md5": "ee9b9f8f3e70e1f50cdc4a9a651f643a",
"sha256": "54e6e6cd505b9841db309f945da9588567672d8fd942b6e2f82ec46d2b9088a8"
},
"downloads": -1,
"filename": "BREWasm-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "ee9b9f8f3e70e1f50cdc4a9a651f643a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 154066,
"upload_time": "2024-01-16T03:17:09",
"upload_time_iso_8601": "2024-01-16T03:17:09.209385Z",
"url": "https://files.pythonhosted.org/packages/ad/37/4f057385640e841a8dfbbbd2be5b7222711a0909ae4277c0bb5005a47a01/BREWasm-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-16 03:17:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BREWasm",
"github_project": "brewasm-project",
"github_not_found": true,
"lcname": "brewasm"
}
JSON
