@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/rules/path-traversal.ts

@@ -0,0 +1,101 @@
+/**
+ * PATH TRAVERSAL  (CWE-22, OWASP A01:2025 - Broken Access Control)
+ *
+ * WHAT THE BUG IS, in plain language:
+ * The server opens a file whose name the request chose.
+ *
+ *     res.sendFile(path.join(__dirname, 'uploads', req.query.name));
+ *
+ * The code means "a file in uploads". The request sends
+ * `../../../etc/passwd`, and `..` walks up one folder per step until it is
+ * out of uploads and anywhere the server process can read - its own source,
+ * its `.env`, the keys on the box. On a write or a delete it is worse.
+ *
+ * THE FIX: keep only the file name (`path.basename`, `os.path.basename`,
+ * `secure_filename`, `filepath.Base`, `Path.getFileName`), or resolve the
+ * full path and check that it still starts with the folder you meant. Or
+ * hand the folder to an API that refuses to leave it (Express `sendFile`
+ * with `root`, Flask `send_from_directory`).
+ *
+ * ============================================================================
+ * WHY THIS RULE HAS NO SIGNATURE PASS
+ * ============================================================================
+ * Same reason as SSRF: "this code opens a file" is what programs do. Only a
+ * traced path from a request value to the open is a finding, so `check()`
+ * returns null and the taint engine emits every one.
+ *
+ * A path from the COMMAND LINE, the environment or the terminal is chosen by
+ * whoever runs the program, who could open that file themselves. It is
+ * reported low, as to review, not proven: it matters only when the program
+ * runs with more rights than its caller (setuid, a service, a CGI script).
+ */
+
+import { type Rule, type RuleHit } from './contract.js';
+
+export const pathTraversalRule: Rule = {
+  id: 'path-traversal',
+  name: 'File path the user chose',
+  cwe: 'CWE-22',
+  owasp: 'A01:2025 Broken Access Control',
+  severity: 'high',
+  summary: 'The server opens a file path the request may choose, so `../` could reach files outside the folder the code meant.',
+  fix:
+    'Keep only the file name (basename / secure_filename / filepath.Base), or resolve the path and check it still starts with the intended folder.',
+  explanation:
+    'The code means "a file in this folder", but the name comes from the request, ' +
+    'and every `../` in it climbs one folder up. Enough of them and the server reads, ' +
+    'writes or deletes any file its process can reach: its own source, its secrets, ' +
+    'the keys on the machine. Keep only the last name in the path, or resolve the ' +
+    'full path and check it still starts with the folder you meant before opening it.',
+  limitations:
+    'FLOW-VERIFIED ONLY: "opens a file" describes almost every program, so there is no ' +
+    'pattern pass and every finding comes from a traced path. A path from the command ' +
+    'line, the environment or the terminal is chosen by whoever runs the program and is ' +
+    'reported low, to review. A path opened after a prefix check (`resolved.startsWith(base)`) ' +
+    'or a `..` blocklist in the same function is reported to review, never proven and never ' +
+    'cleared: what the check compares is NOT read, so a correct one and a wrong one look the ' +
+    'same here. path.join, path.resolve and filepath.Clean are NOT treated as fixes, because ' +
+    'none of them stops `../`. A "not found" answer before the open (`if (!x) return res.status(404)`, ' +
+    'abort(404), Http404) is read as a possible lookup of known names and also gives to review: ' +
+    'what the lookup accepts is NOT read, and any 404 above the open in the function counts, ' +
+    'even one about a different value.',
+  shapes: ['call'],
+  support: {
+    javascript: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers fs / fs.promises / fs-extra reads, writes, deletes and directory listings, destructured readFileSync-style names, and Express res.sendFile / res.download without a root option. NOT covered: a bare readFile() whose import we cannot see.',
+    },
+    typescript: {
+      status: 'implemented',
+      note: 'Data-flow only. Identical to JavaScript.',
+    },
+    python: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers open(), os file and directory calls, shutil copy / move / rmtree, and Flask send_file. NOT covered: pathlib (Path(x).read_text()), where the path lives in an object the tracer does not follow.',
+    },
+    java: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers new File / FileInputStream / FileOutputStream / FileReader / FileWriter / RandomAccessFile / FileSystemResource and the java.nio Files calls that open a path (readAllBytes, newInputStream, write, delete, ...). Paths.get / Path.of only build a path and are followed, not reported. NOT covered: a Path held in a field and opened in another method.',
+    },
+    php: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers file_get_contents, fopen, readfile, file, file_put_contents, unlink, opendir, scandir, copy, rename, mkdir and rmdir. NOT covered: include / require, which are statements, not calls, and are not in the sink tables.',
+    },
+    go: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers os and ioutil Open / OpenFile / ReadFile / WriteFile / Create / Remove / RemoveAll / ReadDir / Mkdir / Rename and http.ServeFile. NOT covered: http.FileServer, which is configured once rather than called with a path.',
+    },
+    c: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers fopen, freopen, open, openat, creat, remove, unlink, rename and opendir. argv, getenv and stdin are reported low, to review: they are chosen by whoever runs the program.',
+    },
+    cpp: {
+      status: 'partial',
+      note: 'PARTIAL: the C library calls only. std::ifstream / std::ofstream and std::filesystem are NOT modelled - a stream is opened by a declaration, not a call.',
+    },
+  },
+  /* Deliberately silent: see the header. The taint engine emits every finding for this rule id. */
+  check(): RuleHit | null {
+    return null;
+  },
+};

package/src/rules/registry.ts

@@ -0,0 +1,90 @@
+/**
+ * THE RULE REGISTRY
+ *
+ * One list, one place. Adding a rule = write the file, import it, add it here.
+ * The engine imports nothing but this.
+ *
+ * `validateRegistry()` runs on every scan. It refuses to start if a rule breaks
+ * the honesty contract - for example by declaring a language as `implemented`
+ * with an empty note. A rule that cannot say what it does not cover has not
+ * finished thinking, and shipping it silently is the failure mode this whole
+ * project is a reaction to.
+ */
+
+import type { LanguageId } from '../parse/languages.js';
+import { LANGUAGES } from '../parse/languages.js';
+import type { Rule } from './contract.js';
+import { codeInjectionRule } from './code-injection.js';
+import { commandInjectionRule } from './command-injection.js';
+import { hardcodedSecretRule } from './hardcoded-secret.js';
+import { sqlInjectionRule } from './sql-injection.js';
+import { ssrfRule } from './ssrf.js';
+import { pathTraversalRule } from './path-traversal.js';
+import { unsafeDeserializationRule } from './unsafe-deserialization.js';
+import { weakHashRule } from './weak-hash.js';
+import { formatStringRule } from './format-string.js';
+import { unboundedCopyRule } from './unbounded-copy.js';
+import { xssRule } from './xss.js';
+
+export const ALL_RULES: readonly Rule[] = [
+  sqlInjectionRule,
+  commandInjectionRule,
+  formatStringRule,
+  unboundedCopyRule,
+  codeInjectionRule,
+  xssRule,
+  ssrfRule,
+  pathTraversalRule,
+  unsafeDeserializationRule,
+  hardcodedSecretRule,
+  weakHashRule,
+];
+
+export function rulesForLanguage(language: LanguageId): Rule[] {
+  return ALL_RULES.filter((rule) => {
+    const support = rule.support[language];
+    return support !== undefined && support.status !== 'not-implemented';
+  });
+}
+
+export function getRule(id: string): Rule | undefined {
+  return ALL_RULES.find((rule) => rule.id === id);
+}
+
+/** Throws if the registry violates the project's own honesty requirements. */
+export function validateRegistry(): void {
+  const problems: string[] = [];
+  const seen = new Set<string>();
+
+  for (const rule of ALL_RULES) {
+    if (seen.has(rule.id)) problems.push(`duplicate rule id: ${rule.id}`);
+    seen.add(rule.id);
+
+    if (rule.limitations.trim().length < 20) {
+      problems.push(`${rule.id}: 'limitations' is missing or too short to be useful`);
+    }
+    if (rule.explanation.trim().length < 40) {
+      problems.push(`${rule.id}: 'explanation' is missing or too short to teach anything`);
+    }
+    for (const language of LANGUAGES) {
+      const support = rule.support[language.id];
+      if (!support) continue;
+      if (support.note.trim().length < 15) {
+        problems.push(
+          `${rule.id}/${language.id}: support note is empty - a gap must be described, not implied`,
+        );
+      }
+      if (support.status !== 'implemented' && !/PARTIAL|NOT|not covered|missing/i.test(support.note)) {
+        problems.push(
+          `${rule.id}/${language.id}: status is '${support.status}' but the note does not say what is missing`,
+        );
+      }
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new Error(
+      `Rule registry violates the honesty contract:\n  - ${problems.join('\n  - ')}`,
+    );
+  }
+}

package/src/rules/sql-injection.ts

@@ -0,0 +1,311 @@
+/**
+ * SQL INJECTION  (CWE-89, OWASP A05:2025 - Injection)
+ *
+ * WHAT THE BUG IS, in plain language:
+ * A database doesn't receive "a question" - it receives a string of text that it
+ * reads as INSTRUCTIONS. If you build that string by gluing user input into it,
+ * the user gets to write part of your instructions.
+ *
+ *     db.query("SELECT * FROM users WHERE id = " + userId)
+ *
+ * If someone sends `userId = 1 OR 1=1`, the database is asked for every user.
+ * If they send `1; DROP TABLE users --`, it may be asked to delete the table.
+ * The database is not tricked or hacked; it does exactly what the text says.
+ * The mistake happened when data and instructions were mixed into one string.
+ *
+ * THE FIX, so the rule can suggest it:
+ * Parameterised queries (also called prepared statements). You send the query
+ * shape and the values SEPARATELY:
+ *
+ *     db.query("SELECT * FROM users WHERE id = ?", [userId])
+ *
+ * The driver never lets the value become part of the instruction, whatever it
+ * contains. This is not "escaping harder" - it is a structurally different
+ * thing, and it is why "we sanitise our inputs" is a weaker answer than
+ * "we parameterise our queries".
+ *
+ * WHAT THIS RULE ACTUALLY CHECKS (and does not):
+ * We look for a call to a known query-executing method whose argument was
+ * BUILT rather than written, and whose visible text looks like SQL. We do NOT
+ * know whether the spliced-in value came from an attacker. That is data-flow
+ * analysis. The taint engine does exactly that, and when it succeeds the
+ * verified finding supersedes this one. Everything the tracer could not confirm
+ * stays here, signature-based, saying so on the finding itself.
+ */
+
+import type { LanguageId } from '../parse/languages.js';
+import { asAssignment, asCall, type Rule, type RuleHit } from './contract.js';
+import {
+  analyzeStringExpression,
+  isStringBuildingExpression,
+  looksLikeSql,
+  expandsOnlyPlaceholders,
+  constantProof,
+} from './lib/strings.js';
+import { partsAreGuarded } from './lib/guards.js';
+
+/**
+ * Methods that hand a string to a database engine.
+ * Case matters: Go and Java capitalise, JavaScript and Python do not.
+ */
+const QUERY_METHODS: Record<LanguageId, readonly string[]> = {
+  javascript: [
+    'query', 'execute', 'exec', 'raw', 'prepare', 'run', 'all', 'get', 'each',
+    'queryRaw', '$queryRawUnsafe', '$executeRawUnsafe', 'unsafe', 'sequelize.query',
+  ],
+  typescript: [
+    'query', 'execute', 'exec', 'raw', 'prepare', 'run', 'all', 'get', 'each',
+    'queryRaw', '$queryRawUnsafe', '$executeRawUnsafe', 'unsafe',
+  ],
+  python: [
+    'execute', 'executemany', 'executescript', 'raw', 'text', 'query', 'from_statement',
+  ],
+  java: [
+    'executeQuery', 'executeUpdate', 'execute', 'prepareStatement', 'prepareCall',
+    'createQuery', 'createNativeQuery', 'createSQLQuery', 'rawQuery', 'addBatch',
+    'queryForObject', 'queryForList', 'update',
+  ],
+  go: [
+    'Query', 'QueryRow', 'QueryContext', 'QueryRowContext', 'Exec', 'ExecContext',
+    'Prepare', 'PrepareContext', 'Raw', 'MustExec', 'Select', 'Get', 'NamedExec',
+  ],
+  // PHP mixes procedural functions (mysqli_query) with PDO/mysqli methods
+  // ($pdo->query). Both are bare names by the time the shape reaches us, so
+  // one list covers both. `prepare` is included on purpose: a prepared
+  // statement built by concatenation is not parameterised, it is just a slower
+  // injection.
+  php: [
+    'query', 'exec', 'prepare', 'unprepared', 'statement', 'select', 'selectOne',
+    'mysqli_query', 'mysqli_real_query', 'mysqli_multi_query', 'mysqli_prepare',
+    'pg_query', 'pg_send_query', 'sqlite_query', 'sqlsrv_query',
+    'mysql_query', 'db_query',
+  ],
+  /*
+   * C database APIs are plain functions, not methods, and every one of them
+   * takes the SQL as a bare char* - there is no query builder to be confused
+   * with. The parameterised forms have DIFFERENT names (mysql_stmt_prepare,
+   * PQexecParams, sqlite3_prepare_v2), so they are absent here and the correct
+   * code stays quiet, which is the same distinction the other languages draw
+   * between `query` and `prepare`.
+   */
+  c: [
+    'mysql_query', 'mysql_real_query', 'PQexec', 'sqlite3_exec',
+    'sqlite3_get_table', 'dbsqlexec', 'SQLExecDirect',
+  ],
+  // C++ adds the method-call forms that wrapper libraries expose.
+  cpp: [
+    'mysql_query', 'mysql_real_query', 'PQexec', 'sqlite3_exec',
+    'sqlite3_get_table', 'SQLExecDirect',
+    'query', 'execute', 'exec',
+  ],
+};
+
+const METHOD_SETS: Record<LanguageId, ReadonlySet<string>> = {
+  javascript: new Set(QUERY_METHODS.javascript),
+  typescript: new Set(QUERY_METHODS.typescript),
+  python: new Set(QUERY_METHODS.python),
+  java: new Set(QUERY_METHODS.java),
+  go: new Set(QUERY_METHODS.go),
+  php: new Set(QUERY_METHODS.php),
+  c: new Set(QUERY_METHODS.c),
+  cpp: new Set(QUERY_METHODS.cpp),
+};
+
+const MECHANISM_WORDS: Record<string, string> = {
+  concatenation: 'string concatenation (+)',
+  interpolation: 'string interpolation (template literal / f-string)',
+  'format-call': 'a string-formatting call (Sprintf / .format / String.format)',
+  opaque: 'a variable whose contents we cannot see here',
+};
+
+export const sqlInjectionRule: Rule = {
+  id: 'sql-injection',
+  name: 'SQL query assembled from a built string',
+  cwe: 'CWE-89',
+  owasp: 'A05:2025 Injection',
+  severity: 'critical',
+  summary: 'The SQL query text is built from pieces; if any piece comes from outside, it can rewrite what the query does.',
+  fix:
+    'Use a parameterised query: keep the SQL fixed with placeholders and pass values separately, e.g. cursor.execute("... WHERE name = ?", (name,)).',
+  explanation:
+    'A database reads the string you give it as instructions, not as a question. ' +
+    'When a query is glued together from pieces, anything spliced in can change what ' +
+    'the query does - reading other users\' rows, bypassing a login check, or deleting ' +
+    'a table. The fix is parameterised queries: send the query and the values ' +
+    'separately, so a value can never be read as an instruction.',
+  limitations:
+    'UNVERIFIED (signature-based): we confirmed the query string was built rather than ' +
+    'written literally. We did NOT confirm that any part of it is attacker-controlled. ' +
+    'If every spliced value is a hard-coded constant or an internal enum, this is safe ' +
+    'and is a false positive. When the data-flow engine CAN confirm the source, the ' +
+    'finding is upgraded to flow-verified and this text is replaced by a traced path. ' +
+    'When every spliced value is PROVABLY a fixed literal - including a write in a ' +
+    'branch that cannot run, a condition decided at compile time, literals joined ' +
+    'with `+`, a Java helper reached through `new X().m()` or through a local that ' +
+    'certainly holds a `new X()` (declared once, never written again, used only as the ' +
+    'receiver of calls), a private/static method, ' +
+    'or a static method named through its class (`Utils.m()`, in this file or another, ' +
+    'when exactly one class of that full name and one method of that name exist in ' +
+    'the scan) whose returns are built from literals and parameters passed fixed ' +
+    'values, a read from a local Java map or list that returns a literal - or a local ' +
+    'name fixed where it was stored - put under that key or at that position, or a ' +
+    'dirty write that is certainly overwritten ' +
+    'before the query - the guess is withdrawn and listed as proved clean with the ' +
+    'reason, rather than reported. That proof stops at one helper level, does not ' +
+    'follow helpers outside Java or choose between overloads, does not use the ' +
+    'last-write rule in C or C++, and does not model String methods or any collection ' +
+    'other than those local maps and lists, so a value fixed by any of those is still ' +
+    'reported here. A name must be declared where the read can see it (Java, JavaScript, ' +
+    'TypeScript, Go block scoping); one declared outside the reading function counts only ' +
+    'when no other function in its file writes it, and a Java field only when it is ' +
+    'private or final; inside a helper, a field written from a parameter is input, ' +
+    'since it keeps what an EARLIER call passed. What the proof does NOT see, and so ' +
+    'can wrongly call fixed: a ' +
+    'write from ANOTHER file to a JavaScript or Python module-level name or a Go package ' +
+    'variable declared in this file; a member inherited from a superclass outside the ' +
+    'scan (a library class such as HttpServlet), which could shadow a name or supply an ' +
+    'overload; a write made by reflection (`Field.set` with setAccessible, from code ' +
+    'that never names the field); and a write made through `new Function(...)` or ' +
+    'a string handed to setTimeout. A withdrawal whose values are all plain literals ' +
+    'leaves no proved-clean record. Three rounds of an agent trying to break this proof ' +
+    'found 70 ways in; every one is fixed and kept as a test in tests/probes/, and a ' +
+    'fourth round would likely find more.',
+  shapes: ['call', 'assignment'],
+  support: {
+    javascript: {
+      status: 'implemented',
+      note: 'Covers node-postgres, mysql/mysql2, sqlite3, knex .raw, Prisma $queryRawUnsafe, Sequelize .query.',
+    },
+    typescript: {
+      status: 'implemented',
+      note: 'Same coverage as JavaScript; type annotations are ignored because a `string` type says nothing about trust.',
+    },
+    python: {
+      status: 'implemented',
+      note: 'Covers DB-API cursor.execute/executemany, SQLAlchemy text()/raw(). ORM query-builder misuse is not modelled.',
+    },
+    java: {
+      status: 'implemented',
+      note: 'Covers JDBC Statement/PreparedStatement, JPA createQuery/createNativeQuery, Spring JdbcTemplate. StringBuilder.append chains that build SQL over several statements are NOT followed: the tracer tracks variables, not the interior of a mutable object.',
+    },
+    go: {
+      status: 'implemented',
+      note: 'Covers database/sql and sqlx. Go code frequently builds SQL with fmt.Sprintf even when every value is a constant, so the signature pass is noisier here than elsewhere - the data-flow engine is what separates the real ones.',
+    },
+    php: {
+      status: 'implemented',
+      note: 'Covers PDO and mysqli in both their forms - the procedural functions (mysqli_query, pg_query) and the object methods ($pdo->query, ->prepare). `prepare` is watched on purpose: a prepared statement whose SQL was concatenated is not parameterised, it is a slower injection. NOT covered: an ORM that builds SQL inside its own package, and .blade.php / .twig templates, which are not parsed.',
+    },
+    c: {
+      status: 'implemented',
+      note:
+        'Covers the C database APIs, which are plain functions taking the statement as a bare char*: mysql_query, mysql_real_query, PQexec, sqlite3_exec, sqlite3_get_table and SQLExecDirect. The parameterised forms have DIFFERENT names (mysql_stmt_prepare, PQexecParams, sqlite3_prepare_v2) so correct code stays quiet. Queries are almost always built by sprintf into a char buffer, which the out-parameter tracking follows.',
+    },
+    cpp: {
+      status: 'implemented',
+      note:
+        'Every C entry applies unchanged, since C++ inherits the whole libc surface and real code still uses it. Namespace-qualified calls (std::system) and method calls on objects are recognised in addition.',
+    },
+  },
+  check(shape, ctx): RuleHit | null {
+    const language = ctx.language;
+
+    /* ---- Case 1: the query text is visible right at the call site ---- */
+    const call = asCall(shape);
+    if (call) {
+      if (!METHOD_SETS[language].has(call.calleeName)) return null;
+
+      for (const arg of call.args) {
+        // Only look at arguments that could BE a string. An options object
+        // `{ text: "...", values: [...] }` is a container, not a query.
+        if (!isStringBuildingExpression(arg, language)) continue;
+        const built = analyzeStringExpression(arg, language);
+        // Two conditions, both required:
+        //   1. the string was assembled, not written whole, and
+        //   2. what we CAN read of it actually looks like SQL.
+        // Condition 2 is what stops us shouting about `log("hi " + name)`.
+        if (!built.isDynamic) continue;
+        if (!looksLikeSql(built.literalText)) continue;
+        // "Assembled" from values that are all fixed literals is not assembled
+        // in any way a reader cares about. When saying so took reasoning - a
+        // branch that cannot run, a condition fixed at compile time - the
+        // withdrawal leaves a receipt, because reasoning can be wrong.
+        const argProof = constantProof(arg, built.dynamicParts, language, { staticMethod: ctx.staticMethod, javaTypeInScan: ctx.javaTypeInScan });
+        if (argProof) {
+          if (argProof.reasoned) ctx.noteClean?.('sql-injection', arg, argProof.reason);
+          continue;
+        }
+        /*
+         * A VALIDATION GUARD. `is_numeric($octet[0])` transforms nothing, so the
+         * sanitiser model never saw it - but inside the branch it guards, the
+         * value provably holds no metacharacter. This is DVWA's own fix for
+         * command injection, and reporting it was the seventh time this project
+         * punished a corrected file. See lib/guards.ts for how narrow the list is.
+         */
+        if (partsAreGuarded(arg, built.dynamicParts, language, 'sql')) continue;
+        // `${new Array(n).fill('(?,?)').join(',')}` expands to placeholders,
+        // never to data. Reporting it punishes the correct bulk-insert form.
+        if (built.dynamicParts.every((part) => expandsOnlyPlaceholders(part))) continue;
+
+        const how = MECHANISM_WORDS[built.mechanism] ?? built.mechanism;
+        return {
+          node: arg,
+          message: `SQL passed to ${call.calleeText}() is built with ${built.mechanism}`,
+          reasoning:
+            `\`${call.calleeText}()\` is a database query method. Its argument is not a ` +
+            `fixed string - it was assembled using ${how}. The literal part reads like SQL ` +
+            `("${built.literalText.replace(/\s+/g, ' ').trim().slice(0, 70)}"), and the ` +
+            `spliced-in part${built.dynamicParts.length === 1 ? ' is' : 's are'} ` +
+            `${built.dynamicParts.slice(0, 3).map((p) => `\`${p}\``).join(', ')}. ` +
+            `If any of those can be influenced by a user, they can rewrite the query.`,
+        };
+      }
+      return null;
+    }
+
+    /* ---- Case 2: SQL is built into a variable first ----
+     * `const sql = "SELECT ... " + id;` then later `db.query(sql)`.
+     * The SIGNATURE pass cannot connect those two statements - that is data-flow
+     * analysis, and the taint engine does it now. This branch stays as the
+     * fallback for everything the tracer could not confirm: no recognised
+     * source, a value arriving from another file, a framework we do not model.
+     * When the tracer DOES confirm it, the verified finding supersedes this one
+     * automatically, so the two never both appear.                          */
+    const assignment = asAssignment(shape);
+    if (assignment) {
+      // The scope gate. Without it, assigning a large object literal to a
+      // variable let every string inside it merge into one fake "query".
+      // This is the check that stopped Defuse reporting its own rule files.
+      if (!isStringBuildingExpression(assignment.value, language)) return null;
+      const built = analyzeStringExpression(assignment.value, language);
+      if (!built.isDynamic) return null;
+      if (!looksLikeSql(built.literalText)) return null;
+      const buildProof = constantProof(assignment.value, built.dynamicParts, language, { staticMethod: ctx.staticMethod, javaTypeInScan: ctx.javaTypeInScan });
+      if (buildProof) {
+        if (buildProof.reasoned) ctx.noteClean?.('sql-injection', assignment.node, buildProof.reason);
+        return null;
+      }
+      if (partsAreGuarded(assignment.value, built.dynamicParts, language, 'sql')) return null;
+      if (built.dynamicParts.every((part) => expandsOnlyPlaceholders(part))) return null;
+
+      return {
+        node: assignment.node,
+        severity: 'high',
+        message: `SQL string \`${assignment.targetName}\` is built with ${built.mechanism}`,
+        reasoning:
+          `\`${assignment.targetName}\` is assigned a string that reads like SQL and was ` +
+          `assembled using ${MECHANISM_WORDS[built.mechanism] ?? built.mechanism}. ` +
+          `The tracer did not confirm that this variable reaches a database call, so ` +
+          `this is reported as dangerous construction, not as a confirmed injection.`,
+        limitations:
+          'UNVERIFIED (signature-based): we saw SQL text being assembled. We did NOT verify ' +
+          'that it reaches a query method, and we did NOT verify that any part is ' +
+          'attacker-controlled. The data-flow engine ran and could not confirm either step ' +
+          'here - most often because no recognised source feeds it, or the value comes from ' +
+          'another file.',
+      };
+    }
+
+    return null;
+  },
+};

package/src/rules/ssrf.ts

@@ -0,0 +1,118 @@
+/**
+ * SERVER-SIDE REQUEST FORGERY - SSRF  (CWE-918, OWASP A01:2025 - Broken Access Control)
+ *
+ * WHAT THE BUG IS, in plain language:
+ * Your server fetches a URL that the user chose. That sounds harmless - it is
+ * just an HTTP request - until you remember WHERE your server is standing.
+ *
+ *     const data = await fetch(req.query.target);
+ *
+ * The attacker's browser cannot reach your database, your admin panel on
+ * port 8080, or `169.254.169.254` - the cloud metadata endpoint that hands out
+ * your instance's credentials to anything inside the network. Your server can
+ * reach all three. So the attacker stops trying to get in, and asks your server
+ * to go and fetch it for them. The firewall sees a request from a trusted
+ * machine and lets it through.
+ *
+ * THE FIX is an allowlist of hosts, not a blocklist. Blocklists lose, always:
+ * `localhost` has `127.0.0.1`, `127.1`, `0.0.0.0`, `[::1]`, `2130706433`, a
+ * DNS name that resolves to loopback, and a redirect from a public host to a
+ * private one. Decide the small set of hosts you MEANT to talk to, resolve the
+ * URL, and check membership - then fetch.
+ *
+ * ============================================================================
+ * WHY THIS RULE HAS NO SIGNATURE PASS
+ * ============================================================================
+ * Every one of the other rules can say something useful from shape alone: a
+ * query built by concatenation is suspicious whatever flows into it. This one
+ * cannot. "This code makes an HTTP request" is not a finding - it is what
+ * servers do all day, and a signature pass here would report every API client,
+ * every webhook, every health check in the codebase.
+ *
+ * The finding only exists when the URL is attacker-chosen, and that is a
+ * data-flow question, not a pattern. So `check()` deliberately returns null
+ * always, and every SSRF finding this tool produces is flow-verified with a
+ * printed path. It is the first rule where "we cannot say anything without the
+ * tracer" is the honest answer rather than a limitation to apologise for.
+ */
+
+import { type Rule, type RuleHit } from './contract.js';
+
+export const ssrfRule: Rule = {
+  id: 'ssrf',
+  name: 'Server fetches a URL the user chose',
+  cwe: 'CWE-918',
+  owasp: 'A01:2025 Broken Access Control',
+  severity: 'high',
+  summary: 'The server fetches a URL the request may choose, so an attacker could make it reach internal systems.',
+  fix:
+    'Only fetch hosts on an allowlist, checked after the URL is resolved, and do not follow redirects off it.',
+  explanation:
+    'Your server sits inside the network. It can reach the database, the admin ' +
+    'panel, and the cloud metadata endpoint that hands out instance credentials - ' +
+    'and the attacker\'s browser cannot. When the URL your server fetches is chosen ' +
+    'by a request, the attacker stops trying to get past the firewall and simply ' +
+    'asks your server to fetch the thing for them. The fix is an allowlist of hosts ' +
+    'you meant to talk to, checked after resolving the URL. A blocklist loses: ' +
+    'localhost is also 127.1, 0.0.0.0, [::1], 2130706433, a DNS name pointing at ' +
+    'loopback, and a redirect from a public host to a private one.',
+  limitations:
+    'FLOW-VERIFIED ONLY: this rule has no pattern pass, because "makes an HTTP ' +
+    'request" describes almost every server and would report every API client in ' +
+    'the codebase. A finding here always comes from a traced path from a request ' +
+    'value to the fetch. Only one that can choose the DESTINATION is proven: a value ' +
+    'spliced in after a fixed start of the address (`https://host/path/`, `${base}/`, ' +
+    '`./`), or one read from a browser-only source (the address bar, browser storage), ' +
+    'cannot send the request to a server the attacker picks, and is reported as to ' +
+    'review with that reason instead. DELIBERATE GAP: we cannot see a host allowlist. Code that ' +
+    'correctly resolves the URL and checks the hostname against a fixed set is ' +
+    'still reported, because recognising a correct allowlist means understanding ' +
+    'what the check compares and what it does on failure - which is beyond what ' +
+    'this engine models. Treat an SSRF finding as "confirm the host check", not as ' +
+    '"this is definitely exploitable". A REDIRECT from an allowed host to an ' +
+    'internal one is invisible to any static tool, allowlist or not.',
+  shapes: ['call'],
+  support: {
+    javascript: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers http/https get and request, fetch, axios, got, node-fetch and request. NOT covered: a URL assembled inside an options object (fetch({url: dirty})) - we read the URL argument positionally.',
+    },
+    typescript: {
+      status: 'implemented',
+      note: 'Data-flow only. Identical to JavaScript.',
+    },
+    python: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers requests (get/post/put/delete/head/request), urllib.request.urlopen and httpx. NOT covered: aiohttp sessions, where the URL is passed to a method on a session object we do not model.',
+    },
+    java: {
+      status: 'partial',
+      note: 'PARTIAL, data-flow only. Covers new URL(x), URI.create(x), HttpRequest.newBuilder(x), and RestTemplate getForObject/getForEntity/postForObject/exchange on a receiver named or typed RestTemplate (or `rest`). The URL or URI being built is the sink, so new URL(x) used only to read its host is reported too. NOT covered: new URI(x) on its own, HttpRequest.newBuilder().uri(x), WebClient, OkHttp, Apache HttpClient, and a URL held in an object field.',
+    },
+    php: {
+      status: 'implemented',
+      note: 'Data-flow only. Covers file_get_contents, fopen, curl_setopt with CURLOPT_URL, and curl_init with a URL argument. Note that file_get_contents doubles as a file reader, so a finding here may be path traversal wearing a URL\'s clothes - both are worth the same second look.',
+    },
+    go: {
+      status: 'partial',
+      note: 'PARTIAL, data-flow only. Covers the net/http package functions http.Get, http.Post, http.Head, http.PostForm, http.NewRequest and http.NewRequestWithContext. NOT covered: the same methods on a client (client.Get(u), http.DefaultClient.Get(u)), because the receiver is not `http`, and third-party clients such as resty.',
+    },
+    c: {
+      status: 'not-implemented',
+      note:
+        'libcurl is how C makes outbound requests - curl_easy_setopt(handle, CURLOPT_URL, url) - and it is NOT modelled: the URL is one argument of a variadic setter whose meaning depends on the option constant next to it, which this engine does not read. Server-side request forgery written with libcurl is missed entirely.',
+    },
+    cpp: {
+      status: 'not-implemented',
+      note:
+        'Not implemented. C++ code reaches the network through libcurl (not modelled - the URL is one argument of a variadic setter), or through a framework HTTP client such as cpp-httplib or Boost.Beast, none of which are in the sink tables.',
+    },
+  },
+  /*
+   * Deliberately silent. See the header: there is no honest pattern for this
+   * bug, only a flow. The taint engine emits every finding for this rule id.
+   */
+  check(): RuleHit | null {
+    return null;
+  },
+};