circle-ir 3.1.0

package/examples/node-example.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env npx tsx
+/**
+ * Node.js Example - Circle-IR Core Library
+ *
+ * This example demonstrates how to use circle-ir-core to:
+ * 1. Parse Java code
+ * 2. Extract IR components (types, calls, CFG, DFG)
+ * 3. Detect taint sources and sinks
+ * 4. Find source-to-sink flows
+ *
+ * Run: npx tsx examples/node-example.ts
+ */
+
+import {
+  initParser,
+  parse,
+  collectAllNodes,
+  extractMeta,
+  extractTypes,
+  extractCalls,
+  buildCFG,
+  buildDFG,
+  analyzeTaint,
+  propagateTaint,
+  analyzeConstantPropagation,
+  isFalsePositive,
+  getDefaultConfig,
+} from '../src/core-lib.js';
+
+// Sample vulnerable Java code
+const vulnerableCode = `
+package com.example;
+
+import javax.servlet.http.*;
+import java.sql.*;
+
+public class UserController extends HttpServlet {
+
+    public void doGet(HttpServletRequest request, HttpServletResponse response) {
+        // SOURCE: User input from HTTP parameter
+        String userId = request.getParameter("id");
+
+        // No sanitization - direct use in SQL query
+        String query = "SELECT * FROM users WHERE id = '" + userId + "'";
+
+        try {
+            Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/db");
+            Statement stmt = conn.createStatement();
+
+            // SINK: SQL injection vulnerability
+            ResultSet rs = stmt.executeQuery(query);
+
+            while (rs.next()) {
+                response.getWriter().println(rs.getString("name"));
+            }
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+}
+`;
+
+// Sample safe Java code (uses PreparedStatement)
+const safeCode = `
+package com.example;
+
+import javax.servlet.http.*;
+import java.sql.*;
+
+public class SafeUserController extends HttpServlet {
+
+    public void doGet(HttpServletRequest request, HttpServletResponse response) {
+        String userId = request.getParameter("id");
+
+        try {
+            Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/db");
+
+            // SAFE: Using PreparedStatement with parameterized query
+            PreparedStatement stmt = conn.prepareStatement(
+                "SELECT * FROM users WHERE id = ?"
+            );
+            stmt.setString(1, userId);
+
+            ResultSet rs = stmt.executeQuery();
+
+            while (rs.next()) {
+                response.getWriter().println(rs.getString("name"));
+            }
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+    }
+}
+`;
+
+// Node types needed for analysis
+const NODE_TYPES = new Set([
+  'method_invocation',
+  'object_creation_expression',
+  'class_declaration',
+  'method_declaration',
+  'constructor_declaration',
+  'field_declaration',
+  'import_declaration',
+  'interface_declaration',
+  'enum_declaration',
+]);
+
+async function analyzeCode(code: string, filename: string): Promise<void> {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`Analyzing: ${filename}`);
+  console.log('='.repeat(60));
+
+  // Parse the code
+  const tree = await parse(code, 'java');
+  const nodeCache = collectAllNodes(tree.rootNode, NODE_TYPES);
+
+  // Extract IR components
+  const meta = extractMeta(code, tree, filename, 'java');
+  const types = extractTypes(tree, nodeCache);
+  const calls = extractCalls(tree, nodeCache);
+  const cfg = buildCFG(tree);
+  const dfg = buildDFG(tree, nodeCache);
+
+  console.log(`\nIR Summary:`);
+  console.log(`  Lines of code: ${meta.loc}`);
+  console.log(`  Classes: ${types.length}`);
+  console.log(`  Method calls: ${calls.length}`);
+  console.log(`  CFG blocks: ${cfg.blocks.length}`);
+  console.log(`  DFG definitions: ${dfg.defs.length}`);
+
+  // Analyze taint
+  const config = getDefaultConfig();
+  const taint = analyzeTaint(calls, types, config);
+
+  console.log(`\nTaint Analysis:`);
+  console.log(`  Sources: ${taint.sources.length}`);
+  taint.sources.forEach(s => {
+    console.log(`    - Line ${s.line}: ${s.type} (${s.location})`);
+  });
+
+  console.log(`  Sinks: ${taint.sinks.length}`);
+  taint.sinks.forEach(s => {
+    console.log(`    - Line ${s.line}: ${s.type} (${s.location})`);
+  });
+
+  console.log(`  Sanitizers: ${taint.sanitizers.length}`);
+  taint.sanitizers.forEach(s => {
+    console.log(`    - Line ${s.line}: ${s.type} (${s.method})`);
+  });
+
+  // Find taint flows
+  const propagationResult = propagateTaint(
+    dfg,
+    calls,
+    taint.sources,
+    taint.sinks,
+    taint.sanitizers ?? []
+  );
+
+  // Run constant propagation for false positive elimination
+  const constPropResult = analyzeConstantPropagation(tree, code);
+
+  // Filter false positives
+  const verifiedFlows = propagationResult.flows.filter(flow => {
+    // Check each step in the path - if any variable has a constant value, it's a FP
+    for (const step of flow.path) {
+      const fpCheck = isFalsePositive(constPropResult, step.line, step.variable);
+      if (fpCheck.isFalsePositive) {
+        return false;
+      }
+    }
+    return true;
+  });
+
+  console.log(`\nVulnerability Detection:`);
+  if (verifiedFlows.length > 0) {
+    console.log(`  Found ${verifiedFlows.length} potential vulnerabilities:`);
+    verifiedFlows.forEach((flow, i) => {
+      console.log(`\n  [${i + 1}] ${flow.sink.type.toUpperCase()}`);
+      console.log(`      Source: Line ${flow.source.line} (${flow.source.type})`);
+      console.log(`      Sink: Line ${flow.sink.line} (${flow.sink.type})`);
+      console.log(`      Confidence: ${(flow.confidence * 100).toFixed(0)}%`);
+      if (flow.path.length > 0) {
+        console.log(`      Path:`);
+        flow.path.forEach(step => {
+          console.log(`        -> ${step.variable} (line ${step.line})`);
+        });
+      }
+    });
+  } else {
+    console.log(`  No vulnerabilities detected.`);
+  }
+}
+
+async function main(): Promise<void> {
+  console.log('Circle-IR Core Library - Node.js Example');
+  console.log('=========================================\n');
+
+  // Initialize the parser
+  console.log('Initializing parser...');
+  await initParser();
+  console.log('Parser initialized.\n');
+
+  // Analyze vulnerable code
+  await analyzeCode(vulnerableCode, 'VulnerableController.java');
+
+  // Analyze safe code
+  await analyzeCode(safeCode, 'SafeUserController.java');
+
+  console.log('\n' + '='.repeat(60));
+  console.log('Analysis complete.');
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "circle-ir",
+  "version": "3.1.0",
+  "description": "High-performance Static Application Security Testing (SAST) library for detecting security vulnerabilities through taint analysis",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/circle-ir-core.d.ts",
+      "import": "./dist/core/circle-ir-core.js",
+      "require": "./dist/core/circle-ir-core.cjs"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser/circle-ir.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "configs",
+    "examples",
+    "wasm",
+    "docs/SPEC.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsc",
+    "build:browser": "esbuild src/browser.ts --bundle --format=esm --platform=browser --external:fs --external:fs/promises --external:path --external:module --external:crypto --external:pino --outfile=dist/browser/circle-ir.js && mkdir -p dist/wasm && cp node_modules/web-tree-sitter/web-tree-sitter.wasm dist/wasm/ && cp wasm/*.wasm dist/wasm/",
+    "build:core": "esbuild src/core-lib.ts --bundle --format=esm --platform=neutral --external:fs --external:fs/promises --external:path --external:module --external:pino --external:crypto --outfile=dist/core/circle-ir-core.js && esbuild src/core-lib.ts --bundle --format=cjs --platform=neutral --external:fs --external:fs/promises --external:path --external:module --external:pino --external:crypto --outfile=dist/core/circle-ir-core.cjs && cp dist/core-lib.d.ts dist/core/circle-ir-core.d.ts",
+    "build:all": "npm run build && npm run build:browser && npm run build:core",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build:all && npm test",
+    "prepack": "npm run build:all"
+  },
+  "keywords": [
+    "sast",
+    "security",
+    "static-analysis",
+    "taint-analysis",
+    "vulnerability-detection",
+    "code-analysis",
+    "java",
+    "javascript",
+    "typescript",
+    "python",
+    "rust",
+    "tree-sitter",
+    "sql-injection",
+    "xss",
+    "command-injection",
+    "path-traversal",
+    "owasp"
+  ],
+  "author": {
+    "name": "Cognium Labs",
+    "url": "https://github.com/cogniumhq"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cogniumhq/circle-ir.git"
+  },
+  "homepage": "https://github.com/cogniumhq/circle-ir#readme",
+  "bugs": {
+    "url": "https://github.com/cogniumhq/circle-ir/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/cognitim"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "pino": "^10.3.0",
+    "web-tree-sitter": "^0.26.3",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@types/unzipper": "^0.10.11",
+    "@vitest/coverage-v8": "^3.0.0",
+    "esbuild": "^0.27.2",
+    "pino-pretty": "^13.1.3",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-rust": "^0.24.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "unzipper": "^0.12.3",
+    "vitest": "^3.0.0"
+  }
+}