Output Formats

Oculum supports multiple output formats for different use cases. Choose the right format for your workflow.

Available Formats

---

Terminal (Default)

Human-readable colored output for interactive use.

oculum scan
# or explicitly
oculum scan --format terminal

Example Output

┌────────────────────────────────────────────────────────────────┐
│  Oculum Security Scan                                          │
│  Repository: my-ai-app                                         │
│  Files scanned: 47                                             │
└────────────────────────────────────────────────────────────────┘

Found 3 issues:

  CRITICAL: Hardcoded API Key
   src/lib/openai.ts:12
   API key exposed in source code
   Use environment variables instead

  HIGH: Unvalidated User Input to LLM
   src/api/chat.ts:45
   User input passed directly to prompt without sanitization
   Sanitize or validate user input before use

  MEDIUM: Missing Rate Limiting
   src/api/chat.ts:1
   No rate limiting on AI endpoint
   Consider adding rate limiting

Summary:
  Critical: 1
  High: 1
  Medium: 1
  Low: 0
  Info: 0

Scan completed in 1.2s

Options

# Disable colors
oculum scan --no-color

# Compact output (severity + title + location only)
oculum scan --compact

# Verbose output with additional details
oculum scan --verbose

# Quiet mode (minimal output)
oculum scan --quiet

---

JSON

Machine-readable format for integrations and scripting.

oculum scan --format json

Example Output

{
  "scanId": "scan_abc123xyz",
  "repoName": "my-ai-app",
  "timestamp": "2026-01-20T10:30:00Z",
  "filesScanned": 47,
  "scanDuration": 1234,
  "depth": "verified",
  "findings": [
    {
      "id": "finding_xyz789",
      "hash": "a1b2c3d4e5f67890",
      "category": "hardcoded_secret",
      "severity": "critical",
      "confidence": "high",
      "message": "Hardcoded OpenAI API key detected",
      "file": "src/lib/openai.ts",
      "line": 12,
      "column": 15,
      "snippet": "const apiKey = \"sk-proj-abc123...\"",
      "remediation": "Use environment variables to store API keys",
      "validationNotes": "String matches OpenAI API key pattern and is assigned to a variable named 'apiKey'."
    }
  ],
  "summary": {
    "total": 3,
    "critical": 1,
    "high": 1,
    "medium": 1,
    "low": 0,
    "info": 0
  },
  "hasBlockingIssues": true
}

Save to File

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

Pipe to Other Tools

# Filter with jq
oculum scan --format json | jq '.findings[] | select(.severity == "critical")'

# Count findings
oculum scan --format json | jq '.summary.total'

---

SARIF

Static Analysis Results Interchange Format — compatible with GitHub Code Scanning and other tools.

oculum scan --format sarif

Example Output

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Oculum",
          "version": "1.0.0",
          "informationUri": "https://oculum.dev",
          "rules": [
            {
              "id": "hardcoded_secret",
              "name": "Hardcoded Secret",
              "shortDescription": {
                "text": "Detects hardcoded secrets in source code"
              },
              "defaultConfiguration": {
                "level": "error"
              }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "hardcoded_secret",
          "level": "error",
          "message": {
            "text": "Hardcoded OpenAI API key detected"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/lib/openai.ts"
                },
                "region": {
                  "startLine": 12,
                  "startColumn": 15
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

GitHub Integration

# .github/workflows/security.yml
- name: Run Oculum
  run: oculum scan --format sarif --output results.sarif --fail-on high

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Results appear in Security → Code scanning alerts.

---

Markdown

Report-style output for documentation and sharing.

oculum scan --format markdown

Example Output

# Oculum Security Scan Report

**Repository:** my-ai-app
**Scan Date:** 2026-01-20 10:30 UTC
**Files Scanned:** 47
**Scan Depth:** verified

## Summary

| Severity | Count |
|----------|-------|
| Critical | 1 |
| High | 1 |
| Medium | 1 |
| Low | 0 |
| Info | 0 |
| **Total** | **3** |

## Findings

### Critical: Hardcoded API Key

**File:** `src/lib/openai.ts:12`
**Category:** `hardcoded_secret`

API key exposed in source code

**Remediation:** Use environment variables to store API keys

---

### High: Unvalidated User Input to LLM

**File:** `src/api/chat.ts:45`
**Category:** `ai_prompt_injection`

User input passed directly to prompt without sanitization

**Remediation:** Validate and sanitize user input before including in prompts

Save as Report

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

---

Writing to Files

Use --output to write results to a file:

# JSON report
oculum scan --format json --output results.json

# SARIF for GitHub
oculum scan --format sarif --output results.sarif

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

When using --output, terminal also shows a summary (unless --quiet is used).

---

Combining Options

# JSON output, save to file, fail on high
oculum scan --format json --output results.json --fail-on high

# SARIF for CI with quiet mode
oculum scan --format sarif --output results.sarif --quiet --fail-on high

# Verbose terminal + JSON file
oculum scan --verbose --output results.json --format json

---

Format Comparison

---

Related

• Exit Codes — CI/CD exit code reference
• CI/CD Setup — Pipeline integration
• GitHub Action — Automated scanning