PHPackages                             securerun/bubblewrap-sandbox - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. securerun/bubblewrap-sandbox

ActiveLibrary[Security](/categories/security)

securerun/bubblewrap-sandbox
============================

Security layer to run external commands inside bubblewrap for Laravel 5 through 12.

v1.1.0(4mo ago)127[1 PRs](https://github.com/greenn-company/bubblewrap-sandbox/pulls)MITPHPPHP >=7.0

Since Jan 5Pushed 4mo agoCompare

[ Source](https://github.com/greenn-company/bubblewrap-sandbox)[ Packagist](https://packagist.org/packages/securerun/bubblewrap-sandbox)[ RSS](/packages/securerun-bubblewrap-sandbox/feed)WikiDiscussions production Synced 1mo ago

READMEChangelogDependencies (3)Versions (5)Used By (0)

Laravel Bubblewrap Guard
========================

[](#laravel-bubblewrap-guard)

Security layer that forbids executing external commands without a bubblewrap sandbox. Designed for Laravel apps from 5 through 12 that need to process files (PDF, image, video, document) with mandatory `bubblewrap (bwrap)` isolation.

Why use this
------------

[](#why-use-this)

- Prevents RCE via unsafe `shell_exec/exec/system/passthru/proc_open`.
- Isolates filesystem, environment variables, and network for the child process.
- Compatible with Laravel 5.x to 12.x on PHP 7.0+ (Composer requirement). Runtime code sticks to older syntax for legacy apps, but tests and support start on PHP 7.x; use PHP 7+ (or newer) in production.
- Runs on Linux only (bubblewrap is a Linux-specific sandbox).

Installation
------------

[](#installation)

```
composer require securerun/bubblewrap-sandbox
```

For Laravel >= 5.5, package auto-discovery already registers the provider and the `BubblewrapSandbox` alias (now pointing to the facade at `SecureRun\BubblewrapSandbox`).

For older versions, add manually in `config/app.php`:

```
SecureRun\Sandbox\BubblewrapServiceProvider::class,
'BubblewrapSandbox' => SecureRun\BubblewrapSandbox::class,
```

Publish the configuration (optional):

```
php artisan vendor:publish --tag=sandbox-config
```

Basic usage
-----------

[](#basic-usage)

```
use SecureRun\BubblewrapSandboxRunner;

$runner = app(\SecureRun\BubblewrapSandboxRunner::class); // or the BubblewrapSandbox facade for static calls

// Command to run inside the sandbox
$command = array('gs', '-q', '-sDEVICE=png16m', '-o', '/tmp/out.png', '/tmp/in.pdf');

// Bind mounts for input/output (read-only by default)
$binds = array(
    array('from' => storage_path('uploads/in.pdf'), 'to' => '/tmp/in.pdf', 'read_only' => true),
    array('from' => storage_path('tmp'), 'to' => '/tmp', 'read_only' => false),
);

$wrapper = $runner->run($command, $binds, '/tmp', null, 120);
$output = $wrapper->getOutput(); // ProcessWrapper works like Process

// Optional: access environment variables (when explicitly enabled)
use SecureRun\RunOptions;
$wrapper = $runner->run($command, $binds, '/tmp', ['VAR' => 'value'], 120, [
    RunOptions::UNSECURE_ENV_ACCESS => true
]);
$env = $wrapper->getEnv(); // returns ['VAR' => 'value']
```

Or via the Laravel facade (no `/Laravel` namespace anymore):

```
use SecureRun\BubblewrapSandbox;

$wrapper = BubblewrapSandbox::run(['ls', '-la']);
$output = $wrapper->getOutput(); // ProcessWrapper is compatible with Process
```

Note: `SecureRun\Sandbox\BubblewrapSandbox` remains as a backwards-compatible shim for apps that imported the old namespace. Prefer `SecureRun\BubblewrapSandbox` (or the `BubblewrapSandbox` alias).

Documentation
-------------

[](#documentation)

- Quick usage guide: [docs/USING\_SANDBOX.md](docs/USING_SANDBOX.md)
- Run method parameters: [docs/PARAMETROS\_RUN.md](docs/PARAMETROS_RUN.md)
- Environment variables access examples: [docs/EXEMPLOS\_ENV.md](docs/EXEMPLOS_ENV.md)

### Advanced features

[](#advanced-features)

- **RunOptions**: Centralized option constants for the `run()` method. Use `RunOptions::UNSECURE_ENV_ACCESS` instead of string literals to prevent typos.
- **ProcessWrapper**: The `run()` method always returns `ProcessWrapper` (which is compatible with Symfony Process) for consistent return types. Environment variable access via `getEnv()` is only available when `unsecure_env_access` is explicitly enabled.

### Security rules enforced

[](#security-rules-enforced)

- Every command is prefixed with `bwrap` and `--unshare-all --die-with-parent --new-session`.
- Default mounts: `/usr`, `/bin`, `/lib`, `/sbin`, `/etc/resolv.conf`, `/etc/ssl` as read-only (adds `/lib64` when the host has it); `/tmp` isolated and writable.
- Default binary points to `/usr/bin/bwrap` (adjust `config/sandbox.php` if `bwrap` lives elsewhere).
- PATH is limited (`/usr/bin:/bin:/usr/sbin:/sbin`).
- If `bwrap` is unavailable or not executable, a `BubblewrapUnavailableException` is thrown.

### Do not

[](#do-not)

- Do not call `shell_exec`, `exec`, `system`, `passthru`, `proc_open`, or raw `Symfony Process` for sensitive binaries. Always go through `BubblewrapSandbox`.
- Do not mount directories containing secrets (e.g., `/home`, `/var/www/.env`).

Configuration
-------------

[](#configuration)

Edit `config/sandbox.php` after publishing:

- `binary`: path to `bwrap` (default `/usr/bin/bwrap`; use `bwrap` if it’s on PATH).
- `base_args`: default flags (avoid removing unshare/die-with-parent).
- `read_only_binds`: automatic read-only binds.
- `write_binds`: writable binds (default empty; `/tmp` is already a sandbox tmpfs).

Quick examples
--------------

[](#quick-examples)

- **Image** with ImageMagick: `['convert', '/tmp/in.png', '-resize', '800x600', '/tmp/out.png']`.
- **Video** with FFmpeg: `['ffmpeg', '-i', '/tmp/in.mp4', '-vf', 'scale=1280:720', '/tmp/out.mp4']` plus binds for input/output paths.
- **PDF** with Ghostscript: use the basic usage example.

Tests
-----

[](#tests)

- Requires PHP `ext-dom` enabled.
- Local run (single version):

    ```
    composer install --no-interaction --no-progress
    vendor/bin/phpunit
    ```

    On PHP 5.6–7.x, Composer will pull PHPUnit 5.7; on PHP 8.x it will use PHPUnit 9.6 (coverage is optional if `xdebug`/`pcov` are installed).
- Matrix via Docker:

    ```
    chmod +x tools/test-matrix.sh
    tools/test-matrix.sh
    ```

    The script spins up PHP containers and runs PHPUnit across multiple PHP/Laravel pairs. Adjust the `COMBOS` list to narrow versions. Note: the current test suite uses anonymous classes, so the PHP 5.6/Laravel 5.4 combo is commented out (PHP 5.6 lacks that feature).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance78

Regular maintenance activity

Popularity9

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 90.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

2

Last Release

122d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d025cf96f7d52a35c9ac1fe453a81345a962a838e4924286cf1fbf070ae2dbb3?d=identicon)[devgreenn](/maintainers/devgreenn)

---

Top Contributors

[![jeferls](https://avatars.githubusercontent.com/u/170640380?v=4)](https://github.com/jeferls "jeferls (29 commits)")[![dariocoutinho1985](https://avatars.githubusercontent.com/u/166048319?v=4)](https://github.com/dariocoutinho1985 "dariocoutinho1985 (3 commits)")

---

Tags

laravelsecuritysandboxbubblewrapbwrap

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/securerun-bubblewrap-sandbox/health.svg)

```
[![Health](https://phpackages.com/badges/securerun-bubblewrap-sandbox/health.svg)](https://phpackages.com/packages/securerun-bubblewrap-sandbox)
```

###  Alternatives

[tzsk/otp

A secure, database-free One-Time Password (OTP) generator and verifier for PHP and Laravel.

241641.4k1](/packages/tzsk-otp)[dgtlss/warden

A Laravel package that proactively monitors your dependencies for security vulnerabilities by running automated composer audits and sending notifications via webhooks and email

8745.6k](/packages/dgtlss-warden)[ercsctt/laravel-file-encryption

Secure file encryption and decryption for Laravel applications

642.6k](/packages/ercsctt-laravel-file-encryption)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)