Skip to content

Commit 145e1c1

Browse files
kaman1claude
andcommitted
docs: add Sandbox (Experimental) section with just-bash integration
Adds a new docs section at /docs/sandbox with two pages: 1. Overview — when and why to sandbox gate scripts, what isolation adds over the built-in require_inside_project confinement. 2. just-bash — step-by-step integration guide for running gate-check inside Vercel Labs' just-bash virtual bash environment. Includes: - A complete, tested Node.js wrapper (sandbox/run-gate-check.mjs) that loads project files into just-bash's in-memory filesystem - Gates A, B, and F running inside the sandbox - Config parsing and JSONL output done in JavaScript (Python WASM is not available in local Node.js) - Verified compatibility table of which commands work - Honest limitations: no python3, no git, no shasum, no network - Clear callout that this adds an npm dependency vs the zero-dep core scripts All code examples were tested against just-bash@latest in Node.js. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 7222d73 commit 145e1c1

4 files changed

Lines changed: 477 additions & 0 deletions

File tree

docs-site/content/docs/meta.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"how-it-works",
77
"commands",
88
"security",
9+
"sandbox",
910
"customization",
1011
"agent-compatibility",
1112
"development-rules",
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Sandbox (Experimental)
3+
description: Run speckit-security gate scripts inside a sandboxed environment for defense-in-depth isolation.
4+
---
5+
6+
> **Experimental.** Everything on this page is exploratory. APIs,
7+
> integration patterns, and supported runtimes may change without
8+
> notice. Do not depend on sandbox support in production CI pipelines
9+
> until it graduates from experimental status.
10+
11+
## Why sandbox?
12+
13+
By default, speckit-security scripts run directly on the host shell.
14+
They have [project-root confinement](/docs/security) via
15+
`require_inside_project`, but that's a **check**, not a **boundary**
16+
-- a bug in the scripts or a crafted input could still access the
17+
host filesystem or network.
18+
19+
A sandbox adds a real isolation boundary:
20+
21+
| Layer | What it prevents |
22+
|-------|------------------|
23+
| **Filesystem isolation** | Scripts can only see files you explicitly mount -- no `/etc`, no `~/.ssh`, no sibling repos |
24+
| **Network disabled** | Gate scripts have no reason to make network calls -- sandbox enforces it at the runtime level |
25+
| **Execution limits** | Malicious spec files cannot trigger infinite loops or fork bombs |
26+
| **Write isolation** | Scripts read your real project files but writes go to an in-memory layer -- the real project is never modified |
27+
28+
## When to use a sandbox
29+
30+
- **Untrusted specs.** Running gate-check against a spec file from an
31+
external contributor or a pull request you haven't reviewed yet.
32+
- **CI on shared runners.** If your CI runner processes multiple repos,
33+
sandboxing prevents cross-repo information leakage.
34+
- **Web-based gate runners.** If you build a UI that lets users run
35+
gate-check from a browser, the sandbox is essential.
36+
- **Defense in depth.** Even if you trust the input, sandboxing limits
37+
the blast radius of any bug in the scripts themselves.
38+
39+
## When you don't need it
40+
41+
- **Local development.** If you're the only person running the scripts
42+
on your own machine against your own specs, the built-in
43+
`require_inside_project` confinement is sufficient.
44+
- **Trusted CI.** If your CI only processes your own repo and the
45+
runner is ephemeral (e.g. GitHub Actions), host isolation is already
46+
provided by the runner VM.
47+
48+
## Available sandbox runtimes
49+
50+
<Cards>
51+
<Card
52+
title="just-bash"
53+
href="/docs/sandbox/just-bash"
54+
description="Virtual bash environment by Vercel Labs. In-memory filesystem, network disabled by default, execution limits. TypeScript/Node.js."
55+
/>
56+
</Cards>
57+
58+
More runtimes may be added as the ecosystem matures. Contributions
59+
welcome -- see [CONTRIBUTING.md](https://github.com/TEKIMAX/speckit-security/blob/main/CONTRIBUTING.md).

0 commit comments

Comments
 (0)