COMMAND_SECURITY_MODEL.md

VT Code Command Security Model

Overview

VT Code implements a comprehensive, defense-in-depth command security system that enables non-powered users to run safe commands by default while protecting against dangerous operations. This system helps the agent use system and build tools properly via environment PATH configuration.

Design Philosophy

Safe-by-default: All known safe commands for development and system utilities are enabled without requiring user confirmation or configuration.

Layered Defense: Multiple validation layers (allow_list, allow_glob, deny_list, deny_glob, allow_regex, deny_regex) work together to prevent dangerous commands from executing.

Deny-rules-first: If a command matches any deny pattern, it is blocked regardless of allow patterns.

Architecture

Configuration Sources (Precedence Order)

1. vtcode.toml - User/project-level overrides (highest priority)
2. vtcode-config/src/core/commands.rs - Code defaults (runtime)
3. vtcode-config/src/constants.rs - System constants (backup)

Command Validation Layers

Commands are validated against these layers in order:

Input: command → Check deny_list → Check deny_glob → Check deny_regex
                    ↓ MATCH = DENY
              Check allow_list → Check allow_glob → Check allow_regex
                    ↓ MATCH = ALLOW
              Otherwise → DENY (fail-closed)

Safe Commands (Enabled by Default)

Categories

1. File System Utilities (Read-Only)

Safely query and display file information without modification:

• Basic: ls, pwd, cat, head, tail, echo, printf
• Search: grep, find, locate
• Analysis: wc, sort, uniq, cut, awk, sed
• Inspection: file, stat, diff, tree, du, df

2. Version Control (Git/Hg/SVN)

Inspect repository state and manage commits safely:

• Inspection: git status, git log, git show, git diff, git branch
• Safe workflows: git fetch, git pull, git add, git commit, git stash, git tag
• Other VCS: hg, svn, git-lfs

3. Build Systems

Core compilation and build tool execution:

• Make-based: make, cmake, ninja, meson, bazel
• Rust ecosystem: cargo, rustc, rustfmt, rustup, cargo test
• All major subcommands: cargo build, cargo test, cargo check, cargo run, etc.

4. Language Runtimes & Package Managers

Execution and dependency management for all major languages:

• Python: python, python3, pip, pip3, virtualenv, pytest, black, flake8, mypy, ruff
• Node.js: npm, node, yarn, pnpm, bun, npx
• Go: go, gofmt, golint
• Java: java, javac, mvn, gradle
• C/C++: gcc, g++, clang, clang++

5. Compression & Archiving

Safe data compression without system-level access:

• tar, zip, unzip, gzip, gunzip, bzip2, bunzip2, xz, unxz

6. Container Tools

Docker and container platforms:

• docker, docker-compose (with restrictions on docker run)
• Note: docker run * is denied; containers require careful review

7. System Information

Safe read-only system monitoring:

• ps, top, htop - Process listing and monitoring
• df, du - Disk usage
• whoami, hostname, uname - System identity

Glob Patterns for Workflows

Patterns like git *, cargo *, npm run * enable entire command families:

allow_glob = [
  "git *",              # All git subcommands
  "cargo *",            # All cargo workflows
  "cargo test *",    # Test execution
  "python *",           # Python with any flags
  "npm run *",          # NPM script execution
  "docker *",           # All docker (except restricted)
]

Dangerous Commands (Always Denied)

Categories

1. Destructive Filesystem Operations

• Root deletion: rm -rf /, rm -rf /*, rm -rf /home, rm -rf /usr, rm -rf /etc
• Home deletion: rm -rf ~
• Filesystem tools: mkfs, mkfs.ext4, fdisk, dd if=/dev/*

2. System Shutdown/Reboot

• shutdown, reboot, halt, poweroff
• systemctl poweroff, systemctl reboot, systemctl halt
• init 0, init 6

3. Privilege Escalation

• Any sudo command: sudo rm, sudo chmod, sudo bash, etc.
• Root switching: su root, su -
• Admin shells: sudo -i, nohup bash -i, exec bash -i

4. Filesystem Mounting/Unmounting

• mount, umount - Prevent unauthorized filesystem manipulation

5. Disk/Data Destruction

• format, fdisk, mkfs, shred, wipe
• dd if=/dev/zero, dd if=/dev/random, dd if=/dev/urandom

6. Permission/Ownership Changes

• chmod 777, chmod -R 777 - Make files world-writable (dangerous)
• chown -R, chgrp -R - Recursive ownership changes

7. Shell Exploits

• Fork bomb: :(){ :|:& };:
• Code evaluation: eval - Prevents arbitrary code injection
• Config sourcing: source /etc/bashrc, source ~/.bashrc

8. Sensitive Data Access

• User databases: cat /etc/passwd, cat /etc/shadow
• SSH keys: cat ~/.ssh/id_*, rm ~/.ssh/*, rm -r ~/.ssh
• System logs: tail -f /var/log, direct log access

9. Process Control

• kill, pkill - Process termination
• Note: Allows monitoring (ps, top, htop) but not process killing

10. Service Management

• systemctl * - System service manipulation (denied at glob level)
• service * - Legacy service management
• crontab, at - Task scheduling (dangerous for automation)

VT Code supports automation through internal scheduling primitives instead:

• /loop for session-scoped recurring prompts in interactive chat
• vtcode schedule for durable local automation and reminders

11. Container/Orchestration

• kubectl * - Kubernetes operations (admin access)
• docker run * - Container creation (requires careful review)

Validation Rules (Configuration Reference)

allow_list - Explicit Commands

Exact command matches allowed without confirmation.

[commands]
allow_list = [
  "ls",
  "pwd",
  "git status",
  "cargo build",
]

deny_list - Explicit Blocks

Exact command patterns that are always blocked.

deny_list = [
  "rm -rf /",
  "rm -rf ~",
  "sudo rm",
  ":(){ :|:& };:",
]

allow_glob - Glob Patterns

Wildcard patterns for command families.

allow_glob = [
  "git *",        # All git commands
  "cargo *",      # All cargo commands
  "npm run *",    # NPM scripts
]

deny_glob - Denied Patterns

Blocks entire command families.

deny_glob = [
  "rm *",         # All rm variations
  "sudo *",       # All sudo usage
  "chmod *",      # All chmod variations
]

allow_regex - Regex Patterns

Regular expressions for complex allow rules.

allow_regex = [
  r"^cargo (build|test|run|check|clippy|fmt)\b",
  r"^git (status|log|show|diff|branch)\b",
]

deny_regex - Regex Blocks

Regular expressions to block patterns.

deny_regex = [
  r"rm\s+(-rf|--force|--recursive)",
  r"sudo\s+.*",
  r"docker\s+run\s+.*--privileged",
]

PATH Configuration

The system extends the shell PATH with safe, common locations:

[commands]
extra_path_entries = [
  "$HOME/.cargo/bin",           # Rust tools (rustup, cargo)
  "$HOME/.local/bin",           # User-installed binaries
  "$HOME/.nvm/versions/node/*/bin",  # Node.js versions
  "/opt/homebrew/bin",          # Homebrew (macOS)
]

This allows the agent to access:

• Rust tools: cargo, rustc, rustfmt, rustup
• Python tools: pytest, black, flake8, mypy
• Node tools: npm, yarn, node
• Go tools: go, gofmt
• And all other build/development tools installed via package managers

Environment Variables

Configuration for tool execution:

[commands.environment]
RUST_BACKTRACE = "1"
PATH = { append = ["$HOME/.cargo/bin"] }
HOME = "$HOME"

Audit & Logging

The permission system logs all decisions for security and debugging:

[permissions]
enabled = true
audit_enabled = true
audit_directory = "~/.vtcode/audit"
log_allowed_commands = true
log_denied_commands = true
cache_ttl_seconds = 300

Audit logs track:

• Allowed commands executed
• Blocked/denied commands attempted
• Permission decision cache hits
• Command resolution paths

Usage with the VT Code Agent

Default Behavior (Non-Powered Users)

Out of the box:

1. Agent can execute all safe commands from allow_list
2. Agent can use pattern-based commands like git *, cargo *
3. Dangerous commands are automatically blocked with no prompt

Adding Custom Commands

To enable additional safe commands:

[commands]
allow_list = [
  # ... existing commands ...
  "custom-build-tool",
  "my-deployment-script",
]

Or via globs:

allow_glob = [
  "my-tool *",
  "custom-build *",
]

Requiring Confirmation for Destructive Operations

When using run_pty_cmd, set confirm=true for commands that need approval:

# Example from agent
run_pty_cmd(
  command=["git", "reset", "--hard"],
  confirm=True  # Requires user confirmation despite being in allow_glob
)

Customization Guide

Restrictive Setup (High Security)

[commands]
# Only allow explicit commands
allow_list = [
  "ls", "pwd", "cat", "git", "cargo", "python"
]

# Block everything else
allow_glob = []
allow_regex = []

# Extensive deny lists
deny_glob = [
  "*",  # Deny everything by default
]

Permissive Setup (Developer Productivity)

[commands]
# Allow development tools broadly
allow_glob = [
  "git *",
  "cargo *",
  "npm *",
  "python *",
  "*-cli *",     # CLI tools
  "*-build *",   # Build tools
]

# Still block dangerous patterns
deny_glob = [
  "rm *",
  "sudo *",
  "chmod *",
]

Project-Specific Setup

[commands]
allow_list = [
  "ls", "pwd", "cat", "grep",
]

# Allow project-specific tools
allow_glob = [
  "make *",
  "./scripts/*",
  "docker compose *",
]

deny_glob = [
  "rm -rf",
  "sudo *",
]

Security Considerations

What This Protects Against

Accidental destructive commands Privilege escalation attempts Malicious shell exploits (forkbombs, eval injection) Sensitive data exposure (SSH keys, password files) System shutdown/corruption Filesystem manipulation

What This Does NOT Protect Against

Compromised agent LLM (if it's compromised, it can craft allowed commands to cause harm) Commands that are allowed but have dangerous flags (e.g., cargo build --offline with missing dependencies) Zip bombs or other valid-but-malicious allowed file operations Side effects of running safe commands in a bad state

Best Practices

1. Keep deny_list comprehensive - Always block system-altering commands
2. Use allow_glob sparingly - More specific allow_list entries are safer
3. Monitor audit logs - Review ~/.vtcode/audit/ regularly for suspicious patterns
4. Test configurations - Validate with cargo test before deploying
5. Avoid eval-like patterns - Never allow eval, source, dynamic command construction
6. Isolate workspaces - Consider separate configurations for different project types

Examples

Example 1: Rust Development Project

[commands]
allow_list = [
  "ls", "pwd", "cat", "grep", "find",
  "git", "cargo", "rustc", "rustfmt",
]

allow_glob = [
  "git *",
  "cargo *",
  "cargo test *",
]

deny_glob = [
  "rm *", "sudo *", "chmod *", "kill *",
]

Example 2: Python Data Science Project

[commands]
allow_list = [
  "ls", "pwd", "cat", "grep", "find",
  "python", "python3", "pip", "pip3",
  "jupyter", "git",
]

allow_glob = [
  "python *",
  "python3 *",
  "pip *",
  "git *",
  "conda *",
]

deny_glob = [
  "rm *", "sudo *", "chmod *",
]

Example 3: Full-Stack Development (Node + Backend)

[commands]
allow_list = [
  "ls", "pwd", "cat", "grep", "find",
  "git", "npm", "node", "python",
  "docker", "docker-compose",
]

allow_glob = [
  "git *",
  "npm *",
  "npm run *",
  "node *",
  "python *",
  "docker *",
  "docker-compose *",
]

deny_glob = [
  "rm *", "sudo *", "chmod *", "kill *",
  "docker run *",  # Explicit deny for container creation
]

Testing & Validation

Test command permissions using VT Code's built-in validation:

# Build and test
cargo build
cargo test

# Check configuration
cargo run -- ask "list safe commands"

# Run with debug logging
RUST_LOG=debug cargo run

See Also

• docs/development/EXECUTION_POLICY.md - Overall execution policy
• docs/environment/ALLOWED_COMMANDS_REFERENCE.md - Complete command reference
• vtcode-config/src/core/commands.rs - Implementation
• vtcode.toml.example - Configuration examples