AI Assistants Integration

Integrate Oculum findings directly with AI coding assistants like Cursor, Windsurf, and Claude Code. Give your AI assistant security context to write safer code.

Overview

When you run a scan with AI assistant flags, Oculum generates configuration files that:

• Inform the AI about security issues in your codebase
• Provide rules to prevent common vulnerabilities
• Give context about your specific security concerns

---

Supported Assistants

---

Quick Start

Generate for Your IDE

# For Cursor
oculum scan --cursor

# For Windsurf
oculum scan --windsurf

# For Claude Code
oculum scan --claude-code

# Auto-detect and update all
oculum scan --ide-rules

Generate AI Context Document

# Generate structured context for any AI
oculum scan --ai-context

Creates .oculum/ai-context.md with detailed finding information.

---

Cursor Integration

Generate Cursor-specific security rules:

oculum scan --cursor

What Gets Generated

.cursor/rules/security.mdc:

---
description: Security rules from Oculum scan
globs:
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.js"
alwaysApply: true
---

# Security Guidelines

Based on Oculum security scan, follow these rules:

## Active Findings

### src/api/chat.ts
- Line 45: User input passed directly to LLM prompt
  - Always validate and sanitize user input before including in prompts

## Security Rules

1. **Never hardcode secrets** - Use environment variables
2. **Validate all user input** - Especially before LLM prompts
3. **Use parameterized queries** - Prevent SQL injection
4. **Escape output** - Prevent XSS

Usage in Cursor

Once generated, Cursor will:

• Apply these rules to code completions
• Suggest secure alternatives
• Warn about patterns in the findings

---

Windsurf Integration

Generate Windsurf-specific security rules:

oculum scan --windsurf

What Gets Generated

.windsurfrules:

# Security Rules (Oculum)

## Current Findings

The following security issues were found in this codebase:

- **src/api/chat.ts:45** - Unvalidated user input to LLM prompt
- **src/lib/auth.ts:12** - Potential hardcoded credential

## Rules

When generating code, follow these security practices:

1. Never include API keys or secrets in code
2. Always validate user input before use
3. Use environment variables for configuration
4. Sanitize input before including in prompts

---

Claude Code Integration

Update your CLAUDE.md with a security section:

oculum scan --claude-code

What Gets Generated

Adds or updates a ## Security section in CLAUDE.md:

## Security

Based on Oculum security scan (2026-01-20):

### Active Findings

| File | Line | Issue | Severity |
|------|------|-------|----------|
| src/api/chat.ts | 45 | Unvalidated LLM input | High |
| src/lib/auth.ts | 12 | Potential hardcoded credential | Critical |

### Security Guidelines

When writing code for this project:

1. **Secrets Management**: Use environment variables, not hardcoded values
2. **LLM Safety**: Validate and sanitize all user input before prompts
3. **Authentication**: Follow existing auth patterns in src/middleware/
4. **Data Validation**: Use Zod schemas for input validation

### Files to Review

- `src/api/chat.ts` - Contains LLM integration
- `src/lib/auth.ts` - Authentication logic

Preserves Existing Content

The --claude-code flag only updates the Security section, preserving all other content in your CLAUDE.md.

---

Auto-Detect Mode

Automatically detect and update all IDE configs:

oculum scan --ide-rules

This:

1. Detects which IDE config files exist
2. Updates them with current findings
3. Creates missing files if the IDE is detected

Detection Logic

• Cursor: Looks for .cursor/ directory
• Windsurf: Looks for .windsurfrules or Windsurf markers
• Claude Code: Looks for CLAUDE.md

---

Clear IDE Files

Remove generated security rules:

# Clear all IDE rule files
oculum scan --ide-rules --clear

# Or clear without scanning
oculum scan --clear

Use this after fixing all findings to remove the rules.

---

AI Context Document

Generate a detailed context document for any AI:

oculum scan --ai-context

What Gets Generated

.oculum/ai-context.md:

# Security Context for AI Assistants

Generated by Oculum on 2026-01-20

## Summary

- Total findings: 5
- Critical: 1
- High: 2
- Medium: 2

## Findings

### Critical

#### Hardcoded OpenAI API Key

**File**: src/lib/openai.ts:12
**Category**: hardcoded_secret

API key exposed in source code. This could allow unauthorized access.

**Code**:
\`\`\`typescript
const apiKey = "sk-proj-abc123..."
\`\`\`

**Remediation**: Use environment variables to store API keys.

...

## Project Security Profile

- Uses Next.js with App Router
- Authentication via Clerk
- Database: PostgreSQL with Prisma
- AI: OpenAI API integration

---

Combining with Scans

Use with other scan options:

# Verified depth + Cursor rules
oculum scan --depth verified --cursor

# Save JSON report + IDE rules
oculum scan --format json --output report.json --ide-rules

# Incremental scan + Claude Code
oculum scan --incremental --claude-code

---

Best Practices

Keep Rules Updated

Run IDE flag scans regularly:

# Add to your workflow
npm run scan  # package.json: "scan": "oculum scan --ide-rules"

Pre-Commit Hook

Update IDE rules before commits:

# .husky/pre-commit
oculum scan --ide-rules --quiet

CI Integration

Update IDE rules in CI:

- name: Update IDE Security Rules
  run: oculum scan --ide-rules --depth verified
  continue-on-error: true

Clear After Fixing

Remove rules when findings are resolved:

# After fixing all issues
oculum scan --ide-rules --clear
git add .cursor/ .windsurfrules CLAUDE.md
git commit -m "Clear security rules - all findings resolved"

---

Example Workflow

1. Initial scan: oculum scan --ide-rules
2. AI assists: Cursor/Windsurf/Claude Code see security context
3. Fix issues: Use AI suggestions to fix findings
4. Re-scan: oculum scan --ide-rules
5. Repeat until clean
6. Clear: oculum scan --clear

---

Related

• VS Code Extension — VS Code integration
• Scan Depths — Understanding scan modes
• Suppressing Findings — Handle false positives