Scan Depths

Oculum offers three scan depth levels that control how thoroughly your code is analyzed. Each depth represents a trade-off between speed, cost, and detection accuracy.

Quick Reference

Cheap (Pattern Matching)

The default scan depth. Fast, free, and deterministic.

oculum scan
# or explicitly
oculum scan --depth cheap

What It Does

• Layers used: 1 (Pattern Matching) + 2 (Structural Analysis)
• No AI validation — findings are based purely on patterns and heuristics
• Best for: Quick feedback during development, PR checks

Detectors Enabled

Layer 1 (Pattern Matching):

• Hardcoded secrets (API keys, tokens, passwords)
• High-entropy strings (potential secrets)
• Sensitive URLs (webhook endpoints, internal services)
• Risky configurations (debug flags, insecure settings)
• Weak cryptography (MD5, SHA1, DES)

Layer 2 (Structural Analysis):

• Dangerous functions (eval(), innerHTML, SQL concatenation)
• Missing authentication patterns
• AI code fingerprints (common LLM-generated patterns)
• Data exposure risks

When to Use

• Local development (quick feedback loop)
• Pull request checks (fast CI/CD)
• When you need immediate results
• When cost is a concern

Validated (AI-Validated)

Adds AI validation to reduce false positives by ~70%.

oculum scan --depth validated

What It Does

• Layers used: 1 + 2 + AI Validation
• AI validates each finding against the full file context
• ~70% fewer false positives compared to cheap scans
• Requires authentication (oculum login)

How AI Validation Works

1. Pattern matching (Layer 1) and structural analysis (Layer 2) identify potential issues
2. Each finding is sent to an AI model along with:
   • The full file content (not just the snippet)
   • Project context (auth middleware, ORM patterns, etc.)
3. The AI determines if the finding is:
   • Confirmed — real security issue
   • Downgraded — valid but lower severity
   • Dismissed — false positive

When to Use

• Interactive development (VS Code extension)
• When you want actionable results with minimal noise
• Pre-merge validation
• When false positives are slowing you down

Deep (Full Semantic Analysis)

The most thorough scan. Includes full AI semantic analysis.

oculum scan --depth deep

What It Does

• Layers used: 1 + 2 + AI Validation + Layer 3 (Semantic Analysis)
• Full taint analysis — traces data flow from sources to sinks
• Business logic analysis — detects authorization bypasses, logic flaws
• Requires authentication (oculum login)

Additional Capabilities in Layer 3

• Taint analysis: Traces user input through the codebase to dangerous sinks
• SQL injection detection: Finds injection vulnerabilities even in complex code
• XSS detection: Respects framework protections (React auto-escaping)
• Command injection: Identifies shell command construction from user input
• Authorization flaws: Detects missing or bypassable auth checks
• Framework-specific analysis: Understands Next.js, React, Express patterns

When to Use

• Initial repository onboarding (full security picture)
• Security audits and reviews
• Before major releases
• When investigating specific security concerns

Three-Layer Architecture

Oculum uses a layered detection system. Each layer adds capabilities:

Layer 1: Pattern Matching

Speed: ~1-2 seconds for typical repos

Fast, deterministic detection using:

• Regex patterns for known secrets (AWS keys, GitHub tokens, etc.)
• Entropy analysis for potential secrets (high-randomness strings)
• URL detection for sensitive endpoints
• Config auditing for risky settings

Layer 2: Structural Analysis

Speed: ~2-5 seconds for typical repos

Context-aware heuristics that analyze code structure:

• Auth patterns — detects missing authentication with middleware awareness
• Dangerous functions — eval(), innerHTML, SQL concatenation
• AI fingerprinting — patterns common in LLM-generated code
• Data exposure — logging or exposing sensitive information

Layer 2 is smarter than simple patterns. It understands:

• Auth middleware (Clerk, NextAuth, Auth0, custom)
• Throwing auth helpers (getCurrentUserId(), auth().protect())
• Static vs dynamic content in dangerous functions

Layer 3: AI Semantic Analysis

Speed: ~3-10 seconds depending on complexity

Deep analysis using AI models:

• Taint tracking — follows data from user input to dangerous operations
• Business logic — understands application-specific security requirements
• Cross-file analysis — traces flows across module boundaries

Only runs on high-priority files (API routes, auth handlers, middleware).

Severity Levels

Findings are categorized by severity:

Blocking issues: Any critical or high severity finding will cause CI checks to fail (when using --fail-on high or default behavior).

Choosing the Right Depth

Decision Guide

Is this a quick local check?
  └─ Yes → cheap (instant feedback)

Is this a PR/CI check?
  └─ Speed critical? → cheap
  └─ Quality critical? → validated

Is this a security audit?
  └─ Yes → deep (full analysis)

First time scanning a repository?
  └─ Yes → deep (understand the full picture)

Recommended Defaults by Workflow

Configuration

Set your default depth in oculum.config.json:

{
  "depth": "validated",
  "profiles": {
    "ci": {
      "depth": "cheap",
      "quiet": true
    },
    "audit": {
      "depth": "deep"
    }
  }
}

Then use profiles:

oculum scan -p ci     # Uses cheap depth
oculum scan -p audit  # Uses deep depth

Related

• Quickstart Guide — Get started with Oculum
• CLI Reference — All CLI commands and options
• Credits & Usage — Understand usage and quotas