bmsdna-devtools 0.25.0__tar.gz → 0.26.0__tar.gz

{bmsdna_devtools-0.25.0 → bmsdna_devtools-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.25.0
+Version: 0.26.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: pgdevkit[db]>=0.7.1
@@ -575,6 +575,41 @@ already pulled in transitively via `pgdevkit[db]`, but declared explicitly as
 the `bmsdna-devtools[lint]` extra; a clear install hint is printed (not a raw
 `ImportError`) if it's ever missing.
 
+## `bdt find-injection`
+
+Scans backend and frontend code for injection risks, and warns when a web project has no
+Content-Security-Policy.
+
+```bash
+bdt find-injection [PATHS...]            # files/folders, default: current directory
+bdt find-injection --diff [--base main]  # only files changed on this branch + uncommitted/untracked
+bdt find-injection --strict              # also fail on "review" items
+```
+
+Findings have two severities: **error** (a definite unsafe pattern, exit code 1) and **review**
+(depends on where a value comes from; listed with an instruction for an AI/human to verify, exit
+code 0 unless `--strict`).
+
+- **SQL** (Python `.execute()`): f-string / `%` / concatenation / `.format()` SQL is an error.
+  SQL from `load_sql()`, `sql.SQL`, sqlglot (`expr.sql()`, `sqlglot.*`), `cast(LiteralString, <sqlglot expr>)` (the cast is only as safe as its argument) or
+  a function in the same file annotated `-> LiteralString` is trusted; SQL from any other function
+  call is a `sql-unverified-call` review item. (`bdt lint` accepts the same trusted forms but never
+  reports unverified calls.)
+- **Other Python sinks**: `eval`/`exec`, `os.system`, `subprocess(..., shell=True)`, `yaml.load`
+  without a safe loader, `pickle.loads`, `Markup()`/`mark_safe()`, Jinja `autoescape=False`,
+  `render_template_string`.
+- **Frontend** (TS/JS/JSX/Vue/Svelte/HTML): `innerHTML`/`outerHTML`/`insertAdjacentHTML`,
+  `dangerouslySetInnerHTML`, `v-html`, `document.write`, `eval`, `new Function`, string
+  `setTimeout`/`setInterval`, `javascript:` URLs, `postMessage(..., "*")`, `srcdoc`, and `<iframe>`
+  without `sandbox` (or with `allow-scripts` + `allow-same-origin`).
+- **CSP**: `csp-missing` when a web project (frontend files or a Python web framework) has no
+  `Content-Security-Policy` anywhere in the repo (header in code, `<meta http-equiv>`,
+  `staticwebapp.config.json`, nginx/web.config, ...); `csp-weakened` for `'unsafe-inline'`,
+  `'unsafe-eval'` or a wildcard `script-src`. The CSP lookup always covers the whole repo, even with `--diff`.
+
+Test files and generated code are skipped. Silence a confirmed-safe finding with
+`# bdt-lint: ignore <rule>` (Python) or `// bdt-lint: ignore <rule>` (TS/JS) on, or directly above, the line.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

{bmsdna_devtools-0.25.0 → bmsdna_devtools-0.26.0}/README.md

@@ -562,6 +562,41 @@ already pulled in transitively via `pgdevkit[db]`, but declared explicitly as
 the `bmsdna-devtools[lint]` extra; a clear install hint is printed (not a raw
 `ImportError`) if it's ever missing.
 
+## `bdt find-injection`
+
+Scans backend and frontend code for injection risks, and warns when a web project has no
+Content-Security-Policy.
+
+```bash
+bdt find-injection [PATHS...]            # files/folders, default: current directory
+bdt find-injection --diff [--base main]  # only files changed on this branch + uncommitted/untracked
+bdt find-injection --strict              # also fail on "review" items
+```
+
+Findings have two severities: **error** (a definite unsafe pattern, exit code 1) and **review**
+(depends on where a value comes from; listed with an instruction for an AI/human to verify, exit
+code 0 unless `--strict`).
+
+- **SQL** (Python `.execute()`): f-string / `%` / concatenation / `.format()` SQL is an error.
+  SQL from `load_sql()`, `sql.SQL`, sqlglot (`expr.sql()`, `sqlglot.*`), `cast(LiteralString, <sqlglot expr>)` (the cast is only as safe as its argument) or
+  a function in the same file annotated `-> LiteralString` is trusted; SQL from any other function
+  call is a `sql-unverified-call` review item. (`bdt lint` accepts the same trusted forms but never
+  reports unverified calls.)
+- **Other Python sinks**: `eval`/`exec`, `os.system`, `subprocess(..., shell=True)`, `yaml.load`
+  without a safe loader, `pickle.loads`, `Markup()`/`mark_safe()`, Jinja `autoescape=False`,
+  `render_template_string`.
+- **Frontend** (TS/JS/JSX/Vue/Svelte/HTML): `innerHTML`/`outerHTML`/`insertAdjacentHTML`,
+  `dangerouslySetInnerHTML`, `v-html`, `document.write`, `eval`, `new Function`, string
+  `setTimeout`/`setInterval`, `javascript:` URLs, `postMessage(..., "*")`, `srcdoc`, and `<iframe>`
+  without `sandbox` (or with `allow-scripts` + `allow-same-origin`).
+- **CSP**: `csp-missing` when a web project (frontend files or a Python web framework) has no
+  `Content-Security-Policy` anywhere in the repo (header in code, `<meta http-equiv>`,
+  `staticwebapp.config.json`, nginx/web.config, ...); `csp-weakened` for `'unsafe-inline'`,
+  `'unsafe-eval'` or a wildcard `script-src`. The CSP lookup always covers the whole repo, even with `--diff`.
+
+Test files and generated code are skipped. Silence a confirmed-safe finding with
+`# bdt-lint: ignore <rule>` (Python) or `// bdt-lint: ignore <rule>` (TS/JS) on, or directly above, the line.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

{bmsdna_devtools-0.25.0 → bmsdna_devtools-0.26.0}/bmsdna/devtools/cli.py

@@ -16,6 +16,7 @@ from . import ado_issue, app_service_logs, commit as commit_mod
 from . import env_config
 from . import find_repo as find_repo_mod
 from . import gh_issue, gh_pr
+from . import find_injection as find_injection_mod
 from . import lint as lint_mod
 from . import logs as logs_mod
 from . import pr_build, pr_issue_link, pr_labels, pull as pull_mod, worktree as worktree_mod
@@ -926,6 +927,22 @@ def lint(
     raise typer.Exit(lint_mod.print_report(result))
 
 
+@app.command("find-injection")
+def find_injection_cmd(
+    paths: list[str] = typer.Argument(None, help="Files and/or directories to scan (default: current directory, recursive)."),
+    diff: bool = typer.Option(False, "--diff", help="Scan only files changed on this branch vs --base, plus uncommitted and untracked files."),
+    base: str = typer.Option(None, "--base", help="Branch/ref to diff against with --diff (default: origin's default branch)."),
+    strict: bool = typer.Option(False, "--strict", help="Also exit 1 when there are items to review (default: only definite errors fail)."),
+) -> None:
+    """Find injection risks (bmsuisse/devtools#54) in backend and frontend code: SQL built from f-strings/
+    concatenation or from an unverifiable function call, eval/exec/shell/unsafe deserialization in Python,
+    innerHTML/dangerouslySetInnerHTML/eval/new Function/un-sandboxed iframes in the frontend, and a missing
+    or weakened Content-Security-Policy. Definite problems are errors; the rest are listed for a human/AI to verify.
+    """
+    result = find_injection_mod.run(paths or [], diff=diff, base=base)
+    raise typer.Exit(find_injection_mod.print_report(result, strict=strict))
+
+
 @app.command("find-repo")
 def find_repo_cmd(
     name: str,

bmsdna_devtools-0.26.0/bmsdna/devtools/find_injection.py

@@ -0,0 +1,310 @@
+"""`bdt find-injection` (bmsuisse/devtools#54): scan a folder, explicit files, or a git diff for
+injection risks in both backend (Python) and frontend (TS/JS/HTML/Vue) code, and warn when a
+web project has no Content-Security-Policy.
+
+Findings come in two severities: "error" (a definite unsafe pattern) and "review" (depends on
+where a value comes from -- a human or AI has to verify it). Exit code 1 for any error;
+review items only fail the run with `strict=True`.
+
+A finding is silenced with `# bdt-lint: ignore <rule>` (Python) or `// bdt-lint: ignore <rule>`
+(TS/JS) on, or on the comment line directly above, the flagged line.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .injection_frontend import (
+    FRONTEND_SUFFIXES,
+    check_frontend_file,
+    find_csp_weakening,
+    has_csp,
+)
+from .injection_python import check_python_sinks
+from .lint import _DEFAULT_EXCLUDE_DIR_NAMES, _iter_files
+from .lint_findings import Finding, render_findings
+from .lint_sql import check_sql_file, require_sqlglot
+from .lint_typescript import DEFAULT_TS_EXCLUDE_DIR_NAMES, is_excluded_ts_file
+
+SQL_INJECTION_RULES = frozenset(
+    {
+        "sql-fstring-injection",
+        "sql-percent-format-injection",
+        "sql-concat-injection",
+        "sql-format-injection",
+    }
+)
+_IGNORE_RE = re.compile(r"bdt-lint:\s*ignore\s+([\w-]+(?:\s*,\s*[\w-]+)*)")
+_WEB_FRAMEWORK_RE = re.compile(
+    r"^\s*(?:from|import)\s+(?:fastapi|flask|starlette|django|aiohttp|quart|sanic|litestar)\b",
+    re.MULTILINE,
+)
+_CONFIG_SUFFIXES = (
+    ".json",
+    ".conf",
+    ".config",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".cjs",
+    ".mjs",
+    ".js",
+    ".ts",
+    ".py",
+    ".html",
+    ".htm",
+    ".tsx",
+)
+_CONFIG_NAMES = frozenset(
+    {
+        "web.config",
+        "nginx.conf",
+        "staticwebapp.config.json",
+        "_headers",
+        "Caddyfile",
+        ".htaccess",
+    }
+)
+_EXCLUDE_TEST_DIR_NAMES = DEFAULT_TS_EXCLUDE_DIR_NAMES - {"generated", "__generated__"}
+_SKIP_NAMES = frozenset({"package-lock.json", "pnpm-lock.yaml", "yarn.lock", "uv.lock", "poetry.lock", "npm-shrinkwrap.json"})
+_MAX_CSP_FILE_BYTES = 1_000_000
+_TS_LIKE = (".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs")
+
+AI_INSTRUCTION = (
+    "AI reviewer: for every [review] item above, open the code, trace where the value comes from, and decide whether "
+    "attacker-controlled input can reach it. Fix real risks (parameterise / sanitise / sandbox); for confirmed-safe cases add "
+    "`# bdt-lint: ignore <rule>` (Python) or `// bdt-lint: ignore <rule>` (TS/JS) with a one-line reason."
+)
+
+
+@dataclass(frozen=True, slots=True)
+class InjectionResult:
+    findings: list[Finding]
+
+    @property
+    def errors(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == "error"]
+
+    @property
+    def reviews(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == "review"]
+
+
+def _git(args: list[str], cwd: Path) -> str:
+    try:
+        return subprocess.check_output(["git", *args], encoding="utf-8", cwd=cwd, stderr=subprocess.PIPE)
+    except FileNotFoundError:
+        sys.exit("'git' is required for --diff but wasn't found on PATH.")
+    except subprocess.CalledProcessError as e:
+        sys.exit(f"git {' '.join(args)} failed: {(e.stderr or '').strip()}")
+
+
+def diff_files(root: Path, base: str | None = None) -> list[Path]:
+    """Files added/changed on this branch vs `base` (default: origin's default branch, else main), plus
+    uncommitted and untracked ones. Deleted files are skipped."""
+    repo = Path(_git(["rev-parse", "--show-toplevel"], root).strip())
+    candidates = [base] if base else []
+    if not base:
+        head = subprocess.run(
+            ["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+            cwd=root,
+            capture_output=True,
+            encoding="utf-8",
+        )
+        candidates += [head.stdout.strip()] if head.returncode == 0 and head.stdout.strip() else []
+        candidates += ["origin/main", "main", "origin/master", "master"]
+    chosen = next(
+        (c for c in candidates if c and subprocess.run(["git", "rev-parse", "--verify", "-q", c], cwd=root, capture_output=True).returncode == 0),
+        None,
+    )
+    if chosen is None:
+        sys.exit(f"Couldn't find a base branch to diff against (tried {', '.join(c for c in candidates if c)}); pass --base.")
+    names: set[str] = set()
+    names.update(_git(["diff", "--name-only", "-z", "--diff-filter=ACMR", f"{chosen}...HEAD"], root).split("\0"))
+    names.update(_git(["diff", "--name-only", "-z", "--diff-filter=ACMR", "HEAD"], root).split("\0"))
+    names.update(_git(["ls-files", "--others", "--exclude-standard", "--full-name", "-z"], root).split("\0"))
+    return sorted(p for p in (repo / n for n in names if n) if p.is_file())
+
+
+def _pragma_ignored(lines: list[str], finding: Finding) -> bool:
+    if finding.line <= 0:
+        return False
+    for number in (finding.line, finding.line - 1):
+        if not 1 <= number <= len(lines):
+            continue
+        text = lines[number - 1]
+        if number != finding.line and not text.lstrip().startswith(("#", "//", "/*", "*", "<!--")):
+            continue
+        match = _IGNORE_RE.search(text)
+        if match and finding.rule in {r.strip() for r in match.group(1).split(",")}:
+            return True
+    return False
+
+
+def _filter_ignored(findings: list[Finding]) -> list[Finding]:
+    cache: dict[Path, list[str]] = {}
+    kept: list[Finding] = []
+    for finding in findings:
+        if finding.path not in cache:
+            try:
+                cache[finding.path] = finding.path.read_text(encoding="utf-8").splitlines()
+            except OSError, UnicodeDecodeError:
+                cache[finding.path] = []
+        if not _pragma_ignored(cache[finding.path], finding):
+            kept.append(finding)
+    return kept
+
+
+def _scan_python(path: Path) -> list[Finding]:
+    sql = [f for f in check_sql_file(path, review=True) if f.rule in SQL_INJECTION_RULES or f.rule in ("sql-unverified-call", "sql-unverified-cast")]
+    return sql + check_python_sinks(path)
+
+
+def _walk_repo_text_files(root: Path, exclude_dirs: frozenset[str]):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in exclude_dirs]
+        for name in filenames:
+            if name in _SKIP_NAMES or name.endswith(".min.js") or not (name in _CONFIG_NAMES or name.endswith(_CONFIG_SUFFIXES)):
+                continue
+            candidate = Path(dirpath, name)
+            try:
+                if candidate.stat().st_size <= _MAX_CSP_FILE_BYTES:
+                    yield candidate
+            except OSError:
+                continue
+
+
+def check_csp(root: Path, scanned: list[Path], exclude_dirs: frozenset[str], only: set[Path] | None = None) -> list[Finding]:
+    """Warns when the project serves a web UI/API (frontend files scanned, or a Python web framework
+    imported) but no file anywhere under `root` mentions a Content-Security-Policy. Always searches the
+    whole repo -- a diff that doesn't touch the header config mustn't look like "no CSP configured".
+    `only` (diff mode) restricts `csp-weakened` findings to the changed files."""
+    is_web = any(p.suffix.lower() in FRONTEND_SUFFIXES for p in scanned)
+    if not is_web:
+        for p in scanned:
+            if p.suffix == ".py":
+                try:
+                    if _WEB_FRAMEWORK_RE.search(p.read_text(encoding="utf-8")):
+                        is_web = True
+                        break
+                except OSError, UnicodeDecodeError:
+                    continue
+    if not is_web:
+        return []
+    weakened: list[Finding] = []
+    found = False
+    for candidate in _walk_repo_text_files(root, exclude_dirs):
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except OSError, UnicodeDecodeError:
+            continue
+        if has_csp(text):
+            found = True
+            weakened.extend(find_csp_weakening(candidate, text))
+    if found:
+        return [f for f in weakened if only is None or f.path.resolve() in only]
+    return [
+        Finding(
+            root,
+            0,
+            "csp-missing",
+            "No Content-Security-Policy configured anywhere in the repo (response header, `<meta http-equiv>`, "
+            "staticwebapp.config.json, nginx/web.config, ...). A CSP is the main defence-in-depth against XSS -- add one "
+            "(start with `default-src 'self'` and no 'unsafe-inline'/'unsafe-eval').",
+            severity="review",
+        )
+    ]
+
+
+def run(
+    paths: list[str],
+    *,
+    root: Path | None = None,
+    diff: bool = False,
+    base: str | None = None,
+) -> InjectionResult:
+    root = (root or Path.cwd()).resolve()
+    exclude_dirs = _DEFAULT_EXCLUDE_DIR_NAMES | {
+        ".next",
+        "coverage",
+        "storybook-static",
+    }
+    findings: list[Finding] = []
+    changed: list[Path] = []
+
+    if diff:
+        changed = [p for p in diff_files(root, base) if not _in_excluded_dir(p, root, exclude_dirs)]
+        py_files = [p for p in changed if p.suffix == ".py"]
+        fe_files = [p for p in changed if p.suffix.lower() in FRONTEND_SUFFIXES]
+    else:
+        targets = [Path(p).resolve() for p in paths] if paths else [root]
+        py_files, missing = _iter_files(targets, exclude_dirs, (".py",))
+        fe_files, _ = _iter_files(targets, exclude_dirs, FRONTEND_SUFFIXES)
+        findings.extend(
+            Finding(
+                p,
+                0,
+                "path-not-found",
+                f"'{p}' doesn't exist -- nothing was scanned for it.",
+            )
+            for p in missing
+        )
+
+    py_files = [p for p in py_files if not _is_test_file(p, root)]
+    fe_files = [p for p in fe_files if not _is_test_file(p, root)]
+
+    if py_files:
+        require_sqlglot()
+    for path in py_files:
+        findings.extend(_scan_python(path))
+    for path in fe_files:
+        findings.extend(check_frontend_file(path))
+
+    findings.extend(check_csp(root, py_files + fe_files, exclude_dirs, {p.resolve() for p in changed} if diff else None))
+    return InjectionResult(findings=_filter_ignored(findings))
+
+
+def _in_excluded_dir(path: Path, root: Path, exclude_dirs: frozenset[str]) -> bool:
+    try:
+        parts = path.relative_to(root).parts[:-1]
+    except ValueError:
+        parts = path.parts[:-1]
+    return any(part in exclude_dirs for part in parts)
+
+
+def _is_test_file(path: Path, root: Path) -> bool:
+    try:
+        parts = path.relative_to(root).parts[:-1]
+    except ValueError:
+        parts = ()
+    name = path.name
+    return (
+        any(part in _EXCLUDE_TEST_DIR_NAMES for part in parts)
+        or name.startswith("test_")
+        or name.endswith("_test.py")
+        or name == "conftest.py"
+        or (path.suffix in _TS_LIKE and is_excluded_ts_file(path, repo_root=root))
+    )
+
+
+def print_report(result: InjectionResult, *, strict: bool = False) -> int:
+    """Prints the report and returns the exit code (1 on any error, or on any review item with `strict`)."""
+    if not result.findings:
+        print("bdt find-injection: no injection risks found")
+        return 0
+    errors, reviews = result.errors, result.reviews
+    if errors:
+        print("Errors:")
+        print(render_findings(errors))
+    if reviews:
+        print(("\n" if errors else "") + "Review (verify these are safe):")
+        print(render_findings(reviews))
+    print(f"\n{len(errors)} error(s), {len(reviews)} item(s) to review.")
+    if reviews:
+        print(AI_INSTRUCTION)
+    return 1 if errors or (strict and reviews) else 0

bmsdna_devtools-0.26.0/bmsdna/devtools/injection_frontend.py

@@ -0,0 +1,237 @@
+"""`bdt find-injection`'s frontend rules (bmsuisse/devtools#54): DOM-XSS sinks in TS/JS/JSX/Vue
+(comments and string contents are masked with lint_typescript's tokenizer so a mention inside
+a comment or string never matches), un-sandboxed iframes, and Content-Security-Policy checks.
+
+Deliberately heuristic, like lint_typescript: no JS parser. Findings that depend on where a
+value comes from are "review" items.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .lint_findings import Finding
+from .lint_typescript import _line_of, _mask
+
+FRONTEND_SUFFIXES = (
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".vue",
+    ".svelte",
+    ".html",
+    ".htm",
+)
+_HTML_SUFFIXES = (".html", ".htm")
+_MASKABLE_SUFFIXES = (".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs")
+
+_CSP_RE = re.compile(r"content-security-policy", re.IGNORECASE)
+_CSP_WEAK_RE = re.compile(r"'unsafe-(?:inline|eval)'|(?:script|default)-src[^;\n]*\s\*(?=[\s;\"'`]|$)", re.IGNORECASE)
+
+_INNER_HTML_ASSIGN_RE = re.compile(r"\.\s*(?:inner|outer)HTML\s*\+?=(?!=)")
+_INSERT_HTML_RE = re.compile(r"\.\s*insertAdjacentHTML\s*\(")
+_DOC_WRITE_RE = re.compile(r"(?<![\w$])document\s*\.\s*write(?:ln)?\s*\(")
+_EVAL_RE = re.compile(r"(?<![\w$.])eval\s*\(")
+_NEW_FUNCTION_RE = re.compile(r"(?<![\w$.])new\s+Function\s*\(")
+_TIMER_STRING_RE = re.compile(r"(?<![\w$.])(?:setTimeout|setInterval)\s*\(\s*(?:['\"`]|[\w$.]+\s*\+)")
+_DANGEROUS_HTML_RE = re.compile(r"\bdangerouslySetInnerHTML\b")
+_V_HTML_RE = re.compile(r"\bv-html\s*=|\{@html\b")
+_JS_URL_ATTR_RE = re.compile(r"""(?:href|src|action|formaction)\s*=\s*\{?\s*[`'"]\s*javascript\s*:""", re.IGNORECASE)
+_POST_MESSAGE_STAR_RE = re.compile(r"""postMessage\s*\([^;]*?,\s*['"]\*['"]\s*[,)]""")
+_IFRAME_RE = re.compile(r"<iframe\b", re.IGNORECASE)
+_SRCDOC_RE = re.compile(r"\bsrc[dD]oc\b\s*=")
+
+
+def _sink(path: Path, text: str, pos: int, rule: str, message: str, severity: str) -> Finding:
+    return Finding(path, _line_of(text, pos), rule, message, severity=severity)
+
+
+def _iframe_tag(code: str, start: int) -> str:
+    """The `<iframe ...>` opening tag (attribute values may contain `>` inside `{...}` or quotes)."""
+    depth = 0
+    quote = ""
+    for k in range(start, len(code)):
+        c = code[k]
+        if quote:
+            if c == quote:
+                quote = ""
+        elif c in "\"'":
+            quote = c
+        elif c == "{":
+            depth += 1
+        elif c == "}":
+            depth = max(0, depth - 1)
+        elif c == ">" and depth == 0:
+            return code[start : k + 1]
+    return code[start:]
+
+
+def _check_iframes(path: Path, code: str, skeleton: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for match in _IFRAME_RE.finditer(skeleton):
+        tag = _iframe_tag(code, match.start())
+        sandbox = re.search(
+            r"(?<=\s)sandbox(?![\w-])(?:\s*=\s*(?:\"([^\"]*)\"|'([^']*)'|\{\s*[\"'`]([^\"'`]*)[\"'`]\s*\}))?",
+            tag,
+        )
+        if sandbox is None:
+            findings.append(
+                _sink(
+                    path,
+                    code,
+                    match.start(),
+                    "fe-iframe-no-sandbox",
+                    "`<iframe>` without a `sandbox` attribute -- embedded content runs with the page's full privileges. "
+                    "Add `sandbox` (with only the allow-* flags it needs).",
+                    "error",
+                )
+            )
+            continue
+        flags = next((g for g in sandbox.groups() if g), "")
+        if "allow-scripts" in flags and "allow-same-origin" in flags:
+            findings.append(
+                _sink(
+                    path,
+                    code,
+                    match.start(),
+                    "fe-iframe-sandbox-escape",
+                    "`sandbox` combines `allow-scripts` and `allow-same-origin`, which lets the framed page remove its own sandbox.",
+                    "error",
+                )
+            )
+    return findings
+
+
+def check_frontend_file(path: Path, source: str | None = None) -> list[Finding]:
+    if source is None:
+        try:
+            source = path.read_text(encoding="utf-8")
+        except OSError, UnicodeDecodeError:
+            return []
+    full_text: str = source
+    suffix = path.suffix.lower()
+    if suffix in _MASKABLE_SUFFIXES:
+        masked = _mask(source)
+        skeleton, code = masked.skeleton, masked.code
+    else:  # .vue/.svelte/.html: `//` appears in URLs and `'` in prose, so the JS tokenizer would mangle them
+        skeleton = code = source
+
+    findings: list[Finding] = []
+
+    def scan(
+        regex: re.Pattern[str],
+        rule: str,
+        message: str,
+        severity: str,
+        text: str | None = None,
+    ) -> None:
+        haystack = skeleton if text is None else text
+        findings.extend(_sink(path, full_text, m.start(), rule, message, severity) for m in regex.finditer(haystack))
+
+    if suffix not in _HTML_SUFFIXES:
+        scan(
+            _INNER_HTML_ASSIGN_RE,
+            "fe-inner-html",
+            "Assigning to `innerHTML`/`outerHTML` -- XSS if the value contains user data. AI reviewer: verify it's sanitised "
+            "(e.g. DOMPurify) or use `textContent`.",
+            "review",
+        )
+        scan(
+            _INSERT_HTML_RE,
+            "fe-inner-html",
+            "`insertAdjacentHTML` parses its argument as HTML -- XSS if it contains user data. AI reviewer: verify it's sanitised.",
+            "review",
+        )
+        scan(
+            _DOC_WRITE_RE,
+            "fe-document-write",
+            "`document.write()` injects raw HTML -- avoid it.",
+            "error",
+        )
+        scan(
+            _EVAL_RE,
+            "fe-eval",
+            "`eval()` executes arbitrary code -- remove it.",
+            "error",
+        )
+        scan(
+            _NEW_FUNCTION_RE,
+            "fe-new-function",
+            "`new Function()` is `eval` in disguise -- remove it.",
+            "error",
+        )
+        scan(
+            _TIMER_STRING_RE,
+            "fe-timer-string",
+            "`setTimeout`/`setInterval` with a string argument evaluates it as code -- pass a function.",
+            "error",
+        )
+        scan(
+            _DANGEROUS_HTML_RE,
+            "fe-dangerously-set-inner-html",
+            "`dangerouslySetInnerHTML` -- XSS if the HTML contains user data. AI reviewer: verify it's sanitised (DOMPurify) or static.",
+            "review",
+        )
+        scan(
+            _POST_MESSAGE_STAR_RE,
+            "fe-post-message-star",
+            "`postMessage(..., '*')` sends to any origin -- pass the exact target origin.",
+            "review",
+            code,
+        )
+        scan(
+            _SRCDOC_RE,
+            "fe-iframe-srcdoc",
+            "`srcdoc` renders an HTML string inside a frame -- verify no user data reaches it.",
+            "review",
+        )
+        findings.extend(_check_iframes(path, code, skeleton))
+    else:
+        findings.extend(_check_iframes(path, code, code))
+
+    if suffix in (".vue", ".svelte"):
+        scan(
+            _V_HTML_RE,
+            "fe-v-html",
+            "`v-html`/`{@html}` renders raw HTML -- XSS if it contains user data. AI reviewer: verify it's sanitised.",
+            "review",
+        )
+    scan(
+        _JS_URL_ATTR_RE,
+        "fe-javascript-url",
+        "`javascript:` URL executes code on click -- use an event handler.",
+        "error",
+        code,
+    )
+    return findings
+
+
+def find_csp_weakening(path: Path, source: str | None = None) -> list[Finding]:
+    """`'unsafe-inline'`/`'unsafe-eval'`/wildcard script-src inside a file that defines a CSP."""
+    if source is None:
+        try:
+            source = path.read_text(encoding="utf-8")
+        except OSError, UnicodeDecodeError:
+            return []
+    if not _CSP_RE.search(source) and "script-src" not in source.lower() and "default-src" not in source.lower():
+        return []
+    return [
+        _sink(
+            path,
+            source,
+            m.start(),
+            "csp-weakened",
+            f"CSP contains `{m.group(0).strip()}`, which weakens XSS protection. AI reviewer: verify this relaxation is necessary "
+            "(prefer nonces/hashes).",
+            "review",
+        )
+        for m in _CSP_WEAK_RE.finditer(source)
+    ]
+
+
+def has_csp(source: str) -> bool:
+    return _CSP_RE.search(source) is not None