{"id":13508461,"url":"https://github.com/airbus-seclab/ramooflax","last_synced_at":"2025-04-15T01:54:29.379Z","repository":{"id":86152214,"uuid":"1859646","full_name":"airbus-seclab/ramooflax","owner":"airbus-seclab","description":"a bare metal (type 1) VMM (hypervisor) with a python remote control API","archived":false,"fork":false,"pushed_at":"2018-02-08T11:26:51.000Z","size":2308,"stargazers_count":182,"open_issues_count":2,"forks_count":35,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-04-15T01:54:24.731Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/airbus-seclab.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2011-06-07T12:26:45.000Z","updated_at":"2025-03-29T13:20:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"95fc57fa-e181-449b-9b1e-8112abf854bd","html_url":"https://github.com/airbus-seclab/ramooflax","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/airbus-seclab%2Framooflax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Framooflax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Framooflax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airbus-seclab%2Framooflax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airbus-seclab","download_url":"https://codeload.github.com/airbus-seclab/ramooflax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991540,"owners_count":21194894,"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-08-01T02:00:53.318Z","updated_at":"2025-04-15T01:54:29.363Z","avatar_url":"https://github.com/airbus-seclab.png","language":"C","funding_links":[],"categories":["Research Projects","C","others"],"sub_categories":["AMD"],"readme":"#+LANGUAGE: en\n#+OPTIONS: H:3 num:nil toc:nil \\n:nil @:t ::t |:t ^:t -:t f:t *:t \u003c:t\n#+OPTIONS: TeX:t LaTeX:nil skip:nil d:nil todo:t pri:nil tags:not-in-toc\n#+EXPORT_EXCLUDE_TAGS: exclude\n#+STARTUP: showall\n\n* What is Ramooflax ?\n\nRamooflax is a free and open source (GPLv2) virtualization tool.\n\nRamooflax aims at analyzing/debugging/controlling modern operating systems and complex software pieces as well as real life BIOS running on a *physical* machine.\n\nRamooflax provides a small hypervisor and a remote client allowing high-level access to the features implemented into the hypervisor.\n\n* On what hardware does it run ?\n\nRamooflax has been implemented for the PC world. That is Intel and AMD x86 32 and 64 bits.\n\nRamooflax relies on hardware virtualization extensions (AMD-V and Intel VT-x) that can be found in *recent* CPUs.\n\nFor Intel ones, Ramooflax needs /EPT/ and /Unrestricted guest/ features present since the *Westmere* microarchitecture. More details can be found on this [[http://en.wikipedia.org/wiki/Nehalem_(microarchitecture)][wikipedia]] page.\n\nFor AMD ones, the only required feature is /RVI/ and can be found into *Phenom II* CPUs. Some details are given on this [[http://en.wikipedia.org/wiki/AMD-V#AMD_virtualization_.28AMD-V.29][wikipedia]] page.\n\nRamooflax can run under VMware workstation/fusion using the \"virtualize vm-x/EPT\" feature. But you still need a skilled enough CPU.\n\nNotice that you can also run Ramooflax under Bochs 2.4.6.\n\n* How does it work ?\n\nRamooflax starts during the boot process of the machine. It can be seen as the first operating system started by the BIOS.\n\nOnce started, Ramooflax will automatically virtualize the running BIOS and all the /to be run/ software pieces.\n\nFor instance, if you already have installed an operating system, it will be started as a virtual machine.\n\nRamooflax is an hypervisor dedicated to only one virtual machine, running in a virtualized environment which is as close as its native environment.\n\nRamooflax needs to be installed on a bootable storage (ie USB key with GRUB).\n\n* Documentation\n\nAll documents can be found on the Ramooflax [[https://github.com/sduverger/ramooflax/wiki][wiki]] pages.\n\n* Software requirements\n\nramooflax has been compiled/tested using gcc-4.8. The loader is a 32 bits ELF while the setup and vmm kernels are 64 bits ELF.\n\nUnder Debian-like systems, the following packages are needed whether you run a 32 or 64 bits OS:\n\n$ sudo apt-get install gcc-4.8 gcc-4.8-multilib make\n\n* Limitations\n\nIntel and AMD are *both* supported. Notice that multi-cores feature is not supported yet, so you will only have one core while running virtualized.\n\nIt is recommended to read the documentation.\n\n* Obtaining\n\n$ git clone git@github.com:sduverger/ramooflax.git\n\n* Configuring\n\nFirst cleanup everything and call the specific configuration menu to choose your components\n\n$ make distclean config\n\nUnder the /build/ menu you will be able to choose from Intel or AMD manufacturer, which control device you want to use, debug device and so on.\n\nFor the time being, it is recommended to use NET as controlling device and UART as debugging one.\n\n* Building\n\nOnce configured you can run\n\n$ make\n\nThis will build the loader, setup and vmm binaries.\n\n* Installing\n\n$ make install\n\nThe installation rules looks for a script named /installer.sh/. We provide example scripts, located in /tools/, which update VMware and QEMU virtual disk images. You can define your own one and override the /INSTOOL/ make variable:\n\n#+BEGIN_EXAMPLE\nmake INSTOOL=tools/installer_qemu.sh install\n#+END_EXAMPLE\n\nRamooflax needs a /multiboot compliant/ bootloader (such as GRUB). The following GRUB 1 (legacy) entry can be defined to boot ramooflax:\n\n#+BEGIN_EXAMPLE\ntitle  Ramooflax\nroot   (hd0,0)\nkernel /loader.bin\nmodule /setup.bin\nmodule /vmm.bin pool=1234 ip=192.168.0.2 gateway=192.168.0.1 netmask=255.255.255.0\n#+END_EXAMPLE\n\nWe also provide a disk image creation tool (which needs GRUB legacy), in /tools/:\n\n#+BEGIN_EXAMPLE\nsudo ./tools/create_disk.sh ramooflax.img 32M ../grub/ loader/build/loader.bin setup/build/setup.bin vmm/build/vmm.bin \n\n[+] building disk image (32MB)\n[+] create part on disk image\n[+] formating disk\n[+] mounting disk\n[+] copy grub\n[+] installing files\n[+] configure grub\n[+] install grub\n[+] unmounting disk\n\nDisk is ready !\n- mnt it using : \"mount -o loop,offset=512 ramooflax.img /mnt\"\n- run it using : \"qemu -hda ramooflax.img\"\n#+END_EXAMPLE\n\nThe tool builds a GRUB bootable disk image of the given size, with ramooflax as default entry.\n\n* Using\n\nYou will need python (tested with 2.6.x) to run the client.\n\n** EHCI interface\n\nIf you use the EHCI Debug device configuration to control the hypervisor from the remote client, you will need a USB debug device on the client side.\n\nYou can either buy one or use the DBGP USB Gadget provided into the Linux kernel since the 2.6.36 version.\n\nTo be able to use such a Gadget, you need a *device* USB controller as found in embedded ARM development boards or smartphones.\n\nPlease read documentation to have usage examples of the client API.\n\n** Network interface\n\nDo not forget to provide Ramooflax network settings on vmm module cmd line into the GRUB configuration entry.\n\nAs shown into /Installing/ section, you can provide /ip/, /netmask/ and /gateway/ options to the vmm module.\n\nReaching the hypervisor will depend on your setup (real machine, running on a host using VMware, ...) for the IP configuration part.\n\nThe VMM is listening to /UDP/ port /1337/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbus-seclab%2Framooflax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairbus-seclab%2Framooflax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairbus-seclab%2Framooflax/lists"}