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
• LLM Verification: Verify exploitability of detected vulnerabilities
• Pattern Discovery: Discover sources/sinks beyond YAML patterns
• Cross-File Analysis: Track taint across file boundaries
• AI Skills Analysis: Security analysis for AI agent skills (OpenClaw, 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
• Benchmark Suite: OWASP, Juliet, SecuriBench, CWE-Bench test runners

Installation

npm install circle-ir-ai circle-ir

Quick Start

CLI

# Analyze a single file
circle-ir-ai src/App.java

# Analyze with LLM verification
circle-ir-ai src/App.java --llm

# Analyze a directory (auto-parallelized)
circle-ir-ai ./src --threads 20

# Security scan with OWASP Top 10 mapping
circle-ir-ai scan ./src

# Detect dead/unreachable code
circle-ir-ai dead-code ./src

# Scan for secrets
circle-ir-ai secrets ./src

# Calculate codebase health score
circle-ir-ai health ./src

# Run OWASP Benchmark
circle-ir-ai benchmark ./testcode --expected ./expected.csv

# Analyze AI Skills (OpenClaw, MCP servers)
circle-ir-ai analyze-skill ./my-skill
circle-ir-ai analyze-skill ./my-skill --format json -o report.json

AI Skills Analysis

Analyze AI agent skills for security issues and capability mismatches. Supports OpenClaw skills and MCP servers.

CLI Usage:

# Analyze a skill directory
circle-ir-ai analyze-skill ./my-skill

# With JSON output
circle-ir-ai analyze-skill ./my-skill --format json -o report.json

# With markdown report
circle-ir-ai analyze-skill ./my-skill --format markdown -o SECURITY.md

# Filter by severity and confidence
circle-ir-ai analyze-skill ./my-skill --min-severity high --min-confidence 0.8

What it analyzes:

• SKILL.md - Natural language instructions (extracts declared capabilities)
• Code files (.ts, .js, .py, .java, .rs) - Actual implementation
• mcp-server.json - MCP server configuration (if present)
• Cross-artifact analysis - Detects capability mismatches between documentation and code

Output:

================================================================================
SKILL ANALYSIS REPORT: github-reader
================================================================================

Skill ID:       github-reader-001
Version:        1.0.0
Trust Score:    22.0% 🚨
Findings:       13
Analysis Time:  21.84s

CRITICAL FINDINGS (1)
────────────────────────────────────────────────────────────────────────────────

1. Server-Side Request Forgery (CWE-918) not declared
   Type:       capability_mismatch
   Artifact:   src/index.ts
   Confidence: 90%
   Description: The code performs outbound HTTP requests via `https.request()`
                but SKILL.md does not list any such sink.

RECOMMENDATIONS
────────────────────────────────────────────────────────────────────────────────

1. Update SKILL.md to accurately describe all capabilities
2. Add input validation and sanitization

Trust Score Interpretation:

• 90-100% ✅ - High trust, minimal issues
• 70-89% ⚠️ - Medium trust, some concerns
• 50-69% ❌ - Low trust, significant issues
• <50% 🚨 - Critical issues, do not deploy

Programmatic API:

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

const result = await analyzeSkillBundle('./my-skill', {
  enableCrossArtifact: true,    // Detect capability mismatches
  enableVerification: true,      // LLM verification
  minConfidence: 0.7,
  minSeverity: 'medium',
  onProgress: (status) => console.log(status.message),
});

console.log(`Trust Score: ${result.score}`);
console.log(`Findings: ${result.findings.length}`);
console.log(`Recommendations: ${result.recommendations.join('\n')}`);

Key Features:

• Multi-Artifact Analysis: Analyzes SKILL.md + code + MCP config together
• Capability Mismatch Detection: LLM-based semantic comparison between declared and actual behavior
• Vulnerability Detection: Standard taint analysis on code files
• Trust Score: 0.0-1.0 score based on severity-weighted findings
• Actionable Recommendations: Specific guidance for remediation

Production Quality:

• ✅ 74% false positive reduction through test file exclusion, validation utility recognition, and timeout fixes
• ✅ Real-world validated on official MCP servers (fetch: 84% trust, filesystem: accurate findings)
• ✅ Fast analysis (~25s for typical skills)
• ⚠️ Large SKILL.md files (>10KB) may take longer to extract

Known Limitations:

• Capability mismatch detection quality depends on LLM model used
• Trust score may be conservative for complex codebases with many filesystem operations

Programmatic API

import { analyze, initAnalyzer } from 'circle-ir';
import { runHybridAnalysis, applyLLMAnalysis } from 'circle-ir-ai';

// Initialize
await initAnalyzer();

// Run hybrid analysis with LLM
const result = await runHybridAnalysis(
  'MyClass.java',
  code,
  sources,
  sinks,
  types,
  imports,
  {
    enableEnrichment: true,
    enableVerification: true,
  }
);

console.log('Verified vulnerabilities:', result.vulnerabilities);

Project-Level Analysis

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

const files = [
  { path: 'src/Controller.java', content: controllerCode },
  { path: 'src/Service.java', content: serviceCode },
];

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

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

Security Scanning

import { scanDirectory, formatScanReport } from 'circle-ir-ai';

const result = await scanDirectory('/path/to/project');
console.log(formatScanReport(result));
// Shows vulnerabilities mapped to OWASP Top 10 categories

Dead Code Detection

import { detectDeadCode, formatDeadCodeReport } from 'circle-ir-ai';

const result = await detectDeadCode({
  target: '/path/to/project',
  languages: ['javascript', 'typescript'],
});

console.log(formatDeadCodeReport(result));
// Shows: dead methods, entry points, and LOC with reachability info

Secret Scanning

import { scanForSecrets, formatSecretReport } from 'circle-ir-ai';

const result = await scanForSecrets('/path/to/project', {
  scanHistory: true,      // Scan Git history
  maxCommits: 100,
  minSeverity: 'medium',
});

console.log(formatSecretReport(result));

Health Scoring

import { calculateHealthScore, formatHealthReport } from 'circle-ir-ai';

const result = await calculateHealthScore('/path/to/project', {
  includeSecurity: true,
  includeSecrets: true,
  includeDeadCode: true,
});

console.log(formatHealthReport(result));
// Scores: Security 35%, Maintainability 25%, Quality 25%, Performance 15%

LLM Configuration

Set environment variables or pass options:

export LLM_API_KEY=your-api-key
export LLM_BASE_URL=http://localhost:4000/v1

Or in code:

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

const config = createLLMConfig({
  baseUrl: 'http://localhost:4000/v1',
  apiKey: 'your-api-key',
});

CLI Options

circle-ir-ai <file|dir> [options]

Commands:
  <file|dir>           Analyze file or directory
  scan <dir>           Security scan with OWASP mapping
  dead-code <dir>      Detect unreachable code
  secrets <dir>        Scan for secrets
  health <dir>         Calculate health score
  benchmark <dir>      Run benchmark suite

Options:
  -f, --format <fmt>       Output format: json, summary, sarif
  -o, --output <file>      Write output to file
  --llm                    Enable LLM enrichment and verification
  --llm-enrich             Enable LLM enrichment only
  --llm-verify             Enable LLM verification only
  --llm-base-url <url>     LLM proxy URL
  --llm-api-key <key>      LLM API key
  --threads <n>            Parallel analysis threads (default: 10)
  -d, --discover-patterns  Enable dynamic pattern discovery
  -q, --quiet              Suppress progress messages
  -h, --help               Show help

Benchmark Results

| Benchmark | Score | Details | |-----------|-------|---------| | OWASP Benchmark (Java) | +100% | 1415/1415 perfect | | OWASP BenchmarkPython | 25.2% | 1230 test cases | | Juliet Test Suite | +100% | 156/156 perfect | | SecuriBench Micro | 97.7% TPR | 105/108 vulns, 6.7% FPR | | CWE-Bench-Java | 81.7% (with LLM) | 98/120 projects (vs CodeQL 22.5%, IRIS+GPT-4 45.8%) | | NodeJS Synthetic | 100% TPR | 25 test cases, 94.1% Precision | | OWASP NodeGoat | +100% | 14 tests, 5 vulns detected | | CWE-Bench-Rust | +100% | 30 test cases (6 CWEs) |

Supported Languages

| Language | Extensions | Frameworks | |----------|-----------|------------| | Java | .java | Spring, JAX-RS, Servlet API | | JavaScript | .js, .jsx, .mjs, .cjs | Express, Fastify, Node.js | | TypeScript | .ts, .tsx, .mts, .cts | Express, Fastify, Node.js | | Python | .py | Flask, Django, FastAPI | | Rust | .rs | Actix-web, Rocket, Axum |

Related Packages

• circle-ir: Core SAST library
• circle-pack: Cloudflare Workers API deployment

License

ISC