Oculum/Docs

Your First Scan

Run your first Oculum scan and discover security vulnerabilities in your code. This guide walks you through the basics of scanning a project.

Quick Start

Navigate to your project and run a scan:

cd your-project
oculum scan

That's it! Oculum will:

  1. Detect your project type
  2. Scan all supported files
  3. Display results in your terminal

Scanning Options

Scan Current Directory

oculum scan

Scan Specific Directory

oculum scan src/

Scan a Single File

oculum scan src/api/auth.ts

Scan Depths

Oculum offers three scan depths:

DepthCommandDescription
localoculum scanFast pattern matching (default, free)
verifiedoculum scan --depth verifiedAI-validated (~70% fewer false positives)
deepoculum scan --depth deepFull semantic analysis

verified and deep scans require authentication.

Example Output

┌────────────────────────────────────────────────────────────────┐
│  Oculum Security Scan                                          │
│  Repository: my-ai-app                                         │
│  Files scanned: 47                                             │
└────────────────────────────────────────────────────────────────┘

Found 3 issues:

  CRITICAL: Hardcoded API Key
   src/lib/openai.ts:12
   API key exposed in source code
   Use environment variables instead

  HIGH: Unvalidated User Input to LLM
   src/api/chat.ts:45
   User input passed directly to prompt without sanitization
   Sanitize or validate user input before use

  MEDIUM: Missing Rate Limiting
   src/api/chat.ts:1
   No rate limiting on AI endpoint
   Consider adding rate limiting

Scan completed in 1.2s

Common Scan Options

# Use verified scan depth (more accurate)
oculum scan --depth verified

# Output as JSON
oculum scan --format json

# Save to file
oculum scan --output report.json --format json

# Fail if high severity issues found
oculum scan --fail-on high

# Minimal output for CI
oculum scan --quiet

Authentication (Optional)

Authentication unlocks:

  • AI-validated scans (fewer false positives)
  • Deep semantic analysis
  • Dashboard sync
  • API access

Browser OAuth

oculum login

This opens your browser for GitHub authentication.

API Key

oculum login --api-key YOUR_KEY

Get your API key from the Dashboard Settings.

Check Status

oculum status

What Gets Scanned

Oculum focuses on security-relevant code:

  • API routes and handlers — Authentication, authorization, input validation
  • Database operations — SQL injection, data exposure
  • External integrations — API keys, secrets, credentials
  • AI/LLM code — Prompt injection, unsafe execution
  • Configuration files — Debug settings, exposed secrets

Oculum automatically skips:

  • node_modules/, vendor/, .git/
  • Build output (dist/, build/, .next/)
  • Lock files and minified code

Next Steps