circle-ir 3.194.0 → 3.195.0

package/configs/README.md

@@ -0,0 +1,39 @@
+# `configs/` — documentation and export surface (not runtime)
+
+**Nothing in `src/` reads these files.** circle-ir must run in the browser and
+in Cloudflare Workers, so the library cannot touch the filesystem at all. The
+taint patterns that actually drive analysis live in TypeScript:
+
+| Surface | Location | Role |
+|---|---|---|
+| `DEFAULT_SOURCES` / `DEFAULT_SINKS` / `DEFAULT_SANITIZERS` / `DEFAULT_SINK_SEMANTICS` | `src/analysis/config-loader.ts` | **Canonical.** Language-agnostic by default; scope a pattern with `languages: ['python']` when its method name collides across ecosystems. |
+| `LanguagePlugin.getBuiltinSources()` / `getBuiltinSinks()` | `src/languages/plugins/<lang>.ts` | Supplement for language-specific patterns that have **no** `DEFAULT_*` counterpart. `TaintMatcherPass` merges them after the canonical registry. |
+| `configs/**` (this directory) | — | Documentation, and an export for downstream tools that want a machine-readable view of the ruleset. Editing a file here changes nothing about how code is analysed. |
+
+See ADR-004 in `.specifica/mvp/design.md` for the rationale.
+
+## Adding or fixing a pattern
+
+Add it to `DEFAULT_SINKS` / `DEFAULT_SOURCES` in `src/analysis/config-loader.ts`
+(scoped with `languages` if it is language-specific). Only reach for a plugin
+builtin when the pattern genuinely has no place in the canonical registry.
+
+Never register the same `(class, method, cwe)` in both surfaces:
+`findSinks` dedupes by `location:line:cwe` and keeps the higher-confidence
+match, so the duplicate is invisible — you can "fix" the copy that loses and
+see no change in behaviour. That failure mode cost an extra investigation round
+on Issue #4 (`yaml.safe_load`). It is now locked by
+`tests/languages/sink-registry-contract.test.ts`.
+
+## Drift
+
+Because these files are not executable, they lag the runtime registries. To see
+by how much:
+
+```bash
+npm run config:drift
+```
+
+The report lists documented sinks that no longer exist at runtime, and entries
+whose vulnerability type disagrees with the code. It is informational and never
+fails the build — treat a large delta as a documentation debt signal, not a bug.

package/dist/analysis/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/analysis/config-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,UAAU,EACX,MAAM,oBAAoB,CAAC;AAE5B;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAEjD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,CAiB1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG;IACtD,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC,CAcA;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,mBAAmB,EAAE,GAC7B,kBAAkB,EAAE,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EAAE,EACxB,YAAY,EAAE,MAAM,EAAE,EACtB,qBAAqB,GAAE,MAAM,EAAO,GACnC,WAAW,CAYb;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,EA6uB1C,CAAC;AA+KF,eAAO,MAAM,aAAa,EAAE,WAAW,EA2wDtC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,gBAAgB,EA+hBhD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,EAiDtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAO9C;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAAU,EA8F5C,CAAC"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/analysis/config-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,UAAU,EACX,MAAM,oBAAoB,CAAC;AAE5B;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAEjD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,CAiB1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG;IACtD,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC,CAcA;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,mBAAmB,EAAE,GAC7B,kBAAkB,EAAE,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EAAE,EACxB,YAAY,EAAE,MAAM,EAAE,EACtB,qBAAqB,GAAE,MAAM,EAAO,GACnC,WAAW,CAYb;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,EAivB1C,CAAC;AA+KF,eAAO,MAAM,aAAa,EAAE,WAAW,EA+yDtC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,gBAAgB,EA+hBhD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,EAiDtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAO9C;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAAU,EA8F5C,CAAC"}

package/dist/analysis/config-loader.js

@@ -500,7 +500,11 @@ export const DEFAULT_SOURCES = [
     { method: 'Json', type: 'http_body', severity: 'high', return_tainted: true, languages: ['rust'] },
     { method: 'Query', type: 'http_param', severity: 'high', return_tainted: true, languages: ['rust'] },
     { method: 'Path', type: 'http_path', severity: 'high', return_tainted: true, languages: ['rust'] },
-    { method: 'Form', type: 'http_param', severity: 'high', return_tainted: true, languages: ['rust'] },
+    // `Form<T>` decodes the urlencoded request *body* (`Query<T>` above is the
+    // query-string extractor), so it is http_body — retyped from http_param
+    // when the RustPlugin's http_body duplicate was removed, so the two
+    // surfaces no longer disagree. Matches Gin's `Context.PostForm`.
+    { method: 'Form', type: 'http_body', severity: 'high', return_tainted: true, languages: ['rust'] },
     // Rust std library
     { method: 'var', class: 'env', type: 'env_input', severity: 'medium', return_tainted: true },
     { method: 'var_os', class: 'env', type: 'env_input', severity: 'medium', return_tainted: true },
@@ -1823,7 +1827,11 @@ export const DEFAULT_SINKS = [
     // Also match without receiver (destructured imports: const { exec } = require('child_process'))
     // `exec` is intentionally classless: catches Node.js child_process.exec AND
     // Java Runtime.exec (via `r.exec()` where heuristic can't resolve r → Runtime).
-    { method: 'exec', type: 'command_injection', cwe: 'CWE-78', severity: 'high', arg_positions: [0] },
+    // Excluded from Python: there, bare `exec(code)` is the code-execution
+    // builtin, registered below as code_injection / CWE-94. Before the exclusion
+    // a Python `exec(user_code)` matched both patterns and emitted two findings
+    // for one call — CWE-78 (wrong: no shell is involved) and CWE-94 (right).
+    { method: 'exec', type: 'command_injection', cwe: 'CWE-78', severity: 'high', arg_positions: [0], exclude_languages: ['python'] },
     // `execSync`/`spawn`/`spawnSync`/`execFile` are Node-specific — language-scope them.
     { method: 'execSync', type: 'command_injection', cwe: 'CWE-78', severity: 'high', arg_positions: [0], languages: ['javascript', 'typescript'] },
     { method: 'spawn', type: 'command_injection', cwe: 'CWE-78', severity: 'high', arg_positions: [0], languages: ['javascript', 'typescript'] },
@@ -1851,7 +1859,11 @@ export const DEFAULT_SINKS = [
     // Note: classless { method: 'query' } removed — too many FPs (UriComponentsBuilder.query(), etc.)
     // SQL query calls are covered by class-specific patterns above (Connection, Pool, Client, JdbcTemplate)
     // Note: `raw` is shared with Python (Django ORM) — scoped to JS+TS to avoid leaking.
-    { method: 'raw', type: 'sql_injection', cwe: 'CWE-89', severity: 'high', arg_positions: [0], languages: ['javascript', 'typescript'] },
+    // Severity `critical` (not `high`) preserves what the JS plugin's duplicate
+    // builtin emitted before the #4 follow-up consolidation removed it: the
+    // plugin copy carried `critical`, which won the `findSinks` dedup slot via
+    // the +0.1 critical-severity confidence boost.
+    { method: 'raw', type: 'sql_injection', cwe: 'CWE-89', severity: 'critical', arg_positions: [0], languages: ['javascript', 'typescript'] },
     // sqlite3 (npm) — Database/Statement methods. The JS plugin resolves
     // `const db = new sqlite3.Database(...); db.all(sql)` to the resolution
     // target `Connection.all`, so class-scoped patterns matching `Connection`
@@ -2410,10 +2422,30 @@ export const DEFAULT_SINKS = [
     { method: 'Sprintf', class: 'fmt', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [0], languages: ['go'] },
     { method: 'Printf', class: 'fmt', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [0], languages: ['go'] },
     { method: 'Errorf', class: 'fmt', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [0], languages: ['go'] },
+    // `fmt.Fprintf` is deliberately dual-classified: this CWE-134 entry and the
+    // Go plugin's xss (CWE-79) entry both cover arg[1], so a tainted format
+    // string emits two findings. Unlike the logger case above, neither is
+    // redundant — CWE-134 holds for any writer, while CWE-79 is the actionable
+    // finding when the writer is an http.ResponseWriter (`fmt.Fprintf(w, taint)`
+    // is the standard Go reflected-XSS shape). Collapsing it requires deciding
+    // by the *type of arg[0]*, which sink patterns cannot express today: the
+    // options are a Go-specific gate (mirroring isSafeGoJsonUnmarshalCall) that
+    // emits xss only for a resolved ResponseWriter, or dropping one CWE and
+    // accepting either lost XSS recall or a mis-classified stderr write.
+    // Left as-is pending the Go corpus run — see tasks.md.
     { method: 'Fprintf', class: 'fmt', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [1], languages: ['go'] },
     // cognium-dev #264 — Go stdlib `log` package format-string entry points.
     // log.Printf / Fatalf / Panicf take the format string at arg[0]; tainted
     // format string reaches the same fmt.Sprintf machinery internally.
+    //
+    // These deliberately coexist with the Go plugin's log_injection (CWE-117)
+    // entries for the same methods, so such a call emits both. The Logger
+    // decision note in the Java log_injection section above does NOT apply
+    // here: it reasons about SLF4J-style APIs where the format string is a
+    // literal with `{}` placeholders, whereas Go's `log.Printf(fmt, ...)` takes
+    // a real format string that an attacker can control. CWE-117 covers the
+    // forged log line, CWE-134 the format string itself. Locked by
+    // tests/analysis/passes/format-string-additions.test.ts.
     { method: 'Printf', class: 'log', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [0], languages: ['go'] },
     { method: 'Fatalf', class: 'log', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [0], languages: ['go'] },
     { method: 'Panicf', class: 'log', type: 'format_string', cwe: 'CWE-134', severity: 'medium', arg_positions: [0], languages: ['go'] },
@@ -2427,6 +2459,14 @@ export const DEFAULT_SINKS = [
     { method: 'cookie', type: 'crlf', cwe: 'CWE-113', severity: 'medium', arg_positions: [1], languages: ['javascript', 'typescript'] },
     // Express: res.location(url) and res.redirect(url) — Location header.
     { method: 'location', type: 'crlf', cwe: 'CWE-113', severity: 'medium', arg_positions: [0], languages: ['javascript', 'typescript'] },
+    // `redirect` is deliberately dual-classified: this crlf (CWE-113) entry
+    // coexists with the open_redirect (CWE-601) entry for js/ts, so a tainted
+    // redirect target emits two flows. That is intentional, not duplication —
+    // #189 Sprint 82 shipped a sink-type-aware flow dedup specifically so both
+    // survive ("res.redirect is both open_redirect AND crlf"), and #132 added a
+    // crlf recall test for the bare `res.redirect(req.query.url)` shape. Locked
+    // by issue-189-sprint82-open-redirect-cluster.test.ts and
+    // crlf-stage8-fp.test.ts — do not collapse without revisiting both tickets.
     { method: 'redirect', type: 'crlf', cwe: 'CWE-113', severity: 'medium', arg_positions: [0], languages: ['javascript', 'typescript'] },
     // Go net/http: w.Header().Set(k, v) / Add(k, v) — first arg is the value
     // (Header is a map; the actual `value` is arg 1 of the call). We flag the