{"id":13725049,"url":"https://github.com/marin-m/vmlinux-to-elf","last_synced_at":"2026-05-14T08:01:46.560Z","repository":{"id":41538591,"uuid":"230286627","full_name":"marin-m/vmlinux-to-elf","owner":"marin-m","description":"A tool to recover a fully analyzable .ELF from a raw kernel, through extracting the kernel symbol table (kallsyms)","archived":false,"fork":false,"pushed_at":"2026-05-08T00:56:19.000Z","size":12577,"stargazers_count":1731,"open_issues_count":21,"forks_count":178,"subscribers_count":24,"default_branch":"master","last_synced_at":"2026-05-08T02:46:07.919Z","etag":null,"topics":["elf","firmware-analysis","linux","linux-kernel","reverse-engineering","vmlinux"],"latest_commit_sha":null,"homepage":"https://fossplant.re/wiki/Main_page","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marin-m.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-12-26T15:31:16.000Z","updated_at":"2026-05-08T00:56:23.000Z","dependencies_parsed_at":"2024-07-20T20:21:17.593Z","dependency_job_id":"f3dd3c42-289f-4ef8-9319-32d7498c3cf9","html_url":"https://github.com/marin-m/vmlinux-to-elf","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/marin-m/vmlinux-to-elf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marin-m%2Fvmlinux-to-elf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marin-m%2Fvmlinux-to-elf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marin-m%2Fvmlinux-to-elf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marin-m%2Fvmlinux-to-elf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marin-m","download_url":"https://codeload.github.com/marin-m/vmlinux-to-elf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marin-m%2Fvmlinux-to-elf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33015817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"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":["elf","firmware-analysis","linux","linux-kernel","reverse-engineering","vmlinux"],"created_at":"2024-08-03T01:02:10.871Z","updated_at":"2026-05-14T08:01:46.554Z","avatar_url":"https://github.com/marin-m.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# vmlinux-to-elf\n\nThis tool allows to obtain a fully analyzable .ELF file from a vmlinux/vmlinuz/bzImage/zImage kernel image (either a raw binary blob or a preexisting but stripped .ELF file), with recovered function and variable symbols.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/marin-m/vmlinux-to-elf/master/pics/landing_illustration.png\" alt=\"Landing illustration\"\u003e\n\u003c/p\u003e\n\nFor this, it scans your kernel for a kernel symbol table ([kallsyms](https://github.com/torvalds/linux/blob/master/kernel/kallsyms.c)), a compressed symbol table that is present in almost every kernel, mostly unaltered.\n\nBecause the concerned symbol table is originally compressed, it should recover strings that aren't visible in the original binary.\n\nIt produces an .ELF file that you can analyze using IDA Pro and Ghidra. This tool is hence useful for embedded systems reverse engineering.\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://snapcraft.io/vmlinux-to-elf\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/marin-m/vmlinux-to-elf/master/pics/snap_badge.svg?raw=true\" alt=\"Get it from the Snap Store\"\u003e\u003c/a\u003e \u0026nbsp; \u003ca href=\"https://flathub.org/en/apps/re.fossplant.vmlinux-to-elf\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/marin-m/vmlinux-to-elf/master/pics/flathub_badge.svg?raw=true\" alt=\"Get it on Flathub\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nUsage:\n```bash\n# Command line:\nvmlinux-to-elf \u003cinput_kernel.bin\u003e \u003coutput_kernel.elf\u003e\n\n# Command line, list symbol addresses only:\nkallsyms-finder \u003cinput_kernel.bin\u003e # If installed with uv\nvmlinux-to-elf.kallsyms-finder # If installed with snap\n\n# Command line, just decompress the kernel:\nvmlinuz-decompressor \u003cinput_kernel.bin\u003e \u003coutput_kernel.bin\u003e # If installed with uv\nvmlinux-to-elf.vmlinuz-decompressor # If installed with snap\n\n# Graphical:\nvmlinux-to-elf-gui # If installed with uv\nvmlinux-to-elf.gui # If installed with snap\nflatpak run re.fossplant.vmlinux-to-elf # If installed with flatpak\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/marin-m/vmlinux-to-elf/master/pics/Screenshot_2_Kernel_loaded.png?raw=true\" alt=\"Application main screen\" width=\"850\"\u003e\n    \n\u003cimg src=\"https://raw.githubusercontent.com/marin-m/vmlinux-to-elf/master/pics/Screenshot_6_Offsets_view_with_hex_dump.png?raw=true\" alt=\"Application kernel offsets view\" width=\"850\"\u003e\n\u003c/p\u003e\n\nInstallation:\n```bash\n# Install CLI+GUI with Snap (recommended on Ubuntu)\nsudo snap install vmlinux-to-elf\n\n# Install CLI+GUI with yay (recommended on Arch, Manjaro)\nyay -S vmlinux-to-elf libadwaita python-gobject\n\n# Install CLI+GUI with uv (example with Fedora)\nsudo dnf install -y uv glib2-devel libadwaita-devel gtk4-devel \\\n    gobject-introspection-devel python3-gobject-devel \\\n    python3-devel cairo-devel @development-tools\nuv tool install vmlinux-to-elf[gui]\nvmlinux-to-elf-gui --install-metadata # Install .desktop file\n\n# Install CLI with uv and GUI with Flatpak (recommended on\n# distributions with libadwaita \u003c 1.6)\nsudo dnf install -y uv flatpak @development-tools\nuv tool install vmlinux-to-elf\n\nflatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo\nflatpak install re.fossplant.vmlinux-to-elf\n```\n\nLocal development environment setup:\n\n```bash\nsudo snap install --classic astral-uv\nsudo apt install git\ngit clone git@github.com:marin-m/vmlinux-to-elf.git\n\n# Dependencies for the GTK-4 GUI\nsudo apt install libgirepository-2.0-dev libgtk-4-dev libadwaita-1-dev \\\n    gir1.2-adw-1 gir1.2-gtk-4.0 python3-dev glib-compile-resources\n\ncd vmlinux-to-elf\ncp -a .github/hooks/* .git/hooks/\n# Download Python modules and initialize virtualenv (creates \".venv\",\n# call \"source .venv/bin/activate\" to set up)\nuv sync --extra gui\n# Add vmlinux-to-elf to $PATH, so that the commands are callable\n# system-wide (creates a symlink to the source in \"~/.local/bin\")\nuv tool install -e .[gui]\n```\n\n## Features\n* Take a raw binary blob or ELF kernel file as an input  [OK]\n* Automatically detect and unpack the main compression formats used for the Linux kernel [OK]\n* Find and extract the embedded kernel symbols table (kallsyms) from the input file  [OK]\n* Infer the instruction set architecture, endianness, bit size, relying upon other things on common function prologue signatures [OK]\n* Infer the entry point of the kernel from the symbols contained in the kallsyms table  [OK]\n* Provide basic inference for the kernel base address  [OK] (for now, consider that it is the first \"TEXT\" symbol address of the binary with the lower 0xfff bits clear - seems to work well enough)\n* Unpack certain types of Android `boot.img` files, starting with an `ANDROID!` or `UNCOMPRESSED_IMG` magic [OK]\n* Produce an .ELF file fully analyzable with IDA Pro or Ghidra as an output  [OK]\n\n\n## How does it work, really?\n\nA brief history of the \"kallsyms\" symbol table can be found at the top of the \"[kallsyms.py](vmlinux_to_elf/core/kallsyms.py)\" file. Briefly, this was introduced circa 2004 in the Linux kernel in its current form and is used to print the \"Kernel oops\" messages, among other things.\n\nIt contains tuples of \"symbol name\", \"symbol address\", \"symbol type\" (symbol types being designated with a single letter in a fashion similar to the [`nm`](http://man7.org/linux/man-pages/man1/nm.1p.html) utility), this information being tightly packed with a simple compression algorithm.\n\nThe schema below displays how this information is serialized into the kernel, the offset of each respective structure being detected by `vmlinux-to-elf` through [heuristics](vmlinux_to_elf/core/kallsyms.py):\n\n| Array name | Description | Sample contents |\n| ---------- | ----------- | --------------- |\n| `kallsyms_addresses` (or `kallsyms_offsets` + `kallsyms_relative_base`) |  The addresses (or offsets relative to a base, in recent kernels) of each symbol, as an array | `80 82 00 C0  80 82 00 C0  80 82 00 C0  0C 84 00 C0  B4 84 00 C0  5C 85 00 C0  60 85 00 C0  60 85 00 C0` ...\n| `kallsyms_num_syms`      | The total number of symbols, as an integer (useful for checking for endianness, alignment, correct decoding of the symbols table) | `54 D4 00 00`\n| `kallsyms_names`         | The compressed, length-separated symbol names themselves. Each byte in the compressed symbol strings references an index in the \"kallsyms_token_index\" array, that itself references the offset of a character or string fragment in the \"kallsyms_token_table\" array. | `09 54 64 6F  5F E1 F1 66  F5 25 05 54  F3 74 AB 74  0E 54 FF AB` ...\n| `kallsyms_markers`       | A lookup table serving to find quickly the approximative offset of a compressed symbol name in \"kallsyms_names\": every 256 symbols, an offset to the concerned symbol in \"kallsyms_names\" is added as a long to this table. | `00 00 00 00  03 0C 00 00  0C 18 00 00  1B 24 00 00  0F 31 00 00  DA 3D 00 00  CF 4A 00 00` ...\n| `kallsyms_seqs_of_names` | This lookup table (present in 6.2+ kernels only) contains an array sequence of packed 3-byte integers, where array indexes match the alphanumeric order for a given symbol name, and array values match the corresponding entry indexes in the `kallsyms_addresses` and `kallsyms_names` arrays\n| `kallsyms_token_table`   | Null-terminated string fragments or characters that may be contained in kernel symbol names. This can contain at most 256 string fragments or characters. Indexes corresponding to ASCII code points which are actually used in any kernel symbol will correspond to the concerned ASCII character, other positions will contain a statistically chosen string fragment. This tool tries to heuristically find this array across the passed file first in order to find the `kallsyms` symbols table. | `73 69 00 67  70 00 74 74  00 79 6E 00  69 6E 74 5F  00 66 72 00  ` ...\n| `kallsyms_token_index`   | 256 words, each mapping to the offsets of the characters or string fragments designated by their respective indexes in \"kallsyms_token_table\". |  `00 00 03 00  06 00 09 00  0C 00 11 00  14 00 1B 00  1E 00 22 00  2C 00 30 00  35 00 38 00` ...\n\nThese fields have variable alignment and field size. The field sizes may vary over architecture and kernel version too. For this reason, `vmlinux-to-elf` has been tested over a variety of cases.\n\nOpenWRT [since 2013](https://git.openwrt.org/?p=openwrt/svn-archive/archive.git;a=commit;h=5317e9cb69bb42dee167e0552a5e1f01147ba072) has a [patch](https://github.com/openwrt-mirror/openwrt/blob/9b4650b/target/linux/generic/patches-4.4/203-kallsyms_uncompressed.patch) that removes compression over the `kallsyms` table by default (when building `kallsyms` has been enabled by the user). They do this in order to save space when re-compressing over the kernel using LZMA.\n\nThis means that the `kallsyms_token_table` and `kallsyms_token_address` entries disappear, and that the symbol names use plain text ASCII instead. This case is supported too.\n\nIn standard Linux 6.2 kernels, `kallsyms` arrays are encoded in the following order:\n\n1. `kallsyms_addresses` (or `kallsyms_offsets` + `kallsyms_relative_base`)\n2. `kallsyms_num_syms`\n3. `kallsyms_names`\n4. `kallsyms_markers`\n5. `kallsyms_seqs_of_names` (6.2+ only)\n6. `kallsyms_token_table`\n7. `kallsyms_token_index`\n\nFor Linux 6.4+ kernels, this layout is changed to: \n\n1. `kallsyms_num_syms`\n2. `kallsyms_names`\n3. `kallsyms_markers`\n4. `kallsyms_token_table`\n5. `kallsyms_token_index`\n6. `kallsyms_addresses` (or `kallsyms_offsets` + `kallsyms_relative_base`)\n7. `kallsyms_seqs_of_names`\n\nWhile these are parsed in the following order by `vmlinux-to-elf`'s parsing algorithm:\n\n1. `kallsyms_token_table` (before-last structure)\n2. `kallsyms_token_index` (last structure, forwards)\n3. `kallsyms_markers` (backwards)\n4. `kallsyms_names` (backwards again)\n5. `kallsyms_num_syms` (backwards again)\n6. `kallsyms_addresses` (or `kallsyms_offsets` + `kallsyms_relative_base`) (backwards again)\n\n## Kernels support\nIt should support kernels from version 2.6.10 (December 2004), until the current 6.4 (as of August 2023). Only kernels explicitly configured without `CONFIG_KALLSYMS` should not be supported. If this kernel configuration variable was not set at build, then you will get: `KallsymsNotFoundException: No embedded symbol table found in this kernel`.\n\nFor raw kernels, the following architectures can be detected (using magics from [binwalk](https://github.com/ReFirmLabs/binwalk/blob/master/src/binwalk/magic/binarch)): MIPSEL, MIPSEB, ARMEL, ARMEB, PowerPC, SPARC, x86, x86-64, ARM64, MIPS64, SuperH, ARC.\n\nThe following kernel compression formats can be automatically detected: XZ, LZMA, GZip, BZ2, LZ4, LZO and Zstd.\n\n## Advanced usage\n\nYou can also obtain a text-only output of the kernel's symbol names, addresses and types through using the `kallsyms-finder` utility, also bundled with this tool. The format of its output will be similar to the `/proc/kallsyms` procfs file.\n\nSome parameters that should be automatically inferred by the tool (such as the instruction set or base address) may be overriden in case of issue. The full specification of the arguments allowing to do that is presented below:\n\n```\n$ vmlinux-to-elf -h\nusage: vmlinux-to-elf [-h] [--e-machine DECIMAL_NUMBER] [--bit-size BIT_SIZE]\n                      [--file-offset HEX_NUMBER] [--base-address HEX_NUMBER]\n                      [--bss-size BSS_SIZE] [--use-absolute]\n                      input_file output_file\n\nTurn a raw or compressed kernel binary, or a kernel ELF without symbols, into a fully analyzable ELF whose symbols were extracted from the kernel symbol table\n\npositional arguments:\n  input_file            Path to the vmlinux/vmlinuz/zImage/bzImage/kernel.bin/kernel.elf file to make into an analyzable .ELF\n  output_file           Path to the analyzable .ELF to output\n\noptions:\n  -h, --help            show this help message and exit\n  --e-machine DECIMAL_NUMBER\n                        Force overriding the output ELF \"e_machine\" field with this integer value (rather than auto-detect)\n  --bit-size BIT_SIZE   Force overriding the input kernel bit size, providing 32 or 64 bit (rather than auto-detect)\n  --file-offset HEX_NUMBER\n                        Consider that the raw kernel starts at this offset of the provided raw file or compressed stream (rather than 0, or the beginning of the ELF\n                        sections if an ELF header was present in the input)\n  --base-address HEX_NUMBER\n                        Force overriding the output ELF base address field with this integer value (rather than auto-detect)\n  --bss-size BSS_SIZE   Size in megabytes of the .bss section in the binary\n  --use-absolute        Assume kallsyms offsets are absolute addresses\n\n```\n\n## How is the source code organized?\n\n\u003ca href=\"https://raw.githubusercontent.com/marin-m/vmlinux-to-elf/master/pics/vmlinux-to-elf internal charting.pdf?raw=true\"\u003e\n\u003cimg src=\"https://docs.google.com/drawings/d/e/2PACX-1vSnK-GDr74AXNPLHgwmHC9eH0e9MtMzSZ7XLqBkwynmImcT6K1QQP0WL6i5BG1zgajOnSaVxq6QQHRL/pub?w=1440\u0026amp;h=2160\u0026amp;\" alt=\"Source code chart\"\u003e\n\u003c/a\u003e\n\n## Bug fixes, improvements, etc.\n\nDon't hesitate to [open an issue](https://github.com/marin-m/vmlinux-to-elf/issues/new/choose) for any suggestion of improvement.\n\nPlease privilege the current Github repository issues and pull requests in priority for reporting bugs, asking questions, etc.\n\nAlternatively, you can use [this matrix channel](https://matrix.to/#/#vmlinux-to-elf:matrix.org) if needing directly contact with the author of the project, but please reserve this as a secondary channel e.g for sending kernel samples, what goes here otherwise is more likely to be lost.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarin-m%2Fvmlinux-to-elf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarin-m%2Fvmlinux-to-elf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarin-m%2Fvmlinux-to-elf/lists"}