{"id":19508052,"url":"https://github.com/jonatanSh/shelf","last_synced_at":"2025-04-26T02:33:46.975Z","repository":{"id":38018562,"uuid":"487273629","full_name":"jonatanSh/shelf","owner":"jonatanSh","description":"Python library to convert elf to os-independent shellcodes","archived":false,"fork":false,"pushed_at":"2023-08-27T17:55:04.000Z","size":1134,"stargazers_count":57,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-25T17:15:19.229Z","etag":null,"topics":["aarch64","arm","arm64","assembly","binary","c","dynamic","elf","embedded","embedded-systems","exploitation","hooks","mips","os","python","shellcode","shellcode-convert","shellcodes","x86","x86-64"],"latest_commit_sha":null,"homepage":"","language":"Python","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/jonatanSh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-04-30T12:38:10.000Z","updated_at":"2025-03-06T07:24:24.000Z","dependencies_parsed_at":"2023-11-23T22:32:48.500Z","dependency_job_id":"4da10490-18a5-4eaa-a2f9-c388cf06f620","html_url":"https://github.com/jonatanSh/shelf","commit_stats":{"total_commits":570,"total_committers":2,"mean_commits":285.0,"dds":"0.024561403508771895","last_synced_commit":"aea98d761802292bf70580c119c0ba1e3e41b6f2"},"previous_names":["jonatansh/elf_to_shellcode"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonatanSh%2Fshelf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonatanSh%2Fshelf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonatanSh%2Fshelf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonatanSh%2Fshelf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonatanSh","download_url":"https://codeload.github.com/jonatanSh/shelf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250860508,"owners_count":21498944,"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":["aarch64","arm","arm64","assembly","binary","c","dynamic","elf","embedded","embedded-systems","exploitation","hooks","mips","os","python","shellcode","shellcode-convert","shellcodes","x86","x86-64"],"created_at":"2024-11-10T23:03:06.429Z","updated_at":"2025-04-26T02:33:46.942Z","avatar_url":"https://github.com/jonatanSh.png","language":"Python","readme":"# Shelf - Shellcode ELF convert elf to shellcode\nConvert standard elf files to standalone shellcodes.\nPlease read the following documentation and view the examples for this project to work properly\n\n#### Project links\n[Github](https://github.com/jonatanSh/shelf)\n\n[Pypi](https://pypi.org/project/py_shelf/)\n\n#### Supported architectures\n* mips\n* i386 (intel x32)\n* x86_64 (intel x64)\n* arm (32bit)\n* aarch64 (arm 64 bit)\n* RISC-V rv64\n\n#### Installation:\n```bash\npip install py_shelf\n```\n###### Python version support\n* python3\n\n\n## How does this work ?\nThe python library parses the elf and create a simple relocatable file format called shelf (shellcode elf).\n\nThe mini loader is inserted as the entry point for shelf.\n\nthe mini loader will load and relocate the shelf then it will execute it.\nThere are no special requirements, the library contain the compiled\nmini loaders and resources.\n\nThe diagram below explain the format (Only work in browsers)\n\n```mermaid\n  classDiagram\n    ShellcodeEntryPoint --|\u003e MiniLoader\n    ShellcodeEntryPoint: Shellcode containing pre mini loader logic\n    MiniLoader --|\u003e Relocation table\n    MiniLoader: Contain all the logic for parsing the relocation table\n    MiniLoader: fully os independent\n    Relocation table --|\u003e HOOKS Optional\n    Relocation table : Contain table required for shellcode runtime relocation\n    HOOKS Optional --|\u003e SHELF\n    HOOKS Optional: Read more about hooks in the documentation below\n    HOOKS Optional: This section is optional and only exists if hooks are used\n    SHELF: Shellcode elf - This is the compiled binary we convert into shellcode\n    SHELF: This binary is stripped into only opcodes\n    SHELF: fully relocatable using the relocation table\n```\n\nThis project is intended to convert elf to os independent shellcodes.\nTherefor the loader never allocate memory and the shellcode format is not packed.\nYou can just execute it, eg ...\n```c\n((void (*)()) shellcode)();\n```\n* note that __libc_start_main perform syscalls\ntherefor if you want your shellcode to be fully os independent you must compile with -nostartfiles\n* Shelf by default expects RWX (Read Write Execute) memory shelf can run in [RX environments (Read Execute) Click the link to read more](docs/mitigation_bypass.md)\n\nfollow the examples below\n\n## Creating a shellcode\n\nSome compilation flags are required for this to work properly.\nYou must compile the binary with -fPIE and -static take a look at the provided examples below\n(makefile).\n\nshellcode is a stripped binary with no symbols and no elf information only opcodes, in order \nto make the shellcode this library require a binary with elf information.\nso make sure you are not stripping the binary before using this library\n\nsimplified make command for mips big endian\n\n```c\ngcc example.c -fno-stack-protector -fPIE -fpic -static -nostartfiles --entry=main -o binary.out\npython -m shelf --input binary.out                                     \n```\n\n### Examples:\n\n[Makefile](https://github.com/jonatanSh/shelf/blob/master/examples/Makefile)\n\n[Example.c](https://github.com/jonatanSh/shelf/blob/master/examples/example.c)\n\n\n\n### Testing your shellcode\nYou can use the provided shellcode [Loader](https://github.com/jonatanSh/shelf/tree/master/shellcode_loader)\nto test you shellcodes\n\n```bash\nqemu-mips ./shellcode_loader ./myshellcode.out\n```\n\n#### Using the shelf loader library\nit is advised to use the shelf loader library to tests your shellcode\nhere you can read more about it: [Shelf loader documentation](https://github.com/jonatanSh/shelf/tree/master/docs/shelf_loader.md)\n\n\n\n## Advanced concepts and features\nfor following links only work on the github page\n* [Opcode relocations](docs/opcodes_relocation.md)\n* [Compiling with libc](docs/libc.md)\n* [Dynamic shellcode](docs/dynamic.md)\n* [Hooking the mini loader](docs/hooks.md)\n* [Mitigation bypass](docs/mitigation_bypass.md)\n* [Optimizations](docs/optimizations.md)\n* [Output formats](docs/output_formats.md)\n* [Python api](docs/py_api.md)\n* [Development](docs/develop.md)\n* [Specific architecture limitations](docs/speific_arch_limitations.md)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FjonatanSh%2Fshelf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FjonatanSh%2Fshelf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FjonatanSh%2Fshelf/lists"}