npm package: @oculum/cli
Description: AI-native security scanner CLI for detecting vulnerabilities in AI-generated code, BYOK patterns, and modern web applications
Author: Felix Westin
Latest version: 1.0.21

# Oculum CLI

AI-native security scanner for detecting vulnerabilities in AI-generated code, BYOK patterns, and modern web applications.

[![npm version](https://img.shields.io/npm/v/@oculum/cli.svg)](https://www.npmjs.com/package/@oculum/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🤖 **AI-Native Security**: Specialized detection for AI-era risks (BYOK patterns, agent tools, AI-generated code)
- ⚡ **Multiple Scan Depths**: Choose between local (fast), verified (AI-verified), or deep (comprehensive) scans
- 🎯 **Low False Positives**: AI validation reduces noise by ~70%
- 📊 **Multiple Output Formats**: Terminal, JSON, SARIF, or Markdown
- 🔄 **Incremental Scanning**: Scan only changed files for faster CI/CD
- 🎨 **Interactive TUI**: Beautiful terminal UI for exploring findings
- 🔐 **Secure Authentication**: Device flow authentication with GitHub

## Installation

```bash
npm install -g @oculum/cli
```

Or use with npx (no installation required):

```bash
npx @oculum/cli scan .
```

## Quick Start

### 1. Authenticate

```bash
oculum login
```

This will open a browser window for GitHub authentication. Follow the prompts to complete the login.

### 2. Run Your First Scan

```bash
# Local scan (fast, local-only)
oculum scan .

# Verified scan (AI-verified, recommended)
oculum scan . --mode verified

# Deep scan (comprehensive analysis)
oculum scan . --mode deep
```

### 3. Explore Results Interactively

```bash
oculum ui
```

## Commands

### `oculum scan [path]`

Scan a directory or file for security vulnerabilities.

**Options:**

- `-d, --depth <mode>` - Scan depth: `local`, `verified`, or `deep` (default: `local`)
- `-f, --format <format>` - Output format: `terminal`, `json`, `sarif`, or `markdown` (default: `terminal`)
- `-o, --output <file>` - Write output to file instead of stdout
- `--incremental` - Only scan files changed since last commit (git required)
- `--config <path>` - Path to config file (default: `oculum.config.json`)

**Examples:**

```bash
# Scan current directory with verified mode
oculum scan . --mode verified

# Scan specific file with JSON output
oculum scan src/api/auth.ts --format json

# Incremental scan for CI/CD
oculum scan . --incremental --mode verified

# Save results to file
oculum scan . --output results.sarif --format sarif
```

### `oculum ui`

Launch interactive terminal UI for scanning and exploring results.

**Features:**
- Visual file tree navigation
- Real-time scan progress
- Interactive findings explorer
- Severity filtering
- Code snippet preview

### `oculum login`

Authenticate with Oculum API using GitHub device flow.

**Process:**
1. CLI displays a URL and code
2. Open URL in browser
3. Enter code and authorize with GitHub
4. CLI automatically completes authentication

### `oculum status`

Check authentication status and current tier.

**Output:**
- Logged in status
- Email address
- Current tier (free/pro)
- API key status

### `oculum logout`

Remove stored credentials and log out.

## Scan Depth Modes

### Local (Free)

- **Speed**: Very fast (~5-10s for 100 files)
- **Cost**: Free, runs locally
- **Detection**: Pattern-based detection (Layer 1 + Layer 2)
- **Use Case**: Quick checks, pre-commit hooks, local development

### Verified (Pro)

- **Speed**: Moderate (~30-60s for 100 files)
- **Cost**: Paid, requires API key
- **Detection**: Pattern + AI validation (reduces false positives by ~70%)
- **Use Case**: PR checks, CI/CD pipelines, production code

### Deep (Pro)

- **Speed**: Slower (~2-5min for 100 files)
- **Cost**: Higher cost, requires API key
- **Detection**: Full semantic analysis with project context
- **Use Case**: Security audits, critical code paths, compliance

## Configuration File

Create `oculum.config.json` in your project root:

```json
{
  "depth": "verified",
  "format": "terminal",
  "ignore": [
    "**/node_modules/**",
    "**/dist/**",
    "**/*.test.ts"
  ],
  "include": [
    "src/**/*.ts",
    "src/**/*.js"
  ]
}
```

**Options:**

- `depth` - Default scan depth (`local`, `verified`, `deep`)
- `format` - Default output format (`terminal`, `json`, `sarif`, `markdown`)
- `ignore` - Glob patterns to exclude from scanning
- `include` - Glob patterns to include in scanning (overrides ignore)

## Output Formats

### Terminal (Default)

Human-readable output with colors and formatting:

```
════════════════════════════════════════════════════════════
  OCULUM SECURITY SCAN RESULTS
════════════════════════════════════════════════════════════

🔴 2 critical issues found

🔑 Secrets & Credentials (1 critical)
────────────────────────────────────────────────────────────
  🔴 CRITICAL Hardcoded API key detected
     src/config.ts:12
     API key appears to be hardcoded in source code.
     💡 Move to environment variables: process.env.API_KEY
```

### JSON

Machine-readable JSON for programmatic processing:

```json
{
  "summary": {
    "totalIssues": 2,
    "critical": 2,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "findings": [...]
}
```

### SARIF

GitHub Security tab compatible format:

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

Upload to GitHub:
```yaml
- uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif
```

### Markdown

Documentation-friendly format:

```bash
oculum scan . --format markdown --output SECURITY.md
```

## What Oculum Detects

### AI-Era Risks

- **BYOK Patterns**: Bring-your-own-key usage, storage, and logging
- **Agent Tools**: Over-permissive tool definitions, unsafe tool execution
- **AI-Generated Code**: Common patterns from AI coding assistants
- **Prompt Injection**: User input in AI prompts without sanitization

### Traditional Security

- **Secrets**: Hardcoded API keys, tokens, credentials
- **Injection**: SQL injection, command injection, XSS
- **Authentication**: Missing auth checks, weak session handling
- **Data Exposure**: Sensitive data in logs, error messages, responses
- **Dangerous Functions**: `eval`, `exec`, unsafe deserialization

### Configuration Issues

- **Docker**: Running as root, hardcoded secrets in Dockerfiles
- **CORS**: Permissive origins, credential exposure
- **Environment**: Committed `.env` files, hardcoded configs

## CI/CD Integration

### GitHub Actions

```yaml
name: Security Scan
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Oculum
        run: npm install -g @oculum/cli
      
      - name: Authenticate
        run: echo "${{ secrets.OCULUM_API_KEY }}" | oculum login --stdin
      
      - name: Scan
        run: oculum scan . --mode verified --format sarif --output results.sarif
      
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif
```

### GitLab CI

```yaml
security_scan:
  stage: test
  script:
    - npm install -g @oculum/cli
    - echo "$OCULUM_API_KEY" | oculum login --stdin
    - oculum scan . --mode verified --format json --output results.json
  artifacts:
    reports:
      codequality: results.json
```

## Troubleshooting

### Authentication Issues

**Problem**: `Login failed: APIError`

**Solution**:
1. Check your internet connection
2. Verify API endpoint is accessible: `curl https://oculum-api.vercel.app/api/v1/auth/device`
3. Try logging out and back in: `oculum logout && oculum login`

### Scan Failures

**Problem**: `Scan failed: quota exceeded`

**Solution**:
- Check your usage: `oculum status`
- Upgrade to Pro tier for higher limits
- Use `--mode local` for unlimited local scans

**Problem**: Too many files being scanned

**Solution**:
- Add ignore patterns to `oculum.config.json`
- Use `.gitignore` patterns (automatically respected)
- Scan specific directories: `oculum scan src/`

### Performance Issues

**Problem**: Scans are slow

**Solution**:
- Use `--mode local` for faster local scans
- Enable incremental scanning: `--incremental`
- Reduce scope with ignore patterns
- Scan only changed files in CI/CD

## API Key Management

### Getting an API Key

1. Sign up at https://oculum-api.vercel.app
2. Navigate to Dashboard → API Keys
3. Click "Create New Key"
4. Copy the key (shown only once)
5. Use with CLI: `oculum login --api-key YOUR_KEY`

### Storing API Keys Securely

**Local Development:**
```bash
# Store in config (recommended)
oculum login

# Or use environment variable
export OCULUM_API_KEY="your-key-here"
```

**CI/CD:**
- Store as encrypted secret in your CI/CD platform
- Never commit API keys to version control
- Rotate keys regularly

## Pricing

### Free Tier
- ✅ Unlimited local scans
- ✅ Basic CLI access
- ✅ All output formats
- ❌ No verified/deep scans

### Pro Tier
- ✅ Everything in Free
- ✅ Verified scans (AI-verified)
- ✅ Deep scans (semantic analysis)
- ✅ API access
- ✅ Priority support

[View detailed pricing →](https://oculum-api.vercel.app/pricing)

## Examples

### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit

oculum scan . --mode local --format terminal
if [ $? -ne 0 ]; then
  echo "Security issues found. Commit blocked."
  exit 1
fi
```

### Watch Mode (Development)

```bash
# Scan on file changes
oculum watch src/ --mode local
```

### Scan Specific File Types

```bash
# Only TypeScript files
oculum scan . --include "**/*.ts" --include "**/*.tsx"

# Exclude tests
oculum scan . --ignore "**/*.test.ts" --ignore "**/*.spec.ts"
```

## Support

- 📧 Email: felix.lwestin@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/flexipie/oculum/issues)
- 📚 Docs: [Documentation](https://oculum-api.vercel.app/docs)

## License

MIT © Felix Westin

---

**Made with ❤️ for developers building with AI**