{"id":26708983,"url":"https://github.com/Zouuup/landrun","last_synced_at":"2025-03-27T08:02:20.879Z","repository":{"id":283715860,"uuid":"952651301","full_name":"Zouuup/landrun","owner":"Zouuup","description":"Run any Linux process in a secure, unprivileged sandbox using Landlock LSM. Think firejail, but lightweight, user-friendly, and baked into the kernel.","archived":false,"fork":false,"pushed_at":"2025-03-21T18:01:22.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-21T19:21:41.940Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zouuup.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":"2025-03-21T16:31:47.000Z","updated_at":"2025-03-21T18:01:26.000Z","dependencies_parsed_at":"2025-03-21T19:21:46.568Z","dependency_job_id":"18391c27-13bd-4f79-9c19-2e7cb199f39e","html_url":"https://github.com/Zouuup/landrun","commit_stats":null,"previous_names":["zouuup/landrun"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zouuup%2Flandrun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zouuup%2Flandrun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zouuup%2Flandrun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zouuup%2Flandrun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zouuup","download_url":"https://codeload.github.com/Zouuup/landrun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245806452,"owners_count":20675298,"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":"2025-03-27T08:01:35.233Z","updated_at":"2025-03-27T08:02:20.862Z","avatar_url":"https://github.com/Zouuup.png","language":"Go","funding_links":[],"categories":["Go","语音识别与合成_其他","命令行工具","\u003ca name=\"system\"\u003e\u003c/a\u003eSystem tools","Self-hosted / Open Source"],"sub_categories":["资源传输下载"],"readme":"# landrun\n\nA lightweight, secure sandbox for running Linux processes using Landlock. Think firejail, but with kernel-level security and minimal overhead.\n\nLinux Landlock is a kernel-native security module that lets unprivileged processes sandbox themselves.\n\nLandrun is designed to make it practical to sandbox any command with fine-grained filesystem and network access controls. No root. No containers. No SELinux/AppArmor configs.\n\nIt's lightweight, auditable, and wraps Landlock v5 features (file access + TCP restrictions).\n\n## Features\n\n- 🔒 Kernel-level security using Landlock\n- 🚀 Lightweight and fast execution\n- 🛡️ Fine-grained access control for directories\n- 🔄 Support for read and write paths\n- ⚡ Path-specific execution permissions\n- 🌐 TCP network access control (binding and connecting)\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo.gif\" alt=\"landrun demo\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n## Requirements\n\n- Linux kernel 5.13 or later with Landlock enabled\n- Linux kernel 6.7 or later for network restrictions (TCP bind/connect)\n- Go 1.18 or later (for building from source)\n\n## Installation\n\n### Quick Install\n\n```bash\ngo install github.com/zouuup/landrun/cmd/landrun@latest\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/zouuup/landrun.git\ncd landrun\ngo build -o landrun cmd/landrun/main.go\nsudo cp landrun /usr/local/bin/\n```\n\n### Distros\n\n#### Arch (AUR)\nmaintained by [Vcalv](https://github.com/vcalv)\n```bash\nyay -S landrun\n```\n\n## Usage\n\nBasic syntax:\n\n```bash\nlandrun [options] \u003ccommand\u003e [args...]\n```\n\n### Options\n\n- `--ro \u003cpath\u003e`: Allow read-only access to specified path (can be specified multiple times or as comma-separated values)\n- `--rox \u003cpath\u003e`: Allow read-only access with execution to specified path (can be specified multiple times or as comma-separated values)\n- `--rw \u003cpath\u003e`: Allow read-write access to specified path (can be specified multiple times or as comma-separated values)\n- `--rwx \u003cpath\u003e`: Allow read-write access with execution to specified path (can be specified multiple times or as comma-separated values)\n- `--bind-tcp \u003cport\u003e`: Allow binding to specified TCP port (can be specified multiple times or as comma-separated values)\n- `--connect-tcp \u003cport\u003e`: Allow connecting to specified TCP port (can be specified multiple times or as comma-separated values)\n- `--env \u003cvar\u003e`: Environment variable to pass to the sandboxed command (format: KEY=VALUE or just KEY to pass current value)\n- `--best-effort`: Use best effort mode, falling back to less restrictive sandbox if necessary [default: disabled]\n- `--log-level \u003clevel\u003e`: Set logging level (error, info, debug) [default: \"error\"]\n- `--unrestricted-network`: allows unrestricted network access.\n- `--unrestricted-filesystem`: allows unrestricted filesystem access.\n\n### Important Notes\n\n- You must explicitly add the directory to the command you want to run with `--rox` flag\n- For system commands, you typically need to include `/usr/bin`, `/usr/lib`, and other system directories\n- Use `--rwx` for directories where you need both write access and the ability to execute files\n- Network restrictions require Linux kernel 6.7 or later with Landlock ABI v4\n- By default, no environment variables are passed to the sandboxed command. Use `--env` to explicitly pass environment variables\n- The `--best-effort` flag allows graceful degradation on older kernels that don't support all requested restrictions\n- Paths can be specified either using multiple flags or as comma-separated values (e.g., `--ro /usr,/lib,/home`)\n\n### Environment Variables\n\n- `LANDRUN_LOG_LEVEL`: Set logging level (error, info, debug)\n\n### Examples\n\n1. Run a command with read-only access to a directory:\n\n```bash\nlandrun --rox /usr/ --ro /path/to/dir ls /path/to/dir\n```\n\n2. Run a command with write access to a directory:\n\n```bash\nlandrun --rox /usr/bin --ro /lib --rw /path/to/dir touch /path/to/dir/newfile\n```\n\n3. Run a command with execution permissions:\n\n```bash\nlandrun --rox /usr/ --ro /lib,/lib64 /usr/bin/bash\n```\n\n4. Run with debug logging:\n\n```bash\nlandrun --log-level debug --rox /usr/ --ro /lib,/lib64,/path/to/dir ls /path/to/dir\n```\n\n5. Run with network restrictions:\n\n```bash\nlandrun --rox /usr/ --ro /lib,/lib64 --bind-tcp 8080 --connect-tcp 80 /usr/bin/my-server\n```\n\nThis will allow the program to only bind to TCP port 8080 and connect to TCP port 80.\n\n6. Run a DNS client with appropriate permissions:\n\n```bash\nlandrun --log-level debug --ro /etc,/usr --rox /usr/ --connect-tcp 443 nc kernel.org 443\n```\n\nThis allows connections to port 443, requires access to /etc/resolv.conf for resolving DNS.\n\n7. Run a web server with selective network permissions:\n\n```bash\nlandrun --rox /usr/bin --ro /lib,/lib64,/var/www --rwx /var/log --bind-tcp 80,443 /usr/bin/nginx\n```\n\n8. Running anything without providing parameters is... maximum security jail!\n\n```bash\nlandrun ls\n```\n\n9. If you keep getting permission denied without knowing what exactly going on, best to use strace with it.\n\n```bash\nlandrun --rox /usr strace -f -e trace=all ls\n```\n\n10. Run with specific environment variables:\n\n```bash\nlandrun --rox /usr --ro /etc --env HOME --env PATH --env CUSTOM_VAR=my_value -- env\n```\n\nThis example passes the current HOME and PATH variables, plus a custom variable named CUSTOM_VAR.\n\n## Security\n\nlandrun uses Linux's Landlock to create a secure sandbox environment. It provides:\n\n- File system access control\n- Directory access restrictions\n- Execution control\n- TCP network restrictions\n- Process isolation\n\nLandlock is an access-control system that enables processes to securely restrict themselves and their future children. As a stackable Linux Security Module (LSM), it creates additional security layers on top of existing system-wide access controls, helping to mitigate security impacts from bugs or malicious behavior in applications.\n\n### Landlock Access Control Rights\n\nlandrun leverages Landlock's fine-grained access control mechanisms, which include:\n\n**File-specific rights:**\n\n- Execute files (`LANDLOCK_ACCESS_FS_EXECUTE`)\n- Write to files (`LANDLOCK_ACCESS_FS_WRITE_FILE`)\n- Read files (`LANDLOCK_ACCESS_FS_READ_FILE`)\n- Truncate files (`LANDLOCK_ACCESS_FS_TRUNCATE`) - Available since Landlock ABI v3\n\n**Directory-specific rights:**\n\n- Read directory contents (`LANDLOCK_ACCESS_FS_READ_DIR`)\n- Remove directories (`LANDLOCK_ACCESS_FS_REMOVE_DIR`)\n- Remove files (`LANDLOCK_ACCESS_FS_REMOVE_FILE`)\n- Create various filesystem objects (char devices, directories, regular files, sockets, etc.)\n- Refer/reparent files across directories (`LANDLOCK_ACCESS_FS_REFER`) - Available since Landlock ABI v2\n\n**Network-specific rights** (requires Linux 6.7+ with Landlock ABI v4):\n\n- Bind to specific TCP ports (`LANDLOCK_ACCESS_NET_BIND_TCP`)\n- Connect to specific TCP ports (`LANDLOCK_ACCESS_NET_CONNECT_TCP`)\n\n### Limitations\n\n- Landlock must be supported by your kernel\n- Network restrictions require Linux kernel 6.7 or later with Landlock ABI v4\n- Some operations may require additional permissions\n- Files or directories opened before sandboxing are not subject to Landlock restrictions\n\n## Kernel Compatibility Table\n\n| Feature                            | Minimum Kernel Version | Landlock ABI Version |\n| ---------------------------------- | ---------------------- | -------------------- |\n| Basic filesystem sandboxing        | 5.13                   | 1                    |\n| File referring/reparenting control | 5.19                   | 2                    |\n| File truncation control            | 6.2                    | 3                    |\n| Network TCP restrictions           | 6.7                    | 4                    |\n| IOCTL on special files             | 6.10                   | 5                    |\n\n## Troubleshooting\n\nIf you receive \"permission denied\" or similar errors:\n\n1. Ensure you've added all necessary paths with `--ro` or `--rw`\n2. Try running with `--log-level debug` to see detailed permission information\n3. Check that Landlock is supported and enabled on your system:\n   ```bash\n   grep -E 'landlock|lsm=' /boot/config-$(uname -r)\n   # alternatively, if there are no /boot/config-* files\n   zgrep -iE 'landlock|lsm=' /proc/config.gz\n   # another alternate method\n   grep -iE 'landlock|lsm=' /lib/modules/$(uname -r)/config\n   ```\n   You should see `CONFIG_SECURITY_LANDLOCK=y` and `lsm=landlock,...` in the output\n4. For network restrictions, verify your kernel version is 6.7+ with Landlock ABI v4:\n   ```bash\n   uname -r\n   ```\n\n## Technical Details\n\n### Implementation\n\nThis project uses the [landlock-lsm/go-landlock](https://github.com/landlock-lsm/go-landlock) package for sandboxing, which provides both filesystem and network restrictions. The current implementation supports:\n\n- Read/write/execute restrictions for files and directories\n- TCP port binding restrictions\n- TCP port connection restrictions\n- Best-effort mode for graceful degradation on older kernels\n\n### Best-Effort Mode\n\nWhen using `--best-effort` (disabled by default), landrun will gracefully degrade to using the best available Landlock version on the current kernel. This means:\n\n- On Linux 6.7+: Full filesystem and network restrictions\n- On Linux 6.2-6.6: Filesystem restrictions including truncation, but no network restrictions\n- On Linux 5.19-6.1: Basic filesystem restrictions including file reparenting, but no truncation control or network restrictions\n- On Linux 5.13-5.18: Basic filesystem restrictions without file reparenting, truncation control, or network restrictions\n- On older Linux: No restrictions (sandbox disabled)\n\n### Tests\n\nThe project includes a comprehensive test suite that verifies:\n\n- Basic filesystem access controls (read-only, read-write, execute)\n- Directory traversal and path handling\n- Network restrictions (TCP bind/connect)\n- Environment variable isolation\n- System command execution\n- Edge cases and regression tests\n\nRun the tests with:\n\n```bash\n./test.sh\n```\n\nUse `--keep-binary` to preserve the test binary after completion:\n\n```bash\n./test.sh --keep-binary\n```\n\nUse `--use-system` to test against the system-installed landrun binary:\n\n```bash\n./test.sh --use-system\n```\n\n## Future Features\n\nBased on the Linux Landlock API capabilities, we plan to add:\n\n- 🔒 Enhanced filesystem controls with more fine-grained permissions\n- 🌐 Support for UDP and other network protocol restrictions (when supported by Linux kernel)\n- 🔄 Process scoping and resource controls\n- 🛡️ Additional security features as they become available in the Landlock API\n\n## Acknowledgements\n\nThis project wouldn't exist without:\n\n- [Landlock](https://landlock.io), the kernel security module enabling unprivileged sandboxing - maintained by [@l0kod](https://github.com/l0kod)\n- [go-landlock](https://github.com/landlock-lsm/go-landlock), the Go bindings powering this tool - developed by [@gnoack](https://github.com/gnoack)\n\n## License\n\nThis project is licensed under the GNU General Public License v2\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZouuup%2Flandrun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FZouuup%2Flandrun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZouuup%2Flandrun/lists"}