Oculum/Docs

Targeting Files & Directories

Control exactly what Oculum scans with path arguments, include patterns, and ignore patterns. Focus your scans on the code that matters most.

Basic Targeting

Scan Current Directory

oculum scan

Scan Specific Directory

oculum scan src/
oculum scan packages/api/

Scan Multiple Paths

oculum scan src/ lib/ tests/

Scan Specific File

oculum scan src/api/auth.ts

Include Patterns

Limit scanning to files matching specific patterns:

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

# Only scan API routes
oculum scan --include "src/api/**"

# Multiple patterns
oculum scan --include "src/**" --include "lib/**"

In Configuration

{
  "include": [
    "src/**",
    "lib/**"
  ]
}

When include is set, only files matching these patterns are scanned.

Ignore Patterns

Exclude files from scanning:

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

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

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

In Configuration

{
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "__tests__/**",
    "fixtures/**"
  ]
}

.oculumignore File

Create a .oculumignore file for gitignore-style patterns:

# Comments start with #

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

# Ignore fixtures and mocks
fixtures/
**/*.mock.ts
**/*.fixture.ts

# Ignore legacy code
legacy/
deprecated/

# Ignore minified files
*.min.js
*.bundle.js

# Ignore generated code
generated/
.next/
dist/

Pattern Syntax

Oculum uses glob patterns (same as .gitignore):

PatternMatches
*.test.tsFiles ending in .test.ts in current directory
**/*.test.tsFiles ending in .test.ts anywhere
tests/Directory named tests and all contents
src/legacy/*Files directly in src/legacy/
src/legacy/**All files under src/legacy/ recursively
*.{js,ts}Files ending in .js or .ts

Default Ignore Patterns

These patterns are always ignored (you don't need to add them):

Directories

  • node_modules/
  • dist/, build/, out/
  • .git/, .svn/
  • coverage/
  • .next/, .nuxt/, .turbo/
  • vendor/, venv/, .venv/

Files

  • package-lock.json, yarn.lock, pnpm-lock.yaml
  • *.min.js, *.bundle.js
  • Binary files (images, fonts, etc.)

Combining Include and Ignore

Use both for precise control:

{
  "include": ["src/**"],
  "ignore": ["src/**/*.test.ts"]
}

This scans everything in src/ except test files.

Priority: Ignore patterns take precedence over include patterns.

Supported File Types

Oculum only scans security-relevant file types:

CategoryExtensions
JavaScript/TypeScript.js, .jsx, .ts, .tsx
Python.py
Go.go
Java.java
Ruby.rb
PHP.php
C#.cs
Config.json, .yaml, .yml, .toml
SpecialDockerfile, .env*, package.json

Files outside this list are automatically skipped.

Monorepo Patterns

Scan Specific Package

oculum scan packages/api/

Scan Multiple Packages

oculum scan packages/api/ packages/web/

Profile-Based Targeting

{
  "profiles": {
    "api": {
      "include": ["packages/api/src/**"]
    },
    "web": {
      "include": ["packages/web/src/**"]
    },
    "all": {
      "include": ["packages/*/src/**"]
    }
  }
}

oculum scan -p api
oculum scan -p web

Examples

Basic Project

{
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts"
  ]
}

Large Monorepo

{
  "include": [
    "packages/api/src/**",
    "packages/web/src/**"
  ],
  "ignore": [
    "**/__tests__/**",
    "**/fixtures/**"
  ]
}

Security-Focused Scan

Focus on high-risk areas:

{
  "include": [
    "**/api/**",
    "**/auth/**",
    "**/middleware/**",
    "**/*.env*"
  ]
}

Verbose Mode

See exactly what files are being scanned:

oculum scan --verbose

This shows:

  • Files included in the scan
  • Files skipped and why
  • Pattern matching details

Related