From fb3609da9d7835e366e4a7296485eee8804cebb6 Mon Sep 17 00:00:00 2001 From: Mykhailo Chalyi Date: Mon, 16 Mar 2026 03:07:22 +0000 Subject: [PATCH] docs(security): add public docs folder with security overview article --- AGENTS.md | 7 ++-- docs/security.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 docs/security.md diff --git a/AGENTS.md b/AGENTS.md index bc8a4f57..629ff50f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,11 +45,12 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn ### Documentation -- Guides live in `crates/bashkit/docs/` as markdown files -- Embedded into rustdoc via `include_str!` (see `specs/008-documentation.md`) +- **Public docs** live in `docs/` — user-facing articles (security, guides, etc.) +- **Rustdoc guides** live in `crates/bashkit/docs/` as markdown files +- Rustdoc guides embedded via `include_str!` (see `specs/008-documentation.md`) - Edit `crates/bashkit/docs/*.md`, not the doc modules in `lib.rs` - Add "See also" cross-links when creating new guides -- Run `cargo doc --open` to preview changes +- Run `cargo doc --open` to preview rustdoc changes ### Bashkit Principles diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 00000000..0265aca8 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,103 @@ +# Security in Bashkit + +Bashkit is a virtual Bash interpreter designed for safe, sandboxed script +execution. Security is a first-class concern — every design decision considers +what an untrusted script could do and how to prevent it. + +This article gives a high-level overview. For the full threat model with +individual threat IDs and mitigation status, see the +[rustdoc threat model guide](https://docs.rs/bashkit/latest/bashkit/threat_model/index.html). + +## Core security boundaries + +| Boundary | What it does | +|----------|-------------| +| **Virtual filesystem** | Scripts run against an in-memory VFS. No real filesystem access by default. Path traversal (`../../../etc/passwd`) is normalised away. Symlinks are stored but never followed. | +| **No process execution** | `exec` is excluded entirely. `bash -c` re-invokes the virtual interpreter instead of spawning a real process. Background jobs (`&`) parse but run synchronously. | +| **Network allowlist** | HTTP/HTTPS only, pre-validated against an explicit host allowlist. No DNS resolution, no auto-redirect, no auto-decompression. | +| **Resource limits** | Configurable caps on commands, loop iterations, recursion depth, AST depth, timeouts, and parser operations prevent denial-of-service from malicious scripts. | +| **Filesystem limits** | Total bytes, per-file size, file count, path depth, and filename length are all capped to prevent storage exhaustion (zip bombs, tar bombs, recursive copies). | + +## Threat model + +Bashkit maintains a living threat model in [`specs/006-threat-model.md`](../specs/006-threat-model.md) +with stable threat IDs across these categories: + +| Category | ID prefix | Examples | +|----------|-----------|----------| +| Denial of Service | `TM-DOS` | Resource exhaustion, infinite loops, parser bombs | +| Sandbox Escape | `TM-ESC` | Path traversal, real FS access, privilege escalation | +| Information Disclosure | `TM-INF` | Secret leakage, host info exposure, data exfiltration | +| Injection | `TM-INJ` | Command injection, variable namespace pollution | +| Network | `TM-NET` | DNS rebinding, allowlist bypass, response flooding | +| Multi-Tenant Isolation | `TM-ISO` | Cross-tenant data leaks | +| Internal Errors | `TM-INT` | Panics, error message information leaks | +| Git | `TM-GIT` | Repo access control, remote URL injection | +| Logging | `TM-LOG` | Sensitive data in logs, log injection | +| Python Sandbox | `TM-PY` | Monty resource limits, VFS bridge escapes | +| Unicode | `TM-UNI` | Byte-boundary panics, homoglyph attacks | + +The full threat model — including mitigation status for each threat — is +published in the rustdoc: +[**bashkit::threat_model**](https://docs.rs/bashkit/latest/bashkit/threat_model/index.html). + +## POSIX deviations for security + +Bashkit intentionally deviates from POSIX where compliance would compromise +the sandbox. Key exclusions: + +- **`exec`** — would break sandbox containment (`TM-ESC-005`) +- **`trap`** — conflicts with the stateless execution model +- **Real process spawning** — all subprocess commands stay within the virtual interpreter (`TM-ESC-015`) + +These decisions are documented in [`specs/008-posix-compliance.md`](../specs/008-posix-compliance.md). + +## Security testing + +Bashkit uses multiple layers of security testing: + +**Threat model tests** — Over 50 tests in `threat_model_tests.rs` that directly +validate mitigations against documented threat IDs. Each test maps to a specific +`TM-*` threat. + +**Fail-point injection** — A framework defined in [`specs/005-security-testing.md`](../specs/005-security-testing.md) +that injects failures at specific points to verify the interpreter handles them +safely. 14+ tests in `security_failpoint_tests.rs`. + +**Network security tests** — 53 tests covering allowlist enforcement, URL +validation, timeout behaviour, and response limits. + +**Error handling tests** — 39 tests verifying that builtins wrapped with +`catch_unwind` never leak panic messages, stack traces, or memory addresses. + +**Logging security tests** — 26 tests confirming that sensitive data (passwords, +tokens, API keys, JWTs) is redacted in logs and that log injection is prevented. + +**Fuzz testing** — Parser and lexer fuzzing to catch panics and unexpected +behaviour on malformed input. + +**Differential tests** — Compare Bashkit output against real Bash to ensure +behaviour parity where expected, and confirm intentional divergences where +security requires it. + +## Panic safety + +All builtin commands are wrapped with `catch_unwind`. If a builtin panics, the +error is caught and converted to a sanitised error message — no stack traces, no +memory addresses, no real filesystem paths leak to the caller (`TM-INT-001`, +`TM-INT-002`). + +## Reporting security issues + +**Do not open a public GitHub issue for security vulnerabilities.** + +Email: **security@everruns.com** + +Please include a description of the vulnerability, steps to reproduce, and +potential impact. We acknowledge reports within 48 hours, provide an initial +assessment within 7 days, and target 30-day resolution for critical issues. + +See [`SECURITY.md`](../SECURITY.md) for the full policy. + +We appreciate responsible disclosure and acknowledge researchers who report +valid vulnerabilities (with permission).