Security Documentation Index

Complete guide to VT Code's security documentation.

Quick Start

New to VT Code Security? Start here:

• Security Model - Complete security architecture

Core Documentation

For Users

Security Guide

• Security features overview
• Configuration instructions
• Best practices
• Incident response

For Developers

Security Model

• Complete security architecture
• Defense-in-depth layers
• Threat model
• Adding new commands safely
• Security testing procedures

Unsafe Code Inventory

• Maintainer inventory of intentional unsafe and FFI boundaries
• Safety invariants and review rules for new sites

Web Fetch Security

• Web fetch security policies

For Organizations

Tool Policies

• Command execution policies
• Approval workflows
• Policy configuration

Security Features by Layer

Layer 1: Command Allowlist

• Location: crates/codegen/vtcode-core/src/execpolicy/mod.rs
• Documentation: Security Model - Layer 1
• Only 9 commands allowed: ls, cat, cp, head, printenv, pwd, rg, sed, which

Layer 2: Argument Validation

• Location: crates/codegen/vtcode-core/src/execpolicy/mod.rs
• Documentation: Security Model - Layer 2
• Per-command validators: Explicit flag allowlists, execution flag blocking

Layer 3: Workspace Isolation

• Location: crates/codegen/vtcode-core/src/execpolicy/mod.rs
• Documentation: Security Model - Layer 3
• Path validation: Normalization, symlink resolution, boundary checks

Layer 4: Sandbox Integration

• Location: crates/codegen/vtcode-core/src/sandbox/, crates/codegen/vtcode-core/src/tools/bash_tool.rs
• Documentation: Security Guide - Sandbox
• Anthropic sandbox: Filesystem isolation, network allowlist

Layer 5: Human-in-the-Loop

• Location: src/agent/runloop/unified/tool_routing.rs
• Documentation: Security Guide - Approval System
• Three-tier approval: Once, Session, Permanent

Layer 6: Shell Shape Validation and Approval Learning

• Location: crates/codegen/vtcode-safety/src/command_safety/shell_parser.rs, src/agent/runloop/unified/tool_routing/shell_approval.rs
• Documentation: Security Model - Shell Shape Validation
• Dynamic find syntax: Rejected at preflight and excluded from learned read-only families

Layer 7: Workspace Lifecycle Hook Approval

• Location: crates/codegen/vtcode-config/src/loader/manager.rs (workspace-hook collection), crates/codegen/vtcode-core/src/hooks/lifecycle/engine.rs (fail-closed gate + SHA-256 digest), src/agent/runloop/unified/session_setup/hook_approval.rs (approval overlay)
• Documentation: Security Model - Workspace Lifecycle Hook Approval, Security Guide - Workspace Lifecycle Hook Approval
• Workspace-controlled hooks (vtcode.toml, .vtcode/, project profiles, agent-spec files): gate the whole engine — no lifecycle hook runs until the exact command set is approved for the workspace; digest-bound approval revalidated before every spawn, after config reload, and across primary-agent switches

Configuration

Tool Policy

• Defaults: vtcode.toml in the canonical user config directory
• Persisted approvals: tool-policy.json in the canonical user config directory
• Documentation: Tool Policies, User Data Directories

Workspace Configuration

• File: vtcode.toml
• Documentation: Configuration Guide

Sandbox Configuration

• File: vtcode.toml (sandbox section)
• Documentation: Security Guide - Sandbox

Reporting Security Issues

Responsible Disclosure

1. Do Not Disclose Publicly - Report privately first
2. GitHub Security Advisory - Use GitHub's security advisory feature
3. Provide Details - Include reproduction steps
4. Coordinate Disclosure - Allow time for fix

Contact

• GitHub: Security Advisories
• Email: See GitHub profile

---

Documentation Version: 1.0 Last Updated: October 25, 2025 Security Model Version: 1.0