AI Agent Integration

Configure Cursor, Copilot, and other AI coding assistants to use Vectra Guard

Overview

AI coding assistants like Cursor, GitHub Copilot, and others can execute commands that might be risky. Vectra Guard protects you by automatically sandboxing and validating commands suggested by AI agents.

Supported Agents

  • Cursor - AI-powered code editor
  • GitHub Copilot - AI pair programmer
  • Codeium - AI coding assistant
  • Tabnine - AI code completion
  • Generic Agents - Any AI agent via .agents/AGENTS.md

Quick Start

Seed agent instructions in your project with a single command:

Seed Agent Instructions
# Seed instructions for all supported agents
vg seed agents --target .

# Seed for specific agents
vg seed agents --target . --targets "cursor,copilot"

# This creates:
# - .cursorrules (Cursor AI rules)
# - .github/copilot-instructions.md (Copilot instructions)
# - .agents/AGENTS.md (Generic agent instructions)

Cursor Integration

Cursor reads instructions from .cursorrules file. Vectra Guard automatically generates this file with security-focused rules.

Setup Cursor
# Generate .cursorrules
vg seed agents --target . --targets cursor

# The generated .cursorrules includes:
# - Instructions to use Vectra Guard for all commands
# - Security best practices
# - Command validation rules

Example .cursorrules Content

# Vectra Guard Security Rules for Cursor

## Command Execution
- Always use Vectra Guard (vg) to execute commands
- Use `vg exec` instead of direct command execution
- Use `vg validate` before running scripts
- Use `vg cve scan` before installing dependencies

## Security Guidelines
- Never execute commands that modify system files without approval
- Always scan for CVEs before installing packages
- Use sandbox mode for untrusted commands
- Validate scripts before execution

## Example Usage
```bash
# Instead of: npm install
vg exec -- npm install

# Instead of: ./deploy.sh
vg validate scripts/deploy.sh && vg exec -- ./deploy.sh
```

GitHub Copilot Integration

Copilot reads instructions from .github/copilot-instructions.md. Configure it to use Vectra Guard for safer command suggestions.

Setup Copilot
# Generate Copilot instructions
vg seed agents --target . --targets copilot

# Creates .github/copilot-instructions.md

Copilot Instructions Example

# Vectra Guard Security Instructions

When suggesting commands:
1. Always prefix with `vg exec --` for execution
2. Use `vg validate` for script validation
3. Use `vg cve scan` before package installation
4. Prefer sandboxed execution for untrusted code

Example:
- ❌ Bad: `npm install express`
- ✅ Good: `vg exec -- npm install express`
- ✅ Better: `vg cve scan --path . && vg exec -- npm install express`

Generic Agent Integration

For any AI agent that can read markdown files, use .agents/AGENTS.md. This file contains universal instructions for AI agents.

Setup Generic Agents
# Generate generic agent instructions
vg seed agents --target . --targets agents

# Creates .agents/AGENTS.md

Agent Instructions Template

# Vectra Guard - AI Agent Instructions

## Overview
This project uses Vectra Guard for secure command execution. All commands should be executed through Vectra Guard.

## Command Execution Rules

### 1. Always Use Vectra Guard
- Use `vg exec -- <command>` instead of direct execution
- Example: `vg exec -- npm install` not `npm install`

### 2. Validate Scripts
- Use `vg validate <script>` before executing scripts
- Example: `vg validate scripts/deploy.sh`

### 3. Scan for CVEs
- Run `vg cve scan --path .` before installing dependencies
- Check for high/critical severity vulnerabilities

### 4. Use Sessions
- Start a session: `SESSION=$(vg session start --agent "ai-agent")`
- Export: `export VECTRAGUARD_SESSION_ID=$SESSION`

## Security Best Practices
- Never execute destructive commands without validation
- Always scan dependencies for vulnerabilities
- Use sandbox mode for untrusted code
- Review command output before proceeding

Configuration

Customize agent instructions by editing the generated files or configuring Vectra Guard:

Agent Configuration
# Configuration for agent integration
agents:
  enabled: true
  auto_seed: true  # Auto-generate on vg init
  
  # Instruction templates
  templates:
    cursor: .cursorrules
    copilot: .github/copilot-instructions.md
    generic: .agents/AGENTS.md
  
  # Security level for agent commands
  security_level: 2  # 1-4, default is 2
  
  # Auto-sandbox agent commands
  auto_sandbox: true

Workflow Integration

Integrate Vectra Guard into your AI-assisted development workflow:

1. Project Setup

# Initialize Vectra Guard
vg init --local

# Seed agent instructions
vg seed agents --target .

2. Start Development Session

# Start a tracked session
SESSION=$(vg session start --agent "cursor")
export VECTRAGUARD_SESSION_ID=$SESSION

# Now Cursor will use Vectra Guard automatically

3. AI Agent Workflow

  1. AI agent suggests a command
  2. Command is automatically routed through Vectra Guard
  3. Vectra Guard validates and sandboxes if needed
  4. Command executes safely
  5. Results are logged to session

4. Review Session

# View all commands executed in session
vg session show $SESSION

# Export session report
vg session export $SESSION --format json

Best Practices

1. Always Seed Instructions

Run vg seed agents in every project to ensure AI agents know about Vectra Guard.

2. Use Sessions

Start a session when working with AI agents. This provides a complete audit trail of all commands.

3. Review Before Execution

Even with Vectra Guard, review commands suggested by AI agents before executing them.

4. Enable Auto-Sandbox

Configure agents.auto_sandbox: true to automatically sandbox all AI-suggested commands.

5. Regular CVE Scans

When AI agents suggest installing packages, always run CVE scans first to check for vulnerabilities.

Troubleshooting

Agent Not Using Vectra Guard

If your AI agent isn't following Vectra Guard instructions:

  • Verify the instruction file exists (e.g., .cursorrules)
  • Check that the agent supports reading instruction files
  • Try regenerating instructions: vg seed agents --target . --force
  • Restart your editor/agent after seeding

Commands Still Running on Host

If commands aren't being sandboxed:

  • Check sandbox configuration: vg config show
  • Verify sandbox is enabled: sandbox.enabled: true
  • Enable auto-sandbox for agents: agents.auto_sandbox: true