Ignore Patterns

Exclude files and directories from scanning entirely. Use ignore patterns for test fixtures, generated code, and other files that shouldn't be scanned.

Quick Start

Create a .oculumignore file in your project root:

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

# Ignore generated code
generated/
dist/
.next/

.oculumignore File

The .oculumignore file uses gitignore-style syntax.

Basic Example

# 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/
out/

# Ignore vendor code
vendor/
node_modules/

Pattern Syntax

Pattern	Matches
`*.test.ts`	Files ending in `.test.ts` in current directory only
`*/.test.ts`	Files ending in `.test.ts` anywhere in the project
`tests/`	Directory named `tests` and all its contents
`src/legacy/*`	Files directly in `src/legacy/` (not subdirectories)
`src/legacy/**`	All files under `src/legacy/` recursively
`*.{js,ts}`	Files ending in `.js` or `.ts`
`!important.ts`	Negation - don't ignore this file

Configuration File

You can also specify ignore patterns in your configuration file:

YAML Format

# .oculum.yaml
version: 1

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

JSON Format

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

CLI Ignore Flag

Temporarily ignore patterns via CLI:

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

# Multiple patterns
oculum scan -i "**/*.test.ts" -i "fixtures/**"

# Combine with config patterns
oculum scan -i "additional-pattern/**"

CLI patterns are added to config file patterns.

Default Ignored Patterns

These 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/
__pycache__/

Files

package-lock.json
yarn.lock
pnpm-lock.yaml
*.min.js
*.bundle.js
*.map

Binary Files

Images, fonts, and other binary files are automatically skipped.

Include Patterns

Use include to scan only specific paths:

# .oculum.yaml
include:
  - "src/**"
  - "lib/**"

When include is set, only matching files are scanned.

Combining Include and Ignore

# Scan src/ except test files
include:
  - "src/**"

ignore:
  - "src/**/*.test.ts"

Priority Order

When patterns conflict:

Default ignores (always applied)
Config file patterns (from .oculum.yaml)
.oculumignore file
CLI -i flags (highest priority for ignores)

Ignore patterns take precedence over include patterns.

Ignore vs Suppression

Use Case	Solution
Don't scan test files at all	Ignore pattern
Scan but suppress specific finding	Suppression
Exclude generated code	Ignore pattern
False positive on specific line	Suppression
Skip vendor/third-party code	Ignore pattern
Accepted risk with audit trail	Suppression

Common Patterns

JavaScript/TypeScript Projects

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

# Build output
dist/
build/
.next/
out/

# Generated
*.generated.ts
generated/

# Config (already validated)
*.config.js
*.config.ts

Python Projects

# Tests
test_*.py
*_test.py
tests/
conftest.py

# Virtual environments
venv/
.venv/
env/

# Build
dist/
build/
*.egg-info/

# Cache
__pycache__/
.pytest_cache/

Monorepo

# Shared test utilities
packages/test-utils/**

# Example apps
examples/
apps/demo/

# Build outputs
**/dist/
**/build/

# Package-specific tests
packages/*/tests/
packages/*/__tests__/

Debugging Ignore Patterns

See which files are being scanned:

oculum scan --verbose

This shows:

Files included in scan
Files ignored and why
Patterns that matched

Best Practices

1. Ignore Test Fixtures

Test files with intentional vulnerabilities should be ignored:

fixtures/
**/*.fixture.ts
test-data/

2. Don't Over-Ignore

Avoid patterns too broad:

# Too broad - might miss real issues
*.ts

# Better - specific to intent
**/*.test.ts

3. Document Non-Obvious Patterns

# Ignore legacy auth module (replaced by Clerk, tracked in SECURITY-123)
src/legacy-auth/

4. Review Periodically

Ignored files might become relevant again. Review .oculumignore periodically.

Suppressing Findings — Suppress specific findings
Targeting Files — Include/exclude patterns
Config Files — Full configuration reference