Threat Model

gbash maintains a detailed threat model document. This page summarizes the key risks and mitigations. For the full analysis, see THREAT_MODEL.md on GitHub.

gbash is alpha software. The security model is actively evolving. Use OS-level isolation (containers, VMs) for production workloads handling sensitive data.

Attacker model

The expected attacker is an untrusted script -- typically generated by an LLM or provided by an end user. The attacker can supply arbitrary shell text, control command arguments, and use nested execution (bash -c, xargs, etc.) within the session. The attacker cannot cause unknown commands to run on the host or use network egress unless the embedder explicitly enables it.

Key risk areas

Filesystem escape

Risk: Scripts enumerate and read files beyond the intended workspace when read/write roots are too broad or a non-memory filesystem backend exposes host-adjacent content.

Mitigations: Registry-backed command resolution (no host fallback), path root checks on every file operation, default in-memory filesystem. Configure narrow read/write roots for production use.

Command injection

Risk: Nested execution through bash, sh, env, timeout, and xargs amplifies attacker-controlled work while staying inside the sandbox.

Mitigations: All nested execution stays within the same sandbox session and policy. Execution budgets (command count, loop iterations, substitution depth) bound the total work. Unknown commands always fail with exit code 127.

Resource exhaustion

Risk: Large stdin, unbounded file reads, or fanout through nested commands can exhaust memory or CPU.

Mitigations: Command count limits, loop iteration caps, stdout/stderr truncation, network response size caps, and execution timeouts. Per-file size limits are defined in policy.

Network SSRF

Risk: When network access is enabled with a broad allowlist, curl can probe internal services or exfiltrate workspace data.

Mitigations: Network is off by default. When enabled, requests are constrained by URL-prefix allowlists, method allowlists, and redirect revalidation. Optional private-range blocking prevents access to internal network addresses. Response size is capped.

Symlink traversal

Risk: Overlay filesystem backends may not fully resolve symlinks, allowing reads outside intended roots.

Mitigations: Default symlink mode is deny. The default in-memory filesystem resolves symlinks correctly. Exercise caution with overlay backends and untrusted workloads.

Trace data leakage

Risk: Trace events include command arguments and file paths, which may contain secrets (e.g., curl -H "Authorization: Bearer ..." in argv).

Mitigations: Traces are in-memory per execution and returned only to the caller. TraceRedacted scrubs common secret-bearing argv values before events are recorded or emitted. TraceRaw still exposes full metadata, so treat it as sensitive and restrict its sinks and retention.