Suppressing Findings

Suppress false positives and acknowledged risks without removing them from your codebase. Oculum supports both inline comments and configuration-based suppressions.

Inline Suppressions

Add comments directly in your code to suppress specific findings.

Next-Line Suppression

Suppress the finding on the next line:

// oculum-ignore-next-line: This is a test API key
const apiKey = "sk-test-12345";

Same-Line Suppression

Suppress a finding on the same line:

const apiKey = "sk-test-12345"; // oculum-ignore: Test key for development

Category-Specific Suppression

Target a specific detector:

// oculum-ignore[hardcoded_secret]: Static config, not a real secret
const staticToken = "example-token-123";

Block Suppression

Suppress multiple lines:

/* oculum-ignore-block: Test fixtures */
const testKey1 = "sk-test-111";
const testKey2 = "sk-test-222";
const testKey3 = "sk-test-333";
/* oculum-ignore-block-end */

---

Comment Syntax Support

Oculum recognizes these comment styles:

---

CLI Suppression

Use oculum ignore to suppress findings by hash:

Add a Suppression

# Get finding hash from scan output
oculum scan

# Suppress by hash with reason
oculum ignore abc123def4567890 --reason "False positive - static config"

# With expiration date
oculum ignore abc123def4567890 --reason "Approved by security team" --expires 2026-06-01

List Suppressions

oculum ignore --list

Output:

Suppressed Findings:

  abc123def4567890
    File: src/config.ts
    Reason: False positive - static config
    Suppressed by: developer@example.com
    Suppressed at: 2026-01-20
    Expires: Never

  def456ghi7890123
    File: src/api/auth.ts
    Reason: Approved by security team
    Suppressed by: security@example.com
    Suppressed at: 2026-01-15
    Expires: 2026-06-01

Remove a Suppression

oculum ignore --remove abc123def4567890

---

Configuration-Based Suppression

Suppress findings in your configuration file (.oculum.yaml or oculum.config.json).

Rule-Based Suppressions

Suppress all findings of a specific category:

# .oculum.yaml
version: 1

suppressions:
  rules:
    - category: hardcoded_secret
      reason: "All secrets in test files are fixtures"
      paths:
        - "**/*.test.ts"
        - "**/*.spec.ts"
        - "__tests__/**"

Finding-Based Suppressions

Suppress specific findings by hash:

# .oculum.yaml
version: 1

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

JSON Format

{
  "suppressions": {
    "rules": [
      {
        "category": "hardcoded_secret",
        "reason": "Test fixtures",
        "paths": ["**/*.test.ts"]
      }
    ],
    "findings": [
      {
        "hash": "a1b2c3d4e5f67890",
        "reason": "Approved exception"
      }
    ]
  }
}

---

Finding Hashes

Each finding has a unique 16-character hash based on:

• Normalized file path
• Normalized line content
• Detector category

Hash Stability

• Survives whitespace changes
• Survives minor formatting
• Changes when code actually changes
• Changes when file is moved

Get a Finding Hash

# Show hashes in scan output
oculum scan --verbose

Or from JSON output:

oculum scan --format json | jq '.findings[].hash'

---

Suppression Priority

When multiple suppressions apply, this order determines precedence:

1. Inline comments (highest priority)
2. Config finding suppressions (by hash)
3. Config rule suppressions (by category)

---

Expiration Dates

Suppressions can expire automatically:

suppressions:
  findings:
    - hash: "a1b2c3d4e5f67890"
      reason: "Temporary exception during migration"
      expires: "2026-03-01"

After the expiration date, the finding will reappear in scan results.

CLI Expiration

oculum ignore abc123 --reason "Sprint exception" --expires 2026-02-01

---

Audit Trail

All suppressions are tracked with:

• Who suppressed the finding
• When it was suppressed
• The reason provided
• Expiration date (if set)

View the audit trail:

oculum ignore --list --verbose

---

Best Practices

Always Provide Reasons

Good:

// oculum-ignore: LDAP connection string, not a password
const ldapUrl = "ldap://admin@directory.corp.local";

Bad:

// oculum-ignore
const ldapUrl = "ldap://admin@directory.corp.local";

Use Specific Categories When Possible

Good:

// oculum-ignore[high_entropy_string]: UUIDv4 constant
const requestId = "550e8400-e29b-41d4-a716-446655440000";

Better than:

// oculum-ignore: Not a secret
const requestId = "550e8400-e29b-41d4-a716-446655440000";

Set Expiration Dates for Temporary Exceptions

oculum ignore abc123 \
  --reason "Temporary during auth migration" \
  --expires 2026-03-01

Review Suppressions Regularly

# List all suppressions
oculum ignore --list

# Check for expired suppressions
oculum ignore --list --show-expired

---

Show Suppressed Findings

To include suppressed findings in scan output:

oculum scan --show-suppressed

This helps audit what's being suppressed.

---

Related

• Baselines — Track findings over time
• Ignore Patterns — Exclude files from scanning
• Understanding Results — Interpret findings