From 7b8d823b55ecbbc9ecef5718078646aa20350f22 Mon Sep 17 00:00:00 2001
From: ChethanUK <chethanuk@outlook.com>
Date: Wed, 15 Jul 2026 10:05:47 +0200
Subject: [PATCH] feat(rules): add FreeMarker (.ftl/.ftlh/.ftlx) review support

Adds the FreeMarker template extensions to the supported-file-type
allowlist and introduces a freemarker.md system rule layer (glob
**/*.{ftl,ftlh,ftlx}) covering SSTI (?new()/Execute/ObjectConstructor,
?eval/?api), output escaping vs the ftlh/ftlx auto-escape formats,
null/missing-value handling, logic-in-template smells, include/import
hygiene, and locale-sensitive formatting. Extends the allowlist and
system-rules tests and documents the new mapping in the en/ja/zh pages.

Closes #371
---
 internal/config/allowlist/allowed_ext_test.go |  6 ++++
 .../allowlist/supported_file_types.json       |  3 ++
 internal/config/rules/rule_docs/freemarker.md | 36 +++++++++++++++++++
 internal/config/rules/system_rules.json       |  1 +
 internal/config/rules/system_rules_test.go    |  4 +++
 pages/src/content/docs/en/review-rules.md     |  1 +
 pages/src/content/docs/ja/review-rules.md     |  1 +
 pages/src/content/docs/zh/review-rules.md     |  1 +
 8 files changed, 53 insertions(+)
 create mode 100644 internal/config/rules/rule_docs/freemarker.md

diff --git a/internal/config/allowlist/allowed_ext_test.go b/internal/config/allowlist/allowed_ext_test.go
index 79b9891a..0d128468 100644
--- a/internal/config/allowlist/allowed_ext_test.go
+++ b/internal/config/allowlist/allowed_ext_test.go
@@ -22,6 +22,12 @@ func TestIsAllowedExt(t *testing.T) {
 		{".ETS", true},
 		{".json5", true},
 		{".JSON5", true},
+		{".ftl", true},
+		{".FTL", true},
+		{".ftlh", true},
+		{".FTLH", true},
+		{".ftlx", true},
+		{".FTLX", true},
 		{".txt", false},
 		{".md", false},
 		{".png", false},
diff --git a/internal/config/allowlist/supported_file_types.json b/internal/config/allowlist/supported_file_types.json
index 2c75bded..69b9b416 100644
--- a/internal/config/allowlist/supported_file_types.json
+++ b/internal/config/allowlist/supported_file_types.json
@@ -43,6 +43,9 @@
   ".less",
   ".html",
   ".htm",
+  ".ftl",
+  ".ftlh",
+  ".ftlx",
   ".astro",
   ".vue",
   ".svelte",
diff --git a/internal/config/rules/rule_docs/freemarker.md b/internal/config/rules/rule_docs/freemarker.md
new file mode 100644
index 00000000..07e1d040
--- /dev/null
+++ b/internal/config/rules/rule_docs/freemarker.md
@@ -0,0 +1,36 @@
+#### Obvious Typos or Spelling Errors
+- Spelling errors in macro names, assigned variable names, or user-facing text at their declaration sites; do not report at reference sites
+- Typos in `<#assign>`/`<#macro>`/`<#function>` names that surface only at render time (`InvalidReferenceException` / macro not found), or that are silently masked by `!` defaults and `??` guards
+
+#### Output Escaping and XSS
+- Interpolations (`${...}`) that reach HTML without escaping: flag only when auto-escaping is not already active — i.e. the template lacks `<#ftl output_format="HTML">` (FreeMarker 2.3.24+) AND does not use the `.ftlh`/`.ftlx` extension (which auto-activate HTML/XML escaping via `recognize_standard_file_extensions`, on by default since 2.3.24) — and the value is not passed through `?html`/`?url`/`?js_string` appropriate to its sink (HTML body, attribute, URL, JS, CSS)
+- Explicit `?no_esc` or `<#noautoesc>` on values that carry user-controlled data — treat as a high-risk escape hatch; flag unless the source is clearly trusted or already sanitized
+- Escaping with the wrong context builtin (e.g. `?html` for a value placed inside a URL or inline `<script>`)
+- Do not report missing `?html` when auto-escaping is active for the file's output format and no override disables it
+
+#### Template Injection / RCE (SSTI)
+- User-controlled data concatenated into template source, or templates whose name/body derives from request input (`<#include>`, `<#import>`, `.get_optional_template(userValue)`) — enables server-side template injection
+- Use of the `?new()` builtin to instantiate `TemplateModel` classes, especially `freemarker.template.utility.Execute` or `ObjectConstructor` — arbitrary code execution; flag unless the class is a vetted internal type
+- `?api` / `?eval` on untrusted input, or exposing raw `Class`/`ClassLoader`/`ProcessBuilder`-reachable objects into the data model
+- Templates authored from untrusted input without a restricted `TemplateClassResolver` (e.g. `SAFER_RESOLVER`) — call it out as a hardening gap
+
+#### Null and Missing-Value Handling
+- Interpolations or directive arguments on possibly-absent values without `!` (default) or `??` (existence) — missing values raise `InvalidReferenceException` at render time
+- Overuse of a bare `!` that masks genuinely-required data with a silent empty string; prefer an explicit default (`value!"fallback"`) or an `<#if value??>` guard where absence is meaningful
+- `!` precedence mistakes in expressions (`a.b.c!` guards only the last step); confirm the intended nullable segment
+
+#### Logic-in-Template Smells
+- Business logic, data-access, or non-trivial computation embedded in templates that belongs in the controller/model layer
+- Deeply nested `<#if>`/`<#list>` or duplicated conditional blocks that indicate the view is doing the model's job
+- `<#assign>` used to build state that should have been prepared before rendering
+
+#### Macro and Include Hygiene
+- `<#include>` where `<#import>` (namespaced) is intended, causing global-namespace pollution or accidental variable shadowing
+- Macros/functions defined but never called, or duplicated across templates instead of shared via a common library template
+- Relative template names passed to `<#include>`/`.get_optional_template` without `?absolute_template_name` when resolution context is ambiguous
+- Missing-template failures not handled (`.get_optional_template(...).exists`) where the include is optional
+
+#### Internationalization and Locale-Sensitive Formatting
+- Numbers, dates, times, and currency emitted with locale-default formatting where a fixed machine format is required (e.g. `?string`/`?c` for numbers in URLs, JSON, or IDs) — `?c` (computer format) prevents locale-dependent thousands separators corrupting non-display output
+- Hard-coded user-facing strings that should come from a localized message/resource bundle
+- Date/number output relying on an implicit locale/timezone without confirming the render environment sets them intentionally
diff --git a/internal/config/rules/system_rules.json b/internal/config/rules/system_rules.json
index b16518ff..5d0d4b14 100644
--- a/internal/config/rules/system_rules.json
+++ b/internal/config/rules/system_rules.json
@@ -12,6 +12,7 @@
     ".github/**/*.{yaml,yml}": "github_config.md",
     "**/*.{yaml,yml}": "yaml.md",
     "**/*.java": "java.md",
+    "**/*.{ftl,ftlh,ftlx}": "freemarker.md",
     "**/*.ets": "arkts.md",
     "**/*.astro": "astro.md",
     "**/*.{ts,js,tsx,jsx}": "ts_js_tsx_jsx.md",
diff --git a/internal/config/rules/system_rules_test.go b/internal/config/rules/system_rules_test.go
index cf54f3a9..6ea47ab1 100644
--- a/internal/config/rules/system_rules_test.go
+++ b/internal/config/rules/system_rules_test.go
@@ -59,6 +59,10 @@ func TestResolve_DefaultRules(t *testing.T) {
 	}{
 		{"src/main/java/com/example/foo.java", "Logic Error Detection"},
 		{"foo.java", "Logic Error Detection"},
+		{"src/main/resources/templates/email.ftl", "Template Injection"},
+		{"foo.ftl", "Template Injection"},
+		{"foo.ftlh", "Template Injection"},
+		{"foo.ftlx", "Template Injection"},
 		{"src/main/resources/mapper/usermapper.xml", "SQL Logic Error Detection"},
 		{"src/main/resources/dao/userdao.xml", "SQL Logic Error Detection"},
 		{"pom.xml", "snapshot"},
diff --git a/pages/src/content/docs/en/review-rules.md b/pages/src/content/docs/en/review-rules.md
index 33384c57..0da420c0 100644
--- a/pages/src/content/docs/en/review-rules.md
+++ b/pages/src/content/docs/en/review-rules.md
@@ -156,6 +156,7 @@ The embedded `system_rules.json` ships with these patterns (in order):
 | `.github/**/*.{yaml,yml}` | `github_config.md` — other `.github` config YAML. |
 | `**/*.{yaml,yml}` | `yaml.md` |
 | `**/*.java` | `java.md` |
+| `**/*.{ftl,ftlh,ftlx}` | `freemarker.md` — FreeMarker templates (SSTI / XSS / null handling). |
 | `**/*.ets` | `arkts.md` — ArkTS / HarmonyOS. |
 | `**/*.{ts,js,tsx,jsx}` | `ts_js_tsx_jsx.md` |
 | `**/*.{kt}` | `kotlin.md` |
diff --git a/pages/src/content/docs/ja/review-rules.md b/pages/src/content/docs/ja/review-rules.md
index bf1f8f00..56a4110e 100644
--- a/pages/src/content/docs/ja/review-rules.md
+++ b/pages/src/content/docs/ja/review-rules.md
@@ -119,6 +119,7 @@ OCR は [`bmatcuk/doublestar/v4`](https://pkg.go.dev/github.com/bmatcuk/doublest
 | `.github/**/*.{yaml,yml}` | `github_config.md`: その他の `.github` 設定 YAML。 |
 | `**/*.{yaml,yml}` | `yaml.md` |
 | `**/*.java` | `java.md` |
+| `**/*.{ftl,ftlh,ftlx}` | `freemarker.md`: FreeMarker テンプレート（SSTI / XSS / null 処理）。 |
 | `**/*.ets` | `arkts.md`: ArkTS / HarmonyOS。 |
 | `**/*.{ts,js,tsx,jsx}` | `ts_js_tsx_jsx.md` |
 | `**/*.{kt}` | `kotlin.md` |
diff --git a/pages/src/content/docs/zh/review-rules.md b/pages/src/content/docs/zh/review-rules.md
index b14ef69e..12bed5e1 100644
--- a/pages/src/content/docs/zh/review-rules.md
+++ b/pages/src/content/docs/zh/review-rules.md
@@ -140,6 +140,7 @@ OCR 用 [`bmatcuk/doublestar/v4`](https://pkg.go.dev/github.com/bmatcuk/doublest
 | `.github/**/*.{yaml,yml}` | `github_config.md`——其他 `.github` 配置 YAML。 |
 | `**/*.{yaml,yml}` | `yaml.md` |
 | `**/*.java` | `java.md` |
+| `**/*.{ftl,ftlh,ftlx}` | `freemarker.md`——FreeMarker 模板（SSTI / XSS / null 处理）。 |
 | `**/*.ets` | `arkts.md`——ArkTS / HarmonyOS。 |
 | `**/*.{ts,js,tsx,jsx}` | `ts_js_tsx_jsx.md` |
 | `**/*.{kt}` | `kotlin.md` |