From f1c9fac3658dc4f1053a9406a0d333af5e657f76 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Tue, 7 Apr 2026 17:12:10 +0200 Subject: [PATCH] docs(llm-security): expand sandboxed cloning with platform matrix and links Add detailed platform matrix with links to sandbox-exec, bubblewrap, Windows Sandbox, Docker Desktop, WSL2, and AppContainer documentation. CVE reference for .gitattributes attack vector. Git config flag table with per-flag mitigation descriptions. Windows guidance with concrete options and recommendations. Note on why Node.js --permission is not applicable. Co-Authored-By: Claude Opus 4.6 --- plugins/llm-security/README.md | 40 ++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/plugins/llm-security/README.md b/plugins/llm-security/README.md index cc82bb4..99bbe06 100644 --- a/plugins/llm-security/README.md +++ b/plugins/llm-security/README.md @@ -190,23 +190,45 @@ claude plugin add plugin-marketplace/llm-security **Injection-safe remote scanning (v2.5+):** Remote scans pre-extract structured evidence via `content-extractor.mjs` and strip injection patterns BEFORE LLM agents see the content. Agents analyze a JSON evidence package, never raw files from untrusted repos. `[INJECTION-PATTERN-STRIPPED]` markers are confirmed findings. -**Sandboxed cloning (v5.1+):** `git clone` can execute arbitrary code via `.gitattributes` filter/smudge drivers. Remote clones are now hardened with defense-in-depth: +**Sandboxed cloning (v5.1+):** `git clone` can execute arbitrary code via `.gitattributes` filter/smudge drivers ([CVE-2024-32002](https://github.blog/open-source/git/git-security-vulnerabilities-announced-5/) and related). Remote clones are now hardened with defense-in-depth: -**Layer 1 — Git config hardening (all platforms):** 8 config flags disable hooks (`core.hooksPath=/dev/null`), symlinks (`core.symlinks=false`), filter/smudge drivers (all LFS filters cleared), fsmonitor, and local file protocol. Environment variables isolate from system/user git config and block interactive prompts. +**Layer 1 — Git config hardening (all platforms):** 8 config flags neutralize known attack vectors: + +| Flag | Mitigates | +|------|-----------| +| `core.hooksPath=/dev/null` | Git hooks executed during clone/checkout | +| `core.symlinks=false` | Symlink traversal out of temp directory | +| `core.fsmonitor=false` | Arbitrary command execution via fsmonitor | +| `filter.lfs.{process,smudge,clean}=` | Filter/smudge driver code execution (`.gitattributes`) | +| `protocol.file.allow=never` | Local file protocol traversal | +| `transfer.fsckObjects=true` | Malformed git objects | + +Environment variables (`GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null`, `GIT_ATTR_NOSYSTEM=1`, `GIT_TERMINAL_PROMPT=0`) isolate from system/user git config and block interactive prompts. **Layer 2 — OS-level filesystem sandbox (platform-dependent):** -| Platform | Sandbox | Status | -|----------|---------|--------| -| macOS | `sandbox-exec` | Always available — restricts file writes to specific temp dir | -| Linux | `bubblewrap` (bwrap) | Works on Fedora/Arch. May require admin AppArmor config on Ubuntu 24.04+ | -| Windows | None | No practical zero-install CLI sandbox exists. Git config hardening only | +| Platform | Sandbox | How it works | Limitations | +|----------|---------|-------------|-------------| +| **macOS** | [`sandbox-exec`](https://keith.github.io/xcode-man-pages/sandbox-exec.1.html) | Restricts file writes to only the clone temp dir via Seatbelt profiles | Deprecated by Apple but still functional (no replacement exists) | +| **Linux** | [`bubblewrap`](https://github.com/containers/bubblewrap) (bwrap) | Read-only root bind mount + writable clone dir + namespace isolation | Requires `bwrap` package. [Fails on Ubuntu 24.04+](https://discourse.ubuntu.com/t/understanding-apparmor-user-namespace-restriction/58007) without admin AppArmor config. Works on Fedora/Arch | +| **Windows** | None available | Git config hardening only (Layer 1) | See Windows guidance below | -When no OS sandbox is available, the plugin warns and proceeds with git config hardening only. The sandbox is an additional defense layer — even without it, the git config flags neutralize all known `.gitattributes` attack vectors. +The plugin probe-tests sandbox availability at runtime and falls back gracefully. When no OS sandbox is available, a WARN is logged and cloning proceeds with git config hardening only. **Additional protections:** Post-clone size check (100MB max), UUID-unique evidence filenames (prevents race conditions), cleanup guarantee (temp files removed even on error). -**Windows guidance:** Windows has no equivalent to `sandbox-exec` or `bwrap` that ships with the OS. The most practical mitigation for Windows users is to run Claude Code itself inside a sandboxed environment (e.g., Windows Sandbox on Pro/Enterprise, Docker Desktop, or WSL2). The git config hardening layer provides baseline protection on all platforms. +**Windows guidance:** Windows has no CLI-level filesystem sandbox equivalent to `sandbox-exec` or `bwrap`. The alternatives either require additional software or admin privileges: + +| Option | Isolation level | Requirements | +|--------|----------------|--------------| +| [Windows Sandbox](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview) | Full VM (Hyper-V) | Windows Pro/Enterprise, Hyper-V enabled. GUI-oriented, not scriptable | +| [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) | Container | Requires Docker install. Best option for automated isolation | +| [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) | Linux VM | Requires WSL2 install. Once inside, `bwrap` is available (except Ubuntu 24.04+ caveat) | +| [AppContainer](https://learn.microsoft.com/en-us/windows/win32/secauthz/appcontainer-isolation) | Process sandbox | Requires native C++ helper binary — not practical to ship in a Node.js plugin | + +**Recommendation for Windows users:** Run Claude Code inside WSL2 or Docker Desktop for full sandbox coverage. The git config hardening (Layer 1) provides baseline protection on all platforms and neutralizes all known `.gitattributes` attack vectors even without an OS sandbox. + +> **Why not Node.js `--permission`?** Node's [permission model](https://nodejs.org/api/permissions.html) restricts `fs` module access within the Node process, but does **not** sandbox child processes like `git` which run as separate OS processes. It is therefore not useful for this use case. Output: structured report with ALLOW / WARNING / BLOCK verdict, risk score (0-100), and findings sorted by severity.