NAME
Langertha::Holmgang::Sandbox::Docker - Runs one real program on a copy of a device's files in a locked-down container
VERSION
version 0.002
SYNOPSIS
use Langertha::Holmgang::Sandbox::Docker;
my $sandbox = Langertha::Holmgang::Sandbox::Docker->new; # image langertha-holmgang-sandbox:1
my ( $r, $why ) = $sandbox->run(
argv => [ 'python3', '-c', 'print(open("/etc/app.conf").read().upper())' ],
files => { '/etc/app.conf' => { content => "debug = on\n", mode => 0644 } },
stdin => undef,
cwd => '/root',
now => 1792490400,
host => 'app1',
);
# $r = { output => "DEBUG = ON\n", exit => 0, changed => {}, deleted => [], ms => 412 }
# $r = undef, $why = 'python3 is not in the image' -- the caller keeps its gap
DESCRIPTION
The simulators answer from their state and never touch the host. A real program they do not model (python3 -c, an awk script past the filter grammar, openssl x509 on a file) is a gap of the simulation: an empty answer and an uncertain case. This class is the way out for such a program: one command runs for real, in a container that is made for this call and removed after it.
The container has no network, no capabilities beyond what unpacking files as root needs, no new privileges, bounded memory, processes and time. No host directory is mounted: the device's files go in as a tar stream on standard input and the result comes back as a tar stream on standard output.
The program sees the files the caller hands over, at their real paths, and nothing else of the simulated device: no services, no other host, no simulated command. What the simulation knows better stays with the simulator — the caller decides which commands may come here ("SANDBOX" in Langertha::Holmgang::Sim::Linux).
The clock is the simulation's (
now) when the image carries libfaketime; the host name is the device's.Afterwards the caller gets the output (standard output and error in one text, as a simulated command answers; Python writes unbuffered, so both come in the order written), the exit status, the files that changed or appeared and the ones that went away, and writes them back into its state.
A program that is not in the image, a result that is too large, a container that does not start: "run" returns nothing and a reason, and the caller keeps its gap. It never guesses an answer.
The image is built from share/sandbox/Dockerfile of this distribution (after installation under File::ShareDir::dist_dir('Langertha-Holmgang')):
docker build -t langertha-holmgang-sandbox:1 share/sandbox
Its programs' output is part of a measurement: name the image digest with a run.
This class is opt-in (holmgang run --sandbox docker). Loading and lint never use it — a case loads and lints the same with and without Docker (ADR 0011).
image
The image to run, default langertha-holmgang-sandbox:1 (share/sandbox/Dockerfile). It needs sh, tar and perl.
docker
The command of the container runtime as a list, default ['docker'] (['podman'] works the same).
timeout
Seconds one program may run, default 10. Past it the program is killed and the call exits 124, as under timeout.
memory
cpus
pids
The limits of the container (--memory, --cpus, --pids-limit), default 512m, 1 and 128.
max_output
max_file
max_new
Bounds of a result: bytes of output (default 256 KiB, cut beyond), bytes of one changed or new file (default 1 MiB) and the number of new files (default 200). A file or count past its bound makes the whole call unusable ("run" returns nothing).
log
Every call that ran, in order: { host, argv, exit, ms }. The runner takes the entries of one tool call into its record ("take_log").
take_log
my @entries = $sandbox->take_log;
The entries of "log" since the last call, and empties it.
run
my ( $result, $why ) = $sandbox->run(
argv => \@argv, # the program and its arguments, no shell
files => { $path => { content => $text, mode => 0640, uid => 0, gid => 0 } | { link => $target } },
dirs => { $path => { mode => 0750, uid => 0, gid => 0 } },
stdin => $text,
cwd => '/root',
env => { NAME => $value },
now => $epoch, # the simulation's clock
tz => 'Europe/Berlin',
host => 'app1',
);
Runs argv as root in a fresh container in which exactly files and dirs exist beside the image. Returns the result, or nothing and the reason it is not usable:
output— standard output and standard error, in the order written.exit— the exit status; 124 after the timeout, 128 + signal after a signal.changed— the files whose content, mode or link target differs from what went in, and the new ones (new), under the directories a server program writes to:{ content, mode }or{ link }.deleted— the paths offilesthat are gone.ms— wall time of the call;clock—simwhen the program sawnow,realwhen the image has no libfaketime.
Texts go in and come back as characters (UTF-8 in the container); a result that is not UTF-8 comes back as bytes.
available
my ( $ok, $id_or_reason ) = $sandbox->available;
Whether the runtime answers and the image is there: true and the image id (to note with a run), or false and the reason.
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.