docs: update inline references and improve XSS detection in Java servlet writers, refactor matchers for clarity and extend sanitizer support

tests/eval_corpus/tabulate.py

@@ -75,6 +75,15 @@ _CAP_BIT_TABLE = [
     (1 << 18, "xss"),              # SSTI (template_injection); also covers XSS sinks
     (1 << 19, "xxe"),
     (1 << 20, "prototype_pollution"),
+    # HTML_ESCAPE (1<<1) is the universal reflected-XSS *sink* cap across every
+    # language (`grep 'Sink(Cap::HTML_ESCAPE)' src/labels/` — PHP echo, JS
+    # innerHTML, Java servlet writers, etc.); the same bit is the html-escape
+    # *sanitizer* cap, so a finding only carries it as a sink when an un-encoded
+    # tainted value reached an HTML output.  Placed LAST so any higher-priority
+    # sink bit (SQL_QUERY, FILE_IO, ...) on the same finding wins; a finding
+    # carrying only HTML_ESCAPE is reflected XSS.  Without this, every
+    # taint-based reflected-XSS finding mis-buckets to "other".
+    (1 << 1, "xss"),
 ]
 
 # Static lens (see --static): SHELL_ESCAPE (1<<2) is the command-injection sink

tests/fixtures/fp_guards/ast_layer_a_java_call_args/expectations.json

@@ -1,7 +1,7 @@
 {
   "required_findings": [
     { "id_prefix": "java.reflection.class_forname", "min_count": 1 },
-    { "id_prefix": "java.crypto.weak_digest", "min_count": 1 }
+    { "id_prefix": "java.crypto.weak_algorithm", "min_count": 1 }
   ],
   "forbidden_findings": [],
   "noise_budget": {

tests/fixtures/real_world/java/mixed/deser_cmdi.expect.json

@@ -45,14 +45,14 @@
       "notes": "Runtime.getRuntime().exec(command) with deserialized input; AST pattern correctly matches"
     },
     {
-      "rule_id": "java.xss.getwriter_print",
+      "rule_id": "taint-unsanitised-flow",
       "severity": "MEDIUM",
       "must_not_match": true,
       "line_range": [
         11,
         11
       ],
-      "notes": "response.getWriter().println(\"Done\") — constant string, Layer B suppresses (regression guard)"
+      "notes": "response.getWriter().println(\"Done\") — constant string, must NOT raise reflected-XSS (Cap::HTML_ESCAPE). Regression guard retargeted from the retired java.xss.getwriter_print AST pattern to the taint sink that now owns reflected XSS."
     },
     {
       "rule_id": "taint-unsanitised-flow",

tests/fixtures/real_world/java/mixed/servlet_full.expect.json

@@ -80,14 +80,14 @@
       "notes": "source at 11:9 (request.getParameter(\"input\")) flows through SQL query (line 17) into result set output at out.println(rs.getString(1)); second-order taint via tainted query results"
     },
     {
-      "rule_id": "java.xss.getwriter_print",
+      "rule_id": "taint-unsanitised-flow",
       "severity": "MEDIUM",
       "must_not_match": true,
       "line_range": [
         26,
         26
       ],
-      "notes": "response.getWriter().println(new String(data)) — file-read data, Layer B suppresses (regression guard)"
+      "notes": "response.getWriter().println(new String(data)) — file-read bytes, not reflected request input, must NOT raise reflected-XSS (Cap::HTML_ESCAPE). Regression guard retargeted from the retired java.xss.getwriter_print AST pattern to the taint sink that now owns reflected XSS."
     }
   ]
 }

tests/fixtures/real_world/java/taint/catch_param_sink.expect.json

@@ -9,15 +9,7 @@
       "must_match": true,
       "line_range": [5, 12],
       "evidence_contains": [],
-      "notes": "catch(Exception e) binds e as tainted; e flows to println sink via catch parameter"
-    },
-    {
-      "rule_id": "java.xss.getwriter_print",
-      "severity": "MEDIUM",
-      "must_match": true,
-      "line_range": [10, 10],
-      "evidence_contains": [],
-      "notes": "response.getWriter().println() in catch block — AST pattern detects potential XSS via error response"
+      "notes": "catch(Exception e) binds e as tainted; e flows to response.getWriter().println at line 10 — reflected XSS via error response. Replaces the retired java.xss.getwriter_print AST pattern: reflected XSS is now a taint sink (Sink(Cap::HTML_ESCAPE)), so this is taint-confirmed rather than flagged on every writer call."
     }
   ]
 }

tests/fixtures/real_world/java/taint/try_catch_sqli.expect.json

@@ -19,21 +19,13 @@
       "evidence_contains": [],
       "notes": "AST pattern detects executeQuery with string concatenation — SQL injection"
     },
-    {
-      "rule_id": "java.xss.getwriter_print",
-      "severity": "MEDIUM",
-      "must_match": true,
-      "line_range": [12, 12],
-      "evidence_contains": [],
-      "notes": "response.getWriter().println() with user input — reflected XSS via error response"
-    },
     {
       "rule_id": "taint-unsanitised-flow",
       "severity": "HIGH",
       "must_match": true,
       "line_range": [7, 12],
       "evidence_contains": [],
-      "notes": "request.getParameter flows to response.getWriter().println — user input reflected in error response"
+      "notes": "request.getParameter flows to response.getWriter().println at line 12 — user input reflected in error response. Replaces the retired java.xss.getwriter_print AST pattern: reflected XSS is now a taint sink (Sink(Cap::HTML_ESCAPE)), taint-confirmed rather than flagged on every writer call."
     }
   ]
 }