{"id":31715351,"url":"https://github.com/hqarroum/microbox","last_synced_at":"2025-10-09T01:57:45.277Z","repository":{"id":317189118,"uuid":"1053049829","full_name":"HQarroum/microbox","owner":"HQarroum","description":"📦 Lightweight, ephemeral, sandboxes for Linux.","archived":false,"fork":false,"pushed_at":"2025-09-29T11:33:19.000Z","size":481,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T13:21:03.087Z","etag":null,"topics":["containers","linux","namespaces","sandbox"],"latest_commit_sha":null,"homepage":"","language":"Go","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/HQarroum.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-08T23:26:10.000Z","updated_at":"2025-09-29T12:25:07.000Z","dependencies_parsed_at":"2025-09-29T13:21:11.945Z","dependency_job_id":"dd4878c4-78c5-4ec6-8ca5-d508259fe1ca","html_url":"https://github.com/HQarroum/microbox","commit_stats":null,"previous_names":["hqarroum/microbox"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/HQarroum/microbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HQarroum%2Fmicrobox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HQarroum%2Fmicrobox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HQarroum%2Fmicrobox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HQarroum%2Fmicrobox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HQarroum","download_url":"https://codeload.github.com/HQarroum/microbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HQarroum%2Fmicrobox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000696,"owners_count":26082894,"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-10-08T02:00:06.501Z","response_time":56,"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":["containers","linux","namespaces","sandbox"],"created_at":"2025-10-09T01:57:43.479Z","updated_at":"2025-10-09T01:57:45.267Z","avatar_url":"https://github.com/HQarroum.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"280\" src=\"assets/icon.png\" alt=\"logo\" /\u003e\n  \u003cbr /\u003e\n  \u003cp align=\"center\"\u003eCreate lightweight sandboxes for Linux with host isolation, rootfs images, and networking.\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/codespaces/new/HQarroum/microbox\"\u003e\n      \u003cimg alt=\"Github Codespaces\" src=\"https://github.com/codespaces/badge.svg\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## 🔖 Features\n\n- **Sandbox Isolation** - Isolates networking, file-system, processes, and users from the host using Linux namespaces.\n- **Filesystem Images** - Uses an [Overlay FS](https://docs.kernel.org/filesystems/overlayfs.html) to mount a custom root file-system from a user image. Also supports minimal `tmpfs` dedicated to bind-mounting.\n- **Networking** - Provides full network isolation by default. `bridge` and `host` modes available.\n- **Bind-mounts** - Selective read-only/read-write bind-mounting of host directories into the sandbox.\n- **Security Features** - Seccomp filtering for syscall restrictions and Linux capability management support.\n- **Resource Limits** - Enforce CPU and Memory constraints using CGroups.\n\n## What is it ❓\n\nMicrobox is a sandbox runtime that creates ephemeral and isolated execution environments on Linux by combining specific kernel features such as [namespaces](https://en.wikipedia.org/wiki/Linux_namespaces), [cgroups](https://en.wikipedia.org/wiki/Cgroups), [seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html), and [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html). It provides lightweight sandboxes to run container-like applications securely.\n\nNamespacing in `microbox` provide *process*, *network*, *filesystem*, *IPC*, and *user* isolation, while cgroups provide resource limitation management, and can run with different filesystem modes, from completely isolated overlay root filesystems, to controlled access to host directories.\n\nMicrobox is built out of an educational purpose to understand how secure non VM based sandboxes can be on Linux. Its philosophy is to provide a maximum isolation by default, unlike other container runtimes such as [`runc`](https://github.com/opencontainers/runc), or [`Podman`](https://github.com/containers/podman) which make the choice of enforcing a good balance between security and usability of applications.\n\n## 🚀 Quickstart\n\nYou can run a simple rootfs image in an isolated sandbox in a couple minutes. First, follow the instructions in the [Creating a Root Filesystem](docs/create-root-fs.md) section to create a Ubuntu rootfs image on your host.\n\n\u003e Feel free to adapt the architecture and packages as needed in your image as needed.\n\n#### Install\n\nDownload the latest release from the [Releases](https://github.com/HQarroum/microbox/releases) page.\n\n#### Create a sandbox\n\nRun `microbox` to create an isolated sandbox using the rootfs image you just created. This will run an isolated sandbox with no network access, using the new rootfs image.\n\n```bash\n./microbox --fs \u003crootfs\u003e -- /bin/bash -c \"echo Hello Sandbox!\"\n```\n\n## Usage\n\n### Filesystem\n\nThe sandbox exposes a file-system that is ephemeral, isolated from the host—unless otherwise specified—and mounted in memory. As such, changes caused by applications within the sandbox's rootfs do not reflect on the host filesystem.\n\nBelow is a comparison table of the different root file-system options supported.\n\nMode | Ephemeral | Isolated | Notes\n---- | --------- | -------- | -----\n`tmpfs` | Yes | Yes | Default value. Full-isolation from the host, minimal rootfs with no binaries. Only `devfs` and `procfs` mounted.\n`rootfs` | Yes | Yes | Full-isolation from the host, mounts a user-provided rootfs.\n`host` | No | No | Minimal isolation, host file-system is available in the sandbox and writes reflect on the host.\n\n#### Mount a specific rootfs image\n\nUsing a custom rootfs image provides a complete environment with binaries and libraries in the sandbox. You can create your own rootfs image using the instructions in the [Creating a Root Filesystem](docs/create-root-fs.md) section.\n\n```bash\nmicrobox --fs ./ubuntu-24.04 -- /bin/ls\n```\n\n#### Control storage size\n\nThe default storage size is set to 512MB in the sandbox. Using the `--storage` option, you can control the size of the writable layer.\n\n```bash\nmicrobox --storage 2GB -- /bin/ls\n```\n\n#### Minimal Filesystem with `tmpfs`\n\nThis is the default, but you can make it explicit by specifying `--fs tmpfs`. In this mode, the sandbox exposes an empty rootfs with only `devfs` and `procfs` mounted.\n\n\u003e In this example, we bind-mount `/bin` and `lib` from the host to provide a minimal environment.\n\n```bash\nmicrobox \\\n  --mount-ro /bin:/bin \\\n  --mount-ro /lib:/lib \\\n  -- /bin/ls\n```\n\nYou can bind mount host directories into the sandbox using the `--mount-ro` and `--mount-rw` options.\n\n\u003e Note that writes made by the sandbox to writable bind mounts will affect the host filesystem.\n\n```bash\n./microbox \\\n  --mount-ro /etc:/etc \\\n  --mount-rw /tmp:/tmp \\\n  -- /bin/bash\n```\n\n### Network\n\nThe default network mode is `none`, which means no network access. You can change this behavior using the `--net` option.\n\n#### `none`\n\n\u003e No networking in sandboxes is the default, you can make it explicit by specifying `--net none`.\n\n```bash\n$ microbox --fs \u003crootfs\u003e -- /bin/curl google.com\ncurl: (6) Could not resolve host: google.com\n```\n\n#### `bridge` Network\n\nIn `bridge` mode, the sandbox gets its own network interface and IP address. It uses [`veth` pairs](https://man7.org/linux/man-pages/man4/veth.4.html) and NAT to provide network access between the host and the sandbox.\n\n```bash\n$ microbox --fs \u003crootfs\u003e --net bridge \\\n-- curl https://api.ipify.org/\n1.2.3.4\n```\n\n#### `host` network access\n\nHost networking does not provide any network isolation with the host. The sandbox shares the host network interface and network stack.\n\n```bash\n$ microbox --fs \u003crootfs\u003e --net host \\\n-- /bin/curl https://api.ipify.org/\n1.2.3.4\n```\n\n### Other Options\n\n#### Limit CPU\n\nYou can limit the number of CPU cores available to the sandbox using the `--cpus` option.\n\n```bash\n./microbox --cpus 1 -- /bin/bash\n```\n\n#### Limit Memory\n\nYou can limit the amount of memory available to the sandbox using the `--memory` option.\n\n```bash\n./microbox --memory 256M -- /bin/bash\n```\n\n#### Environment Variables\n\nYou can chain environment variables in the sandbox using the `--env` option.\n\n```bash\n./microbox --env MY_VAR=hello -- /bin/bash -c 'echo $MY_VAR'\n```\n\n#### Security Profiles\n\nYou can restrict the syscalls available to the sandbox using the `--allow-syscall` and `--deny-syscall` options.\n\n\u003e See the [Default Seccomp Profile](./sandbox/seccomp.go) section for more details on syscalls denied by default.\n\n```bash\n./microbox \\\n  --fs ./rootfs \\\n  --allow-syscall unshare \\\n  --allow-syscall setns \\\n  -- /bin/bash\n```\n\n#### Capabilities\n\nYou can add or drop Linux capabilities in the sandbox using the `--cap-add` and `--cap-drop` options.\n\n```bash\n./microbox \\\n  --fs ./rootfs \\\n  --cap-drop CAP_SETPCAP \\\n  -- /bin/bash\n```\n\n#### Custom DNS Servers\n\nYou can set custom DNS servers for the sandbox using the `--dns` option.\n\n\u003e By default, microbox uses [Google DNS Servers](https://developers.google.com/speed/public-dns/docs/using) for the sandbox.\n\n```bash\n./microbox \\\n  --fs ./rootfs \\\n  --dns 1.1.1.1 \\\n  --dns 8.8.8.8 \\\n  -- /bin/bash\n```\n\n#### Custom Hostname\n\nYou can set a custom hostname for the sandbox using the `--hostname` option.\n\n```bash\n$ ./microbox \\\n  --fs ./rootfs \\\n  --hostname my-sandbox \\\n  -- /bin/bash -c 'hostname'\nmy-sandbox\n```\n\n#### Read-only Rootfs\n\nYou can mount the root filesystem as read-only using the `--readonly` option to disable any writes to the rootfs.\n\n```bash\n./microbox \\\n  --fs \u003crootfs\u003e \\\n  --readonly \\\n  -- /bin/bash\n```\n\n#### User Namespace\n\nBy default, the sandbox runs in a new user namespace, mapping the root user in the sandbox to a user on the host. This can break the normal operations of some applications. You can disable this behavior using the `--userns host` option.\n\n\u003e This is recommended for working with applications such as `apt` which attempt to change the effective user ID at runtime.\n\n```bash\n./microbox \\\n  --fs \u003crootfs\u003e \\\n  --userns host \\\n  -- /bin/bash\n```\n\n#### Logging\n\nYou can control the log level and format using the `--log-level` and `--log-format` options.\n\n##### Log Levels\n\nLog Level | Scope\n--------- | -----\n`info` | Informational logs + warnings + errors\n`warn` | Warnings about potential issues + errors\n`error` | Display only errors\n\n##### Log Formats\n\nFormat | Description\n------ | -----------\n`text` | Human-readable text format (default)\n`json` | Structured JSON format\n\n#### Example\n\n```bash\n./microbox \\\n  --fs ./rootfs \\\n  --log-level info \\\n  --log-format json \\\n  -- /bin/bash\n```\n\n## 🛡️ Isolation\n\nBelow is a description of the isolation features provided by `microbox` by default.\n\n### Namespaces\n\nNamespace | Symbol | Enabled\n--------- | ------ | -------\nProcess | [`CLONE_NEWPID`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | ✅\nHostname and Domain name | [`CLONE_NEWUTS`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | ✅\nMount | [`CLONE_NEWNS`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | ✅\nIPC | [`CLONE_NEWIPC`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | ✅\nTime | [`CLONE_NEWTIME`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | ✅\nCgroups | [`CLONE_NEWCGROUP`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | ✅\nNetwork | [`CLONE_NEWNET`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | Enabled by default ✅. Can be disabled with `--net host`.\nUser | [`CLONE_NEWUSER`](https://man7.org/linux/man-pages/man7/namespaces.7.html) | Enabled by default ✅. Can be disabled with `--userns host`.\n\n### Limits\n\nLimit | Description | Default | Modifiable\n----- | ----------- | ------- | ----------\nCPU | Limit on the number of CPUs usable by the sandbox | 1 CPU | Yes\nMemory | Limit on the amount of memory usable by the sandbox | 1 GB | Yes\nStorage | Limit on the size of the mounted storage | 512 MB | Yes\nSwap | Limit on the amount of swap usable by the sandbox | Disabled | No\n\n## 📟 Options\n\n- `--fs MODE|DIR` - Filesystem mode: `host` (uses host filesystem), `tmpfs` (temporary filesystem), or a path to use a directory as the rootfs\n- `--net MODE` - Network mode: `none` (no network), `host` (use host network), `bridge` (bridged network with NAT)\n- `--mount-ro HOST:DEST` - Create read-only bind mount from host path to sandbox destination\n- `--mount-rw HOST:DEST` - Create read-write bind mount from host path to sandbox destination\n- `--readonly` - Mount the root filesystem as read-only\n- `--env KEY=VALUE` - Set environment variable in the sandbox\n- `--allow-syscall SYSCALL` - Allow specific system calls in the sandbox using seccomp\n- `--deny-syscall SYSCALL` - Deny specific system calls in the sandbox using seccomp\n- `--dns SERVER` - Set custom DNS server for the sandbox\n- `--hostname NAME` - Set custom hostname for the sandbox\n- `--cpus N` - Set CPU limit (e.g., 0.5 for half a core, 2 for two cores)\n- `--memory SIZE` - Set memory limit (e.g., 10MB, 2GB)\n- `--storage SIZE` - Set storage limit for the sandbox filesystem (e.g., 1GB, 10GB)\n- `--log-level LEVEL` - Set log level between `info`, `warn`, `error` (default: `error`)\n- `--log-format FORMAT` - Set log format: `text` or `json` (default: `json`)\n- `--cap-add CAPABILITY` - Add a Linux capability to the sandbox (e.g., `CAP_NET_ADMIN`)\n- `--cap-drop CAPABILITY` - Drop a specific Linux capability from the sandbox (e.g., `CAP_SYS_TIME`)\n- `--help` - Display help message\n\n## 🚧 Limitations\n\n- **Rootless Unsupported** - Sandbox creation currently requires root privileges to create namespaces, cgroups and a network bridge.\n- **OCI Support** - Not a full container runtime replacement, no OCI image support, focused on process isolation.\n- **No AppArmor/SELinux** - Does not currently support AppArmor or SELinux profiles for additional security layers.\n\n## 👀 See Also\n\n- [Linux Namespaces](https://man7.org/linux/man-pages/man7/namespaces.7.html) - Kernel documentation on namespaces\n- [Seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html) - System call filtering\n- [Cgroups](https://man7.org/linux/man-pages/man7/cgroups.7.html) - Resource control groups\n- [OverlayFS](https://docs.kernel.org/filesystems/overlayfs.html) - Union filesystem for layering filesystems\n- [runc](https://github.com/opencontainers/runc) - Container runtime\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhqarroum%2Fmicrobox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhqarroum%2Fmicrobox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhqarroum%2Fmicrobox/lists"}