~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""Security boundary tests for the `|safe` usage in help_macros.html.
``help_tip(text, variant='info')`` (components/help_macros.html) renders
``{{ text|safe }}`` which DISABLES Jinja autoescaping for its ``text``
argument. The only reason this is acceptable is that every current call site
passes a static developer-written string literal (e.g. pages/benchmark.html,
pages/collection_details.html, pages/collections.html). If a call site ever
passes a runtime/user-derived variable, it becomes a stored/reflected XSS
hole.
These tests lock that boundary from both sides:
1. Static call-site guard: parse every ``*.html`` under the web templates dir
with the production Jinja environment and walk the syntax tree, so Jinja
comments, ``{% raw %}`` text and the HTML around the tags are never
mistaken for calls. Every call of the macro must pass ``text`` (first
positional argument, or the ``text=`` keyword) as quoted string literals,
optionally joined with ``~``. That holds whatever name the macro is called
by:
* the bare name ``help_tip``;
* an alias, ``{% from "components/help_macros.html" import help_tip as
tip %}`` then ``tip(...)``;
* a namespace, ``{% import "components/help_macros.html" as hm %}`` then
``hm.help_tip(...)`` or ``hm["help_tip"](...)``.
Aliases and namespaces are collected from every template, because an
included template sees the names its includer imported. An import whose
template name is computed at runtime counts as an import of
help_macros.html. Calls inside another macro's body are checked like any
other call; only the ``{% macro help_tip %}`` definition itself is not a
call. Any other use of the macro or of such a namespace, such as
``{% set t = help_tip %}``, passing it to another macro, or
``hm|attr("help_tip")``, is reported too, because the call it leads to
cannot be checked. So is a call that passes ``*args`` or ``**kwargs``.
2. Render-behavior sanity: through the real Jinja2 environment used at
runtime (``local_deep_research.web.template_config.templates.env`` —
same ``FileSystemLoader`` and ``autoescape`` configuration the
production templates use), prove that a literal keeps its trusted
HTML, that a sibling macro (``tooltip``) autoescapes a variable
carrying ``<script>``, and that ``help_tip`` would NOT escape such a
variable — which is exactly why the static guard above is the real
defense.
Out of scope but noted: base.html lines 16/18 use
``{{ get_themes_json()|safe }}`` / ``{{ get_theme_metadata()|safe }}`` —
server-controlled JSON helpers, not user-derived input.
"""
from functools import lru_cache
from pathlib import Path
from typing import NamedTuple
import pytest
from jinja2 import nodes
from jinja2.exceptions import TemplateNotFound
from jinja2.loaders import split_template_path
from tests.test_utils import add_src_to_path
add_src_to_path()
REPO_ROOT = Path(__file__).resolve().parents[2]
TEMPLATES_DIR = REPO_ROOT / "src" / "local_deep_research" / "web" / "templates"
MACRO_NAME = "help_tip"
MACRO_FILE = "components/help_macros.html"
# The macro parameter rendered with |safe.
TEXT_PARAMETER = "text"
class HelpTipSite(NamedTuple):
"""One place a template defines, calls or otherwise uses ``help_tip``."""
path: Path
line: int
is_definition: bool
is_safe: bool
detail: str
@lru_cache(maxsize=1)
def _jinja_env():
"""The production environment, so the guard parses what the app parses."""
from local_deep_research.web.template_config import templates
return templates.env
def _parse(path, templates_dir):
source = path.read_text(encoding="utf-8")
name = path.relative_to(templates_dir).as_posix()
return _jinja_env().parse(source, name=name, filename=str(path)), source
def _may_name_macro_file(template):
"""True if an import's template expression can resolve to MACRO_FILE.
A constant name is compared after the loader's own normalization
(``split_template_path``), so ``./components/help_macros.html`` matches.
A name computed at runtime might be MACRO_FILE, so it counts as one.
"""
if not isinstance(template, nodes.Const):
return True
if not isinstance(template.value, str):
return False
try:
return "/".join(split_template_path(template.value)) == MACRO_FILE
except TemplateNotFound:
# A `..` segment, which the loader refuses to load.
return False
def _collect_bindings(trees):
"""Names bound to the macro, and to MACRO_FILE namespaces, in any tree."""
aliases = {MACRO_NAME}
namespaces = set()
for tree in trees:
for node in tree.find_all((nodes.Import, nodes.FromImport)):
if not _may_name_macro_file(node.template):
continue
if isinstance(node, nodes.Import):
namespaces.add(node.target)
continue
for name in node.names:
imported, alias = (
name if isinstance(name, tuple) else (name, name)
)
if imported == MACRO_NAME:
aliases.add(alias)
return aliases, namespaces
def _namespace_member(node, namespaces):
"""For ``ns.x`` or ``ns["x"]`` on a tracked namespace: ``x``.
Returns ``""`` for a subscript whose key is not a constant string (the
member cannot be known) and ``None`` when ``node`` is no such lookup.
"""
if not isinstance(node, (nodes.Getattr, nodes.Getitem)):
return None
if not (
isinstance(node.node, nodes.Name)
and node.node.ctx == "load"
and node.node.name in namespaces
):
return None
if isinstance(node, nodes.Getattr):
return node.attr
if isinstance(node.arg, nodes.Const) and isinstance(node.arg.value, str):
return node.arg.value
return ""
def _refers_to_macro(node, aliases, namespaces):
"""True if evaluating ``node`` yields the help_tip macro (or may)."""
if isinstance(node, nodes.Name):
return node.ctx == "load" and node.name in aliases
return _namespace_member(node, namespaces) in (MACRO_NAME, "")
def _text_argument(call):
"""The node passed as ``text``, or None when it cannot be determined."""
if call.dyn_args is not None or call.dyn_kwargs is not None:
return None
if call.args:
return call.args[0]
for keyword in call.kwargs:
if keyword.key == TEXT_PARAMETER:
return keyword.value
return None
def _is_string_literal(node):
"""True iff ``node`` is quoted string literals joined only by ``~``.
Jinja's parser turns adjacent literals into one ``Const`` and ``~`` into
``Concat``. Variables, attribute lookups, calls, filters, tests,
conditionals, arithmetic and non-string constants are all other node
types, so a value spliced between two literals is rejected too.
"""
if isinstance(node, nodes.Const):
return isinstance(node.value, str)
if isinstance(node, nodes.Concat):
return all(_is_string_literal(part) for part in node.nodes)
return False
def _walk(node, parent=None):
"""Yield ``(node, parent)`` for ``node`` and every node below it."""
yield node, parent
for child in node.iter_child_nodes():
yield from _walk(child, node)
def _sites_in_tree(tree, source, rel_path, aliases, namespaces):
lines = source.splitlines()
def _site(node, is_definition, is_safe, what):
text = (
lines[node.lineno - 1].strip() if node.lineno <= len(lines) else ""
)
return HelpTipSite(
rel_path,
node.lineno,
is_definition,
is_safe,
f"{what}: {text[:100]}",
)
for node, parent in _walk(tree):
if isinstance(node, nodes.Macro) and node.name == MACRO_NAME:
yield _site(node, True, True, "definition")
elif isinstance(node, nodes.Call) and _refers_to_macro(
node.node, aliases, namespaces
):
argument = _text_argument(node)
is_safe = argument is not None and _is_string_literal(argument)
yield _site(node, False, is_safe, "call")
elif _refers_to_macro(node, aliases, namespaces) and not (
isinstance(parent, nodes.Call) and parent.node is node
):
yield _site(node, False, False, "macro used without a call")
elif (
isinstance(node, nodes.Name)
and node.ctx == "load"
and node.name in namespaces
and _namespace_member(parent, namespaces) is None
):
yield _site(node, False, False, "namespace used without a lookup")
def _scan_help_tip_calls(templates_dir):
"""Yield a ``HelpTipSite`` for every definition, call and other use of
the macro in the ``*.html`` templates under ``templates_dir``."""
parsed = [
(path, *_parse(path, templates_dir))
for path in sorted(templates_dir.rglob("*.html"))
]
aliases, namespaces = _collect_bindings(tree for _, tree, _ in parsed)
for path, tree, source in parsed:
yield from _sites_in_tree(
tree, source, path.relative_to(templates_dir), aliases, namespaces
)
def _find_violations(templates_dir):
"""file:line strings for every use whose ``text`` is not a literal."""
return [
f" {site.path}:{site.line} -> {site.detail}"
for site in _scan_help_tip_calls(templates_dir)
if not site.is_definition and not site.is_safe
]
class TestHelpTipCallSitesAreStaticLiterals:
"""The static trust-boundary guard for `help_tip(...|safe)`."""
def test_all_call_sites_pass_string_literals(self):
"""Every help_tip() call must pass a quoted literal as `text`."""
violations = _find_violations(TEMPLATES_DIR)
assert not violations, (
"help_tip() renders its `text` argument via {{ text|safe }} "
"(Jinja autoescape DISABLED). Every call site must pass a static "
"developer-written string literal; passing a runtime or "
"user-derived variable is a stored/reflected XSS. "
"Violations:\n" + "\n".join(violations)
)
def test_scan_actually_finds_call_sites(self):
"""Guard against a silently broken scanner passing vacuously."""
sites = list(_scan_help_tip_calls(TEMPLATES_DIR))
call_sites = [s for s in sites if not s.is_definition]
definitions = [s for s in sites if s.is_definition]
assert len(call_sites) >= 5, (
f"Expected at least 5 help_tip() call sites under "
f"{TEMPLATES_DIR}, found {len(call_sites)} — scanner broken?"
)
# The single allowed definition lives in the macro file itself.
assert len(definitions) == 1
assert definitions[0].path.as_posix() == MACRO_FILE
def test_scanner_detects_synthetic_violations(self, tmp_path):
"""Self-test: the scanner must accept literals (including tricky
ones) and reject every variable-derived or untraceable form."""
cases = [
# (template body, is_violation)
('{{ help_tip("<strong>Tip:</strong> static text") }}', False),
("{{ help_tip('single quoted') }}", False),
# Parens, % and commas inside the literal must not end the arg.
(
'{{ help_tip("<strong>A</strong> (<50%, see foo) ok") }}',
False,
),
# Multi-line literal-only concatenation is harmless.
(
'{{ help_tip("<strong>Long</strong> text"\n ~ " more") }}',
False,
),
# `text` passed by keyword is checked, not the first argument.
("{{ help_tip(variant='warning', text='literal') }}", False),
("{{ help_tip(variant='warning', text=user_text) }}", True),
# Variable call sites — live XSS if ever shipped.
("{{ help_tip(user_text) }}", True),
("{{ help_tip(user_text|safe) }}", True),
("{{ help_tip(user_text|truncate(50)) }}", True),
('{{ help_tip("<b>" ~ user_text) }}', True),
("{{ help_tip(prefix ~ user_text) }}", True),
("{% if x %}{{ help_tip(query_result) }}{% endif %}", True),
# Regression (parent review): a variable sandwiched between
# literals defeats any first/last-quote heuristic — only a full
# literal-only `~` concatenation parse catches it.
(
'{{ help_tip("<b>" ~ user_text ~ "</b>") }}',
True,
),
('{{ help_tip("prefix" ~ user.name ~ "suffix") }}', True),
("{{ help_tip(trusted_fn()) }}", True),
('{{ help_tip("count: " ~ 42) }}', True),
('{{ help_tip("a" ~ user_text|safe) }}', True),
("{{ help_tip(*parts) }}", True),
("{{ help_tip(**options) }}", True),
("{% call help_tip(user_text) %}{% endcall %}", True),
# Escaped quotes inside literals keep concatenation literal-only.
(
'{{ help_tip("she said \\"hi\\"" ~ " ok") }}',
False,
),
# Regression (gate review): a namespace import and an import
# alias call the same |safe macro under another name.
(
'{% import "' + MACRO_FILE + '" as hm %}'
"{{ hm.help_tip(user_text) }}",
True,
),
(
'{% from "' + MACRO_FILE + '" import help_tip as ht %}'
"{{ ht(user_text) }}",
True,
),
(
'{% import "' + MACRO_FILE + '" as hm %}'
"{{ hm['help_tip'](user_text) }}",
True,
),
(
'{% from "./' + MACRO_FILE + '" import help_tip as ht %}'
"{{ ht(user_text) }}",
True,
),
(
'{% import "' + MACRO_FILE + '" as hm with context %}'
"{{ hm.help_tip(user_text) }}",
True,
),
# The same forms with literals, and other macros reached through
# the namespace, stay clean.
(
'{% import "' + MACRO_FILE + '" as hm %}'
'{{ hm.help_tip("literal") }}{{ hm.tooltip(label, tip) }}',
False,
),
(
'{% from "' + MACRO_FILE + '" import help_tip as ht %}'
"{{ ht('literal') }}",
False,
),
# The macro or its namespace escaping into something the scan
# cannot follow is reported, whatever is eventually passed.
(
'{% from "' + MACRO_FILE + '" import help_tip %}'
"{% set t = help_tip %}{{ t(user_text) }}",
True,
),
(
'{% import "' + MACRO_FILE + '" as hm %}'
"{% set t = hm.help_tip %}{{ t(user_text) }}",
True,
),
(
'{% import "' + MACRO_FILE + '" as hm %}'
"{% set ns2 = hm %}{{ ns2.help_tip(user_text) }}",
True,
),
(
'{% import "' + MACRO_FILE + '" as hm %}'
"{{ (hm|attr('help_tip'))(user_text) }}",
True,
),
("{{ render_with(help_tip, user_text) }}", True),
(
'{% import "' + MACRO_FILE + '" as hm %}'
"{{ hm[member](user_text) }}",
True,
),
# An import whose template name is computed at runtime may be
# the macro file.
(
"{% import macro_file as hm %}{{ hm.help_tip(user_text) }}",
True,
),
(
"{% from macro_file import help_tip as ht %}{{ ht(user_text) }}",
True,
),
# A call inside another macro's body is a call like any other.
(
"{% macro wrap(x) %}{{ help_tip(x) }}{% endmacro %}",
True,
),
(
"{% macro wrap() %}{{ help_tip('literal') }}{% endmacro %}",
False,
),
# Raw blocks and comments are template text, not calls.
("{% raw %}{{ help_tip(user_text) }}{% endraw %}", False),
("{# {{ help_tip(user_text) }} #}", False),
]
for body, expect_violation in cases:
page = tmp_path / "pages" / "synthetic.html"
page.parent.mkdir(parents=True, exist_ok=True)
page.write_text(body, encoding="utf-8")
violations = _find_violations(tmp_path)
assert bool(violations) is expect_violation, (
f"Scanner misclassified:\n{body}\nviolations: {violations}"
)
def test_scanner_follows_aliases_into_included_templates(self, tmp_path):
"""An included template sees its includer's imports, so an alias
bound in one template is tracked in every template."""
pages = tmp_path / "pages"
pages.mkdir(parents=True, exist_ok=True)
(pages / "outer.html").write_text(
'{% from "' + MACRO_FILE + '" import help_tip as ht %}'
'{% include "pages/inner.html" %}',
encoding="utf-8",
)
(pages / "inner.html").write_text(
"{{ ht(user_text) }}", encoding="utf-8"
)
violations = _find_violations(tmp_path)
assert len(violations) == 1
assert "inner.html:1" in violations[0]
def test_scanner_exempts_definition_and_comments(self, tmp_path):
"""The macro definition and Jinja-commented calls are exempt."""
macros = tmp_path / MACRO_FILE
macros.parent.mkdir(parents=True, exist_ok=True)
macros.write_text(
"{% macro help_tip(text, variant='info') %}"
"<span>{{ text|safe }}</span>"
"{%- endmacro %}\n",
encoding="utf-8",
)
page = tmp_path / "pages" / "uses.html"
page.parent.mkdir(parents=True, exist_ok=True)
page.write_text(
"{# {{ help_tip(commented_out_var) }} #}\n"
"{% macro other_macro() %}{% endmacro %}\n",
encoding="utf-8",
)
sites = list(_scan_help_tip_calls(tmp_path))
assert [s.is_definition for s in sites] == [True]
assert _find_violations(tmp_path) == []
class TestHelpTipRenderBoundary:
"""Render-behavior proof through the real Jinja2 environment and
template loader the app uses in production (mirrors
tests/security/test_xss_prevention.py).
Post-FastAPI-migration (#3299), templates are rendered through
``local_deep_research.web.template_config.templates`` — a
``fastapi.templating.Jinja2Templates`` instance whose ``.env`` is a
real ``jinja2.Environment`` backed by a ``FileSystemLoader`` pointed
at the same template directory used at runtime, with the same
``autoescape`` policy (``jinja2.select_autoescape()``). Rendering
through ``templates.env`` exercises that exact loader/autoescape
configuration directly, without booting the FastAPI app or a test
client.
"""
@pytest.fixture(scope="module")
def jinja_env(self):
from local_deep_research.web.template_config import templates
return templates.env
def test_literal_keeps_trusted_html(self, jinja_env):
"""help_tip with a developer literal keeps its trusted markup."""
template = jinja_env.from_string(
'{% from "' + MACRO_FILE + '" import ' + MACRO_NAME + " %}"
"{{ " + MACRO_NAME + '("<strong>Tip:</strong> trusted text") }}'
)
rendered = template.render()
assert "<strong>Tip:</strong>" in rendered
def test_sibling_macro_autoescapes_variable(self, jinja_env):
"""Control: `tooltip` (no |safe) escapes a variable carrying markup."""
template = jinja_env.from_string(
'{% from "' + MACRO_FILE + '" import tooltip %}'
"{{ tooltip(payload, payload) }}"
)
rendered = template.render(payload="<script>alert('XSS')</script>")
assert "<script>" not in rendered
assert "<script>" in rendered
def test_help_tip_would_not_escape_untrusted_input(self, jinja_env):
"""Documents WHY the static call-site guard is the real defense:
autoescape is active in this environment, and |safe still lets a
runtime variable through untouched."""
template = jinja_env.from_string(
'{% from "' + MACRO_FILE + '" import ' + MACRO_NAME + " %}"
"{{ " + MACRO_NAME + "(payload) }}"
)
rendered = template.render(payload="<script>alert('XSS')</script>")
assert "<script>alert('XSS')</script>" in rendered