lib/sandbox/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! Executes a single command in a temporary working tree so callers can inspect
 2 //! filesystem changes before deciding what to retain. A disposable directory
 3 //! serves as the layer, while execution returns a `Result` holding captured
 4 //! child output and the report of observed filesystem changes.
 5 //!
 6 //! Four selectable backends provide execution environments: copied staging on
 7 //! any host, a Linux Bubblewrap overlay, macOS staging, and Windows staging.
 8 //! With copied staging, the runner clones the source directory into the layer
 9 //! and sets the child process working directory to that copy. This backend
10 //! supplies no operating system confinement against absolute paths, parent
11 //! directory traversals, or symlinks that reach outside the layer for reads and
12 //! writes, so arbitrary child commands can modify the original source tree.
13 //! Bubblewrap provides a dedicated process namespace, with a private network
14 //! namespace enabled when selected by policy.
15 //!
16 //! Execution relies on a borrowed run plan naming arguments, directories,
17 //! isolation policy, and limits on run time and output bytes. Each run records
18 //! an `Audit` describing the backend configuration across filesystem, process,
19 //! network, and environment dimensions. The implementation constructs this
20 //! record from the chosen runner and plan rather than by measuring actual
21 //! isolation, allowing callers to compare supported dimensions against required
22 //! policy instead of assuming every request was granted.
23 //!
24 //! The package does not apply recorded layer changes back to the source tree.
25 //! Callers must copy any files they want to retain out of the layer before
26 //! calling `Result.deinit`, which deletes the layer directory.
27 
28 pub const audit = @import("audit.zig");
29 pub const backend = @import("backend.zig");
30 pub const bwrap = @import("bwrap.zig");
31 pub const change = @import("change.zig");
32 pub const command = @import("command.zig");
33 pub const confined = @import("confined.zig");
34 pub const copied = @import("copied.zig");
35 pub const cwd = @import("cwd.zig");
36 pub const layer = @import("layer.zig");
37 pub const macos = @import("macos.zig");
38 pub const plan = @import("plan.zig");
39 pub const policy = @import("policy.zig");
40 pub const resolve = @import("resolve.zig");
41 pub const result = @import("result.zig");
42 pub const run = @import("run.zig");
43 pub const scan = @import("scan.zig");
44 pub const windows = @import("windows.zig");
45 
46 pub const Audit = audit.Audit;
47 pub const BackendPolicy = backend.Policy;
48 pub const Change = change.Change;
49 pub const ChangeSet = change.Set;
50 pub const Entry = change.Entry;
51 pub const Environment = audit.Environment;
52 pub const Filesystem = audit.Filesystem;
53 pub const Kind = change.Kind;
54 pub const Layer = layer.Layer;
55 pub const Network = audit.Network;
56 pub const Operation = change.Operation;
57 pub const Plan = plan.Plan;
58 pub const Policy = policy.Policy;
59 pub const Preference = policy.Preference;
60 pub const Process = audit.Process;
61 pub const Result = result.Result;
62 pub const Runner = audit.Runner;
63 pub const Snapshot = scan.Snapshot;
64 pub const Status = run.Status;
65 pub const backendPolicyFromName = backend.policyFromName;
66 pub const backendPolicyName = backend.policyName;
67 pub const execute = run.execute;