{"id":21113546,"url":"https://github.com/icsnju/visualinux","last_synced_at":"2025-04-06T02:09:45.408Z","repository":{"id":263581326,"uuid":"849100429","full_name":"icsnju/visualinux","owner":"icsnju","description":"A visualized debugging framework to aid in understanding the Linux kernel.","archived":false,"fork":false,"pushed_at":"2025-03-26T16:53:42.000Z","size":2971,"stargazers_count":110,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T01:09:16.035Z","etag":null,"topics":["debugger","gdb","gdb-extension","linux-kernel","visualization-tool"],"latest_commit_sha":null,"homepage":"https://icsnju.github.io/visualinux/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icsnju.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-29T01:23:38.000Z","updated_at":"2025-03-14T13:08:44.000Z","dependencies_parsed_at":"2025-02-27T09:25:32.267Z","dependency_job_id":"f924f99e-ac07-4b88-b219-83467bbc7ee0","html_url":"https://github.com/icsnju/visualinux","commit_stats":{"total_commits":20,"total_committers":3,"mean_commits":6.666666666666667,"dds":0.35,"last_synced_commit":"b52487aba50cf1c283b26abd114030dfc9cb6e64"},"previous_names":["icsnju/visualinux"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icsnju%2Fvisualinux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icsnju%2Fvisualinux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icsnju%2Fvisualinux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icsnju%2Fvisualinux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icsnju","download_url":"https://codeload.github.com/icsnju/visualinux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423515,"owners_count":20936626,"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":["debugger","gdb","gdb-extension","linux-kernel","visualization-tool"],"created_at":"2024-11-20T01:54:19.526Z","updated_at":"2025-04-06T02:09:45.400Z","avatar_url":"https://github.com/icsnju.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Visualinux\n\n[![](https://img.shields.io/badge/2025-EuroSys-deepgreen.svg)]() [![](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://doi.org/10.5281/zenodo.13710732) [![](https://img.shields.io/badge/DOI-10.5281/zenodo.13710732-blue.svg)](https://doi.org/10.5281/zenodo.13710732)\n\nVisualinux is the first debugging framework that can simplify the program state of Linux kernel to the extent that one can visually understand with low programming complexity and efforts. Our work has been accepted by EuroSys 2025 [[paper]](https://doi.org/10.1145/3689031.3696095).\n\n\u003cdiv\u003e\n    \u003ca href=\"docs/assets/01-process_tree.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/01-process_tree.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/02-workqueue.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/02-workqueue.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/03-runqueue.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/03-runqueue.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/04-addrspace.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/04-addrspace.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/05-proc_vfs.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/05-proc_vfs.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/06-socket.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/06-socket.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/07-signals.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/07-signals.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/08-buddy_system.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/08-buddy_system.png\"/\u003e\u003c/a\u003e\n    \u003ca href=\"docs/assets/09-kmem_cache.png\"\u003e\u003cimg style=\"width: 32%; border: 1px black solid\" src=\"docs/assets/09-kmem_cache.png\"/\u003e\u003c/a\u003e\n\u003c/div\u003e\n\nTo make it easy to get started, this repo provides an out-of-the-box kernel debugging environment with Visualinux enabled. You can also easily integrate Visualinux into your own debugging workflow (see [Standalone Deployment](#standalone-deployment)).\n\nThis README only describes how to deploy and use Visualinux. Please refer to `docs/` for technical details.\n\n## Requirements\n\nVisualinux is fully compatible to gdb and it is available as long as one can debug the Linux kernel through gdb with python extension enabled. Requirements of our prototype implementation are:\n\n- Python 3.10+\n\n- Node.js 18+ (more recommanded 20+)\n\n- Linux kernel 6.1.X (otherwise Visualinux is still available, but some of our example code in `viewcl/` might need to be rewritten due to the kernel version difference)\n\nThe tool has been well-tested on a Ubuntu 22.04 host with Python 3.10.12 and Node.js v18.20/v20.17, with both gdb (QEMU) and kgdb (rpi-400) targeting on Linux kernel 5.15 and 6.1.25.\n\n## Build\n\n### Native\n\n#### Initialization\n\nThis repo provides a one-click initialization script. It generates the same environment as the evaluation in our paper. Specifically, it (1) installs python and node.js requirements, (2) fetchs busybox and linux kernel source, and (3) prepares a vscode development environment. You can use the second script if you do not use VSCode when debugging the Linux kernel.\n\n```sh\n./scripts/initenv.sh default\n./scripts/initenv-no-vscode.sh default\n```\n\nAfter that, you can build the kernel, the workload and the visualizer:\n\n```sh\nmake build\n(cd visualizer/ \u0026\u0026 npm install)\n```\n\n#### Manual Configuration\n\nFirst, please make sure your gdb is able to auto-load gdb scripts and extensions (`kernel/vmlinux-gdb.py`, `scripts/config.gdb` and `visualinux-gdb.py`), e.g. check if they are in your gdb auto-load safe-path. Otherwise you have to manually load these scripts in each new debugging session.\n\n```\nTo enable execution of this file add\n  add-auto-load-safe-path \u003cproject_dir\u003e/kernel/scripts/gdb/vmlinux-gdb.py\n  add-auto-load-safe-path \u003cproject_dir\u003e/scripts/gdb/config.gdb\n  add-auto-load-safe-path \u003cproject_dir\u003e/visualinux-gdb.py\nlines to your configuration file \"\\~/.config/gdb/gdbinit\".\nTo completely disable this security protection add\n   set auto-load safe-path /\nline to your configuration file \"\\~/.config/gdb/gdbinit\".\n```\n\nSecond, you should configure the following private information if necessary: just create a file `.env.local` in the project directory (same location as `.env`), and Visualinux will parse it. If not provided, Visualinux can work correctly with the relevant features disabled.\n\n- `OPENAI_API_KEY`, `OPENAI_API_URL` and `OPENAI_API_MODEL` are used for LLM connection. If not provided, all LLM chat APIs will be disabled (e.g. `vchat`).\n\n- `VISUALINUX_LOCALHOST_IP` is the public IP of your machine. It is only useful if you want to use the unified public web page as the front-end of Visualinux (see below).\n\n```\nOPENAI_API_KEY = deadbeef\nOPENAI_API_URL = https://api.openai.com\nOPENAI_API_MODEL = gpt-4\nVISUALINUX_LOCALHOST_IP = xxx.xxx.xxx.xxx\n```\n\n### Docker\n\nYou can also quickly start Visualinux using Docker (thanks to [Debin](https://github.com/luodeb) and [nan mu](https://github.com/nan-mu) for their contribution):\n\n```sh\n# Compile an image containing Node 20.17.0 and Python 3.11.0\ncd scripts/build\ndocker build -t visualinux:1.0 .\ndocker build --build-arg USE_MIRROR=true -t visualinux:1.0 . # Use mirrors\n# Launch the environment\ncd ../.. # Go back to the project root\n# fish style\ndocker run --network host --rm -it -v (pwd):/app -w /app visualinux:1.0 /bin/bash\n# bash style\ndocker run --network host --rm -it -v $(pwd):/app -w /app visualinux:1.0 /bin/bash\n```\n\n### Standalone Deployment\n\nAlthough this repo provides an out-of-the-box environment, it is easy to integrate Visualinux into your own debugging workflow. Actually, the only essential components of this repo are the gdb extension (`visualinux-gdb.py`, `visualinux/` and `scripts/gdb/`) and the visualizer app (`visualizer/`). Most of the aforementioned scripts and commands is not mandatory to use; you only need to meet the following requirements (most of them are trivial):\n\n- gdb with python extension enabled (which is the default configuration of gdb).\n\n- python packages listed in `scripts/py-requirements.txt` installed.\n\n- npm package requirements in `visualizer/` installed.\n\n- Linux kernel compiled with debug info enabled, and compiled/runned with KASLR disabled.\n\n- workload that can be used as initramfs or init disk image.\n\nAfter that, you can just integrate Visualinux as a normal gdb python extension (with the auxiliary gdb scripts) and a normal node.js application.\n\n## Tool Startup\n\nThis repo provides three different ways to startup Visualinux. You can choose your favourite one.\n\n### Traditional Workflow\n\nVisualinux is designed to be an auxiliary tool and does not interfere with the typical gdb workflow. Thus, you can start the gdb host and stub in separate terminals as usual:\n\n```sh\nmake start    # in terminal 1\nmake attach   # in terminal 2\n```\n\nAnd start the visualizer app in another terminal:\n\n```sh\ncd visualizer/\nnpm run dev\n```\n\nYou can access the visualizer app through `http://localhost:9802` (the port can be configured in `.env`).\n\n### VSCode Workspace\n\nThis repo already provides VSCode configuration files. Therefore, after running our initialization script, you can open the vscode workspace in `.vscode/visualinux.code-workspace` and directly launch a Visualinux-enabled debugging session.\n\nAfter launching the task, two panels will appear in VSCode: one for the gdb-qemu instance, and another for the visualizer app. Terminating the debugging session will stop all of them.\n\nYou can access the visualizer app through `http://localhost:9802` (the port can be configured in `.env`).\n\n### Unified Public Web Page\n\nWe also provide another solution that utilizes ttyd to merge gdb-qemu and visualizer together on a simple web page. You can initialize and launch it through the following commands:\n\n```sh\napt install tmux ttyd\n(cd page/ \u0026\u0026 npm install)\n./page/start.py\n./page/start.py --public\n```\n\nBy default, you can access the web page through port 3000. If you invoke `.start.py` with `--public` option, it will map it to port 80, which may require root user privileges or some environment-level configuration to work.\n\nSince ttyd doesn't work for localhost in several circumstances, please fill in `VISUALINUX_LOCALHOST_IP` in `.env.local` with your public IP.\n\n## Usage\n\n### Quick Start\n\nSet a breakpoint anywhere; when the execution is paused, invoke the following command in gdb to plot the process parent tree on the visualizer:\n\n```\nvplot -f evaluation/textbook/01_process_parenthood.vcl\n```\n\n*Note that invoking gdb commands in VSCode terminal requires a `-exec` prefix. For example, `vplot -f foo.vcl` should be `-exec vplot -f foo.vcl`.*\n\n### How Visualinux Works\n\nVisualinux consists of a gdb extension and a visualizer. The gdb extension does not change the typical gdb workflow, but adds a set of CLI-like commands to the gdb interface, which we call **v-commands**. We will briefly introduce their usage later.\n\nThe visualizer is an independent node app. For v-commands invoked, the gdb extension will notify the visualizer via HTTP POST requests, and then the front-end visualization will be refreshed. For example, `vplot` converts the object graphs into a JSON object and send it to the visualizer.\n\nNote that the gdb extension will be loaded on the first halt (e.g. reaching a breakpoint) and print messages to indicate the successful initialization. If you encounter any initialization issues in your environment (e.g. if gdb complains that the command `vplot` does not exist), you can try to check the entry script `scripts/gdb/config.gdb` to get more details to find the root cause.\n\n### V-Commands\n\nWhenever the execution is paused, you can execute the v-commands as the normal commands of gdb, including `vplot`, `vctrl` and `vchat`.\n\n**vplot** extracts object graphs given a ViewCL source file (from `viewcl/` of the project), or it can synthesize naive ViewCL code for simple usages.\n\n- `vplot -f evaluation/cases/dirty-pipe.vcl`\n\n- `vplot p { pid, comm }`\n\n- `vplot --chat plot p with fields pid, comm`\n\n**vctrl** controls the panes and the views displayed on panes of the visualizer. For instance, split an existed pane to create a new one, or apply a ViewQL request on a view. ViewQL programs can be synthesized via LLM API.\n\n- `vctrl split 1 -d h`\n\n- `vctrl chat split the first pane horizontally`\n\n- `vctrl chat in pane #4, find me all vm_area_struct whose address is not 0xffffffffff871a20, and shrink them`\n\n**vchat** is a unified LLM chat API. The prompt is designed to classify the message as either `vplot` or `vctrl`, and convert it into a well-formed command.\n\nPlease check the help messages in gdb for more details of usages, e.g. invoking `vplot --help`.\n\n### Reproduce the Evaluation\n\n#### Reviving and Beyond the Textbook\n\nAssume that you have used our initialization scripts, you can easily reproduce the textbook results (section 5.1 and 5.2) in our paper:\n\n- Set a breakpoint on the function `security_task_getsid`, then let it continue.\n\n- When the execution is first paused there, invoke the v-command `vplot -f evaluation.vcl` in gdb, and wait for seconds until the plots are generated in the visualizer.\n\nNote that the textbook evaluation #14 (i.e. `viewcl/evaluation/textbook/14_kernfs.vcl`) requires a short hacking into Linux kernel source code. Unless you are on our AE online site, you should manually patch the code in `scripts/kernel.patch/fs.kernfs.dir.c.patch` to the end of `kernel/fs/kernfs/dir.c`, and remove the comment of the corresponding line in `viewcl/evaluation.vcl`.\n\n#### Case Studies\n\nTo reproduce the CVE examples shown in our paper (section 3.3 and 5.3), you may need to make some additional preparations:\n\n- You should use the specified versions of Linux kernel, or the CVEs may not exist.\n\n- You should use the specified workloads to efficiently reproduce the CVE, which this repository already provides (i.e. `workload/src/exp/` and `workload/src/dirty-pipe/`).\n\n- After that, you can set breakpoints at specified program points, debug the CVEs as usual, and use the ViewCL code in `viewcl/evaluation/cases/*` to perform the visualization.\n\nPlease refer to [StackRot](https://github.com/lrh2000/StackRot) and [DirtyPipe](https://dirtypipe.cm4all.com/) for more details.\n\nNote that StackRot is a concurrency bug and Visualinux only focuses on understanding the program state at a single moment, additional gdb operations are still required.\n\n#### Performance\n\nYou can use the `--perf` option of `vplot` for performance evaluation (For example, `vplot -f evaluation.vcl --perf`). Note that the first time of object graph extraction might be slow, since gdb needs to cache several statical information in a cold start.\n\n## Development\n\nPlease check `docs/` for more details about ViewCL/ViewQL programming and ViewQL prompting.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficsnju%2Fvisualinux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficsnju%2Fvisualinux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficsnju%2Fvisualinux/lists"}