{"id":20009878,"url":"https://github.com/plsyssec/lim_rlbox_firefox_root","last_synced_at":"2026-02-15T17:10:01.654Z","repository":{"id":144629425,"uuid":"298687748","full_name":"PLSysSec/lim_rlbox_firefox_root","owner":"PLSysSec","description":null,"archived":false,"fork":false,"pushed_at":"2021-03-09T22:28:55.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-02T01:44:09.680Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Makefile","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/PLSysSec.png","metadata":{"files":{"readme":"README.md","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-25T22:00:08.000Z","updated_at":"2021-03-09T22:28:58.000Z","dependencies_parsed_at":"2023-07-04T19:35:36.343Z","dependency_job_id":null,"html_url":"https://github.com/PLSysSec/lim_rlbox_firefox_root","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PLSysSec/lim_rlbox_firefox_root","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Flim_rlbox_firefox_root","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Flim_rlbox_firefox_root/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Flim_rlbox_firefox_root/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Flim_rlbox_firefox_root/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PLSysSec","download_url":"https://codeload.github.com/PLSysSec/lim_rlbox_firefox_root/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Flim_rlbox_firefox_root/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275063439,"owners_count":25398995,"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","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-13T07:17:22.666Z","updated_at":"2026-02-15T17:09:56.611Z","avatar_url":"https://github.com/PLSysSec.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Repo\n\nThis is the top level repo for the lim + rlbox integration into Firefox. This repo is self sufficient in that it will pull all required repos as part of the builds.\n\nThis repo expects sets up the Firefox inside a docker image. This docker image is then run in simulator that supports LIM. We will refer to these environments as follows\n\n- **lab_host** - Terminal on the machine running the SIMICS software\n- **host** - Terminal on the machine running the Docker image\n- **guest** - Terminal in the Docker image (inside the SIMICS simulation)\n- **simics** - Terminal to run the simics commands like start and stop etc.\n\n**Important** - This repo makefile contains different targets meant for each of the the above enviroments. So all description below will explicitly state which environment to run the command in.\n\nThis repo will automatically pull in the following repos\n- rlbox_sandboxing_api \n- rlbox_lim_sandbox\n- lim_firefox\n- lim_simics (SPR's simics repo with LIM wrappers and LIM simics model)\n\n# Loading a build of this repo\n\n## Via checkpoint\n\nThe recommended way to load the built code in this repo is to use an exising checkpoint if you have access to these.\n\nTo load a checkpoint simply run\n\n```bash\n./simics \u003cpath to checkpoint\u003e\n# Run the following in the simics console\nenable-real-time-mode\nconnect-real-network target-ip = 10.10.0.100\nrun\n```\n\nNow in the terminal that runs is actually a \"guest\" terminal --- it is connected to the docker instance.\n\n## Building from scratch\n\n1. First clone this repo in a fresh directory and in your lab_host machine.\n\n2. Next, it is probably a good idea to build the full repo in you lab_host machine, as this will be your dev environment. You can do this by running the command in a lab_host terminal\n\n    ```\n    make build_guest\n    ```\n\n    or alternately, you can just pull the source code with \n\n    ```\n    make get_source\n    ```\n\n3. Make sure you have enabled VMP in your lab_host machine for simics acceleration. If you haven't already set this up, you can do this by running the following command in a lab_host terminal\n\n    ```\n    make setup_simics_host\n    ```\n\n4. Launch simics with a fresh QSP image by running the following in a lab_host terminal\n\n    ```\n    ./lim_rlbox_firefox_root/lim_simics/simics targets/qsp-x86/qsp-clear-linux.simics\n    ```\n\n5. Setup the qsp image by running the following commands in the guest_terminal.\n\n    ```\n    sudo swupd update\n    sudo swupd bundle-add c-basic containers-basic\n    sudo systemctl start docker\n    ssh-keygen -t rsa -N '' -f ~/.ssh/id_rsa \u003c\u003c\u003c y\n    echo 'Add current SSH key in ~/.ssh/id_rsa to access github repos. You can do this by adding this key to you gitlab/github accounts'\n    ```\n\n6. Clone this repository in the **host** terminal with the commands\n\n    ```\n    git clone \u003cgit root\u003e/lim/lim_rlbox_firefox_root.git\n    cd lim_rlbox_firefox_root\n    ```\n\n7. Next in the host terminal run the command  `make build_host` (It took overnight to finish the builds). This basically runs a docker inside simics, pulls all the source files/directories inside docker. Then runs docker/Dockerfile script, which build debug and release firefox. Once the build is finished, you’ll see ‘build successfully finished’. Please ignore error messages like ‘channel error’\n\n8. You can now save your checkpoint with the command shown below. You can use this checkpoint going forward.\n\n    ```\n    write-configuration -independent-checkpoint ../path_to_save/lim_firefox.ckpt\n    ```\n\n# Updating the firefox build with latest src\n\nIn the guest terminal (terminal with the green font) --- note that this is connected to the docker instance. Here you can just pull the latest code for all repos and build. Note that initial builds of Firefox take a long time, but incremental builds are quite fast.\n\n```bash\n# get latest code\nmake pull\n```\nThen either run\n\n```\n# build debug firefox that uses lim\nmake build_guest_debug\n```\n\nor \n\n```\n# build release firefox  that uses lim\nmake build_guest_release\n```\n\n**Optional** You can also build versions of Firefox that do not use lim, but instead uses WASM or Firefox that uses neither wasm or lim. Note that these builds are not created by default when \"Building from scratch\", so the first time you run this command, will be very slow as it has to do a full build.\n\nTo build Firefox that uses Wasm instead of LIM, use the below commands. Note that gdb will not understand WASM modules, so debugging WASM'd code can be painful without symbols.\n\n```\n# Firefox that uses WASM instead of LIM\nmake build_guest_nolim_debug\nmake build_guest_nolim_release\n```\n\nIf you want to build Firefox without Wasm or LIM, then use\n\n```\n# Firefox that does not use WASM or LIM\nmake build_guest_nosbx_debug\nmake build_guest_nosbx_release\n```\n\n# Running the png benchmark and saving a screenshot\n\nAfter building the debug or release version of firefox, you can run the benchmark.\n\nFirst enable the lim model in SIMICS with the compartment id extension with the SIMICS command shown below.\n\n```\nnew-lim-model -connect-all -use-compartment-id\n```\n\nYou can then run the below command in the **guest** terminal to run the png benchmark. Note that this benchmark runs on whichever firefox was built last --- debug or release.\n\n```bash\nmake test_guest_png\n```\n- If it’s successful, you’ll see the following in the guest terminal\n\n   ```\n   !!!!!!!!!!!!!!!Finished rendering PNG (file:///usr/src/lim_rlbox_firefox_root/lim_firefox/testing/talos/talos/tests/png_perf_test/png_perf_test.png): 800x600\n   ```\n\n    Once the image is successfully rendered, if you want to take screenshot, run the below command in a fresh **lab_host** terminal \n\n    ```bash\n    make guest_get_screenshot\n    ```\n\n    This will save the image to the **lab_host** file system under `$(SRC_DIR)/lim_rlbox_firefox_root/screenshots`. \n\n- If firefox fails with a segfault you will see a stack trace. If this happens see the section on \"debugging below\".\n\nAfter this you will have to force close Firefox as this does not auto close. You can use CTRL+C for this. Note that Firefox may leave zombie processes, so make sure to kill all processes by looking at the output of the command `ps aux | grep firefox` in the guest environment.\n\n\n# Making changes to Firefox\n\n## First test on lab-host enviroment\nTo make changes, it is recommended you first test changes in the **lab_host** environment --- i.e. test changes without LIM. To do this, simply go to the file `lim_rlbox_firefox_root/rlbox_lim_sandbox/c_src/lim_sandbox_wrapper.c` and change the line\n\n```cpp\nconst bool ACTUALLY_USE_LIM = true; // Make this false to disable lim\n```\n\nDo not push this! This for local debugging on the lab_host machine.\n\nIf you see any crashes in the lab_host machine (without lim) fix that first. To debug firefox, I recommend the `rr` reversible debugger. Since Firefox is multi-process and multi-thread, this is the best way to debug this.\n\nAfter fixing this, push your changes.\n\n## Update and test the build in your guest environment with LIM\n\nSee updating the build section to build the debug version of firefox.\n\nThen test the png benchmark as described in \"Running the png benchmark and saving a screenshot\". If this is unsuccessful, see \"Debugging a crash\" below.\n\n# Debugging a crash\n\nIf you make a change to Firefox that causes a crash in the guest environment, we can attach gdb to look at the current backtrace with symbols. We will not use the SIMICS debuggger but rather the one inside the **guest** environment.\n\n**Important** - Make sure to use the debug build of firefox for the next steps. You can debug the release build, but symbol support etc. is not great.\n\n## Identify the details of the crash.\n\nFirefox's debug build crashes with a stack trace followed by the message `Sleeping for 300000 seconds`. Additionally you will also see a message similar to \n\n```\nAttach a debugger with the command 'gdb /usr/src/lim_rlbox_firefox_root/build/obj-ff-dbg/dist/bin/firefox 14847'\n```\n\nHere 14847 is the PID of Firefox. Note this PID for next step.\n\n## Save and reload a checkpoint without LIM\n\nStop the current simics session and save the checkpoint. (Do **not** use an independent checkpoint. It takes too long!). Restart SIMICS with the checkpoint by following the instructions in \"Loading a build of this repo/Via checkpoint.\" Make sure to run the connect-real-network command!\n\nImportantly, do **not** load the LIM simics model. The simulation will become too slow to attach the debugger. \n\n## Attach the debugger\n\nRun the command in a fresh **lab_host** terminal to attach gdb to the firefox running in the guest enviroment.\n\n```bash\nmake guest_attach_debugger\n# Enter the PID observed earlier in step 1 when prompted\n```\n\n## Locate the crash\n\nA firefox process has multiple threads, so to find the one that crashed, use the gdb command\n\n```\ninfo threads\n```\n\nYou will see a list of threads. Any thread that has the top function `nano_sleep` is likely a crashed thread that is sleeping until a debugger is attached. Switch to that thread. If that was thread 12, use gdb command\n\n```\nthread 12\n```\n\n\nIf you then print the backtrace, you will see the crash. You can tell if it is crash because the first 5 or 6 frames will be various firefox crash handling routines such as the `signal raised`, `ah_crap_handler` etc. You will see your code that caused a crash about 7 frames into the `bt`. You can swich to these frames, query variables etc.\n\n# List of all available makefile targets\n\n(Some targets not listed as there is no need to look at those. Some targets below are run automatically by others as part of the build.)\n\n- **setup_simics_host** - setup some lab_host computer to be ready to run simics by enabling vmp.\n- **get_source** - Get the code of all sub repos needed by this repo. Update the code of this and all sub repos pulled in. Can be run in lab_host, or guest env.\n- **pull** - Update the code of this and all sub repos pulled in. Can be run in lab_host, or guest env.\n- **setup_host** - Sets up the host environment by installing docker etc.\n- **setup_guest** - Sets up the guest environment by installing Firefox dependencies etc.\n- **build_guest_debug** - Build debug version of Firefox with LIM. Should be run in the guest env. You can this in lab_host also, but a lim build will not be very useful there as you can't run it.\n- **build_guest_release** - Build release version of Firefox with LIM. Should be run in the guest env. You can this in lab_host also, but a lim build will not be very useful there as you can't run it.\n- **build_guest_nolim_debug** - Build debug version of Firefox with Wasm. Should be run in the lab_host env. You can this in guest also.\n- **build_guest_nolim_release** - Build release version of Firefox with Wasm. Should be run in the lab_host env. You can this in guest also.\n- **build_guest_nosbx_debug** - Build debug version of Firefox without Wasm \u0026 without LIM. Should be run in the lab_host env and useful for basic debugging of Firefox outside of LIM related issues. You can this in guest also.\n- **build_guest_nosbx_release** - Build release version of Firefox without Wasm \u0026 without LIM. Should be run in the lab_host env and useful for basic debugging of Firefox outside of LIM related issues. You can this in guest also.\n- **build_host** - Setup the host, then build the docker image of a guest env that has also been setup. Can be run in the host env.\n- **test_guest_graphite** - Run the graphite font library test. I haven't run this in a while, but this was passing when I last checked. Can be run in the lab_host or guest env. Successful completion will say something like \"TESTS 5/5 pass\".\n- **test_guest_png** - Run the png image rendering test. Can be run in the lab_host or guest env. If successful you will see the message \"!!!!!!!!!!!!!!!Finished rendering PNG ...\"\n- **guest_get_screenshot** - Get a screenshot of firefox that is currently running and save it in `$(SRC_DIR)/lim_rlbox_firefox_root/screenshots`. Must be run in lab_host env.\n- **guest_attach_debugger** - Attach to the Firefox running in the guest env. Command must be run in lab_host env. The target will prompt for the PID of the guest Firefox process to attach to.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplsyssec%2Flim_rlbox_firefox_root","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplsyssec%2Flim_rlbox_firefox_root","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplsyssec%2Flim_rlbox_firefox_root/lists"}