Skip to content

security.md

Latest commit

 

History

History
565 lines (432 loc) · 17.6 KB

security.md

File metadata and controls

565 lines (432 loc) · 17.6 KB

Security & Sandbox

VibeCoding implements Linux process-level sandbox isolation through bubblewrap (bwrap) to protect system security.

Sandbox Overview

What is a Sandbox

A sandbox is a security mechanism that restricts a program's file system and network access permissions.

┌─────────────────────────────────────────────────────────────┐
│                     Sandbox Overview                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                  Sandboxed Process                      ││
│  │                                                          ││
│  │   Project Directory                                      ││
│  │   ┌─────────────────────────────────────────────────┐   ││
│  │   │  RW/RO access                                   │   ││
│  │   └─────────────────────────────────────────────────┘   ││
│  │                                                          ││
│  │   System Directories                                     ││
│  │   ┌─────────────────────────────────────────────────┐   ││
│  │   │  RO access only                                 │   ││
│  │   └─────────────────────────────────────────────────┘   ││
│  │                                                          ││
│  │   Network                                                ││
│  │   ┌─────────────────────────────────────────────────┐   ││
│  │   │  Blocked (standard/strict)                      │   ││
│  │   └─────────────────────────────────────────────────┘   ││
│  │                                                          ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
└─────────────────────────────────────────────────────────────┘

Sandbox Levels

Level Mode File System Network Use Case
none YOLO Full access Allowed System administration, network operations
standard Agent Project R/W, System R/O Disabled Daily development
strict Plan Project R/O, System R/O Disabled Code review, analysis

Detailed Comparison

Feature none standard strict
Read project files ✓ ✓ ✓
Write project files ✓ ✓ ✗
Read system files ✓ ✓ ✓
Write system files ✓ ✗ ✗
Network access ✓ ✗ ✗
Install packages ✓ ✗ ✗
Modify configuration ✓ ✗ ✗

Modes and Sandboxes

Plan Mode (Strict Sandbox)

Purpose: Read-only analysis and planning

vibecoding --mode plan
vibecoding -M plan

Features:

  • Project directory: Read-only
  • System directory: Read-only
  • Network: Disabled

Use Cases:

  • Code review
  • Project analysis
  • Learning codebase
  • Creating development plans

Agent Mode (Standard Sandbox)

Purpose: Standard development tasks

vibecoding --mode agent --sandbox
vibecoding -M agent --sandbox

Features:

  • Project directory: Read/write
  • System directory: Read-only
  • Network: Disabled

Use Cases:

  • Writing code
  • Modifying files
  • Running tests
  • Building projects

YOLO Mode (No Sandbox)

Purpose: Full access

vibecoding --mode yolo
vibecoding -M yolo

Features:

  • Project directory: Full access
  • System directory: Full access
  • Network: Allowed

Use Cases:

  • System administration
  • Installing packages
  • Network requests
  • Cross-project operations

Risks:

  • May modify system files
  • May execute dangerous commands
  • May expose sensitive information

Network Service Hardening

Gateway, Hermes, and A2A can expose HTTP/WebSocket entry points. Treat these services as remote code-execution surfaces whenever tools can run in agent or yolo mode.

  • Gateway: enable auth.enabled before exposing beyond loopback; startup warns when Gateway listens beyond loopback in yolo mode without authentication.
  • A2A: standalone A2A binds to 127.0.0.1 by default. Use --host 0.0.0.0 only for intentional exposure, and configure an auth token.
  • Hermes WebSocket: send tokens with Authorization: Bearer <token> during the WebSocket handshake. Query-string tokens are accepted only for compatibility.
  • Working directories: use allowedWorkDirs / allowed_work_dirs to restrict per-request or per-platform working directories.

Trusted Config Shell Commands

Provider API keys can be loaded from shell commands with apiKey: "!command", but this is disabled by default. Enable it only for trusted local config:

export VIBECODING_ALLOW_SHELL_CONFIG=1

Prefer environment-variable references such as ${DEEPSEEK_API_KEY} for shared configs.

Enabling Sandbox

Command Line

# Enable sandbox
vibecoding --sandbox

# Disable sandbox
vibecoding --no-sandbox

# Combine with mode
vibecoding --sandbox --mode plan

Configuration File

{
  "sandbox": {
    "enabled": true,
    "level": "standard",
    "allowNetwork": false
  }
}

Environment Variable

export VIBECODING_SANDBOX=true

bubblewrap (bwrap)

What is bwrap

bubblewrap is a lightweight Linux sandbox tool that uses Linux namespaces for process isolation.

Installing bwrap

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora/RHEL
sudo dnf install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

# Verify installation
bwrap --version

How bwrap Works

┌─────────────────────────────────────────────────────────────┐
│                    bwrap Namespaces                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Mount Namespace                       ││
│  │  /project    → RW/RO (depending on level)              ││
│  │  /usr        → RO                                       ││
│  │  /lib        → RO                                       ││
│  │  /etc        → RO                                       ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Network Namespace                     ││
│  │  No network access (standard/strict)                    ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    PID Namespace                         ││
│  │  Process isolation                                      ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
└─────────────────────────────────────────────────────────────┘

bwrap Command Examples

# Standard sandbox
bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --ro-bind /etc /etc \
  --bind /home/user/project /home/user/project \
  --tmpdir /tmp \
  --proc /proc \
  --dev /dev \
  --chdir /home/user/project \
  --unshare-net \
  --unshare-pid \
  --die-with-parent \
  -- sh -c "go build ./..."

# Strict sandbox
bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /home/user/project /home/user/project \
  --tmpdir /tmp \
  --proc /proc \
  --dev /dev \
  --chdir /home/user/project \
  --unshare-net \
  --unshare-pid \
  --die-with-parent \
  -- sh -c "go vet ./..."

Sandbox Configuration Details

SandboxManager

type Manager struct {
    level       Level
    workdir     string
    allowNetwork bool
}

type Level int

const (
    LevelNone     Level = iota  // Unrestricted
    LevelStandard               // Standard sandbox
    LevelStrict                 // Strict sandbox
)

Configuration Options

{
  "sandbox": {
    "enabled": true,
    "level": "standard",
    "allowNetwork": false,
    "allowDevices": false,
    "extraBinds": [
      "/path/to/extra:/mnt/extra"
    ]
  }
}
Field Type Default Description
enabled bool false Enable sandbox
level string "standard" Sandbox level
allowNetwork bool false Allow network
allowDevices bool false Allow device access
extraBinds []string [] Extra bind mounts

Security Best Practices

1. Enable Sandbox by Default

# Set alias in shell configuration
alias vibecoding='vibecoding --sandbox'

2. Choose Mode Based on Task

Task Recommended Mode Reason
Reading code Plan Read-only, safest
Modifying code Agent Project R/W, no network
Running tests Agent Needs execution permission
Installing dependencies YOLO Needs network
System administration YOLO Needs full permissions

3. Review High-Risk Operations

The following operations should be reviewed by humans:

  • Deleting files
  • Modifying system configuration
  • Executing unknown scripts
  • Accessing sensitive data

4. Use Version Control

# Commit regularly
git add .
git commit -m "save progress"

# Use branches
git checkout -b feature/new-feature

5. Limit Project Directory

# Run from project root directory
cd /home/user/project
vibecoding --sandbox

Sandbox Limitations

Unsupported Operations

Operation none standard strict
Install system software ✓ ✗ ✗
Access network ✓ ✗ ✗
Modify system files ✓ ✗ ✗
Access other projects ✓ ✗ ✗
Docker operations ✓ ✗ ✗

Performance Impact

  • Startup time: ~10-50ms increase
  • Memory overhead: Negligible
  • I/O performance: Minimal impact

Platform Support

Platform Support
Linux ✓ Full support
macOS ✗ Not supported
Windows ✗ Not supported (WSL usable)

Security Risks

Risks That Still Exist Even With Sandbox

  1. Project file corruption: Agent mode can modify project files
  2. Symbolic link attacks: Symbolic links in project may point outside
  3. Resource exhaustion: May consume excessive CPU/memory
  4. Information leakage: Project files may contain sensitive information

Mitigation Measures

# 1. Use version control
git init
git add .
git commit -m "initial"

# 2. Regular backups
cp -r project project.backup

# 3. Limit resources
timeout 300 vibecoding --sandbox

# 4. Check symbolic links
find . -type l -ls

Approval Mechanism

VibeCoding v0.0.4 introduces an Agent mode approval mechanism for enhanced security.

How It Works

In Agent mode, executing bash commands requires user approval:

  1. Whitelist check: Command prefix matches bashWhitelist entry → Auto-approve
  2. Blacklist check: Command prefix matches bashBlacklist entry → Always require approval
  3. Default behavior: Non-whitelisted commands → Require user y/n approval

Configuration Example

{
  "approval": {
    "bashWhitelist": ["go ", "make ", "git ", "npm ", "yarn "],
    "bashBlacklist": ["rm -rf", "sudo"]
  }
}

Default Whitelist

[
  "go ",
  "make ",
  "git ",
  "npm ",
  "yarn ",
  "node ",
  "python ",
  "pip "
]

Approval Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Approval Flow                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Agent requests bash command execution                       │
│  │                                                           │
│  ▼                                                           │
│  Check mode                                                  │
│  ├─ Plan mode → Deny (read-only)                             │
│  ├─ Agent mode → Continue checking                           │
│  └─ YOLO mode → Auto-approve                                 │
│                                                              │
│  In Agent mode:                                              │
│  ├─ Non-bash tool → Auto-approve                             │
│  ├─ Command matches whitelist → Auto-approve                 │
│  └─ Otherwise → Require user approval                        │
│                                                              │
│  User approval:                                              │
│  ├─ Enter y/yes → Execute command                            │
│  └─ Enter n/no → Deny execution                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Security Recommendations

  1. Keep default whitelist: Only allow common safe commands
  2. Add blacklist: Add dangerous commands like rm -rf, sudo to blacklist
  3. Regular review: Check approval logs to understand Agent-executed commands
  4. Combine with sandbox: Use --sandbox to limit file system access

Audit and Logging

Enable Debug Logging

vibecoding --debug

View Executed Commands

In debug mode, all executed commands are output to stderr:

[DEBUG] Executing: go build ./...
[DEBUG] Sandbox: bwrap --ro-bind /usr /usr ...
[DEBUG] Exit code: 0

Log Recording

# Save logs
vibecoding --debug 2>vibecoding.log

# Analyze logs
grep "Executing:" vibecoding.log

Troubleshooting

bwrap Not Installed

Error: bwrap: command not found

Solution:

# Install bwrap
sudo apt install bubblewrap

# Or disable sandbox
vibecoding --no-sandbox

Permission Issues

Error: bwrap: Permission denied

Solution:

  1. Check if bwrap is correctly installed
  2. Confirm user has permission to execute bwrap
  3. Check file system permissions

Network Access Failure

Error: network is unreachable

Solution:

  1. Use YOLO mode
  2. Or configure allowNetwork: true

File Access Failure

Error: Read-only file system

Solution:

  1. Use Agent mode (standard)
  2. Or use YOLO mode (none)
  3. Check file permissions

References