{"id":14109624,"url":"https://github.com/mebeim/systrack","last_synced_at":"2025-05-16T10:08:02.353Z","repository":{"id":113320409,"uuid":"603910916","full_name":"mebeim/systrack","owner":"mebeim","description":"📡🐧 Linux kernel syscall implementation tracker","archived":false,"fork":false,"pushed_at":"2025-03-26T23:50:46.000Z","size":2789,"stargazers_count":210,"open_issues_count":1,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-09T05:06:50.807Z","etag":null,"topics":["abi","automation","binary-analysis","elf","kconfig","linux","linux-kernel","security-research","syscall","syscall-table","syscalls"],"latest_commit_sha":null,"homepage":"https://syscalls.mebeim.net","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/mebeim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2023-02-19T23:00:50.000Z","updated_at":"2025-04-08T12:23:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"1af29875-1146-4d65-8308-5eb2a0386b12","html_url":"https://github.com/mebeim/systrack","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebeim%2Fsystrack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebeim%2Fsystrack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebeim%2Fsystrack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebeim%2Fsystrack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mebeim","download_url":"https://codeload.github.com/mebeim/systrack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082891,"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":["abi","automation","binary-analysis","elf","kconfig","linux","linux-kernel","security-research","syscall","syscall-table","syscalls"],"created_at":"2024-08-14T10:02:25.022Z","updated_at":"2025-05-16T10:07:57.342Z","avatar_url":"https://github.com/mebeim.png","language":"Python","readme":"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\u003cimg align=\"left\" width=\"150\" height=\"150\" src=\"https://raw.githubusercontent.com/mebeim/systrack/master/assets/logo.png\" alt=\"Systrack logo\"\u003e\u003c/img\u003e\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\n[supported architectures](#supported-architectures-and-abis), and works best at\nanalyzing 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. See also [Command line help](#command-line-help) (`systrack --help`)\nand [Supported architectures and ABIs](#supported-architectures-and-abis)\n(`systrack --arch help`) below.\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 a `--kdir` pointing Systrack to the checked-out sources for the\n  right kernel version (the same as the one to analyze) will help refine and/or\n  correct the location of the definitions.\n\n  Systrack can guess the architecture and ABI to analyze, but if the given\n  kernel was built with 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_source_dir --arch x86-64\n  ```\n\n  When building, kernel sources are configured to enable all syscalls available\n  for the selected architecture/ABI as to produce a `vmlinux` with a \"complete\"\n  syscall table.\n\n  Cross-compilation with GCC is possible specifying the correct toolchain prefix\n  with the `--cross` option, which will set the `CROSS_COMPILE` variable for the\n  kernel's `Makefile`. Other environment variables can also be used as usual and\n  are passed as is to `make`, so LLVM [cross]-compilation and custom toolchain\n  usage is also possible.\n\n  ```none\n  systrack --build --kdir path/to/linux_source --arch arm64 --cross aarch64-linux-gnu-\n  ```\n\n\nSupported architectures and ABIs\n--------------------------------\n\nHere's a list of supported arch/ABI combinations accepted via `--arch` (values\nare case-insensitive). This information is also available running\n`systrack --arch help`.\n\n| Value           | Aliases            | Arch    | Kernel | Syscall ABI    | Build based on                | Notes   |\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,4]* |\n| `arm64`         | `aarch64`          | ARM     | 64-bit | 64-bit AArch64 | `defconfig`                   |         |\n| `arm64-aarch32` | `aarch32`          | ARM     | 64-bit | 32-bit AArch32 | `defconfig`                   | *[1]*   |\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| `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| `riscv`         | `riscv32`, `rv32`  | RISC-V  | 32-bit | 32-bit \"RV32\"  | `defconfig` + `32-bit.config` | *[3,6]* |\n| `riscv64`       | `rv64`             | RISC-V  | 64-bit | 64-bit \"RV64\"  | `defconfig`                   | *[1,6]* |\n| `riscv64-32`    | `rv64-32`          | RISC-V  | 64-bit | 32-bit \"RV32\"  | `defconfig`                   | *[1,6]* |\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\nNotes:\n\n1. Building creates a kernel supporting all ABIs for this architecture.\n2. Build based on `defconfig` for Linux \u003c= v3.7.\n3. Build based on `rv32_defconfig` for Linux \u003c= v6.7 and `defconfig` for\n   Linux \u003c= v5.0.\n4. Building creates an EABI kernel with compat OABI support. Building an\n   OABI-only kernel is NOT supported. The seccomp filter system will be missing.\n5. \"SPU\" is not a real ABI. It indicates a Cell processor SPU (Synergistic\n   Processing Unit). The ABI is really PPC64, but SPUs can only use a subset of\n   syscalls.\n6. \"RV32\" and \"RV64\" are not real ABIs, but rather ISAs. The RISC-V syscall\n   ABI is the same for 32-bit and 64-bit (only register size differs). These\n   names are only used for clarity.\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 (\u003e= 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---\n\n*Copyright \u0026copy; 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\u0026label=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","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmebeim%2Fsystrack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmebeim%2Fsystrack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmebeim%2Fsystrack/lists"}