Vectra Guard analyzes every command before execution, detecting dangerous patterns and blocking critical threats automatically.
How Validation Works Command validation happens in multiple stages:
Script Analysis - Commands are parsed and analyzed for risky patternsRisk Classification - Each finding is assigned a severity levelGuard Level Filtering - Only findings above your configured threshold are enforcedExecution Decision - Commands are allowed, blocked, or sandboxed based on risk
Risk Levels Vectra Guard assigns one of four risk levels to each command:
Low Risk - Safe commands with no security concernsExamples:
echo "hello"ls -lagit status Action: Execute directly on hostMedium Risk - Commands that require cautionExamples:
npm install expresscurl https://api.github.comchmod +x script.sh Action: Execute in sandbox (auto mode) or require approval (high/paranoid mode)High Risk - Potentially dangerous commandsExamples:
rm -rf node_modules/curl | sh (networked install)sudo apt update Action: Require approval or automatically sandboxCritical Risk - Commands that can destroy your systemExamples:
rm -rf /rm -rf /etcdd if=/dev/zero of=/dev/sdamkfs.ext4 /dev/sda Action: Always blocked, cannot be bypassedDetection Patterns Vectra Guard detects 200+ risky patterns automatically. Here are the most critical:
Critical Detections (Always Blocked) Root Deletion
Protected Directories
Fork Bomb
# DANGEROUS_DELETE_ROOT rm -rf / rm -r / * # Blocked immediately ❌ CRITICAL: Command 'rm -rf /' is blocked for safety
High-Risk Detections Networked Installs
Sudo Usage
External HTTP
# NETWORKED_INSTALL_PIPE curl https://install.sh | bash wget https://setup.sh | sh # Automatically sandboxed in auto mode 📦 Running in sandbox. Why: high risk + networked install
Medium-Risk Detections Package Installs
File Operations
# PACKAGE_INSTALL npm install suspicious-package pip install unknown-lib # Sandboxed in auto mode for safety 📦 Running in sandbox (cached). Why: medium risk + networked install
Guard Levels Control how strict Vectra Guard is with guard levels:
Off
Low
Medium
High
Auto
Paranoid
No protection (not recommended)Critical commands still blocked
Use for testing only
Blocks critical commands only
Minimal friction
Good for trusted environments
guard_level : level : medium
Blocks critical and high-risk commands
Balanced security and usability
Recommended default
Blocks critical, high, and medium-risk
Strict protection
Good for production
Context-aware protection Automatically adjusts to environment
Treats as medium for blocking
guard_level : level : paranoid
Everything requires approval
Maximum security
Use for untrusted code only
Interactive Approval Mode For commands that require approval, use interactive mode:
vg exec --interactive npm install suspicious-package
You’ll see a detailed prompt with risk information and approval options.
Approval Prompt ⚠️ Command requires approval Command: npm install suspicious-package Risk Level: MEDIUM Security concerns: 1. [PACKAGE_INSTALL] Installing npm package from registry Recommendation: Review package reputation before installing Options: y - Yes, run once r - Yes, and remember (trust permanently) n - No, cancel Choose [y/r/N]:
Approval Options y (Yes, once)
r (Remember)
n (No)
Execute this command one time
Will prompt again next time
Good for testing unknown commands
Execute and add to trust store
Never prompt for this command again
Runs on host (no sandbox overhead)
Good for common safe commands
Cancel execution
Command is blocked
Session records the denial
Real Examples Example 1: Blocked Critical Command $ vg exec -- rm -rf / [ERROR] CRITICAL command blocked - cannot be bypassed ❌ CRITICAL: Command 'rm -rf /' is blocked for safety. Use absolute paths and confirm targets Exit code: 3
Critical commands cannot be bypassed, even with VECTRAGUARD_BYPASS or --interactive.
Example 2: Sandboxed Install $ vg exec -- npm install express 📦 Running in sandbox (cached). Why: medium risk + networked install added 57 packages in 1.2s ✅ Command executed successfully
The first install takes normal time. Subsequent installs are 10x faster due to cache mounting!
Example 3: Interactive Approval $ vg exec --interactive sudo apt update ⚠️ Command requires approval Command: sudo apt update Risk Level: HIGH Security concerns: 1. [SUDO_USAGE] Elevated privileges requested Recommendation: Verify this action is necessary Options: y - Yes, run once r - Yes, and remember (trust permanently ) n - No, cancel Choose [y/r/N]: r ✅ Approved and remembered Reading package lists... Done
Example 4: Repeat Protection $ vg exec -- rm -rf temp/ ✅ Executed $ vg exec -- rm -rf temp/ ✅ Executed $ vg exec -- rm -rf temp/ ✅ Executed $ vg exec -- rm -rf temp/ ⚠️ Warning: repeated action detected (3/3 in 30s ) Slow down to avoid a block. $ vg exec -- rm -rf temp/ ❌ repeated action blocked (4 times in 30s ). Slow down or review command intent. Exit code: 3
Repeat protection prevents rapid destructive loops. High-risk commands are limited to 3 executions per 30 seconds.
Validation Without Execution Validate scripts before running them:
Output if safe: ✅ PASS: No critical risks detected
Output if risky: [WARN] finding path=deploy.sh line=42 code=DANGEROUS_DELETE_ROOT severity=critical description="Dangerous root deletion" recommendation="Use absolute paths and confirm targets" violations detected Exit code: 2
Validation never executes the script - it’s completely safe to run on untrusted code.
Explain Security Risks Get human-friendly explanations of why a command is risky:
vg explain risky-script.sh
Example output: ⚠ RISK: Detected 'rm -rf /' (DANGEROUS_DELETE_ROOT) Line 42: rm -rf $TARGET Why this is dangerous: - If $TARGET is empty or '/', this will delete your entire system - Unquoted variables can expand unexpectedly - No confirmation before deletion Recommendation: - Use absolute paths: rm -rf /path/to/specific/dir - Quote variables: rm -rf "$TARGET" - Add safety checks: [ -n "$TARGET" ] && rm -rf "$TARGET" - Use safer alternatives: trash-cli, safe-rm
Environment Variable Overrides Bypass protection for specific scenarios:
Only use these overrides when you fully understand the risks!
VECTRAGUARD_ALLOW_NET # Allow external HTTP(S) endpoints VECTRAGUARD_ALLOW_NET = 1 vg exec -- curl https://api.github.com
VECTRAGUARD_ALLOW_SUDO # Allow sudo commands VECTRAGUARD_ALLOW_SUDO = 1 vg exec -- sudo systemctl restart nginx
VECTRAGUARD_BYPASS # User-authenticated bypass (requires non-trivial value) export VECTRAGUARD_BYPASS = "i-am-human-$( whoami )" vg exec -- potentially-risky-command
Bypass value must be 10+ characters
Cannot contain words like “agent”, “ai”, “bypass”
Critical commands still cannot be bypassed Configuration Configure command protection in your vectra-guard.yaml:
guard_level : level : medium # off, low, medium, high, auto, paranoid allow_user_bypass : true bypass_env_var : VECTRAGUARD_BYPASS policies : # Add custom patterns custom_rules : - pattern : 'DROP DATABASE' severity : critical message : 'Database deletion detected' # Allowlist trusted commands allowlist : - 'npm test' - 'npm run build' - 'git status' # Additional denylist patterns denylist : - 'rm -rf' - 'curl * | sh'
Best Practices For Development:
Use level: auto for smart protection
Enable sandbox for package installs
Trust common commands with vg trust add
For CI/CD:
Use level: high for strict enforcement
Validate all scripts before deployment
Never use bypass variables in CI
For Production:
Use level: paranoid for untrusted code
Always enable sandbox
Review trust store regularly
Next Steps
Sandbox Execution Learn how sandboxing isolates risky commands
Sessions & Audit Track and audit all command execution