Oculum/Docs

Understanding Results

Learn how to interpret Oculum scan results and take action on security findings. This guide explains severity levels, finding categories, and recommended actions.

Severity Levels

Results are displayed with severity indicators:

LevelMeaningActionExample
CriticalImmediate action requiredFix nowExposed API keys, hardcoded credentials
HighSignificant security riskFix soonSQL injection, XSS vulnerabilities
MediumModerate riskReviewMissing input validation
LowMinor issuesConsiderSuboptimal patterns
InfoInformationalAwarenessLocalhost URLs in dev configs

Reading a Finding

Each finding includes:

  CRITICAL: Hardcoded API Key
   src/lib/openai.ts:12
   API key exposed in source code
   Use environment variables instead
  1. Severity + Title — What was found
  2. Location — File path and line number
  3. Description — Why it's a problem
  4. Remediation — How to fix it

Finding Categories

Oculum detects issues across several categories:

AI Security

  • Prompt Injection — Unvalidated input to LLM prompts
  • Unsafe Execution — AI-generated code executed without validation
  • Package Hallucination — Dependencies suggested by AI that don't exist

Secrets & Credentials

  • Hardcoded Secrets — API keys, tokens, passwords in code
  • High Entropy Strings — Potential secrets detected by randomness
  • Sensitive URLs — Webhook endpoints, internal services exposed

Traditional Security

  • SQL Injection — Unsanitized input in database queries
  • XSS — Cross-site scripting vulnerabilities
  • Command Injection — Shell commands with user input

Configuration

  • Debug Mode — Debug flags enabled in production configs
  • Weak Crypto — MD5, SHA1, DES usage
  • Insecure Settings — Permissive CORS, disabled security features

Actionable Results

Critical & High: Fix Immediately

These findings represent real security risks. Prioritize fixing them before deployment:

# View only blocking issues
oculum scan --fail-on high

Medium: Review and Decide

Medium findings often require context:

  • Is this code reachable by users?
  • Are there other mitigations in place?
  • Is this a test file or production code?

Low & Info: Consider Later

Low severity findings are suggestions for improvement but not urgent security issues.

Suppressing False Positives

If a finding is a false positive, you can suppress it:

Inline Comment

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

Configuration

# .oculum.yaml
suppressions:
  rules:
    - category: hardcoded_secret
      paths:
        - "**/*.test.ts"

See Suppressing Findings for details.

Output Formats

Terminal (Default)

Human-readable output with colors and formatting.

JSON

Machine-readable format for integrations:

oculum scan --format json --output results.json

SARIF

GitHub Code Scanning compatible:

oculum scan --format sarif --output results.sarif

Markdown

Report-style output for documentation:

oculum scan --format markdown --output report.md

Summary Statistics

At the end of each scan, you'll see a summary:

Summary:
  Critical: 1
  High: 2
  Medium: 3
  Low: 1
  Info: 0
  Total: 7

Scan completed in 1.2s

Troubleshooting

No Issues Found but Expected Some

  • Check file types: Oculum only scans supported extensions
  • Try verified scan: Pattern matching may miss context-dependent issues
  • Check ignore patterns: See if files are excluded
oculum scan --verbose

Too Many False Positives

  • Use verified depth: AI validation reduces false positives by ~70%
  • Add suppressions: Mark known false positives
  • Report issues: Help improve detection

Next Steps