circle-ir-ai

circle-ir-ai

LLM-enhanced static analysis built on circle-ir. Provides CLI tools, AI-powered vulnerability verification, and comprehensive security analysis.

Features

• Multi-Language Support: Java, JavaScript/TypeScript, Python, Rust, Go, Bash, HTML
• LLM Discovery: Discover vulnerabilities beyond static patterns via LLM
• Cross-File Analysis: Track taint across file boundaries
• AI Skills Analysis: Security analysis for AI agent skills (MCP servers)
• Security Scanning: OWASP Top 10 mapping with trend tracking
• Dead Code Detection: Find unreachable code via call graph analysis
• Secret Scanning: Detect secrets in code and Git history
• Health Scoring: Calculate overall codebase health

Installation

npm install circle-ir-ai circle-ir

CLI

For CLI usage, install cognium-ai:

npm install -g cognium-ai

cognium-ai scan ./src                    # Security scan (OWASP Top 10)
cognium-ai scan ./src --language java    # Filter by language
cognium-ai trust ./src                   # Trust score (27 passes)
cognium-ai quality ./src                 # Quality score (5 passes)
cognium-ai dead-code ./src               # Dead code detection
cognium-ai secrets ./src                 # Secret scanning
cognium-ai health ./src                  # Codebase health score

Options: --format json|summary|sarif, -o <file>, --llm, -q

LLM CLI Flags

cognium-ai scan ./src --llm                        # Enable LLM enrichment
cognium-ai scan ./src --llm --llm-model gpt-4o     # Override model
cognium-ai scan ./src --llm --llm-base-url <url>   # Override API base URL

Flag	Description	Default
--llm	Enable LLM enrichment	off
--llm-base-url <url>	LLM API base URL (OpenAI-compatible)	LLM_BASE_URL env var
--llm-api-key <key>	LLM API key	LLM_API_KEY env var
--llm-model <model>	LLM model name	LLM_ENRICHMENT_MODEL env var
--language <lang>	Filter by language (java, typescript, python, etc.)	all

CLI flags override environment variables. Any OpenAI-compatible API works (OpenAI, Azure, Ollama, Together, GitHub Models, etc.).

Programmatic API

import { initAnalyzer } from 'circle-ir';
import { analyzeFile } from 'circle-ir-ai';

await initAnalyzer();

const result = await analyzeFile('MyClass.java', code, {
  language: 'java',
  enableEnrichment: true,
  enableVerification: true,
});

console.log('Findings:', result.findings);

Multi-file analysis

import { analyzeProjectTwoPhase } from 'circle-ir-ai';

const result = await analyzeProjectTwoPhase(files, 'java', {
  enableEnrichment: true,
  parallelPhase1: true,
  maxConcurrency: 10,
});

console.log('Cross-file taint flows:', result.crossFileFlows);

Security scanning, dead code, secrets, health

import { scanDirectory, detectDeadCode, scanForSecrets, calculateHealthScore } from 'circle-ir-ai';

const scan = await scanDirectory('/path/to/project');
const deadCode = await detectDeadCode({ target: '/path/to/project' });
const secrets = await scanForSecrets('/path/to/project', { scanHistory: true });
const health = await calculateHealthScore('/path/to/project');

AI skill analysis

import { analyzeSkillBundle } from 'circle-ir-ai';

const result = await analyzeSkillBundle('./my-skill', {
  enableCrossArtifact: true,
  enableVerification: true,
});

console.log(`Trust Score: ${result.score}`);
console.log(`Findings: ${result.findings.length}`);

LLM Configuration

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

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

# Or use CLI flags directly
cognium-ai scan ./src --llm \
  --llm-base-url https://api.openai.com/v1 \
  --llm-api-key sk-... \
  --llm-model gpt-4o

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

CI/CD with GitHub Actions

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

name: SAST 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"

      - name: Install cognium-ai
        run: |
          npm install cognium-ai@latest
          ln -s node_modules/circle-ir/dist/wasm wasm

      - name: LLM-enhanced SAST scan
        env:
          LLM_BASE_URL: https://models.github.ai/inference
          LLM_API_KEY: ${{ github.token }}
          LLM_ENRICHMENT_MODEL: openai/gpt-4o-mini
        run: |
          npx cognium-ai scan ./src --llm --format json -o sast-results.json

GitHub Models free tier limits: openai/gpt-5 = 50 req/day, openai/gpt-4o-mini = 150 req/day. Auth uses the built-in GITHUB_TOKEN with models: read permission.

Benchmark Results

Benchmark	Score
OWASP Benchmark (Java, 1415 tests)	100%
Juliet Test Suite (243 tests)	100%
SecuriBench Micro	97.7% TPR, 6.7% FPR
CWE-Bench-Java (120 CVEs)	50.8% static (61/120), 86.7% +LLM Discovery (Claude Opus)
NodeJS Synthetic (25 tests)	93.8% TPR
CWE-Bench-Rust (50 tests)	86.5% TPR, 7.7% FPR
Go Synthetic (29 tests)	84.2% TPR, 30% FPR
Vulnerability-goapp (13 tests, real-app)	cmdi/xss/pathtraver 100%; sqli precision pending circle-ir#2

CWE-Bench-Java reference (IRIS-paper strict methodology — sink within fix method range): CodeQL 22.5%, IRIS+GPT-4 45.8%.

Top 100 Secure Repos (LLM Discovery on 21 production repos, 967K LOC)

Model	LLM Findings	Notes
claude-opus-latest	29	Zero JSON failures, most reliable
grok-code-latest	29	Best Rust detection
gpt-oss-120b (FREE)	~27	90% detection at zero cost

Top findings: Jenkins (9), HuggingFace (4), Tauri (6-7), TiKV (3), Deno (3), Cargo (2-5).

Supported Languages

Language	Frameworks
Java	Spring, JAX-RS, Servlet API
JavaScript/TypeScript	Express, Fastify, Node.js
Python	Flask, Django, FastAPI
Rust	Actix-web, Rocket, Axum
Go	net/http, Gin, Echo, Fiber, Chi, Gorilla
Bash	Shell script command-injection / code-injection detection
HTML	XSS detection in templates

Related Packages

• circle-ir: Core SAST library (open source, MIT)

License

PolyForm Noncommercial License 1.0.0 -- free for noncommercial use. Commercial use requires a separate license. See LICENSE for details.