Configuration Files

Configure Oculum's behavior with configuration files, profiles, and environment variables. Settings apply to all CLI commands and the VS Code extension.

Config File Location

Oculum looks for configuration in this order (first found wins):

.oculum.yaml (recommended)
.oculum.yml
oculum.config.json
.oculumrc

Place the config file in your project root.

Basic Configuration

YAML Format (Recommended)

# .oculum.yaml
version: 1

depth: local
failOn: none
format: terminal
quiet: false
verbose: false

ignore:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "__tests__/**"

include: []  # Empty means scan all

profiles: {}
watch: {}
suppressions: {}

JSON Format

{
  "depth": "local",
  "failOn": "none",
  "format": "terminal",
  "quiet": false,
  "verbose": false,
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts"
  ],
  "include": [],
  "profiles": {},
  "watch": {},
  "suppressions": {}
}

Configuration Options

Scan Options

Option	Type	Default	Description
`depth`	string	`local`	Default scan depth: `local`, `verified`, `deep`
`failOn`	string	`none`	Exit 1 on severity: `critical`, `high`, `medium`, `low`, `none`
`format`	string	`terminal`	Output format: `terminal`, `json`, `sarif`, `markdown`
`output`	string	-	Write output to this file path
`quiet`	boolean	`false`	Minimal output
`verbose`	boolean	`false`	Debug output

File Patterns

Option	Type	Default	Description
`ignore`	string[]	`[]`	Glob patterns to ignore
`include`	string[]	`[]`	Only scan files matching these patterns

Profiles

Profiles let you save different configurations for different use cases.

Defining Profiles

# .oculum.yaml
depth: local

profiles:
  ci:
    depth: verified
    format: sarif
    output: results.sarif
    quiet: true
    failOn: high

  audit:
    depth: deep
    format: json
    output: audit-report.json

  quick:
    depth: local
    ignore:
      - "**/*.test.ts"
      - "**/*.spec.ts"

  pr:
    depth: local
    failOn: critical
    incremental: true

Using Profiles

oculum scan -p ci
oculum scan -p audit
oculum scan -p quick
oculum scan -p pr

Priority Order

When options conflict:

CLI flags (highest priority)
Profile settings
Project config file
Built-in defaults (lowest priority)

# Profile says quiet: true, but CLI overrides
oculum scan -p ci --verbose

Watch Options

Configure watch mode defaults:

# .oculum.yaml
watch:
  debounce: 500
  cooldown: 10
  clear: true

Option	Type	Default	Description
`debounce`	number	`500`	Milliseconds to wait after last change
`cooldown`	number	`10`	Minimum seconds between scans
`clear`	boolean	`false`	Clear console before each scan

Suppressions

Configure finding suppressions in config:

# .oculum.yaml
suppressions:
  # Rule-based suppressions (by category)
  rules:
    - category: hardcoded_secret
      reason: "Test fixtures"
      paths:
        - "**/*.test.ts"
        - "__tests__/**"

    - category: high_entropy_string
      reason: "UUIDs in constants"
      paths:
        - "**/constants.ts"

  # Finding-based suppressions (by hash)
  findings:
    - hash: "a1b2c3d4e5f67890"
      file: "src/api/auth.ts"
      line: 42
      reason: "False positive - static config"
      expires: "2026-06-01"
      suppressedBy: "developer@example.com"

See Suppressing Findings for details.

Environment Variables

Variable	Description
`OCULUM_API_KEY`	API key for authentication

CI/CD Example

# GitHub Actions
env:
  OCULUM_API_KEY: ${{ secrets.OCULUM_API_KEY }}

steps:
  - run: oculum scan --depth verified

Environment variables override config file settings for authentication.

Example Configurations

Basic Project

# .oculum.yaml
version: 1

ignore:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "__tests__/**"

Monorepo

# .oculum.yaml
version: 1

include:
  - "packages/api/src/**"
  - "packages/web/src/**"

ignore:
  - "**/__tests__/**"
  - "**/fixtures/**"

profiles:
  api:
    include:
      - "packages/api/src/**"

  web:
    include:
      - "packages/web/src/**"

Full CI Setup

# .oculum.yaml
version: 1

depth: local

profiles:
  ci:
    depth: verified
    format: sarif
    output: results.sarif
    failOn: high
    quiet: true

  pr:
    depth: local
    failOn: critical
    incremental: true

  audit:
    depth: deep
    format: json
    output: audit.json

ignore:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "**/__mocks__/**"
  - "**/__tests__/**"

Security-Focused

# .oculum.yaml
version: 1

depth: verified
failOn: high

# Focus on high-risk areas
include:
  - "**/api/**"
  - "**/auth/**"
  - "**/middleware/**"
  - "**/*.env*"

# Suppress known false positives
suppressions:
  rules:
    - category: sensitive_url
      reason: "Dev URLs in config"
      paths:
        - "**/config.dev.ts"

VS Code Extension

The VS Code extension reads the same config file. Add VS Code-specific settings:

# .oculum.yaml
vscode:
  scanDepth: verified
  autoScanOnSave: true
  severityThreshold: medium

Or use VS Code settings:

{
  "oculum.scanDepth": "verified",
  "oculum.autoScanOnSave": true
}

.oculumignore

For gitignore-style patterns, create .oculumignore:

# Test files
**/*.test.ts
**/*.spec.ts
__tests__/

# Build output
dist/
build/
.next/

# Generated code
generated/
*.generated.ts

This is loaded in addition to config file ignore patterns.

Configuration Precedence

CLI flags
Environment variables (for auth)
Profile settings (if -p specified)
Project config file (.oculum.yaml)
.oculumignore file
Built-in defaults

Validating Configuration

Check your config is valid:

oculum scan --verbose

This shows which config file is loaded and what settings are applied.

CLI Commands — Command reference
Ignore Patterns — Pattern syntax
Suppressing Findings — Suppression config