Vectra Guard - Security for Agentic Development

Overview

Vectra Guard's soft delete feature intercepts rm commands and automatically backs up files before deletion. This provides a safety net for accidental deletions, especially when working with AI agents or automated scripts.

Key Features

Automatic backup of deleted files and directories
Configurable retention policies (age, count, size)
Auto-delete old backups to manage disk space
Enhanced Git protection for repository files
Full restore functionality with flexible options
Comprehensive CLI for backup management

Quick Start

Enable soft delete and start using it immediately:

Basic Usage

# 1. Enable soft delete in configuration
vg init
# Edit vectra-guard.yaml:
# soft_delete:
#   enabled: true

# 2. Delete a file (automatically backed up)
vg exec -- rm important-file.txt

# 3. List backups
vg restore list

# 4. Restore if needed
vg restore <backup-id>

How It Works

When you run vg exec -- rm file.txt, Vectra Guard:

Intercepts the Command

Detects rm commands and analyzes the target files

Creates Backup

Copies files to ~/.vectra-guard/backups/ with unique backup ID and metadata

Executes Deletion

Proceeds with the deletion after backup is complete

Provides Restore

You can restore files anytime using vg restore <backup-id>

Commands

List Backups

# List all backups
vg restore list

# List with JSON output
vg restore list --format json

# Output:
# ID        Timestamp            Command       Files   Size
# --------------------------------------------------------------------------------
# abc123    2026-01-23 10:00:00  rm file.txt   1       1.2 KB

Show Backup Details

Show Backup

# Show details for a specific backup
vg restore show <backup-id>

# Output:
# Backup ID: abc123def456
# Timestamp: 2026-01-23 10:00:00
# Command: rm important-file.txt
# Total Size: 1.2 KB
# Files: 1
# 
# Files:
#   [file] /path/to/important-file.txt (1.2 KB)

Restore Files

# Restore to original location
vg restore <backup-id>

# Restore to different location
vg restore <backup-id> --to /path/to/restore

# Output:
# ✅ Restored 1 files from backup abc123def456
#    Restored to original locations

Backup Statistics

Statistics

# Show backup statistics
vg restore stats

# Output:
# Backup Statistics:
#   Total Backups: 15
#   Total Files: 23
#   Total Size: 45.2 MB
#   Git Backups: 3
# 
# Rotation Policy:
#   Max Age: 30 days
#   Max Backups: 100
#   Max Size: 1.0 GB
# 
# Auto-Delete:
#   Enabled: Yes
#   Threshold: 90 days

Cleanup & Auto-Delete

Cleanup

# Clean old backups (rotation)
vg restore clean

# Manually trigger auto-delete
vg restore auto-delete

# Permanently delete a specific backup
vg restore delete <backup-id>

Git Protection

Git files and directories receive enhanced protection when auto-delete is enabled:

Protected Files

.git/ directory and all contents
.gitignore, .gitattributes, .gitmodules
.gitkeep, .gitconfig
Any file matching **/.git/** pattern

Git Protection Configuration

# Git files get 2x protection threshold
soft_delete:
  enabled: true
  auto_delete: true
  auto_delete_after_days: 90
  protect_git: true
  git_backup_copies: 3

# Example:
# Normal backup: deleted after 90 days
# Git backup: deleted after 180 days (2x threshold)
# Git backups: keep at least 3 copies

Note: Git protection ensures you can always roll back repository changes, even if auto-delete is enabled.

Configuration

Configure soft delete behavior in your vectra-guard.yaml:

Full Configuration

soft_delete:
  enabled: true                    # Enable soft delete
  backup_dir: "~/.vectra-guard/backups"  # Backup directory
  max_age_days: 30                 # Keep backups for 30 days
  max_backups: 100                 # Maximum number of backups
  max_size_mb: 1024                # Maximum backup size (1 GB)
  auto_cleanup: true                # Auto-rotate old backups
  auto_delete: false                # Auto-delete old backups permanently
  auto_delete_after_days: 90        # Delete backups older than 90 days
  protect_git: true                 # Enhanced Git file protection
  git_backup_copies: 3              # Minimum Git backup copies
  rotation_policy: "age_and_count"  # age, count, size, or combined

Rotation Policies

age: Remove backups older than max_age_days
count: Keep only the most recent max_backups backups
size: Remove oldest backups when total size exceeds max_size_mb
age_and_count: Apply both age and count limits (recommended)

Use Cases

AI Agent Safety

When AI agents delete files, they're automatically backed up. Restore them if the agent made a mistake.

Accidental Deletions

Protect against typos in rm commands or accidental wildcard deletions.

Repository Safety

Git files get extra protection, ensuring you can always recover from accidental repository changes.

Automated Scripts

Run cleanup scripts with confidence — deleted files are backed up automatically.

Best Practices

1. Enable Auto-Delete

Set auto_delete: true to prevent backup directory from growing indefinitely. Configure auto_delete_after_days based on your needs.

2. Monitor Backup Size

Use vg restore stats regularly to monitor backup usage. Adjust max_size_mb if needed.

3. Keep Git Protection Enabled

Always enable protect_git: true to ensure repository files have extra protection.

4. Regular Cleanup

Run vg restore clean periodically or enable auto_cleanup for automatic rotation.

Soft Delete