GitHub Action

Integrate Oculum security scanning into your CI/CD pipeline with our GitHub Action. Automatically scan pull requests and upload results to GitHub's Security tab.

Quick Setup

Add this workflow to .github/workflows/security-scan.yml:

name: Security Scan

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - uses: oculum/scan-action@v1
        with:
          api-key: ${{ secrets.OCULUM_API_KEY }}
          depth: validated
          fail-on: high

Configuration

Inputs

Outputs

Examples

Basic Scan

- uses: oculum/scan-action@v1
  with:
    api-key: ${{ secrets.OCULUM_API_KEY }}

Validated Scan with Strict Threshold

- uses: oculum/scan-action@v1
  with:
    api-key: ${{ secrets.OCULUM_API_KEY }}
    depth: validated
    fail-on: medium

Scan Specific Directory

- uses: oculum/scan-action@v1
  with:
    api-key: ${{ secrets.OCULUM_API_KEY }}
    path: ./src

Disable PR Comments

- uses: oculum/scan-action@v1
  with:
    api-key: ${{ secrets.OCULUM_API_KEY }}
    pr-comment: false

Setting Up Your API Key

1. Go to your Dashboard
2. Click Create Key
3. Name it "GitHub Actions"
4. Copy the key
5. In your GitHub repository, go to Settings → Secrets and variables → Actions
6. Click New repository secret
7. Name: OCULUM_API_KEY
8. Value: Paste your API key
9. Click Add secret

SARIF Upload

When sarif-upload is enabled (default), scan results appear in GitHub's Security tab:

1. Go to your repository
2. Click Security tab
3. Click Code scanning alerts
4. View Oculum findings alongside other security tools

Required Permissions

For SARIF upload to work, your workflow needs:

permissions:
  security-events: write

PR Comments

When pr-comment is enabled (default), the action posts a summary comment on pull requests:

## 🔍 Oculum Security Scan

Found **3 issues** in this PR:

| Severity | Count |
|----------|-------|
| 🔴 Critical | 0 |
| 🟠 High | 1 |
| 🟡 Medium | 2 |

### High Severity Issues

- **Unvalidated User Input** in `src/api/chat.ts:45`

[View full report →](link-to-sarif)

Required Permissions

For PR comments to work:

permissions:
  pull-requests: write

Monorepo Setup

For monorepos, run multiple scans:

jobs:
  scan:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: [api, web, shared]

    steps:
      - uses: actions/checkout@v4

      - uses: oculum/scan-action@v1
        with:
          api-key: ${{ secrets.OCULUM_API_KEY }}
          path: ./packages/${{ matrix.package }}

Version Pinning

Pin to a specific version for reproducible builds:

# Pin to major version (recommended - receives compatible updates)
- uses: oculum/scan-action@v1

# Pin to exact version (most stable)
- uses: oculum/scan-action@v1.2.3

# Use latest (not recommended for production)
- uses: oculum/scan-action@main

Performance Tips

Add Node.js Caching

Speed up scans by caching Node.js:

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: 20
      cache: 'npm'

  - uses: oculum/scan-action@v1
    with:
      api-key: ${{ secrets.OCULUM_API_KEY }}

Use Incremental Scans on PRs

Only scan changed files for faster PR feedback:

- uses: oculum/scan-action@v1
  with:
    api-key: ${{ secrets.OCULUM_API_KEY }}
    incremental: 'true'
    diff-base: ${{ github.base_ref }}

Branch Filtering

Run different depths based on branch:

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oculum/scan-action@v1
        with:
          api-key: ${{ secrets.OCULUM_API_KEY }}
          # Use cheap for PRs, validated for main
          depth: ${{ github.event_name == 'push' && 'validated' || 'cheap' }}

Credits & Cost

Each workflow run consumes 1 credit from your quota.

Optimizing Usage

1. Use cheap depth for PRs — Fast feedback, save validated for main
2. Use incremental scans — Only scan changed files
3. Limit scan paths — Scan specific directories instead of entire repo
4. Skip draft PRs — Don't scan work-in-progress

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  scan:
    # Skip draft PRs
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oculum/scan-action@v1
        with:
          api-key: ${{ secrets.OCULUM_API_KEY }}
          depth: cheap  # Save credits on PRs

→ See Credits & Usage for quota details.

Troubleshooting

"API key invalid" Error

• Verify the secret name matches exactly: OCULUM_API_KEY
• Check the key hasn't been revoked in your dashboard
• Ensure the key has sufficient quota

SARIF Upload Fails

• Verify security-events: write permission is set
• Check that GitHub Advanced Security is enabled (for private repos)

Action Times Out

• Large repositories may take longer to scan
• Consider using path to scan specific directories
• Use depth: cheap for faster scans

Rate Limiting

If you hit rate limits:

• Check your quota at /dashboard/usage
• Consider upgrading your plan
• Use incremental scans to reduce calls

Related

• Quickstart — Get started with Oculum
• CLI Reference — Local scanning with CLI
• Scan Depths — Understand cheap vs validated
• Credits & Usage — Quotas and plans