Oculum CLI

AI-native security scanner for detecting vulnerabilities in AI-generated code, BYOK patterns, and modern web applications.

Features

• 🤖 AI-Native Security: Specialized detection for AI-era risks (BYOK patterns, agent tools, AI-generated code)
• ⚡ Multiple Scan Depths: Choose between local (fast), verified (AI-verified), or deep (comprehensive) scans
• 🎯 Low False Positives: AI validation reduces noise by ~70%
• 📊 Multiple Output Formats: Terminal, JSON, SARIF, or Markdown
• 🔄 Incremental Scanning: Scan only changed files for faster CI/CD
• 🎨 Interactive TUI: Beautiful terminal UI for exploring findings
• 🔐 Secure Authentication: Device flow authentication with GitHub

Installation

npm install -g @oculum/cli

Or use with npx (no installation required):

npx @oculum/cli scan .

Quick Start

1. Authenticate

oculum login

This will open a browser window for GitHub authentication. Follow the prompts to complete the login.

2. Run Your First Scan

# Local scan (fast, local-only)
oculum scan .

# Verified scan (AI-verified, recommended)
oculum scan . --mode verified

# Deep scan (comprehensive analysis)
oculum scan . --mode deep

3. Explore Results Interactively

oculum ui

Commands

oculum scan [path]

Scan a directory or file for security vulnerabilities.

Options:

• -d, --depth <mode> - Scan depth: local, verified, or deep (default: local)
• -f, --format <format> - Output format: terminal, json, sarif, or markdown (default: terminal)
• -o, --output <file> - Write output to file instead of stdout
• --incremental - Only scan files changed since last commit (git required)
• --config <path> - Path to config file (default: oculum.config.json)

Examples:

# Scan current directory with verified mode
oculum scan . --mode verified

# Scan specific file with JSON output
oculum scan src/api/auth.ts --format json

# Incremental scan for CI/CD
oculum scan . --incremental --mode verified

# Save results to file
oculum scan . --output results.sarif --format sarif

oculum ui

Launch interactive terminal UI for scanning and exploring results.

Features:

• Visual file tree navigation
• Real-time scan progress
• Interactive findings explorer
• Severity filtering
• Code snippet preview

oculum login

Authenticate with Oculum API using GitHub device flow.

Process:

1. CLI displays a URL and code
2. Open URL in browser
3. Enter code and authorize with GitHub
4. CLI automatically completes authentication

oculum status

Check authentication status and current tier.

Output:

• Logged in status
• Email address
• Current tier (free/pro)
• API key status

oculum logout

Remove stored credentials and log out.

Scan Depth Modes

Local (Free)

• Speed: Very fast (~5-10s for 100 files)
• Cost: Free, runs locally
• Detection: Pattern-based detection (Layer 1 + Layer 2)
• Use Case: Quick checks, pre-commit hooks, local development

Verified (Pro)

• Speed: Moderate (~30-60s for 100 files)
• Cost: Paid, requires API key
• Detection: Pattern + AI validation (reduces false positives by ~70%)
• Use Case: PR checks, CI/CD pipelines, production code

Deep (Pro)

• Speed: Slower (~2-5min for 100 files)
• Cost: Higher cost, requires API key
• Detection: Full semantic analysis with project context
• Use Case: Security audits, critical code paths, compliance

Configuration File

Create oculum.config.json in your project root:

{
  "depth": "verified",
  "format": "terminal",
  "ignore": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.test.ts"
  ],
  "include": [
    "src/**/*.ts",
    "src/**/*.js"
  ]
}

Options:

• depth - Default scan depth (local, verified, deep)
• format - Default output format (terminal, json, sarif, markdown)
• ignore - Glob patterns to exclude from scanning
• include - Glob patterns to include in scanning (overrides ignore)

Output Formats

Terminal (Default)

Human-readable output with colors and formatting:

════════════════════════════════════════════════════════════
  OCULUM SECURITY SCAN RESULTS
════════════════════════════════════════════════════════════

🔴 2 critical issues found

🔑 Secrets & Credentials (1 critical)
────────────────────────────────────────────────────────────
  🔴 CRITICAL Hardcoded API key detected
     src/config.ts:12
     API key appears to be hardcoded in source code.
     💡 Move to environment variables: process.env.API_KEY

JSON

Machine-readable JSON for programmatic processing:

{
  "summary": {
    "totalIssues": 2,
    "critical": 2,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "findings": [...]
}

SARIF

GitHub Security tab compatible format:

oculum scan . --format sarif --output results.sarif

Upload to GitHub:

- uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Markdown

Documentation-friendly format:

oculum scan . --format markdown --output SECURITY.md

What Oculum Detects

AI-Era Risks

• BYOK Patterns: Bring-your-own-key usage, storage, and logging
• Agent Tools: Over-permissive tool definitions, unsafe tool execution
• AI-Generated Code: Common patterns from AI coding assistants
• Prompt Injection: User input in AI prompts without sanitization

Traditional Security

• Secrets: Hardcoded API keys, tokens, credentials
• Injection: SQL injection, command injection, XSS
• Authentication: Missing auth checks, weak session handling
• Data Exposure: Sensitive data in logs, error messages, responses
• Dangerous Functions: eval, exec, unsafe deserialization

Configuration Issues

• Docker: Running as root, hardcoded secrets in Dockerfiles
• CORS: Permissive origins, credential exposure
• Environment: Committed .env files, hardcoded configs

CI/CD Integration

GitHub Actions

name: Security Scan
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Oculum
        run: npm install -g @oculum/cli
      
      - name: Authenticate
        run: echo "${{ secrets.OCULUM_API_KEY }}" | oculum login --stdin
      
      - name: Scan
        run: oculum scan . --mode verified --format sarif --output results.sarif
      
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

GitLab CI

security_scan:
  stage: test
  script:
    - npm install -g @oculum/cli
    - echo "$OCULUM_API_KEY" | oculum login --stdin
    - oculum scan . --mode verified --format json --output results.json
  artifacts:
    reports:
      codequality: results.json

Troubleshooting

Authentication Issues

Problem: Login failed: APIError

Solution:

1. Check your internet connection
2. Verify API endpoint is accessible: curl https://oculum-api.vercel.app/api/v1/auth/device
3. Try logging out and back in: oculum logout && oculum login

Scan Failures

Problem: Scan failed: quota exceeded

Solution:

• Check your usage: oculum status
• Upgrade to Pro tier for higher limits
• Use --mode local for unlimited local scans

Problem: Too many files being scanned

Solution:

• Add ignore patterns to oculum.config.json
• Use .gitignore patterns (automatically respected)
• Scan specific directories: oculum scan src/

Performance Issues

Problem: Scans are slow

Solution:

• Use --mode local for faster local scans
• Enable incremental scanning: --incremental
• Reduce scope with ignore patterns
• Scan only changed files in CI/CD

API Key Management

Getting an API Key

1. Sign up at https://oculum-api.vercel.app
2. Navigate to Dashboard → API Keys
3. Click "Create New Key"
4. Copy the key (shown only once)
5. Use with CLI: oculum login --api-key YOUR_KEY

Storing API Keys Securely

Local Development:

# Store in config (recommended)
oculum login

# Or use environment variable
export OCULUM_API_KEY="your-key-here"

CI/CD:

• Store as encrypted secret in your CI/CD platform
• Never commit API keys to version control
• Rotate keys regularly

Pricing

Free Tier

• ✅ Unlimited local scans
• ✅ Basic CLI access
• ✅ All output formats
• ❌ No verified/deep scans

Pro Tier

• ✅ Everything in Free
• ✅ Verified scans (AI-verified)
• ✅ Deep scans (semantic analysis)
• ✅ API access
• ✅ Priority support

View detailed pricing →

Examples

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

oculum scan . --mode local --format terminal
if [ $? -ne 0 ]; then
  echo "Security issues found. Commit blocked."
  exit 1
fi

Watch Mode (Development)

# Scan on file changes
oculum watch src/ --mode local

Scan Specific File Types

# Only TypeScript files
oculum scan . --include "**/*.ts" --include "**/*.tsx"

# Exclude tests
oculum scan . --ignore "**/*.test.ts" --ignore "**/*.spec.ts"

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📚 Docs: Documentation

License

MIT © Felix Westin

Made with ❤️ for developers building with AI