cognium-ai

AI-powered static analysis CLI with LLM-enhanced vulnerability detection.

Installation

npm install -g cognium-ai

Commands

cognium-ai scan <path>          # Scan for security vulnerabilities (LLM-enhanced)
cognium-ai trust <path>         # Trust score across 36 passes (supply chain, security, AI safety, compliance)
cognium-ai quality <path>       # Quality score (complexity, tests, docs, maintainability, performance)
cognium-ai spec-diff <path>     # Spec-gap analysis (code vs Specifica spec alignment)
cognium-ai generate-spec <path> # Generate Specifica spec from code

cognium-ai init                 # Create cognium.config.json (auto-detects languages)
cognium-ai doctor               # Check environment, LLM config, project setup
cognium-ai version              # Show component versions

Run cognium-ai <command> --help for command-specific options. Several additional commands (dead-code, secrets, health, metrics, understand, cluster, compare, analyze-skill, benchmark) are available but currently undergoing CLI polish — they remain callable but are hidden from the headline --help until they soak.

Scan Options

cognium-ai scan src/                              # LLM-enhanced scan (default)
cognium-ai scan src/ --no-llm                     # Static-only (no LLM)
cognium-ai scan src/ -f json -o results.json      # JSON output to file
cognium-ai scan src/ -f sarif -o results.sarif    # SARIF 2.1.0 (GitHub code-scanning)
cognium-ai scan src/ --severity high              # High+ severity only
cognium-ai scan src/ --exclude-tests              # Skip test files
cognium-ai scan src/ --threads 20                 # Custom parallelism
cognium-ai scan src/ -x '**/vendor/**'            # Exclude paths
cognium-ai scan src/ --llm-timeout 180            # Raise per-call LLM timeout (slow local models)
cognium-ai scan src/ --exit-code                  # Exit 1 on findings (CI)

cognium-ai trust src/ -f sarif -o trust.sarif produces SARIF 2.1.0 across all 36 trust passes (richer than scan -f sarif, which is scoped to OWASP Top 10 findings only).

LLM Configuration

Configure via CLI flags or environment variables (flags take precedence):

# CLI flags (override env vars)
cognium-ai scan src/ \
  --llm-base-url https://api.openai.com/v1 \
  --llm-api-key sk-... \
  --llm-model gpt-4o

# Environment variables (used as defaults)
export LLM_API_KEY=your-api-key
export LLM_BASE_URL=http://localhost:4000/v1
export LLM_ENRICHMENT_MODEL=cognium/gpt-oss-120b

| Flag | Description | Default | |------|-------------|---------| | --llm-base-url <url> | LLM API base URL (OpenAI-compatible) | http://localhost:4000/v1 | | --llm-api-key <key> | LLM API key | LLM_API_KEY env var | | --llm-model <model> | LLM model name (universal — applies to all phases) | cognium/gpt-oss-120b | | --llm-timeout <seconds> | Per-call LLM timeout. Raise for slow local models (e.g. --llm-timeout 180); lower for fail-fast iteration. | 60 | | --no-llm | Disable LLM, use static analysis only | LLM enabled by default |

Provider Examples

| Provider | --llm-base-url | --llm-model | |----------|-------------------|---------------| | Cognium (free) | http://localhost:4000/v1 | cognium/gpt-oss-120b | | OpenAI | https://api.openai.com/v1 | gpt-4o | | GitHub Models (free) | https://models.github.ai/inference | openai/gpt-5 | | Azure OpenAI | https://YOUR.openai.azure.com/... | gpt-4o | | Ollama (local) | http://localhost:11434/v1 | llama3 | | Together AI | https://api.together.xyz/v1 | meta-llama/Llama-3-70b |

Performance: local Ollama vs cloud LLM

LLM-enriched scans dispatch ~3 LLM calls per source file (role classification, source discovery, sink discovery). Throughput is dominated by the LLM endpoint's per-call latency, not the SAST analysis. Practical guidance:

| Setup | Per-call latency | Practical throughput | Recommended for | |---|---|---|---| | Cognium proxy (http://localhost:4000/v1) | ~1–3s | ~10–30 files/min | Daily scans, CI | | Cloud (OpenAI gpt-4o-mini, GitHub Models) | ~1–4s | ~10–30 files/min | Daily scans, CI | | Ollama 7B+ (llama3:8b, qwen2.5-coder:7b) | ~5–15s | ~3–10 files/min | Small repos, local development | | Ollama 1.5B–3B (llama3.2:3b, qwen2.5-coder:1.5b) | ~3–10s | ~5–15 files/min | Development only — JSON quality is unreliable (#25, #37) | | Ollama reasoning (deepseek-r1, o1) | 30–120s+ | <1 file/min | Not recommended (#25 — <think> blocks break JSON parser) | | Static-only (--no-llm) | n/a | 100s files/sec | CI gates, large repos, air-gapped |

For a medium JS repo (~1000 source files), expect:

• Cognium / cloud: 30 sec – 5 min
• Ollama 7B: 2–6 hours
• Ollama 3B: probably similar but with degraded finding quality
• Static-only: <1 min

Tuning knobs

If you must run LLM-enriched scans against a slow endpoint:

# Raise per-call timeout for slow models (default 60s)
cognium-ai scan ./src --llm-timeout 180

# Concurrency control (env vars, default LLM_MAX_CONCURRENT=5, LLM_RATE_LIMIT=10)
LLM_MAX_CONCURRENT=2 LLM_RATE_LIMIT=4 cognium-ai scan ./src

# Bound the file count
cognium-ai scan ./src --max-files 100

# Or skip LLM entirely on large/CI runs
cognium-ai scan ./src --no-llm

When to choose which

• Daily / CI: cognium proxy or a small cloud model (gpt-4o-mini, openai/gpt-4o-mini via GitHub Models — generous free tier)
• Local development: static-only by default; use a 7B+ Ollama model for occasional LLM-augmented runs
• Air-gapped / sensitive repos: static-only; the SAST core covers OWASP Top 10 / Juliet at >97% accuracy without LLM
• Reasoning models (deepseek-r1, o1): route through the cognium proxy — direct calls hit the JSON parser issue documented in #25

CI/CD with GitHub Actions

Run LLM-enhanced SAST in CI using GitHub Models free tier -- no API keys to configure:

name: Security Scan
on: [pull_request]

permissions:
  contents: read
  models: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - run: npm install -g cognium-ai

      - name: LLM-enhanced SAST scan
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cognium-ai scan ./src \
            --llm-base-url https://models.github.ai/inference \
            --llm-api-key "$GITHUB_TOKEN" \
            --llm-model openai/gpt-5 \
            -f json -o scan.json

      - name: Trust score with SARIF for code-scanning upload
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cognium-ai trust ./src \
            --llm-base-url https://models.github.ai/inference \
            --llm-api-key "$GITHUB_TOKEN" \
            --llm-model openai/gpt-5 \
            -f sarif -o trust.sarif

Free tier limits: openai/gpt-5 = 50 req/day, openai/gpt-4o-mini = 150 req/day. Uses the built-in GITHUB_TOKEN with models: read permission.

Supported Languages

| Language | Extensions | Frameworks | |----------|------------|------------| | Java | .java | Spring, JAX-RS, Servlet API | | JavaScript | .js, .mjs | Express, Fastify, Node.js | | TypeScript | .ts, .tsx | Express, Fastify, Node.js | | Python | .py | Flask, Django, FastAPI | | Rust | .rs | Actix-web, Rocket, Axum | | Go | .go | net/http, Gin, Echo, Fiber, Chi, Gorilla | | Bash | .sh, .bash | Shell scripts |

Benchmark Results

| Benchmark | Score | |-----------|-------| | OWASP Benchmark (Java) | 100% (1415/1415) | | Juliet Test Suite (14 CWEs) | 100% (243/243) | | SecuriBench Micro | 97.7% TPR, 6.7% FPR | | CWE-Bench-Java (120 CVEs) | 50.8% static (61/120), 86.7% +LLM Discovery (104/120, Claude Opus) — IRIS-paper strict methodology | | OWASP NodeGoat / Juice Shop / DVJA | 100% | | NodeJS Synthetic (25 tests) | 92.9% Score (96.2% TPR, 11.1% FPR) | | CWE-Bench-Rust (30 tests) | 94.4% TPR, 0% FPR | | Bash Synthetic (31 tests) | 100% TPR, 0% FPR | | Go Synthetic (29 tests) | 84.2% TPR, 30% FPR | | Vulnerability-goapp (13 tests) | cmdi/xss/pathtraver 100%; sqli pending circle-ir#2 |

CWE-Bench-Java reference: CodeQL 22.5%, IRIS+GPT-4 45.8% — cognium-ai with Claude Opus is 2.85× CodeQL.

License

MIT