{"id":13552458,"url":"https://github.com/sickcodes/Docker-eyeOS","last_synced_at":"2025-04-03T03:31:49.823Z","repository":{"id":41376570,"uuid":"300319336","full_name":"sickcodes/Docker-eyeOS","owner":"sickcodes","description":"Run iPhone (xnu-arm64) in a Docker container! Supports KVM + iOS kernel debugging (GDB)! Run xnu-qemu-arm64 in Docker! Works on ANY device.","archived":false,"fork":false,"pushed_at":"2022-01-18T03:51:57.000Z","size":1563,"stargazers_count":913,"open_issues_count":13,"forks_count":86,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-03-28T11:06:46.420Z","etag":null,"topics":["arm","docker","gdb","ios","kernel","xnu"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/sickcodes/docker-eyeos","language":"Shell","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/sickcodes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"sickcodes"}},"created_at":"2020-10-01T15:00:31.000Z","updated_at":"2025-03-27T05:19:54.000Z","dependencies_parsed_at":"2022-09-06T00:11:59.258Z","dependency_job_id":null,"html_url":"https://github.com/sickcodes/Docker-eyeOS","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/sickcodes%2FDocker-eyeOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sickcodes%2FDocker-eyeOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sickcodes%2FDocker-eyeOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sickcodes%2FDocker-eyeOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sickcodes","download_url":"https://codeload.github.com/sickcodes/Docker-eyeOS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246933426,"owners_count":20857049,"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":["arm","docker","gdb","ios","kernel","xnu"],"created_at":"2024-08-01T12:02:04.319Z","updated_at":"2025-04-03T03:31:44.801Z","avatar_url":"https://github.com/sickcodes.png","language":"Shell","funding_links":["https://github.com/sponsors/sickcodes"],"categories":["Shell","Shell (473)"],"sub_categories":[],"readme":"# Docker-eyeOS\n\nRun the iPhone's xnu-qemu-arm64 (iOS) in a Docker container\n\nSupports KVM + GDB kernel debugging! Run armv8-A in a Docker! Works on ANY device!\n\n## [Follow us @sickcodes on Twitter for updates!](https://twitter.com/sickcodes)\n\n![Docker-eyeOS iOS Kernel Debugging](/Docker-eyeOS.gif?raw=true \"Docker-eyeOS iOS Kernel Debugging\")\n\n### Docker-eyeOS v1.0.12.1\n# Features In Docker-eyeOS\n- qemu-system-aarch64 boot into iOS!\n- Runs on ANY device\n- FULL iOS armv8-A GDB Kernel debugging support (step thru \u0026 debug the iOS kernel on Linux!)\n- X11 Forwarding (future Display)\n- SSH on localhost:2222 or container.ip:2222\n- GDB on localhost:1234 or container.ip:1234\n- QEMU Full xnu-qemu-Virtualization\n- Container host Arch\n\n### Author:\n- Sick.Codes Team [@sickcodes](https://twitter.com/sickcodes)\n- [https://twitter.com/sickcodes](https://twitter.com/sickcodes)\n- [https://sick.codes/](https://sick.codes/)\n- [https://github.com/sickcodes](https://github.com/sickcodes)\n\nRun iPhone (xnu-arm64) in a Docker container! Supports KVM + iOS kernel debugging (GDB)! Run xnu-qemu-arm64 in Docker! Works on ANY device.\n\n# Dockerhub\n\n[https://hub.docker.com/r/sickcodes/docker-eyeos](https://hub.docker.com/r/sickcodes/docker-eyeos)\n\n```bash\n\nmkdir -p images\ncd images\n\nwget https://images.sick.codes/hfs.sec.zst\nwget https://images.sick.codes/hfs.main.zst\n\n# decompress images, uses about 15GB\nzstd -d hfs.main.zst\nzstd -d hfs.sec.zst\n\ndocker pull sickcodes/docker-eyeos:latest\n\ndocker run -it --privileged \\\n    --device /dev/kvm \\\n    -e RAM=6 \\\n    -e HFS_MAIN=./images/hfs.main \\\n    -e HFS_SEC=./images/hfs.sec \\\n    -p 2222:2222 \\\n    -v \"$PWD:/home/arch/docker-eyeos/images\" \\\n    -e \"DISPLAY=${DISPLAY:-:0.0}\" \\\n    -v /tmp/.X11-unix:/tmp/.X11-unix \\\n    sickcodes/docker-eyeos:latest\n\n\nssh root@localhost -p 2222\n\n# password is alpine\n\n# -----\u003e Try to SSH about 4 times\n# -----\u003e also needs to HIT ENTER a few times in the terminal to kick it along\n\n\n```\n\n## NOTE:\n\n- Hit enter a few times in the container terminal until you see `-bash-4.4#`\n\n- SSH into the container on `localhost:2222` or `containerIP:2222`\n\n\n# RUN Docker-eyeOS with GDB iOS Kernel Debugging!\n\n```bash\n\ndocker run -it --privileged \\\n    --device /dev/kvm \\\n    -e RAM=6 \\\n    -e HFS_MAIN=./images/hfs.main \\\n    -e HFS_SEC=./images/hfs.sec \\\n    -p 2222:2222 \\\n    -v \"$PWD:/home/arch/docker-eyeos/images\" \\\n    -e \"DISPLAY=${DISPLAY:-:0.0}\" \\\n    -v /tmp/.X11-unix:/tmp/.X11-unix \\\n    -p 1233:1234 \\\n    -e GDB_ARGS='-S -s' \\\n    sickcodes/docker-eyeos:latest\n\n# image will halt\n\n# get container ID\ndocker ps\ndocker exec -it 3cb2d14fc11a /bin/bash -c \"cd /home/arch/docker-eyeos/xnu-qemu-arm64-tools/gdb; gdb-multiarch -q\"\n\n# run \nsource load.py\ntarget remote localhost:1234\n\n\n```\n\n\n### Export PATH\n\n```bash\n# once you have SSH'ed in, export PATH and look busy!\nexport PATH=/iosbinpack64/usr/bin:/iosbinpack64/bin:/iosbinpack64/usr/sbin:/iosbinpack64/sbin:$PATH\n\n```\n\n### How do I mount the disk and put stuff in there?\n\n```bash\nsudo losetup -f \nsudo losetup /dev/loop0 ./hfs.main\n\n# mount in a file manager\n\n# unmount and delete loop device when done\nsudo losetup -d /dev/loop0\n```\n\n# Upstream Projects\n\n- [xnu-qemu-arm64](https://github.com/alephsecurity/xnu-qemu-arm64) a.k.a the guts of this project\n- [xnu-qemu-arm64-tools](https://github.com/alephsecurity/xnu-qemu-arm64-tools)\n\n# Upstream Masterminds\nSupported by:\n\n- Aleph Security [@AlephSecurity](https://alephsecurity.com/)\n- Vera Mens [@v3rochka GitHub](https://github.com/V3rochka) \u0026\u0026 [@v3rochka Twitter](https://twitter.com/V3rochka)\n- Jonathan Afek [@jonyafek GitHub](https://github.com/jonyafek) \u0026\u0026 [@JonathanAfek Twitter](https://twitter.com/JonathanAfek)\n- Lev Aronsky [@aronsky GitHub](https://github.com/aronsky) \u0026\u0026 [@levaronsky Twitter](https://twitter.com/levaronsky)\n\nTCP Tunnel for Linux rework:\n\n- MCApollo [@MCApollo GitHub](https://github.com/MCApollo/)\n\n# Requirements\n\n- 20GB++ of Disk Space\n- QEMU\n- KVM\n\n# GDB Debugging\n\n```bash\n\n# run Docker-eyeOS with\n-e GDB_ARGS='-S -s' \\\n\n# get container id\ndocker ps\n\n# run gdb-multiarch\ndocker exec containerid /bin/bash -c \"cd /home/arch/docker-eyeos/xnu-qemu-arm64-tools/gdb; gdb-multiarch -q\"\n\n# run \nsource load.py\ntarget remote localhost:1234\n\n```\n\n\nRun outside the container\n```bash\n# Ubuntu, Debian, Pop!_OS\nsudo apt install gdb-multiarch\n# Arch, Majaro\nsudo pacman -S gdb-multiarch\n```\n\n```bash\ngit clone https://github.com/alephsecurity/xnu-qemu-arm64-tools.git\ncd ./xnu-qemu-arm64-tools/gdb\nsudo gdb-multiarch -q\nsource load.py\ntarget remote localhost:1234\n```\n\n\n\n# Coming Soon   \n\n- ARCH: xnu-qemu-arm64 for iOS 14\n- ETA: son, follow [@sickcodes](https://twitter.com/sickcodes) \u0026\u0026 [@sickcodes](https://twitter.com/sickcodes)\n\n# Supported\n\n## KVM\n\n### Requires a device that supports armv8-A\n\nSee [https://alephsecurity.com/2020/07/19/xnu-qemu-kvm/](https://alephsecurity.com/2020/07/19/xnu-qemu-kvm/)\n\n```bash\n# proposed docker env command line args when KVM \n    -e KVM=true\n    -e KVM=false\n\n```\n\n# What does it do?\n\nDocker-eyeOS is an exploration platform for researchers and anyone who is interested in the XNU kernel.\n\n# Images\n\n- Create your own using [Docker-OSX](https://github.com/sickcodes/Docker-OSX) \n- And then run `osx-build-xnu-disks.sh` shell script.\n\n[Image build script for Docker-OSX](https://github.com/sickcodes/Docker-eyeOS/blob/master/osx-build-xnu-disks.sh)\n\n```bash\n# compress images for any reason\nzstd -k hfs.main\nzstd -k hfs.sec\n\n# decompress images\nzstd -d hfs.main.zst\nzstd -d hfs.sec.zst\n\n# after you decompress HFS Plus images, you must fsck them until they are OK using hfsprogs.\n\nfsck.hfsplus -fp ./hfs.sec\nfsck.hfsplus -fp ./hfs.sec\nfsck.hfsplus -fp ./hfs.main\nfsck.hfsplus -fp ./hfs.main\n\n```\n\n# Optional Flags\n\nDownload pre-patched image -\n- WARNING 1.8GB of disks are downloaded\n- Expands to 12GB of disks uncompressed\n\n`-e GDB_PORT=1234`\n\nDefault is already set to 1234, feel free to change it\n\n`-e GDB=true`\n\nEnables GDB (QEMU will be interrupted until GDB starts)\n\n# Unpatched Version\n\n- Alternatively, you can create your own disks as abov\n\n- If you do not wish to patch `dyld` then you should include all 4 files in your images folder:\n\n`./hfs.main`\n\n`./hfs.sec`\n\n`./static_tc`\n\n`./tchashes`\n\n\n# To Do (Help Wanted)\n\n### Ad hoc images\n\n`-e STORAGE=host`\n\nStore the images in ./images on the host folder\n\n`-e STORAGE=guest`\n\nStore the images in a local folder inside the container (Watch out for disk space usage if doing this)\n\n\n### VNC\n\n```bash\nmkdir screendump\ncd screendump\nwget https://github.com/cosmosgenius/screendump/releases/download/0.0.3/com.cosmosgenius.screendump_0.0.3_iphoneos-arm.deb\nsudo pacman -S wget\nwget https://github.com/cosmosgenius/screendump/releases/download/0.0.3/com.cosmosgenius.screendump_0.0.3_iphoneos-arm.deb\nar -x com.cosmosgenius.screendump_0.0.3_iphoneos-arm.deb\ntar -xzvf data.tar.lzma\n# mount and put in the disk\n```\n\n### Solve outbound networking\n```bash\n\nbash -i \u003e\u0026 /dev/tcp/google.com/80 0\u003e\u00261          # requires DNS\nbash -i \u003e\u0026 /dev/tcp/172.217.22.142/80 0\u003e\u00261      # perhaps -netdev\n\n```\n\n# How to build your own hfs.main and hfs.sec disk on GNU/Linux for Docker-eyeOS\n\nNote: this process can take around 1-4 hours depending on your specs.\n\n- Use OSX or create a quick OSX-KVM using [Docker-OSX](https://github.com/sickcodes/Docker-OSX)\n\n```bash\n# this is Docker-OSX btw\ndocker run --device /dev/kvm \\\n--device /dev/snd \\\n-e RAM=12 \\\n-p 50922:10022 \\\n-v /tmp/.X11-unix:/tmp/.X11-unix \\\nsickcodes/docker-osx:latest\n```\n\n- Complete the graphical installation, guide here: [https://github.com/sickcodes/Docker-OSX#additional-boot-instructions](https://github.com/sickcodes/Docker-OSX#additional-boot-instructions)\n\n- Turn on SSH in `Sharing Settings`\n\n- Write down your docker container ID with `docker ps`, e.g. `f771bff2192d`\n-- You can start the docker later using `docker run f771bff2192d`\n-- You don't need to login to SSH into the Docker-OSX\n\n- SSH into your [Docker-OSX](https://github.com/sickcodes/Docker-OSX) and add yourself as a NOPASSWD root user (extremely insecure, only do if you will tear-down later).\n\n```bash\n\n# OPTIONAL SPEED UP\nssh fullname@localhost -p 50922\n\nsudo tee \"/private/etc/sudoers.d/sudoers_$USER\" \u003c\u003cEOF\n${USER} ALL = (ALL) NOPASSWD: ALL\nEOF\n\n```\n\n- Complete the script on OSX that is inside this repo\n\n[https://github.com/sickcodes/Docker-eyeOS/blob/master/osx-build-xnu-disks.sh](https://github.com/sickcodes/Docker-eyeOS/blob/master/osx-build-xnu-disks.sh)\n\n- Pull the images out when you're done:\n\n```bash\n\nscp -P 50922 fullname@localhost:~/static_tc .\nscp -P 50922 fullname@localhost:~/tchashes .\nscp -P 50922 fullname@localhost:~/hfs.main .\nscp -P 50922 fullname@localhost:~/hfs.sec .\n\n```\n\nEnjoy!\n\n# \u003c3 Sick.Codes(https://sick.codes)\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsickcodes%2FDocker-eyeOS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsickcodes%2FDocker-eyeOS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsickcodes%2FDocker-eyeOS/lists"}