circle-ir 3.8.3 → 3.9.7

package/dist/analysis/passes/null-deref-pass.js

@@ -0,0 +1,130 @@
+/**
+ * Pass #20: null-deref (CWE-476, category: reliability)
+ *
+ * Detects variables that are explicitly assigned null/None/undefined and then
+ * used as a receiver (method call or field access) without an intervening
+ * null guard.
+ *
+ * Detection strategy:
+ *   1. Find DFG defs where the expression is an explicit null literal
+ *      (null / None / undefined).
+ *   2. For each such def, find all DFG uses via graph.usesOfDef().
+ *   3. For each use that occurs after the def in the same method and is used
+ *      as a receiver, check whether any line between def and use contains a
+ *      null-check for that variable.
+ *   4. Emit a finding if no guard is found.
+ *
+ * Scope is limited to the enclosing method to avoid cross-method FPs.
+ */
+/** Expression values that represent an explicit null assignment. */
+const NULL_EXPR_RE = /^\s*(null|None|undefined)\s*$/;
+/** Escape a variable name for use in a RegExp. */
+function escRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Returns true if any source line in the range [fromLine, toLine) contains a
+ * null-guard pattern referencing varName.
+ *
+ * Guards recognised:
+ *   - Java/JS: `x != null`, `x !== null`, `null != x`
+ *   - Java/JS: `x == null`, `x === null` (guard on the null branch)
+ *   - Python: `x is not None`, `if x:`
+ *   - Optional chaining: `x?.`
+ *   - Optional API: `x.isPresent()`, `Optional`
+ */
+function hasNullGuard(codeLines, varName, fromLine, toLine) {
+    const esc = escRe(varName);
+    // Build one composite regex (OR of guard patterns)
+    const pattern = new RegExp(`\\b${esc}\\b\\s*!==?\\s*(null|None|undefined)` +
+        `|(null|None|undefined)\\s*!==?\\s*\\b${esc}\\b` +
+        `|\\b${esc}\\b\\s*===?\\s*(null|None|undefined)` + // null-branch check
+        `|(null|None|undefined)\\s*===?\\s*\\b${esc}\\b` +
+        `|\\bis\\s+not\\s+None\\b.*\\b${esc}\\b` + // Python is not None
+        `|\\b${esc}\\b.*\\bis\\s+not\\s+None\\b` +
+        `|if\\s*\\(\\s*${esc}\\s*[)!&|]` + // if (x), if (!x)
+        `|if\\s+${esc}\\s*:` + // Python: if x:
+        `|\\b${esc}\\b\\s*\\.\\s*isPresent\\(\\)` + // Optional.isPresent()
+        `|\\bOptional\\b`);
+    for (let l = fromLine; l < toLine; l++) {
+        const line = codeLines[l - 1] ?? '';
+        if (pattern.test(line))
+            return true;
+    }
+    return false;
+}
+export class NullDerefPass {
+    name = 'null-deref';
+    category = 'reliability';
+    run(ctx) {
+        const { graph, code, language } = ctx;
+        // Rust has the Option/Result type system — NPE is not applicable.
+        // Bash has no objects to dereference.
+        if (language === 'rust' || language === 'bash') {
+            return { potentialNullDerefs: [] };
+        }
+        const file = graph.ir.meta.file;
+        const codeLines = code.split('\n');
+        const potentialNullDerefs = [];
+        const reported = new Set(); // deduplicate by variable+useLine
+        for (const def of graph.ir.dfg.defs) {
+            if (!def.expression || !NULL_EXPR_RE.test(def.expression))
+                continue;
+            const varName = def.variable;
+            const defLine = def.line;
+            // Determine enclosing method bounds to limit search scope
+            const methodInfo = graph.methodAtLine(defLine);
+            const methodEnd = methodInfo?.method.end_line ?? Number.MAX_SAFE_INTEGER;
+            // Find all downstream uses of this null-assigned variable
+            const uses = graph.usesOfDef(def.id);
+            for (const use of uses) {
+                const useLine = use.line;
+                // Use must be AFTER the assignment and within the same method
+                if (useLine <= defLine || useLine > methodEnd)
+                    continue;
+                // Check if the variable is used as a call receiver at this line
+                const callsAtLine = graph.callsAtLine(useLine);
+                const isCallReceiver = callsAtLine.some(c => c.receiver === varName);
+                // Also detect field-access pattern: `varName.field`
+                const lineText = codeLines[useLine - 1] ?? '';
+                const fieldAccessRe = new RegExp(`\\b${escRe(varName)}\\s*\\.`);
+                const isFieldAccess = fieldAccessRe.test(lineText);
+                if (!isCallReceiver && !isFieldAccess)
+                    continue;
+                // Optional chaining (`?.`) is safe — skip
+                const optionalChainRe = new RegExp(`\\b${escRe(varName)}\\s*\\?\\s*\\.`);
+                if (optionalChainRe.test(lineText))
+                    continue;
+                // Check whether a null guard exists between the assignment and this use
+                if (hasNullGuard(codeLines, varName, defLine + 1, useLine))
+                    continue;
+                const key = `${varName}-${useLine}`;
+                if (reported.has(key))
+                    continue;
+                reported.add(key);
+                potentialNullDerefs.push({ defLine, useLine, variable: varName });
+                ctx.addFinding({
+                    id: `null-deref-${file}-${useLine}`,
+                    pass: this.name,
+                    category: this.category,
+                    rule_id: this.name,
+                    cwe: 'CWE-476',
+                    severity: 'high',
+                    level: 'error',
+                    message: `Potential null dereference: '${varName}' was assigned null at line ${defLine} ` +
+                        `and is used at line ${useLine} without a null check`,
+                    file,
+                    line: useLine,
+                    snippet: lineText.trim(),
+                    fix: `Add a null check before dereferencing: \`if (${varName} != null) { ... }\``,
+                    evidence: {
+                        variable: varName,
+                        assigned_null_at: defLine,
+                    },
+                });
+            }
+        }
+        return { potentialNullDerefs };
+    }
+}
+//# sourceMappingURL=null-deref-pass.js.map

package/dist/analysis/passes/null-deref-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-deref-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/null-deref-pass.ts"],"names":[],"mappings":"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"}

package/dist/analysis/passes/orphan-module-pass.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pass #71: orphan-module (project-level)
+ *
+ * Flags modules that have no incoming import edges and are not recognized
+ * entry points. Orphan modules are likely dead code, leftover scaffolding,
+ * or files that were accidentally disconnected from the project.
+ *
+ * This is a project-level pass — it does NOT extend AnalysisPass.
+ * It is invoked from analyzeProject() after all per-file analyses are complete.
+ *
+ * Entry points (excluded from flagging): filename base matches
+ * /^(index|main|app|server|mod)$/i
+ *
+ * Category: architecture | Severity: low | Level: note | CWE: none
+ */
+import type { SastFinding } from '../../types/index.js';
+import type { ProjectGraph } from '../../graph/project-graph.js';
+import type { ImportGraph } from '../../graph/import-graph.js';
+export declare class OrphanModulePass {
+    run(_projectGraph: ProjectGraph, importGraph: ImportGraph): SastFinding[];
+}

package/dist/analysis/passes/orphan-module-pass.js

@@ -0,0 +1,38 @@
+/**
+ * Pass #71: orphan-module (project-level)
+ *
+ * Flags modules that have no incoming import edges and are not recognized
+ * entry points. Orphan modules are likely dead code, leftover scaffolding,
+ * or files that were accidentally disconnected from the project.
+ *
+ * This is a project-level pass — it does NOT extend AnalysisPass.
+ * It is invoked from analyzeProject() after all per-file analyses are complete.
+ *
+ * Entry points (excluded from flagging): filename base matches
+ * /^(index|main|app|server|mod)$/i
+ *
+ * Category: architecture | Severity: low | Level: note | CWE: none
+ */
+export class OrphanModulePass {
+    run(_projectGraph, importGraph) {
+        const findings = [];
+        const orphans = importGraph.findOrphans();
+        for (const file of orphans) {
+            const finding = {
+                id: `orphan-module-${file.replace(/[^a-z0-9]/gi, '-')}`,
+                pass: 'orphan-module',
+                category: 'architecture',
+                rule_id: 'orphan-module',
+                severity: 'low',
+                level: 'note',
+                message: `Module '${file}' has no incoming imports and is not a known entry point. It may be dead code.`,
+                file,
+                line: 1,
+                evidence: { file },
+            };
+            findings.push(finding);
+        }
+        return findings;
+    }
+}
+//# sourceMappingURL=orphan-module-pass.js.map

package/dist/analysis/passes/orphan-module-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-module-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/orphan-module-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,OAAO,gBAAgB;IAC3B,GAAG,CAAC,aAA2B,EAAE,WAAwB;QACvD,MAAM,QAAQ,GAAkB,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;QAE1C,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAgB;gBAC3B,EAAE,EAAQ,iBAAiB,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,EAAE;gBAC7D,IAAI,EAAM,eAAe;gBACzB,QAAQ,EAAE,cAAc;gBACxB,OAAO,EAAG,eAAe;gBACzB,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAK,MAAM;gBAChB,OAAO,EAAG,WAAW,IAAI,gFAAgF;gBACzG,IAAI;gBACJ,IAAI,EAAM,CAAC;gBACX,QAAQ,EAAE,EAAE,IAAI,EAAE;aACnB,CAAC;YACF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/analysis/passes/resource-leak-pass.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pass #21: resource-leak (CWE-772, category: reliability)
+ *
+ * Detects I/O resources (streams, connections, sockets) that are opened but
+ * not closed on all exit paths. Unclosed resources exhaust file descriptors
+ * or connection pools and cause subtle failures under load.
+ *
+ * Detection strategy:
+ *   1. Find resource-opening calls: known constructors (FileInputStream, etc.)
+ *      or factory methods (open, createReadStream, etc.).
+ *   2. Get the variable bound to the resource from DFG defs at the open line.
+ *   3. Within the enclosing method, look for a close()/dispose() call whose
+ *      receiver matches the resource variable.
+ *   4a. No close call found → definite leak (high, error).
+ *   4b. Close found but no `finally` keyword in the method after the open
+ *       → potential leak (medium, warning): an exception skips the close.
+ *
+ * Note: Java try-with-resources generates no explicit close() in the source;
+ * the pass treats the absence of both an explicit close AND a finally as a
+ * definite leak.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface ResourceLeakResult {
+    /** Resources that may not be properly closed. */
+    leaks: Array<{
+        line: number;
+        resource: string;
+        variable: string;
+        kind: 'definite' | 'potential';
+    }>;
+}
+export declare class ResourceLeakPass implements AnalysisPass<ResourceLeakResult> {
+    readonly name = "resource-leak";
+    readonly category: "reliability";
+    run(ctx: PassContext): ResourceLeakResult;
+    /** True if a `finally` keyword appears in the method body after the open line. */
+    private hasFinallyBlock;
+    /**
+     * True if a try-with-resources or Python `with` statement wraps the resource,
+     * indicating implicit close. Detects `try (` or `with open(` patterns.
+     */
+    private hasTryWithResources;
+}

package/dist/analysis/passes/resource-leak-pass.js

@@ -0,0 +1,156 @@
+/**
+ * Pass #21: resource-leak (CWE-772, category: reliability)
+ *
+ * Detects I/O resources (streams, connections, sockets) that are opened but
+ * not closed on all exit paths. Unclosed resources exhaust file descriptors
+ * or connection pools and cause subtle failures under load.
+ *
+ * Detection strategy:
+ *   1. Find resource-opening calls: known constructors (FileInputStream, etc.)
+ *      or factory methods (open, createReadStream, etc.).
+ *   2. Get the variable bound to the resource from DFG defs at the open line.
+ *   3. Within the enclosing method, look for a close()/dispose() call whose
+ *      receiver matches the resource variable.
+ *   4a. No close call found → definite leak (high, error).
+ *   4b. Close found but no `finally` keyword in the method after the open
+ *       → potential leak (medium, warning): an exception skips the close.
+ *
+ * Note: Java try-with-resources generates no explicit close() in the source;
+ * the pass treats the absence of both an explicit close AND a finally as a
+ * definite leak.
+ */
+/** Constructors that produce closeable resources. */
+const RESOURCE_CTORS = new Set([
+    // Java IO
+    'FileInputStream', 'FileOutputStream', 'FileReader', 'FileWriter',
+    'BufferedReader', 'BufferedWriter', 'PrintWriter', 'InputStreamReader',
+    'OutputStreamWriter', 'RandomAccessFile', 'DataInputStream', 'DataOutputStream',
+    'ObjectInputStream', 'ObjectOutputStream', 'ZipInputStream', 'ZipOutputStream',
+    'JarInputStream', 'JarOutputStream', 'GZIPInputStream', 'GZIPOutputStream',
+    // Java NIO
+    'FileChannel',
+    // Java Net
+    'Socket', 'ServerSocket', 'DatagramSocket',
+]);
+/** Factory / open methods that return closeable resources. */
+const RESOURCE_FACTORY_METHODS = new Set([
+    // Java NIO/IO
+    'openConnection', 'openStream', 'newInputStream', 'newOutputStream',
+    'newBufferedReader', 'newBufferedWriter', 'newByteChannel',
+    // Python built-in
+    'open',
+    // Node.js streams
+    'createReadStream', 'createWriteStream', 'createConnection',
+]);
+/** Methods that properly release a resource. */
+const CLOSE_METHODS = new Set([
+    'close', 'dispose', 'shutdown', 'disconnect', 'release', 'destroy', 'free',
+    'shutdownNow', 'terminate',
+]);
+export class ResourceLeakPass {
+    name = 'resource-leak';
+    category = 'reliability';
+    run(ctx) {
+        const { graph, code } = ctx;
+        const file = graph.ir.meta.file;
+        const codeLines = code.split('\n');
+        const leaks = [];
+        for (const call of graph.ir.calls) {
+            const name = call.method_name;
+            const isConstructor = call.is_constructor === true && RESOURCE_CTORS.has(name);
+            const isFactory = !call.is_constructor && RESOURCE_FACTORY_METHODS.has(name);
+            if (!isConstructor && !isFactory)
+                continue;
+            const openLine = call.location.line;
+            // Resource must be captured in a variable to be trackable
+            const defs = graph.defsAtLine(openLine);
+            if (defs.length === 0)
+                continue;
+            const resourceVar = defs[0].variable;
+            // Limit search to the enclosing method
+            const methodInfo = graph.methodAtLine(openLine);
+            if (!methodInfo)
+                continue;
+            const methodEnd = methodInfo.method.end_line;
+            // Look for a close() call on this resource within the method
+            const closeCall = graph.ir.calls.find(c => CLOSE_METHODS.has(c.method_name) &&
+                c.receiver === resourceVar &&
+                c.location.line > openLine &&
+                c.location.line <= methodEnd);
+            const snippet = (codeLines[openLine - 1] ?? '').trim();
+            if (!closeCall) {
+                // Also accept try-with-resources or with-statement as implicit close
+                if (this.hasTryWithResources(codeLines, openLine, methodEnd))
+                    continue;
+                // Definite leak: resource is never explicitly released
+                leaks.push({ line: openLine, resource: name, variable: resourceVar, kind: 'definite' });
+                ctx.addFinding({
+                    id: `resource-leak-${file}-${openLine}`,
+                    pass: this.name,
+                    category: this.category,
+                    rule_id: this.name,
+                    cwe: 'CWE-772',
+                    severity: 'high',
+                    level: 'error',
+                    message: `Resource leak: \`${name}\` assigned to '${resourceVar}' at line ${openLine} ` +
+                        `is never closed — file descriptors or connections may be exhausted`,
+                    file,
+                    line: openLine,
+                    snippet,
+                    fix: `Use try-with-resources (Java 7+): \`try (${name} ${resourceVar} = ...) { ... }\`, ` +
+                        `or call \`${resourceVar}.close()\` in a finally block`,
+                    evidence: { resource: name, variable: resourceVar },
+                });
+                continue;
+            }
+            // Close found — check if it is protected by a finally block
+            if (this.hasFinallyBlock(codeLines, openLine, methodEnd))
+                continue;
+            // Potential leak: close() exists but may be skipped on exception
+            leaks.push({ line: openLine, resource: name, variable: resourceVar, kind: 'potential' });
+            ctx.addFinding({
+                id: `resource-leak-${file}-${openLine}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-772',
+                severity: 'medium',
+                level: 'warning',
+                message: `Potential resource leak: \`${name}\` ('${resourceVar}') is closed at ` +
+                    `line ${closeCall.location.line} but not inside a finally block — ` +
+                    `an exception could skip the close`,
+                file,
+                line: openLine,
+                snippet,
+                fix: `Move \`${resourceVar}.close()\` into a finally block, or use try-with-resources`,
+                evidence: {
+                    resource: name,
+                    variable: resourceVar,
+                    close_line: closeCall.location.line,
+                },
+            });
+        }
+        return { leaks };
+    }
+    /** True if a `finally` keyword appears in the method body after the open line. */
+    hasFinallyBlock(lines, fromLine, toLine) {
+        for (let l = fromLine; l <= toLine && l <= lines.length; l++) {
+            if (/\bfinally\b/.test(lines[l - 1] ?? ''))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * True if a try-with-resources or Python `with` statement wraps the resource,
+     * indicating implicit close. Detects `try (` or `with open(` patterns.
+     */
+    hasTryWithResources(lines, fromLine, toLine) {
+        for (let l = fromLine; l <= toLine && l <= lines.length; l++) {
+            const text = lines[l - 1] ?? '';
+            if (/\btry\s*\(/.test(text) || /\bwith\b.*\bopen\b/.test(text))
+                return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=resource-leak-pass.js.map

package/dist/analysis/passes/resource-leak-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-leak-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/resource-leak-pass.ts"],"names":[],"mappings":"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"}

package/dist/analysis/passes/sink-filter-pass.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SinkFilterPass
+ *
+ * Applies the four-stage sink filtering pipeline to eliminate false positives,
+ * followed by language-specific XPath/XSS suppression.
+ *
+ * Filter stages (applied in order):
+ *   1. Dead code — remove sinks on unreachable lines
+ *   2. Clean array elements — strong updates via constant propagation
+ *   3. Clean variables — arguments proven non-tainted by constant propagation
+ *   4. Sanitized sinks — sinks wrapped by a recognised sanitizer call
+ *   5. Python XPath FP reduction
+ *   6. JavaScript XSS FP reduction
+ *
+ * Depends on: taint-matcher, constant-propagation, language-sources
+ */
+import type { TaintSource, TaintSink, TaintSanitizer } from '../../types/index.js';
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface SinkFilterResult {
+    /** Merged sources: taint-matcher + language-sources. */
+    sources: TaintSource[];
+    /** Filtered sinks. */
+    sinks: TaintSink[];
+    sanitizers: TaintSanitizer[];
+}
+export declare class SinkFilterPass implements AnalysisPass<SinkFilterResult> {
+    readonly name = "sink-filter";
+    readonly category: "security";
+    run(ctx: PassContext): SinkFilterResult;
+}
+import type { CircleIR } from '../../types/index.js';
+type Symbols = Map<string, {
+    value: string | number | boolean | null;
+    type: string;
+    sourceLine: number;
+}>;
+export declare function filterCleanVariableSinks(sinks: CircleIR['taint']['sinks'], calls: CircleIR['calls'], taintedVars: Set<string>, symbols: Symbols, dfg?: CircleIR['dfg'], sanitizedVars?: Set<string>, synchronizedLines?: Set<number>): CircleIR['taint']['sinks'];
+export declare function filterSanitizedSinks(sinks: CircleIR['taint']['sinks'], sanitizers: CircleIR['taint']['sanitizers'], calls: CircleIR['calls']): CircleIR['taint']['sinks'];
+export {};