BashBox : un Bash en PHP pur pour vos agents

Ce qui se passe

Un agent qui écrit des scripts shell pose un problème simple : où les exécuter ? BashBox, de Pushpak Chhajed (par ailleurs auteur du paquet Grant pour les rôles et permissions Laravel), répond par un interpréteur Bash écrit en PHP pur. Il n'appelle ni proc_open, ni exec, ni shell_exec : il n'y a aucun binaire sh ou bash derrière.

Laravel News l'a présenté le 11 octobre. Le paquet est en version 0.0.3.

Comment ça marche

Chaque commande est une classe PHP qui agit sur un système de fichiers virtuel. L'interpréteur gère tubes, redirections de descripteurs (2>&1), here-docs, substitution de processus, tableaux, fonctions, structures de contrôle et options set/shopt. Il fournit 58 commandes (grep, sed, sort, find, xargs, sha256sum…) et les commandes internes cd, export, source, read, trap. Un script qui ne se parse pas renvoie le code de sortie 2 avec l'erreur de syntaxe de Bash, sans lever d'exception.

Quatre systèmes de fichiers au choix :

• InMemoryFs, le défaut, ne touche jamais le disque ;
• OverlayFs lit un vrai dossier et garde les écritures dans une couche mémoire ;
• ReadWriteFs lit et écrit sur le disque, confiné à une racine ;
• MountableFs monte plusieurs de ces systèmes à des chemins différents.

Les garde-fous

La classe Limits en expose 18. Dépasser l'une d'elles lève BashBox\Exceptions\ExecutionLimitException. La traversée de chemins et l'injection d'octets nuls sont bloquées, et OverlayFs refuse les liens symboliques par défaut quand il lit un vrai dossier.

Le réseau est coupé : la commande curl n'existe pas tant qu'on n'a pas fourni de NetworkConfig. Une liste de préfixes d'URL vide refuse tout, les plages privées et locales sont refusées (denyPrivateRanges), les redirections exigent -L et sont revérifiées, et les en-têtes Authorization et Cookie sont retirés lors d'une redirection vers une autre origine.

À essayer

composer require shipfastlabs/bashbox

use BashBox\Bash;
use BashBox\BashOptions;
use BashBox\Limits;
use BashBox\Filesystem\OverlayFs;
use BashBox\Network\NetworkConfig;

$bash = new Bash(new BashOptions(
    fs: new OverlayFs('/chemin/du/projet'),      // lecture seule en pratique
    limits: new Limits(maxCommandCount: 100, maxLoopIterations: 500),
    network: new NetworkConfig(
        allowedUrlPrefixes: ['https://api.example.com/'],
        allowedMethods: ['GET'],
    ),
));

$resultat = $bash->exec("find . -name '*.php' | xargs grep TODO | sort");
echo $resultat->stdout;   // à renvoyer au modèle

Le paquet exige PHP 8.4 ou plus et n'a aucune dépendance Composer. L'extension ffi, si elle est présente, active le moteur d'expressions RE2 ; sans elle, PCRE avec des limites strictes. On peut brancher BashBox sur un outil du SDK IA de Laravel ou de n'importe quelle bibliothèque d'agents, et ajouter ses propres commandes en étendant AbstractCommand.

Limites

Version 0.0.3, un seul mainteneur : l'interface peut bouger. Et un interpréteur écrit en PHP n'est pas une isolation au niveau du système, comme le serait un conteneur : c'est une lecture de cette fiche, pas une affirmation de l'article. Avant de lui confier du code qu'on ne maîtrise pas, relire ses garde-fous et garder le réseau fermé.

Source : BashBox: A Sandboxed Bash Interpreter for AI Agents in PHP, Laravel News, 11 octobre 2026.