Security & Sandbox
Relevant source files
The following files were used as context for generating this wiki page:
Marginalia protects the local environment and the GitLab repository through a combination of local-only execution and restricted execution environments. It confines the Claude Code CLI within a sandbox to prevent unauthorized access to the host machine. The system maintains a "user-in-the-loop" model where no data leaves the machine without explicit user confirmation.
Sources: README.md:533-550, PRODUCT.md:13-16, PRODUCT.md:39-44
Execution Sandbox
The bot executes the claude CLI in a dedicated git worktree to isolate it from the developer's working branch. A configuration built in lib/claude-sandbox.mjs defines the boundaries of the execution environment.
Bash Confinement
The sandbox confines Bash operations to specific directories. It limits write access to the bot worktree, the repository's .git folder, and the review output directory. It explicitly denies read access to sensitive locations including ~/.ssh, ~/.aws, and the bot's .env file.
Sources: README.md:533-540
Network and Tool Restrictions
Network access is restricted solely to the GitLab host. The sandbox implements deny rules to prevent the Read, Edit, and Write tools from accessing shell configuration files or trusted hooks. Git operations are restricted to one subcommand at a time through lib/allowed-tools.mjs.
Sources: README.md:540-545, README.md:551-555
Sandbox Logic Flow
The following diagram illustrates how the system isolates the Claude execution process from the host machine.
The diagram shows the isolation between the Claude CLI and sensitive host files, while allowing restricted access to the worktree.
Sources: README.md:533-550, README.md:562-564
Network Security & Local Architecture
The studio server and poller run entirely on the user's local machine. This architecture eliminates the need for public webhooks or HTTPS tunnels.
Local Connectivity
The studio server binds to 127.0.0.1 by default. It provides a read-only interface unless the user explicitly opts into posting capabilities. The server implements DNS-rebinding and cross-site protection by validating the Host and Origin headers for all write requests.
Sources: README.md:27-29, studio/public/openapi.yaml:8-16
External Communication
All communication with GitLab occurs via polling from the user's machine using the GITLAB_TOKEN. The bot never posts comments or reviews automatically. It requires an explicit user action in the studio to publish any drafted content.
Sources: PRODUCT.md:39-44, studio/public/openapi.yaml:18-22
| Feature | Security Control | Purpose |
|---|---|---|
| Server Binding | 127.0.0.1 | Prevents external network access to the studio. |
| Write Protection | Host/Origin validation | Mitigates DNS-rebinding and CSRF attacks. |
| Authentication | Local GitLab Token | Uses existing user permissions without shared credentials. |
| Data Residency | Local-only | No review data is shared or hosted on external servers. |
Sources: PRODUCT.md:13-16, studio/public/openapi.yaml:8-16
Credential Protection
Marginalia scrubs environment variables to prevent credential leakage during AI execution. Before spawning the claude process, the bot strips ANTHROPIC_API_KEY to ensure the tool runs under the user's login session rather than an API key. This prevents unintended billing and forces the use of the user's own connectors.
Sources: README.md:86-90, README.md:545-546
Variable Scrubbing Flow
The system manages environment variables to isolate the AI's execution context.
The sequence shows the transition of environment variables from the host OS to the confined sandbox.
Sources: README.md:86-90, README.md:545-547
Operational Constraints
Several configuration flags govern the safety of automated operations. These are managed via .env or the studio's settings.
- ALLOW_POSTING: If set to
false(default), all write endpoints to GitLab return403 Forbidden. - ALLOW_PUSH: Controls whether the studio can push triage fixes to origin.
- CLAUDE_SANDBOX: Allows users to disable confinement if specific local tools require broader access.
- CLAUDE_EXTRA_ALLOWED_TOOLS: A whitelist for additional tools required by custom commands.
Sources: README.md:188-193, README.md:548-550, studio/public/openapi.yaml:18-22, studio/src/components/SettingsPage.tsx:43-46
Summary
Marginalia implements a layered security model focusing on local isolation. The sandbox confines the AI execution to a temporary worktree, while the studio server uses strict header validation to protect the local web interface. By keeping the user in control of all GitLab interactions, the system minimizes the risk of unauthorized repository changes.
Sources: README.md:533-550, PRODUCT.md:39-44