Skip to main content

​
What are Guard Levels?

Guard levels control what requires approval or is automatically blocked. They determine how strict Vectra Guard is when evaluating commands.
Guard levels answer: “Should I ask the user about this command?”Sandbox mode answers: “Where should this command run?”

​
Guard Level Options

​
Auto-Detection Deep Dive

When level: auto, Vectra Guard analyzes multiple signals to determine the appropriate protection level:

​
1. Git Branch Detection

production_indicators:
  branches:
    - main
    - master
    - production
    - release
    - live

​
2. Command Content Analysis

Vectra Guard scans commands for production indicators: 
# Commands with "prod" or "production"
vg exec "kubectl apply -f prod-config.yaml"  # → high level
vg exec "deploy-to-production.sh"            # → high level

# Deploy commands
vg exec "npm run deploy"                     # → high level
vg exec "./deploy.sh"                        # → high level

​
3. URL and Hostname Detection

# Production URLs
vg exec "curl https://api.production.company.com/deploy"  # → high
vg exec "wget https://prod.example.com/data"              # → high

# Development URLs
vg exec "curl http://localhost:3000"                      # → low
vg exec "curl https://dev.api.company.com"                # → low

​
4. Database Name Detection

# Production databases
vg exec "psql prod_database -c 'SELECT * FROM users'"  # → high
vg exec "mysql -h prod-db.company.com"                 # → high

# Development databases
vg exec "psql dev_database"                            # → low
vg exec "sqlite3 local.db"                             # → low

​
5. File Path Detection

# Production paths
vg exec "cp config.json /var/www/production/"  # → high
vg exec "rm /opt/prod/cache/*"                 # → high

# Development paths
vg exec "cp file.txt /tmp/"                    # → low
vg exec "mkdir ~/dev/new-project"              # → low

​
6. Environment Variable Detection

# Production environment
ENV=production vg exec "node app.js"           # → high
NODE_ENV=production vg exec "npm start"        # → high

# Development environment
ENV=development vg exec "node app.js"          # → low

​
Production Indicators

Teach Vectra Guard your organization’s patterns:
vectra-guard.yaml
production_indicators:
  # Git branches that indicate production
  branches:
    - main
    - master
    - production
    - release
    - live
    - stable
    
  # Keywords in URLs, hostnames, database names, paths
  keywords:
    - prod
    - production
    - prd
    - live
    - staging
    - stg
    - uat
    - preprod
    # Add your org's patterns:
    - company-prod
    - api-live
Customize these patterns to match your infrastructure naming conventions.

​
Detection Priority

When multiple signals conflict, the most dangerous context wins (safety first!): 
# Example: On dev branch, but command has "prod" keyword
git checkout dev/feature
vg exec "deploy-to-prod.sh"
# → Uses HIGH level (production detected in command)

# Example: On main branch, safe command
git checkout main  
vg exec "git log"
# → Uses PARANOID level (production branch)
Priority Order:
  1. Production branch → paranoid
  2. Production keywords in command → high
  3. Production URLs/databases → high
  4. Deploy-related commands → high
  5. Development context → medium or low

​
Environment Variable Overrides

Override guard level at runtime: 
# For trusted operations in prod environment
VECTRA_GUARD_LEVEL=low vg exec "safe-script.sh"
VECTRAGUARD_BYPASS only works when guard_level.allow_user_bypass: true in config.

​
Bypass Configuration

Control whether users can override protection: 
guard_level:
  level: auto
  allow_user_bypass: true  # Allow env var override
  bypass_env_var: VECTRAGUARD_BYPASS  # Custom var name

guard_level:
  level: auto
  allow_user_bypass: true  # Allow bypasses in dev
Developers can override when needed:
VECTRA_GUARD_LEVEL=low vg exec "trusted-script"

​
Guard Level Comparison

LevelCriticalHighMediumLowBest For
off✅ Allow✅ Allow✅ Allow✅ AllowTesting only
low❌ Block⚠️ Warn✅ Allow✅ AllowTrusted dev
medium❌ Block❌ Block⚠️ Warn✅ AllowTeam dev
high❌ Block❌ Block❌ Block✅ AllowCI/CD
paranoid❌ Block❌ Block❌ Block❌ BlockProduction
auto🤖 Smart🤖 Smart🤖 Smart🤖 SmartRecommended
❌ Block = Requires explicit approval ⚠️ Warn = Shows warning but allows ✅ Allow = Executes automatically 🤖 Smart = Adjusts based on context

​
Real-World Examples

guard_level:
  level: auto
  allow_user_bypass: true
Scenario:
# On feature branch - uses low/medium level
git checkout feature/auth
vg exec "npm install"           # ✅ Allowed
vg exec "npm test"              # ✅ Allowed
vg exec "git push"              # ✅ Allowed

# Switch to main branch - bumps to paranoid
git checkout main
vg exec "npm publish"           # ❌ Requires approval
vg exec "git push"              # ❌ Requires approval

guard_level:
  level: high
  allow_user_bypass: false  # No interactive prompts
Scenario:
# In CI environment
vg exec "npm ci"                # ✅ Allowed (low risk)
vg exec "npm test"              # ✅ Allowed (low risk)
vg exec "npm run build"         # ✅ Allowed (low risk)
vg exec "curl | sh"             # ❌ Auto-denied (high risk)
vg exec "rm -rf node_modules"   # ⚠️ Sandboxed (medium risk)

guard_level:
  level: paranoid
  allow_user_bypass: false
Scenario:
# Every command requires explicit approval
vg exec "ls"                    # ❌ Requires approval
vg exec "cat config.json"       # ❌ Requires approval
vg exec "./deploy.sh"           # ❌ Requires approval
vg exec "git status"            # ❌ Requires approval

# User must explicitly approve each operation
# Full audit trail created

guard_level:
  level: auto

production_indicators:
  branches:
    - main
    - release
  keywords:
    - prod
    - production
Scenario:
# On dev branch, safe command
git checkout dev/feature
vg exec "npm install"           # → low (allowed)

# On dev branch, production keyword in command
vg exec "deploy-to-prod.sh"    # → high (requires approval)

# On main branch, any command
git checkout main
vg exec "git log"              # → paranoid (requires approval)

​
Approval Thresholds

Fine-tune what requires approval: 
guard_level:
  level: medium
  require_approval_above: medium  # Require approval for medium+ severity
SettingBehavior
lowApprove low, medium, high, critical
mediumApprove medium, high, critical
highApprove high, critical
criticalApprove critical only

​
Testing Your Configuration

Validate guard level behavior: 
# Test auto-detection
vg explain "deploy-to-production.sh"
vg explain "npm install"
vg explain "curl https://api.prod.company.com"

# Dry run
vg exec --dry-run "risky-command"

# View current level
vg init --show-config | grep guard_level

​
Best Practices

Use Auto

Start with level: auto and let Vectra Guard intelligently adjust protection.

Customize Indicators

Add your organization’s production patterns to production_indicators.

No Bypasses in Prod

Set allow_user_bypass: false in production environments.

Test Detection

Use vg explain to test how commands are evaluated.

​
Troubleshooting

Solutions:
  1. Adjust production indicators to be more specific
  2. Use explicit level: level: medium
  3. Override with env var: VECTRA_GUARD_LEVEL=low
Solutions:
  1. Add your patterns to production_indicators.keywords
  2. Add your branches to production_indicators.branches
  3. Use explicit level: level: high or level: paranoid
Solutions:
  1. Lower guard level: level: medium or level: low
  2. Add safe commands to allowlist
  3. Use auto mode: level: auto

​
Next Steps

Sandbox Config

Configure where commands run (sandbox modes)

Presets

Use pre-configured guard levels for common scenarios

Build docs developers (and LLMs) love

Get started for freeTalk to us