scan

Scan a directory or file for security vulnerabilities. This is the primary command you'll use with Oculum.

oculum scan [path] [options]

Path: Directory or file to scan. Defaults to current directory (.).

Options

Scan Depths

Choose the right depth for your use case:

Note: validated and deep require authentication. See Scan Depths for full details.

Output Formats

terminal (default)

Human-readable colored output with severity indicators:

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
   Sanitize or validate user input before use

json

Machine-readable JSON for integrations:

{
  "scanId": "scan_abc123",
  "repoName": "my-app",
  "filesScanned": 47,
  "findings": [
    {
      "id": "finding_xyz",
      "category": "hardcoded_secret",
      "severity": "high",
      "message": "Hardcoded API key detected",
      "file": "src/api/chat.ts",
      "line": 45,
      "column": 12,
      "snippet": "const apiKey = 'sk-abc123...'",
      "remediation": "Use environment variables"
    }
  ],
  "summary": {
    "total": 1,
    "critical": 0,
    "high": 1,
    "medium": 0,
    "low": 0,
    "info": 0
  }
}

sarif

GitHub Code Scanning compatible format for the Security tab:

oculum scan -f sarif -o results.sarif

Use with the GitHub Action for automatic SARIF uploads.

markdown

Report-style output for documentation or sharing:

oculum scan -f markdown -o report.md

Examples

Basic Usage

# Scan current directory
oculum scan

# Scan specific directory
oculum scan src/

# Scan a single file
oculum scan src/api/chat.ts

Scan Depths

# Fast pattern matching (default)
oculum scan

# AI-validated scan (fewer false positives)
oculum scan --depth validated

# Full security audit
oculum scan --depth deep

CI/CD Integration

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

# Quiet mode for cleaner CI logs
oculum scan --fail-on high --quiet

# Generate SARIF for GitHub Security
oculum scan -f sarif -o results.sarif --fail-on high

Incremental Scanning

# Only scan changed files (great for PRs)
oculum scan --incremental

# Compare against main branch
oculum scan --diff main

# Compare against specific commit
oculum scan --diff abc1234

Filtering

# Ignore test files
oculum scan -i "**/*.test.ts" -i "**/*.spec.ts"

# Ignore entire directories
oculum scan -i "legacy/**" -i "vendor/**"

# Use multiple patterns
oculum scan -i "**/__tests__/**" -i "**/*.mock.ts"

Profiles

# Use a named profile from config
oculum scan -p ci

# Profiles override defaults but CLI flags win
oculum scan -p ci --verbose

Exit Codes

Tips

For Local Development

• Use cheap depth for quick feedback during coding
• Run oculum watch for continuous scanning as you edit

For CI/CD

• Use --incremental on PRs to focus on changed code
• Use validated depth on main branch for accuracy
• Always set --fail-on to enforce quality gates

For Security Audits

• Use deep depth for comprehensive analysis
• Run on the entire codebase, not just changed files
• Export results with -f json -o audit.json for records

Related

• watch - Continuous scanning during development
• Configuration - Config files and profiles
• Scan Depths - Understanding scan modes
• GitHub Action - CI/CD integration