{"id":19034261,"url":"https://github.com/wenzel/nitro","last_synced_at":"2026-05-04T21:30:20.150Z","repository":{"id":71187272,"uuid":"60381427","full_name":"Wenzel/nitro","owner":"Wenzel","description":"KVM-based Virtual Machine Introspection","archived":false,"fork":false,"pushed_at":"2017-05-24T07:29:07.000Z","size":20377,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-02T05:13:12.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/Wenzel.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}},"created_at":"2016-06-03T22:30:17.000Z","updated_at":"2023-09-08T17:11:08.000Z","dependencies_parsed_at":"2023-03-11T10:01:37.360Z","dependency_job_id":null,"html_url":"https://github.com/Wenzel/nitro","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Fnitro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Fnitro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Fnitro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wenzel%2Fnitro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wenzel","download_url":"https://codeload.github.com/Wenzel/nitro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240088542,"owners_count":19746102,"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":[],"created_at":"2024-11-08T21:44:06.610Z","updated_at":"2026-05-04T21:30:20.080Z","avatar_url":"https://github.com/Wenzel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nitro\n\nVirtual Machine Introspection for KVM.\n\nThis is the userland component named `nitro`.\nIt will receive the events generated by KVM and display them.\n\n# New repo\n\nThis repository is not maintained anymore.\n\nAn organization dedicated to bring VMI to KVM has been created on Github: [KVM-VMI](https://github.com/KVM-VMI/kvm-vmi)\n\nNew repository for [Nitro](https://github.com/KVM-VMI/nitro)\n\n# Requirements\n\n- `python 3`\n- `docopt`\n- `libvirt`\n- `ioctl-opt Python 3`\n- [`pebble`](https://pypi.python.org/pypi/Pebble)\n- `libvmi` (optional)\n- `libvmi Python 2` (optional)\n- `Zeromq Python 3` (optional)\n- `Zeromq Python 2` (optional)\n- `rekall` (optional)\n\n# Setup\n\n- Setup a VM. Make sure to use the `qemu:///system` connection.\nGo to the `tests` folder to find a packer template and an import script if\nyou don't have one already.\n\n(Nitro only supports for now `Windows XP x64` and `Windows 7 x64`, see the `Note` section below)\n\n\n# Usage\n\n- Make sure that you have loaded the modified kvm modules. \n(`cd kvm-vmi \u0026\u0026 make modules \u0026\u0026 make reload`)\n\n- Start the VM that you would like to monitor.\n\n- Wait for the desktop to be available on the VM.\n\n- Start `Nitro` as root (go to the *Notes* section to see how to start it as a normal user)\n\n~~~\n\"\"\"Nitro.\n\nUsage:\n  nitro.py [options] \u003cvm_name\u003e\n\nOptions:\n  -h --help     Show this screen.\n  --nobackend   Don't analyze events\n  --stdout      Display events on stdout, not in a log file\n\n\"\"\"\n~~~\n\nNitro monitors the given `\u003cvm_name\u003e` syscalls by activating a set of traps in KVM.\nThe optional components listed above are needed only if you want to extract more information\nabout the captured events. See the Backend section.\n\nHere i will assume that you have installed only the required ones.\nTherefore you have to run Nitro with the option `--nobackend`.\n\nIt will run until the user sends a `CTRL+C` to stop it, in which case Nitro\nwill unset the traps and write the captured events in a file named `events.json`.\n\nIn case the option `--stdout` is enabled, Nitro will display the events immeditely,\nand skip the log file.\n\nAn event should look like this output\n~~~JSON\n  {\n    \"direction\": \"enter\",\n    \"rax\": \"0x1005\",\n    \"vcpu\": 0,\n    \"type\": \"syscall\",\n    \"cr3\": \"0x1b965000\"\n  },\n~~~\n\n\nA successful run should give the following output :\n\n~~~\n$ ./nitro.py --nobackend --stdout nitro_win7x64\nSetting traps to False\nFinding QEMU pid for domain nitro_win7x64\nDetected 1 VCPUs\nSetting traps to True\nStart listening on VCPU 0\n{'cr3': '0x6cdc000',\n 'direction': 'exit',\n 'rax': '0x3f',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'enter',\n 'rax': '0x138',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'exit',\n 'rax': '0x0',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'enter',\n 'rax': '0x58',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'exit',\n 'rax': '0x0',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'enter',\n 'rax': '0x138',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'exit',\n 'rax': '0x0',\n 'type': 'syscall',\n 'vcpu': 0}\n{'cr3': '0x6cdc000',\n 'direction': 'enter',\n 'rax': '0x5f',\n 'type': 'syscall',\n 'vcpu': 0}\nSetting traps to False\n~~~\n\n# Backend\n\nThe Backend is supposed to analyze raw nitro events, and extract useful\ninformations, such as:\n- process name\n- process PID\n- syscall name\n\nFirst, `Rekall` is used in `symbols.py` to extract the syscall table from\nthe memory dump.\n\nThen, a subprocess is started to run `libvmi` (it is only Python2),\nand the communication is managed with `ZeroMQ`.\n\nOn a debian based distro, you can install the following packages:\n- `python-zmq`\n- `python3-zmq`\n\nUnfortunately, `Rekall` is not available as a Debian package.\nFor now you will have to install it system-wide with `pip`.\n\n## libvmi\n\n- Compile and install `libvmi`. See the [install notes](http://libvmi.com/docs/gcode-install.html)\n\n- Configure the file `libvmi.conf`, which is already provided in the repo\n\nConfigure the name of your vm that you want to monitor :\n(only `Windows 7 x64` is supported here)\n\n~~~\nnitro_win7x64 {\n    ostype      = \"Windows\";\n    win_tasks   = 0x188;\n    win_pdbase  = 0x28;\n    win_pid     = 0x180;\n    win_pname   = 0x2e0;\n}\n~~~\n\nAt least, the following keys are required :\n- `win_tasks`\n- `win_pdbase`\n- `win_pid`\n- `win_pname`\n\nIf you have installed everything correctly, you can run Nitro :\n`sudo ./nitro.py nitro_win7x64`\n\nAn event should now look like this:\n~~~JSON\n  {\n    \"event\": {\n      \"cr3\": \"0xbda6000\",\n      \"direction\": \"enter\",\n      \"type\": \"syscall\",\n      \"vcpu\": 0,\n      \"rax\": \"0x14\"\n    },\n    \"name\": \"nt!NtQueryValueKey\",\n    \"process\": {\n      \"name\": \"services.exe\",\n      \"pid\": 456\n    }\n  },\n~~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwenzel%2Fnitro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwenzel%2Fnitro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwenzel%2Fnitro/lists"}