AI Agent Integration

Vectra Guard provides first-class integration with AI coding agents, ensuring they operate safely within your development environment.

Quick Start: Seed Agent Instructions

The seed agents command automatically creates instruction files for AI agents:

# Seed instructions for common agents
vg seed agents --target . --targets "agents,cursor,claude"

# Seed OpenClaw plugin configuration
vg seed agents --target . --targets "openclaw"

# Seed everything at once
vg seed agents --target . --targets "agents,claude,cursor,openclaw,copilot"

Supported AI Agents

Cursor
Claude / Copilot
OpenClaw
Windsurf / Codex

Cursor IDE Integration

Cursor is automatically protected when you install the shell tracker:

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

# Seed Cursor-specific instructions
vg seed agents --target . --targets "cursor"

What gets created:

.cursor/rules/vectra-guard.md - Agent instructions
VSCode tasks for protected commands

Agent workflow:

# Cursor Agent Instructions (from seeded file)

## CVE Scanning
Before installing packages:
1. Run: vg cve sync --path .
2. Run: vg cve scan --path .
3. Review vulnerabilities
4. Install: vg exec -- npm install

## Session Management
- Use $VECTRAGUARD_SESSION_ID for all commands
- Log operations with vg session record

Claude Desktop & GitHub Copilot

Seed instructions for Claude and Copilot:

vg seed agents --target . --targets "claude,copilot"

What gets created:

AGENTS.md - General agent instructions
.github/copilot-instructions.md - Copilot-specific

Agent workflow example:

# Before Package Installation
1. Sync CVE database: vg cve sync --path .
2. Scan for vulnerabilities: vg cve scan --path .
3. If no critical CVEs, proceed: vg exec -- npm install

# For Risky Operations
- Validate scripts before running: vg validate script.sh
- Use interactive mode: vg exec --interactive -- sudo command
- Trust safe commands: vg trust add "npm test"

OpenClaw Plugin

VectraGuard integrates as a first-class OpenClaw plugin with runtime security:

# 1. Seed the plugin config
vg seed agents --target . --targets "openclaw"

# 2. Install the OpenClaw plugin
pnpm add @openclaw/vectraguard

# 3. Config is already created (auto-detected state directory)
# Edit .openclaw/AGENTS.md or ~/Library/Application Support/openclaw/AGENTS.md

Plugin features:

Feature	Hook/Tool	Description
Command gate	`before_tool_call`	Blocks dangerous shell commands
Prompt firewall	`llm_input`	Detects prompt injection (observe)
CVE scanning	`vectraguard_cve_scan`	Agent can check vulnerabilities
Secret detection	`vectraguard_secret_scan`	Finds exposed secrets
Audit trail	`after_tool_call`	Logs all shell executions
CVE sync	Background service	Keeps database updated

Gateway RPC methods:

# Check plugin status
vectraguard.status

# Run scans
vectraguard.scan --type cve --path .
vectraguard.scan --type secrets --path .

# Seed agent files
vectraguard.seed --list
vectraguard.seed --targets agents,cursor

# View configuration
vectraguard.config

How command gate works:

Agent: rm -rf /important-data
  → VectraGuard analyzes: CRITICAL RISK
  → Plugin returns: { block: true, blockReason: "..." }
  → Command never executes ✅

Agent: npm install express
  → VectraGuard analyzes: LOW RISK
  → Plugin allows through
  → OpenClaw's exec approval runs
  → Command executes safely ✅

Windsurf & OpenAI Codex

vg seed agents --target . --targets "windsurf,codex"

What gets created:

General AGENTS.md with security workflows
Agent-specific instruction templates

These agents follow the same security patterns as Claude/Copilot.

Seed Agents Command Reference

List Available Targets

vg seed agents --list

# Output:
# Available targets:
#   agents       -> AGENTS.md
#   claude       -> AGENTS.md
#   codex        -> AGENTS.md
#   copilot      -> .github/copilot-instructions.md
#   cursor       -> .cursor/rules/vectra-guard.md
#   openclaw     -> .openclaw/AGENTS.md (or ~/Library/Application Support/openclaw/)
#   vscode       -> .vscode/vectra-guard.md
#   windsurf     -> AGENTS.md

Seed Multiple Targets

vg seed agents --target . --targets "agents,claude,cursor,openclaw,copilot"

OpenClaw Auto-Detection

The seed agents command automatically detects your OpenClaw installation:

vg seed agents --targets "openclaw"

# Auto-detects:
# - $OPENCLAW_STATE_DIR (environment variable)
# - ~/Library/Application Support/openclaw (macOS default)
# - ~/.config/openclaw (Linux default)
# - ~/.openclaw (legacy fallback)
# - .openclaw/ (current directory fallback)

# Interactive confirmation:
#   OpenClaw detected (environment variable OPENCLAW_STATE_DIR)
#   State directory: /custom/path/openclaw
#   
#   Destination: /custom/path/openclaw/AGENTS.md
#   Confirm? [Y/n/custom path]:

Agent Instruction Templates

CVE Scanning Workflow

All seeded agent files include this workflow:

## CVE Scanning Workflow

### Before Installing Dependencies

1. **Sync CVE Database**
   ```bash
   vg cve sync --path .

Scan for Vulnerabilities
```
vg cve scan --path .
```
Review Results
- If no critical CVEs: proceed with installation
- If critical CVEs: consider alternatives or upgrades
Protected Installation
```
vg exec -- npm install
```

Explain Specific Packages

vg cve explain lodash@4.17.20 --ecosystem npm

### Session Management

```markdown
## Session Management for Agents

### Start Session

```bash
SESSION=$(vg session start --agent "cursor-ai" --workspace .)
export VECTRAGUARD_SESSION_ID=$SESSION

Track Operations

All commands are automatically tracked when using the shell tracker.

Review Activity

vg session show $VECTRAGUARD_SESSION_ID
vg session list

### Trust Store Usage

```markdown
## Trust Store for Repeated Commands

### Trust Safe Commands

```bash
# Trust a command permanently
vg trust add "npm test" --note "Test suite"

# Trust with expiration
vg trust add "npm run build" --duration "7d"

List Trusted

vg trust list

Remove Trust

vg trust remove "npm test"

---

## Complete Workflow Example

Here's a complete agent workflow from seeded instructions:

### Step 1: Initialize Project Security

Set up your security environment:

```bash
# Start session
SESSION=$(vg session start --agent "cursor-ai")
export VECTRAGUARD_SESSION_ID=$SESSION

# Initialize local config
vg init --local

# Sync CVE database
vg cve sync --path .

Step 2: Check Dependencies for Vulnerabilities

Scan for known vulnerabilities:

# Scan manifests
vg cve scan --path .

# Explain specific packages if needed
vg cve explain express@4.17.1 --ecosystem npm

Step 3: Install Dependencies Safely

Use protected execution for installations:

# Protected installation
vg exec -- npm install

# Trust common commands for faster workflow
vg trust add "npm test"
vg trust add "npm run dev"

Step 4: Validate Scripts Before Running

Always validate scripts before execution:

# Validate deployment script
vg validate scripts/deploy.sh

# Explain risks if validation fails
vg explain scripts/deploy.sh

# Run with interactive approval
vg exec --interactive -- ./scripts/deploy.sh

Step 5: Review Session Activity

Check what happened during the session:

# View all operations
vg session show $SESSION

# Export for audit
vg session show $SESSION --output json > audit.json

Seed Output Example

When you run vg seed agents, you get detailed output:

vg seed agents --target . --targets "agents,cursor,openclaw"

============================================================
  VECTRA GUARD — Seed Agent Instructions
============================================================

  Repository:  vectra-guard
  Branch:      main
  Workspace:   /home/user/projects/vectra-guard
  Project:     go

  Seed Results:
  --------------------------------------------------
    [+] ./AGENTS.md                                  2.4 KB
    [+] ./.cursor/rules/vectra-guard.md              1.8 KB
    [+] ~/.openclaw/AGENTS.md                        2.4 KB (merged)

  Agent Coverage:
  --------------------------------------------------
    [*] agents     AGENTS.md                        (just now, 2.4 KB)  NEW
    [ ] claude     AGENTS.md                        (not seeded)
    [*] cursor     .cursor/rules/vectra-guard.md    (just now, 1.8 KB)  NEW
    [*] openclaw   .openclaw/AGENTS.md              (just now, 2.4 KB)  NEW
    [ ] copilot    .github/copilot-instructions.md  (not seeded)

  Coverage: 3/5 agents configured

  VectraGuard Protection:
  --------------------------------------------------
    Guard Level:    auto (context-aware)
    Sandbox:        ENABLED (mode: always)
    CVE Scanner:    ENABLED
    Soft Delete:    ENABLED
    Env Protection: ENABLED (masking: partial)
    Git Ops Guard:  ENABLED

    Config: .vectra-guard/config.yaml

  --------------------------------------------------
  Tip: `vg seed agents --targets agents,cursor,copilot` to add more
  Tip: `vg serve` to open the security dashboard
============================================================

Best Practices

For Agent Instructions

Always sync CVE database first
```
vg cve sync --path .
```
Scan before installing
```
vg cve scan --path .
```

Use sessions for tracking

export VECTRAGUARD_SESSION_ID=$(vg session start --agent "my-agent")

Trust common, safe commands

vg trust add "npm test"
vg trust add "git status"

Validate scripts before execution

vg validate script.sh
vg exec -- ./script.sh

For OpenClaw Integration

Let the plugin handle command gating
- The plugin automatically blocks dangerous commands
- No need for manual vg exec wrapping

Use the CVE scan tool

// Agent can call this tool
await agent.callTool('vectraguard_cve_scan', { path: '.' })

Review audit logs
- All shell executions are logged via after_tool_call hook
- Check logs regularly for suspicious activity

Next Steps

IDE Integration

Set up VSCode and Cursor tasks

CI/CD Integration

Add security to your pipelines

Git Hooks

Validate scripts before commit

Configuration

Customize agent protection settings

Get Started

Core Features

Security

Configuration

Advanced

Integrations

AI Agent Integration

AI Agent Integration

Quick Start: Seed Agent Instructions

Supported AI Agents

Cursor IDE Integration

Claude Desktop & GitHub Copilot

OpenClaw Plugin

Windsurf & OpenAI Codex

Seed Agents Command Reference

List Available Targets

Seed Multiple Targets

OpenClaw Auto-Detection

Agent Instruction Templates

CVE Scanning Workflow

Explain Specific Packages

Track Operations

Review Activity

List Trusted

Remove Trust

Step 2: Check Dependencies for Vulnerabilities

Step 3: Install Dependencies Safely

Step 4: Validate Scripts Before Running

Step 5: Review Session Activity

Seed Output Example

Best Practices

For Agent Instructions

For OpenClaw Integration

Next Steps

IDE Integration

CI/CD Integration

Git Hooks

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Security

Configuration

Advanced

Integrations

​AI Agent Integration

​Quick Start: Seed Agent Instructions

​Supported AI Agents

​Cursor IDE Integration

​Claude Desktop & GitHub Copilot

​OpenClaw Plugin

​Windsurf & OpenAI Codex

​Seed Agents Command Reference

​List Available Targets

​Seed Multiple Targets

​OpenClaw Auto-Detection

​Agent Instruction Templates

​CVE Scanning Workflow

​Explain Specific Packages

​Track Operations

​Review Activity

​List Trusted

​Remove Trust

​Step 2: Check Dependencies for Vulnerabilities

​Step 3: Install Dependencies Safely

​Step 4: Validate Scripts Before Running

​Step 5: Review Session Activity

​Seed Output Example

​Best Practices

​For Agent Instructions

​For OpenClaw Integration

​Next Steps

IDE Integration

CI/CD Integration

Git Hooks

Configuration

Build docs developers (and LLMs) love

AI Agent Integration

Quick Start: Seed Agent Instructions

Supported AI Agents

Cursor IDE Integration

Claude Desktop & GitHub Copilot

OpenClaw Plugin

Windsurf & OpenAI Codex

Seed Agents Command Reference

List Available Targets

Seed Multiple Targets

OpenClaw Auto-Detection

Agent Instruction Templates

CVE Scanning Workflow

Explain Specific Packages

Track Operations

Review Activity

List Trusted

Remove Trust

Step 2: Check Dependencies for Vulnerabilities

Step 3: Install Dependencies Safely

Step 4: Validate Scripts Before Running

Step 5: Review Session Activity

Seed Output Example

Best Practices

For Agent Instructions

For OpenClaw Integration

Next Steps