Systrack
========
[![License][license-badge]](./LICENSE)
[![GitHub actions workflow status][actions-badge]][actions-link]
[![PyPI version][pypi-badge]][pypi-systrack]
[![PyPI downloads][pypi-badge2]][pypistats-systrack]
<img align="left" width="150" height="150" src="https://raw.githubusercontent.com/mebeim/systrack/master/assets/logo.png" alt="Systrack logo"></img>
**See [mebeim/linux-syscalls](https://github.com/mebeim/linux-syscalls) for live syscall tables powered by Systrack**.
Systrack is a tool to analyze Linux kernel images (`vmlinux`) and extract
information about implemented syscalls. Given a `vmlinux` image, Systrack can
extract syscall numbers, names, symbol names, definition locations within kernel
sources, function signatures, and more.
Systrack can configure and build kernels for all its supported architectures,
and works best at analyzing kernels that it has configured and built by itself.
Installation
------------
Systrack is [available on PyPI][pypi-systrack], it requires Python 3.8+ and is
installable through Pip:
```bash
pip install systrack
```
Building and installaing from source requires [`hatch`][pypi-hatch]:
```bash
hatch build
pip install dist/systrack-XXX.whl
```
Usage
-----
Systrack can mainly be used for two purposes: analyzing or building Linux
kernels. For more information, see [`systrack --help`](#command-line-help). For
information about supported architecture/ABI combinations, see
[`systrack --arch help`](#archabi-selection-help).
- **Analyzing** a kernel image can be done given a `vmlinux` ELF with symbols,
and optionally also a kernel source directory (`--kdir`). Systrack will
extract information about implemented syscalls from the symbol table present
in the given `vmlinux` ELF, and if debugging information is present, it will
also extract file and line number information for syscall definitions.
Supplying `--kdir` will help refine and/or correct the location of the
definitions, pointing Systrack to the checked-out sources for the right kernel
version (the same as the one to analyze).
Systrack can guess the architecture and ABI to analyze, but if the given
kernel was built for support for multiple ABIs, the right one can be selected
through `--arch`.
```none
systrack path/to/vmlinux
systrack --format json path/to/vmlinux
systrack --format html path/to/vmlinux
systrack --kdir path/to/linux_git_repo path/to/vmlinux
systrack --kdir path/to/linux_git_repo --arch x86-64-ia32 path/to/vmlinux
```
- **Building** can be done through the `--build` option. You will need to
provide a kernel source directory (`--kdir`) and an architecture/ABI
combination to build for (`--arch`).
```none
systrack --build --kdir path/to/linux_git_repo --arch x86-64
```
Cross-compilation is possible specifying the correct toolchain prefix with
the `--cross` option, which will set the `CROSS_COMPILE` variable for the
kernel's `Makefile`.
```none
systrack --build --kdir path/to/linux_git_repo --arch arm64 --cross aarch64-linux-gnu-
```
Runtime dependencies
--------------------
External (non-Python) runtime dependencies are:
- **Required**: `readelf` (from GNU binutils) is used to parse and extract ELF
metadata such as symbols and sections. This is currently the only *compulsory*
external dependency of Systrack.
- Optional: `addr2line` (from GNU binutils) is used to extract location
information from DWARF debug info. Without this program, Systrack will not
output any information about syscall definition locations.
- Optional: `rg` ([ripgrep][ripgrep]) is used for much faster recursive
grepping of syscall definition locations within kernel sources when needed.
Otherwise, a slower pure-Python implementation is used.
- Optional: a working compiler toolchain and
[kernel build dependencies](https://www.kernel.org/doc/html/latest/process/changes.html)
are obviously needed if you want Systrack to *build* kernels from source.
Limitations
-----------
- Supported kernel images: Systrack works with regular *uncompressed* `vmlinux`
ELF images and *needs* ELF symbols. Compressed and stripped kernel images are
not supported. Tools such as
[`vmlinux-to-elf`](https://github.com/marin-m/vmlinux-to-elf) can be used to
uncompress and unstrip kernel images, after which Systrack will be able to
analyze them.
- Old kernel versions: Systrack was mainly designed for and tested on modern
kernels (>= v4.0) and has not been tested on older kernels. It should still
*somewhat* work on older kernels, but without the same level of guarantee on
the correctness of the output. Support for old kernels may come gradually in
the future.
- Relocatable kernels: Systrack does not currently parse and apply ELF
relocations. This means that Systrack does not support kernels using
relocation entries for the syscall table. On some architectures (notably MIPS)
if the kernel is relocatable the syscall table is relocated at startup and
does not contain valid virtual addresses: Systrack will currently fail to
analyze such kernels.
Command line help
-----------------
```none
$ systrack --help
usage: systrack [OPTIONS...] [VMLINUX]
Analyze a Linux kernel image and extract information about implemented syscalls
positional arguments:
VMLINUX path to vmlinux, if not inside KDIR or no KDIR supplied
options:
-h, --help show this help message and exit
-k KDIR, --kdir KDIR kernel source directory
-a ARCH, --arch ARCH kernel architecture/ABI combination; pass "help" for a list
(default: autodetect)
-b, --build configure and build kernel and exit
-c, --config configure kernel and exit
-C, --clean clean kernel sources (make distclean) and exit
-x PREFIX, --cross PREFIX
toolchain prefix for cross-compilation; use with -b/-c/-C
-o OUTDIR, --out OUTDIR
output directory for out-of-tree kernel build (make O=...); only
meaningful with -b/-c/-C
-f FMT, --format FMT output format: text, json or html (default: text)
--absolute-paths output absolute paths instead of paths relative to KDIR
--remap ORIG_KDIR replace ORIG_KDIR with the KDIR provided with -k/--kdir for paths
obtained from ELF debug information; needed if the kernel was
built with ORIG_KDIR as source directory instead of KDIR, and
debug info contains absolute paths to ORIG_KDIR
--checkout REF git checkout to REF inside KDIR before doing anything; the
special value "auto" can be used to checkout to the tag
corresponding to the detected kernel version from VMLINUX
--disable-opt try building kernel with reduced/disabled optimizations for more
reliable location results; only meaningful with -b
-q, --quiet quietness level:
-q = no info, -qq = no warnings, -qqq = no errors
-qqqq = no standard error output whatsoever
-v, --verbose verbosity level:
-v = info, -vv = debug, -vvv = more debug
-V, --version show version information and exit
```
Arch/ABI selection help
-----------------------
```none
$ systrack-dev --arch help
Supported architectures and ABIs (values are case-insensitive):
Value Aliases Arch Kernel ABI Build based on Notes
-----------------------------------------------------------------------------------------
x86 i386, ia32 x86 32-bit 32-bit IA32 i386_defconfig
x86-64 x64 x86 64-bit 64-bit x86-64 x86_64_defconfig [1]
x86-64-x32 x32 x86 64-bit 64-bit x32 x86_64_defconfig [1]
x86-64-ia32 ia32-64 x86 64-bit 32-bit IA32 x86_64_defconfig [1]
-----------------------------------------------------------------------------------------
arm arm-eabi, eabi ARM 32-bit 32-bit EABI multi_v7_defconfig [2]
arm-oabi oabi ARM 32-bit 32-bit OABI multi_v7_defconfig [2,3]
-----------------------------------------------------------------------------------------
arm64 aarch64 ARM 64-bit 64-bit AArch64 defconfig
arm64-aarch32 aarch32 ARM 64-bit 32-bit AArch32 defconfig [4]
-----------------------------------------------------------------------------------------
mips mips32, o32 MIPS 32-bit 32-bit O32 defconfig
mips64 n64 MIPS 64-bit 64-bit N64 ip27_defconfig [1]
mips64-n32 n32 MIPS 64-bit 64-bit N32 ip27_defconfig [1]
mips64-o32 o32-64 MIPS 64-bit 32-bit O32 ip27_defconfig [1]
-----------------------------------------------------------------------------------------
powerpc ppc, ppc32 PowerPC 32-bit 32-bit PPC32 ppc64_defconfig
powerpc64 ppc64 PowerPC 64-bit 64-bit PPC64 ppc64_defconfig [1]
powerpc64-32 ppc64-32 PowerPC 64-bit 32-bit PPC32 ppc64_defconfig [1]
powerpc64-spu ppc64-spu, spu PowerPC 64-bit 64-bit "SPU" ppc64_defconfig [1,5]
[1] Building creates a kernel supporting all ABIs for this architecture.
[2] Building for Linux <= v3.7 will use "defconfig" instead.
[3] Building creates an EABI kernel with compat OABI support. Building an OABI-only
kernel is NOT supported. The seccomp filter system will be missing.
[4] AArch64 kernel with compat AArch32 support.
[5] "SPU" is not a real ABI. It indicates a Cell processor SPU (Synergistic Processing
Unit). The ABI is really PPC64, but SPUs can only use a subset of syscalls.
```
---
*Copyright © 2023-2025 Marco Bonelli. Licensed under the GNU General Public License v3.0.*
[license-badge]: https://img.shields.io/github/license/mebeim/systrack?color=blue
[actions-badge]: https://img.shields.io/github/actions/workflow/status/mebeim/systrack/publish.yml?event=release&label=publish
[actions-link]: https://github.com/mebeim/systrack/actions/workflows/publish.yml
[pypi-badge]: https://img.shields.io/pypi/v/systrack
[pypi-badge2]: https://img.shields.io/pypi/dm/systrack
[pypi-systrack]: https://pypi.org/project/systrack/
[pypistats-systrack]: https://pypistats.org/packages/systrack
[pypi-hatch]: https://pypi.org/project/hatch
[ripgrep]: https://github.com/BurntSushi/ripgrep
Raw data
{
"_id": null,
"home_page": null,
"name": "systrack",
"maintainer": "Marco Bonelli",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Marco Bonelli <marco@mebeim.net>",
"keywords": "abi, elf, kconfig, kernel, linux, syscall, systrack",
"author": "Marco Bonelli",
"author_email": "Marco Bonelli <marco@mebeim.net>",
"download_url": "https://files.pythonhosted.org/packages/34/16/f2e6a56072bdb9926192b6b82d7360c8121ff5d1364ebe041ead1f1dcd4c/systrack-0.6.tar.gz",
"platform": null,
"description": "Systrack\n========\n\n[![License][license-badge]](./LICENSE)\n[![GitHub actions workflow status][actions-badge]][actions-link]\n[![PyPI version][pypi-badge]][pypi-systrack]\n[![PyPI downloads][pypi-badge2]][pypistats-systrack]\n\n<img align=\"left\" width=\"150\" height=\"150\" src=\"https://raw.githubusercontent.com/mebeim/systrack/master/assets/logo.png\" alt=\"Systrack logo\"></img>\n\n**See [mebeim/linux-syscalls](https://github.com/mebeim/linux-syscalls) for live syscall tables powered by Systrack**.\n\nSystrack is a tool to analyze Linux kernel images (`vmlinux`) and extract\ninformation about implemented syscalls. Given a `vmlinux` image, Systrack can\nextract syscall numbers, names, symbol names, definition locations within kernel\nsources, function signatures, and more.\n\nSystrack can configure and build kernels for all its supported architectures,\nand works best at analyzing kernels that it has configured and built by itself.\n\n\nInstallation\n------------\n\nSystrack is [available on PyPI][pypi-systrack], it requires Python 3.8+ and is\ninstallable through Pip:\n\n```bash\npip install systrack\n```\n\nBuilding and installaing from source requires [`hatch`][pypi-hatch]:\n\n```bash\nhatch build\npip install dist/systrack-XXX.whl\n```\n\nUsage\n-----\n\nSystrack can mainly be used for two purposes: analyzing or building Linux\nkernels. For more information, see [`systrack --help`](#command-line-help). For\ninformation about supported architecture/ABI combinations, see\n[`systrack --arch help`](#archabi-selection-help).\n\n- **Analyzing** a kernel image can be done given a `vmlinux` ELF with symbols,\n and optionally also a kernel source directory (`--kdir`). Systrack will\n extract information about implemented syscalls from the symbol table present\n in the given `vmlinux` ELF, and if debugging information is present, it will\n also extract file and line number information for syscall definitions.\n Supplying `--kdir` will help refine and/or correct the location of the\n definitions, pointing Systrack to the checked-out sources for the right kernel\n version (the same as the one to analyze).\n\n Systrack can guess the architecture and ABI to analyze, but if the given\n kernel was built for support for multiple ABIs, the right one can be selected\n through `--arch`.\n\n ```none\n systrack path/to/vmlinux\n systrack --format json path/to/vmlinux\n systrack --format html path/to/vmlinux\n systrack --kdir path/to/linux_git_repo path/to/vmlinux\n systrack --kdir path/to/linux_git_repo --arch x86-64-ia32 path/to/vmlinux\n ```\n\n- **Building** can be done through the `--build` option. You will need to\n provide a kernel source directory (`--kdir`) and an architecture/ABI\n combination to build for (`--arch`).\n\n ```none\n systrack --build --kdir path/to/linux_git_repo --arch x86-64\n ```\n\n Cross-compilation is possible specifying the correct toolchain prefix with\n the `--cross` option, which will set the `CROSS_COMPILE` variable for the\n kernel's `Makefile`.\n\n ```none\n systrack --build --kdir path/to/linux_git_repo --arch arm64 --cross aarch64-linux-gnu-\n ```\n\nRuntime dependencies\n--------------------\n\nExternal (non-Python) runtime dependencies are:\n\n- **Required**: `readelf` (from GNU binutils) is used to parse and extract ELF\n metadata such as symbols and sections. This is currently the only *compulsory*\n external dependency of Systrack.\n- Optional: `addr2line` (from GNU binutils) is used to extract location\n information from DWARF debug info. Without this program, Systrack will not\n output any information about syscall definition locations.\n- Optional: `rg` ([ripgrep][ripgrep]) is used for much faster recursive\n grepping of syscall definition locations within kernel sources when needed.\n Otherwise, a slower pure-Python implementation is used.\n- Optional: a working compiler toolchain and\n [kernel build dependencies](https://www.kernel.org/doc/html/latest/process/changes.html)\n are obviously needed if you want Systrack to *build* kernels from source.\n\n\nLimitations\n-----------\n\n- Supported kernel images: Systrack works with regular *uncompressed* `vmlinux`\n ELF images and *needs* ELF symbols. Compressed and stripped kernel images are\n not supported. Tools such as\n [`vmlinux-to-elf`](https://github.com/marin-m/vmlinux-to-elf) can be used to\n uncompress and unstrip kernel images, after which Systrack will be able to\n analyze them.\n- Old kernel versions: Systrack was mainly designed for and tested on modern\n kernels (>= v4.0) and has not been tested on older kernels. It should still\n *somewhat* work on older kernels, but without the same level of guarantee on\n the correctness of the output. Support for old kernels may come gradually in\n the future.\n- Relocatable kernels: Systrack does not currently parse and apply ELF\n relocations. This means that Systrack does not support kernels using\n relocation entries for the syscall table. On some architectures (notably MIPS)\n if the kernel is relocatable the syscall table is relocated at startup and\n does not contain valid virtual addresses: Systrack will currently fail to\n analyze such kernels.\n\n\nCommand line help\n-----------------\n\n```none\n$ systrack --help\n\nusage: systrack [OPTIONS...] [VMLINUX]\n\nAnalyze a Linux kernel image and extract information about implemented syscalls\n\npositional arguments:\n VMLINUX path to vmlinux, if not inside KDIR or no KDIR supplied\n\noptions:\n -h, --help show this help message and exit\n -k KDIR, --kdir KDIR kernel source directory\n -a ARCH, --arch ARCH kernel architecture/ABI combination; pass \"help\" for a list\n (default: autodetect)\n -b, --build configure and build kernel and exit\n -c, --config configure kernel and exit\n -C, --clean clean kernel sources (make distclean) and exit\n -x PREFIX, --cross PREFIX\n toolchain prefix for cross-compilation; use with -b/-c/-C\n -o OUTDIR, --out OUTDIR\n output directory for out-of-tree kernel build (make O=...); only\n meaningful with -b/-c/-C\n -f FMT, --format FMT output format: text, json or html (default: text)\n --absolute-paths output absolute paths instead of paths relative to KDIR\n --remap ORIG_KDIR replace ORIG_KDIR with the KDIR provided with -k/--kdir for paths\n obtained from ELF debug information; needed if the kernel was\n built with ORIG_KDIR as source directory instead of KDIR, and\n debug info contains absolute paths to ORIG_KDIR\n --checkout REF git checkout to REF inside KDIR before doing anything; the\n special value \"auto\" can be used to checkout to the tag\n corresponding to the detected kernel version from VMLINUX\n --disable-opt try building kernel with reduced/disabled optimizations for more\n reliable location results; only meaningful with -b\n -q, --quiet quietness level:\n -q = no info, -qq = no warnings, -qqq = no errors\n -qqqq = no standard error output whatsoever\n -v, --verbose verbosity level:\n -v = info, -vv = debug, -vvv = more debug\n -V, --version show version information and exit\n```\n\n\nArch/ABI selection help\n-----------------------\n\n```none\n$ systrack-dev --arch help\n\nSupported architectures and ABIs (values are case-insensitive):\n\n Value Aliases Arch Kernel ABI Build based on Notes\n -----------------------------------------------------------------------------------------\n x86 i386, ia32 x86 32-bit 32-bit IA32 i386_defconfig\n x86-64 x64 x86 64-bit 64-bit x86-64 x86_64_defconfig [1]\n x86-64-x32 x32 x86 64-bit 64-bit x32 x86_64_defconfig [1]\n x86-64-ia32 ia32-64 x86 64-bit 32-bit IA32 x86_64_defconfig [1]\n -----------------------------------------------------------------------------------------\n arm arm-eabi, eabi ARM 32-bit 32-bit EABI multi_v7_defconfig [2]\n arm-oabi oabi ARM 32-bit 32-bit OABI multi_v7_defconfig [2,3]\n -----------------------------------------------------------------------------------------\n arm64 aarch64 ARM 64-bit 64-bit AArch64 defconfig\n arm64-aarch32 aarch32 ARM 64-bit 32-bit AArch32 defconfig [4]\n -----------------------------------------------------------------------------------------\n mips mips32, o32 MIPS 32-bit 32-bit O32 defconfig\n mips64 n64 MIPS 64-bit 64-bit N64 ip27_defconfig [1]\n mips64-n32 n32 MIPS 64-bit 64-bit N32 ip27_defconfig [1]\n mips64-o32 o32-64 MIPS 64-bit 32-bit O32 ip27_defconfig [1]\n -----------------------------------------------------------------------------------------\n powerpc ppc, ppc32 PowerPC 32-bit 32-bit PPC32 ppc64_defconfig\n powerpc64 ppc64 PowerPC 64-bit 64-bit PPC64 ppc64_defconfig [1]\n powerpc64-32 ppc64-32 PowerPC 64-bit 32-bit PPC32 ppc64_defconfig [1]\n powerpc64-spu ppc64-spu, spu PowerPC 64-bit 64-bit \"SPU\" ppc64_defconfig [1,5]\n\n [1] Building creates a kernel supporting all ABIs for this architecture.\n [2] Building for Linux <= v3.7 will use \"defconfig\" instead.\n [3] Building creates an EABI kernel with compat OABI support. Building an OABI-only\n kernel is NOT supported. The seccomp filter system will be missing.\n [4] AArch64 kernel with compat AArch32 support.\n [5] \"SPU\" is not a real ABI. It indicates a Cell processor SPU (Synergistic Processing\n Unit). The ABI is really PPC64, but SPUs can only use a subset of syscalls.\n```\n\n---\n\n*Copyright © 2023-2025 Marco Bonelli. Licensed under the GNU General Public License v3.0.*\n\n[license-badge]: https://img.shields.io/github/license/mebeim/systrack?color=blue\n[actions-badge]: https://img.shields.io/github/actions/workflow/status/mebeim/systrack/publish.yml?event=release&label=publish\n[actions-link]: https://github.com/mebeim/systrack/actions/workflows/publish.yml\n[pypi-badge]: https://img.shields.io/pypi/v/systrack\n[pypi-badge2]: https://img.shields.io/pypi/dm/systrack\n[pypi-systrack]: https://pypi.org/project/systrack/\n[pypistats-systrack]: https://pypistats.org/packages/systrack\n[pypi-hatch]: https://pypi.org/project/hatch\n[ripgrep]: https://github.com/BurntSushi/ripgrep\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Linux kernel syscall implementation tracker",
"version": "0.6",
"project_urls": {
"Changelog": "https://github.com/mebeim/systrack/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/mebeim/systrack",
"Repository": "https://github.com/mebeim/systrack.git"
},
"split_keywords": [
"abi",
" elf",
" kconfig",
" kernel",
" linux",
" syscall",
" systrack"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "14488b8524f63d2930a0b7d60aff46d5a4dcb4588cc0e36eb471d849829e8c08",
"md5": "b7b11c7dc30fc52481799f0dbf98d3d8",
"sha256": "7334d1a89cb7ae3da63bba4776240862a34a4ed7805ac171edf549cb25f6b8ff"
},
"downloads": -1,
"filename": "systrack-0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7b11c7dc30fc52481799f0dbf98d3d8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 83043,
"upload_time": "2025-01-25T18:47:36",
"upload_time_iso_8601": "2025-01-25T18:47:36.973507Z",
"url": "https://files.pythonhosted.org/packages/14/48/8b8524f63d2930a0b7d60aff46d5a4dcb4588cc0e36eb471d849829e8c08/systrack-0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3416f2e6a56072bdb9926192b6b82d7360c8121ff5d1364ebe041ead1f1dcd4c",
"md5": "091b1a18f88a22cd85e4aea3082e0c27",
"sha256": "a9159ec877142baeef1ea9d8dbe14fecff6f599bfd29205162648a8c7211f331"
},
"downloads": -1,
"filename": "systrack-0.6.tar.gz",
"has_sig": false,
"md5_digest": "091b1a18f88a22cd85e4aea3082e0c27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 72981,
"upload_time": "2025-01-25T18:47:35",
"upload_time_iso_8601": "2025-01-25T18:47:35.989225Z",
"url": "https://files.pythonhosted.org/packages/34/16/f2e6a56072bdb9926192b6b82d7360c8121ff5d1364ebe041ead1f1dcd4c/systrack-0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-25 18:47:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mebeim",
"github_project": "systrack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "systrack"
}
JSON
