software-intake-gatekeeper 0.2.1__py3-none-any.whl

intake_gatekeeper/__init__.py

@@ -0,0 +1,3 @@
+"""Software Intake Gatekeeper: evidence-first intake checks for third-party software."""
+
+__version__ = "0.2.1"

intake_gatekeeper/__main__.py

@@ -0,0 +1,3 @@
+from intake_gatekeeper.cli import main
+
+raise SystemExit(main())

intake_gatekeeper/asar.py

@@ -0,0 +1,117 @@
+"""Read-only ASAR archive reader that never extracts files to disk."""
+
+from __future__ import annotations
+
+import json
+import struct
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import BinaryIO
+
+from intake_gatekeeper.model import GatekeeperError
+
+_MAX_DEPTH = 64
+
+
+class AsarError(GatekeeperError):
+    pass
+
+
+@dataclass(frozen=True)
+class AsarEntry:
+    path: str
+    offset: int
+    size: int
+    unpacked: bool
+
+
+def _u32(data: bytes, at: int) -> int:
+    return int(struct.unpack_from("<I", data, at)[0])
+
+
+def read_header(handle: BinaryIO, archive_size: int, max_header_bytes: int) -> tuple[dict[str, object], int]:
+    """Return the parsed header and the absolute offset where file contents start."""
+    prefix = handle.read(8)
+    if len(prefix) != 8 or _u32(prefix, 0) != 4:
+        raise AsarError("not an ASAR archive (missing size pickle)")
+    header_pickle_size = _u32(prefix, 4)
+    if header_pickle_size < 8 or header_pickle_size > archive_size - 8:
+        raise AsarError("ASAR header size exceeds the archive size")
+    if header_pickle_size > max_header_bytes:
+        raise AsarError(f"ASAR header is larger than the {max_header_bytes} byte limit")
+    pickle = handle.read(header_pickle_size)
+    if len(pickle) != header_pickle_size:
+        raise AsarError("truncated ASAR header")
+    payload_size = _u32(pickle, 0)
+    string_size = struct.unpack_from("<i", pickle, 4)[0]
+    if payload_size > header_pickle_size - 4 or not 0 <= string_size <= payload_size - 4:
+        raise AsarError("corrupt ASAR header pickle")
+    try:
+        header = json.loads(pickle[8 : 8 + string_size].decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise AsarError(f"ASAR header is not valid JSON: {error}") from None
+    if not isinstance(header, dict) or not isinstance(header.get("files"), dict):
+        raise AsarError("ASAR header has no root 'files' object")
+    return header, 8 + header_pickle_size
+
+
+def iter_entries(header: dict[str, object], max_entries: int) -> Iterator[AsarEntry | str]:
+    """Yield file entries, or a problem description for entries that were skipped."""
+    stack: list[tuple[str, dict[str, object], int]] = [("", header, 0)]
+    emitted = 0
+    while stack:
+        prefix, node, depth = stack.pop()
+        files = node.get("files")
+        if not isinstance(files, dict):
+            continue
+        for name in sorted(files):
+            child = files[name]
+            if (
+                not isinstance(name, str)
+                or name in ("", ".", "..")
+                or "/" in name
+                or "\\" in name
+                or "\x00" in name
+            ):
+                yield f"unsafe entry name {name!r} under '{prefix or '/'}'"
+                continue
+            path = f"{prefix}{name}"
+            if not isinstance(child, dict):
+                yield f"malformed entry '{path}'"
+                continue
+            if "files" in child:
+                if depth + 1 >= _MAX_DEPTH:
+                    yield f"directory nesting limit reached at '{path}'"
+                    continue
+                stack.append((path + "/", child, depth + 1))
+                continue
+            if "link" in child:
+                continue
+            emitted += 1
+            if emitted > max_entries:
+                yield f"entry limit of {max_entries} reached"
+                return
+            unpacked = child.get("unpacked") is True
+            size = child.get("size")
+            offset = child.get("offset", "0" if unpacked else None)
+            if (
+                not isinstance(size, int)
+                or isinstance(size, bool)
+                or size < 0
+                or not isinstance(offset, str)
+                or not offset.isdigit()
+            ):
+                yield f"entry '{path}' has an invalid offset or size"
+                continue
+            yield AsarEntry(path=path, offset=int(offset), size=size, unpacked=unpacked)
+
+
+def read_entry(handle: BinaryIO, data_start: int, archive_size: int, entry: AsarEntry) -> bytes:
+    start = data_start + entry.offset
+    if start + entry.size > archive_size:
+        raise AsarError(f"entry '{entry.path}' points outside the archive")
+    handle.seek(start)
+    data = handle.read(entry.size)
+    if len(data) != entry.size:
+        raise AsarError(f"entry '{entry.path}' is truncated")
+    return data

intake_gatekeeper/cli.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from intake_gatekeeper import __version__, output
+from intake_gatekeeper.diff import compare
+from intake_gatekeeper.engine import run_scan
+from intake_gatekeeper.model import Decision, GatekeeperError, clean_text
+from intake_gatekeeper.osv import DEFAULT_URL, OsvClient, validate_base_url
+from intake_gatekeeper.policy import load_policy
+from intake_gatekeeper.rules import RULES
+from intake_gatekeeper.scanner import Limits
+
+EXIT_OK = 0
+EXIT_GATE = 1
+EXIT_USAGE = 2
+_FAIL_LEVELS = {
+    "reject": {Decision.REJECT},
+    "review": {Decision.REJECT, Decision.REVIEW},
+    "never": set(),
+}
+
+
+def _common(command: argparse.ArgumentParser) -> None:
+    command.add_argument(
+        "--osv",
+        action="store_true",
+        help="look up known vulnerabilities on OSV.dev (sends ecosystem, name and version of "
+        "each queryable component; nothing else)",
+    )
+    command.add_argument("--osv-url", default=DEFAULT_URL, help="OSV API origin (default: %(default)s)")
+    command.add_argument("--policy", type=Path, help="policy TOML file")
+    command.add_argument("--json", type=Path, metavar="FILE", help="write the full JSON report")
+    command.add_argument(
+        "--sarif",
+        type=Path,
+        metavar="FILE",
+        help="write SARIF 2.1.0 (paths are relative to the current directory when the target "
+        "is inside it, which is what GitHub code scanning expects)",
+    )
+    command.add_argument("--cyclonedx", type=Path, metavar="FILE", help="write a CycloneDX 1.6 SBOM")
+    command.add_argument("--markdown", type=Path, metavar="FILE", help="write a Markdown summary")
+    command.add_argument(
+        "--fail-on",
+        choices=sorted(_FAIL_LEVELS),
+        default="reject",
+        help="decision that produces exit status 1 (default: %(default)s)",
+    )
+    command.add_argument("--max-files", type=int, default=Limits.max_files, help=argparse.SUPPRESS)
+    command.add_argument("-q", "--quiet", action="store_true", help="do not print the summary")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="intake-gatekeeper",
+        description="Evidence-first intake checks for third-party apps and binaries. "
+        "Reads files only; never executes or extracts the target.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    scan = commands.add_parser("scan", help="scan a directory, archive or binary")
+    scan.add_argument("target", type=Path, help="installed app directory, .asar or executable")
+    _common(scan)
+
+    diff = commands.add_parser(
+        "diff",
+        help="compare two versions and gate the update on what it adds",
+        description="Scan the previous and the new version and report new and resolved findings, "
+        "component changes, Electron fuse changes, new network endpoints and new binaries.",
+    )
+    diff.add_argument("old", type=Path, help="previous version (directory, .asar or executable)")
+    diff.add_argument("new", type=Path, help="new version")
+    _common(diff)
+
+    commands.add_parser("rules", help="list configuration rules")
+    return parser
+
+
+def _list_rules() -> int:
+    for rule in RULES.values():
+        print(f"{rule.id:36} {rule.severity.label:8} {rule.title}")
+    return EXIT_OK
+
+
+def _write(outputs: Sequence[tuple[Path | None, Callable[[], str]]]) -> None:
+    for path, render in outputs:
+        if path is not None:
+            output.write_atomic(path, render())
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    osv_factory: Callable[[str], OsvClient] = OsvClient,
+) -> int:
+    args = _parser().parse_args(argv)
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(errors="replace")
+    if args.command == "rules":
+        return _list_rules()
+    try:
+        if args.max_files < 1:
+            raise GatekeeperError("--max-files must be positive")
+        policy = load_policy(args.policy)
+        limits = Limits(max_files=args.max_files)
+        osv = osv_factory(validate_base_url(args.osv_url)) if args.osv else None
+        try:
+            if args.command == "diff":
+                old_report = run_scan(args.old, policy, osv, limits)
+                new_report = run_scan(args.new, policy, osv, limits)
+            else:
+                report = run_scan(args.target, policy, osv, limits)
+        finally:
+            if osv is not None:
+                osv.close()
+        if args.command == "diff":
+            diff = compare(old_report, new_report, policy)
+            prefix = output.sarif_prefix(args.new, Path.cwd())
+            _write(
+                [
+                    (args.json, lambda: output.to_diff_json(diff)),
+                    (args.sarif, lambda: output.diff_sarif(diff, prefix)),
+                    (args.cyclonedx, lambda: output.to_cyclonedx(new_report)),
+                    (args.markdown, lambda: output.to_diff_markdown(diff)),
+                ]
+            )
+            summary, decision = output.to_diff_text(diff), diff.decision
+        else:
+            prefix = output.sarif_prefix(args.target, Path.cwd())
+            _write(
+                [
+                    (args.json, lambda: output.to_json(report)),
+                    (args.sarif, lambda: output.to_sarif(report, prefix)),
+                    (args.cyclonedx, lambda: output.to_cyclonedx(report)),
+                    (args.markdown, lambda: output.to_markdown(report)),
+                ]
+            )
+            summary, decision = output.to_text(report), report.decision
+    except (GatekeeperError, OSError) as error:
+        print(f"intake-gatekeeper: error: {clean_text(str(error), 500)}", file=sys.stderr)
+        return EXIT_USAGE
+    if not args.quiet:
+        sys.stdout.write(summary)
+    return EXIT_GATE if decision in _FAIL_LEVELS[args.fail_on] else EXIT_OK

intake_gatekeeper/diff.py

@@ -0,0 +1,154 @@
+"""Compare two scanned versions of the same software and decide whether the update adds risk."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from intake_gatekeeper.electron import FUSE_RULES
+from intake_gatekeeper.model import Decision, Finding, Report
+from intake_gatekeeper.policy import Policy
+
+
+@dataclass(frozen=True)
+class ComponentChange:
+    ecosystem: str
+    name: str
+    old: tuple[str, ...]
+    new: tuple[str, ...]
+
+    @property
+    def kind(self) -> str:
+        if not self.old:
+            return "added"
+        if not self.new:
+            return "removed"
+        return "changed"
+
+
+@dataclass(frozen=True)
+class FuseChange:
+    executable: str
+    fuse: str
+    old: str | None
+    new: str | None
+    weakened: bool
+
+
+@dataclass
+class UpdateDiff:
+    old: Report
+    new: Report
+    components: list[ComponentChange] = field(default_factory=list)
+    new_findings: list[Finding] = field(default_factory=list)
+    resolved_findings: list[Finding] = field(default_factory=list)
+    persisting_findings: int = 0
+    electron_versions: tuple[str | None, str | None] | None = None
+    fuse_changes: list[FuseChange] = field(default_factory=list)
+    endpoints_added: list[str] = field(default_factory=list)
+    endpoints_removed: list[str] = field(default_factory=list)
+    binaries_added: list[str] = field(default_factory=list)
+    binaries_removed: list[str] = field(default_factory=list)
+    binaries_changed: list[str] = field(default_factory=list)
+    decision: Decision = Decision.APPROVE
+    reasons: list[str] = field(default_factory=list)
+
+
+def _finding_key(finding: Finding) -> tuple[str, str]:
+    if finding.component_purl:
+        return finding.rule_id, finding.component_purl.rsplit("@", 1)[0]
+    return finding.rule_id, finding.location.path if finding.location else ""
+
+
+def _versions(report: Report) -> dict[tuple[str, str], set[str]]:
+    versions: dict[tuple[str, str], set[str]] = {}
+    for component in report.inventory.components:
+        if component.kind == "application":
+            continue
+        versions.setdefault((component.ecosystem, component.name), set()).add(component.version)
+    return versions
+
+
+def compare(old: Report, new: Report, policy: Policy) -> UpdateDiff:
+    diff = UpdateDiff(old=old, new=new)
+
+    old_versions, new_versions = _versions(old), _versions(new)
+    for key in sorted(old_versions.keys() | new_versions.keys()):
+        before, after = old_versions.get(key, set()), new_versions.get(key, set())
+        if before != after:
+            diff.components.append(
+                ComponentChange(key[0], key[1], tuple(sorted(before)), tuple(sorted(after)))
+            )
+
+    old_keys = {_finding_key(f) for f in old.inventory.findings}
+    new_keys = {_finding_key(f) for f in new.inventory.findings}
+    diff.new_findings = [f for f in new.inventory.findings if _finding_key(f) not in old_keys]
+    diff.resolved_findings = [f for f in old.inventory.findings if _finding_key(f) not in new_keys]
+    diff.persisting_findings = len(new.inventory.findings) - len(diff.new_findings)
+
+    old_electron = {info.executable: info for info in old.inventory.electron}
+    new_electron = {info.executable: info for info in new.inventory.electron}
+    old_version = next((i.version for i in old.inventory.electron if i.version), None)
+    new_version = next((i.version for i in new.inventory.electron if i.version), None)
+    if old_version != new_version:
+        diff.electron_versions = (old_version, new_version)
+    risky = {fuse: state for fuse, state, _ in FUSE_RULES}
+    for executable in sorted(old_electron.keys() | new_electron.keys()):
+        old_fuses = old_electron[executable].fuses if executable in old_electron else {}
+        new_fuses = new_electron[executable].fuses if executable in new_electron else {}
+        for fuse in sorted(old_fuses.keys() | new_fuses.keys()):
+            if old_fuses.get(fuse) != new_fuses.get(fuse):
+                weakened = fuse in risky and new_fuses.get(fuse) == risky[fuse]
+                diff.fuse_changes.append(
+                    FuseChange(executable, fuse, old_fuses.get(fuse), new_fuses.get(fuse), weakened)
+                )
+
+    old_hosts, new_hosts = set(old.inventory.endpoints), set(new.inventory.endpoints)
+    diff.endpoints_added = sorted(new_hosts - old_hosts)
+    diff.endpoints_removed = sorted(old_hosts - new_hosts)
+
+    old_bins = {b.path: b.sha256 for b in old.inventory.binaries}
+    new_bins = {b.path: b.sha256 for b in new.inventory.binaries}
+    diff.binaries_added = sorted(new_bins.keys() - old_bins.keys())
+    diff.binaries_removed = sorted(old_bins.keys() - new_bins.keys())
+    diff.binaries_changed = sorted(p for p in new_bins.keys() & old_bins.keys() if new_bins[p] != old_bins[p])
+
+    diff.decision, diff.reasons = _decide(diff, policy)
+    return diff
+
+
+def _decide(diff: UpdateDiff, policy: Policy) -> tuple[Decision, list[str]]:
+    active = [f for f in diff.new_findings if not f.waived]
+    at_reject = [f for f in active if f.severity >= policy.reject_at]
+    at_review = [f for f in active if policy.review_at <= f.severity < policy.reject_at]
+    weakened = [c for c in diff.fuse_changes if c.weakened]
+    added_components = [c for c in diff.components if c.kind == "added"]
+    blocking = [g for g in diff.new.inventory.gaps if g.blocking]
+    reasons: list[str] = []
+    if at_reject:
+        reasons.append(f"{len(at_reject)} new finding(s) at or above {policy.reject_at.label}.")
+    if at_review:
+        reasons.append(
+            f"{len(at_review)} new finding(s) between {policy.review_at.label} and {policy.reject_at.label}."
+        )
+    if weakened:
+        reasons.append(f"{len(weakened)} Electron fuse(s) weakened.")
+    if diff.endpoints_added:
+        reasons.append(f"{len(diff.endpoints_added)} new network endpoint(s) referenced by app code.")
+    if diff.binaries_added:
+        reasons.append(f"{len(diff.binaries_added)} new executable(s) or native module(s).")
+    if added_components:
+        reasons.append(f"{len(added_components)} new component(s).")
+    if blocking:
+        reasons.append(
+            f"{len(blocking)} coverage gap(s) in the new version: "
+            + "; ".join(sorted({g.code for g in blocking}))
+            + "."
+        )
+    if at_reject:
+        return Decision.REJECT, reasons
+    if reasons:
+        return Decision.REVIEW, reasons
+    summary = "No new risk compared with the previous version"
+    if diff.resolved_findings:
+        summary += f"; {len(diff.resolved_findings)} finding(s) resolved"
+    return Decision.APPROVE, [summary + "."]

intake_gatekeeper/electron.py

@@ -0,0 +1,190 @@
+"""Static Electron checks: fuse wire, runtime version and risky BrowserWindow preferences."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from intake_gatekeeper.golang import Bytes
+from intake_gatekeeper.model import Location, clean_text
+
+SENTINEL = b"dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX"
+FUSE_NAMES = (
+    "RunAsNode",
+    "EnableCookieEncryption",
+    "EnableNodeOptionsEnvironmentVariable",
+    "EnableNodeCliInspectArguments",
+    "EnableEmbeddedAsarIntegrityValidation",
+    "OnlyLoadAppFromAsar",
+    "LoadBrowserProcessSpecificV8Snapshot",
+    "GrantFileProtocolExtraPrivileges",
+    "WasmTrapHandlers",
+)
+_STATES = {0x30: "disabled", 0x31: "enabled", 0x72: "removed"}
+# (fuse, risky state, rule id)
+FUSE_RULES = (
+    ("RunAsNode", "enabled", "EGK-FUSE-RUN-AS-NODE"),
+    ("EnableCookieEncryption", "disabled", "EGK-FUSE-COOKIE-ENCRYPTION-OFF"),
+    ("EnableNodeOptionsEnvironmentVariable", "enabled", "EGK-FUSE-NODE-OPTIONS"),
+    ("EnableNodeCliInspectArguments", "enabled", "EGK-FUSE-NODE-INSPECT"),
+    ("EnableEmbeddedAsarIntegrityValidation", "disabled", "EGK-FUSE-ASAR-INTEGRITY-OFF"),
+    ("OnlyLoadAppFromAsar", "disabled", "EGK-FUSE-LOAD-OUTSIDE-ASAR"),
+    ("GrantFileProtocolExtraPrivileges", "enabled", "EGK-FUSE-FILE-PROTOCOL-PRIVILEGES"),
+)
+_VERSION_PREFIX = b"Electron/"
+_VERSION = re.compile(rb"Electron/(\d{1,3}\.\d{1,4}\.\d{1,4}(?:-(?:alpha|beta|nightly)\.[0-9.]{1,20})?)")
+_MAX_VERSION_PROBES = 4096
+
+_TRUE = r"(?:true|!0|1)\b"
+_FALSE = r"(?:false|!1|0)\b"
+
+
+def _key(name: str) -> str:
+    # Patterns start with a literal so re can use its fast substring search; see _boundary().
+    return rf"{name}[\"']?\s*(?::|=(?!=))\s*"
+
+
+JS_RULES: tuple[tuple[str, str, re.Pattern[str]], ...] = (
+    ("EGK-JS-NODE-INTEGRATION", "nodeIntegration", re.compile(_key("nodeIntegration") + _TRUE)),
+    (
+        "EGK-JS-CONTEXT-ISOLATION-OFF",
+        "contextIsolation",
+        re.compile(_key("contextIsolation") + _FALSE),
+    ),
+    ("EGK-JS-WEB-SECURITY-OFF", "webSecurity", re.compile(_key("webSecurity") + _FALSE)),
+    (
+        "EGK-JS-INSECURE-CONTENT",
+        "allowRunningInsecureContent",
+        re.compile(_key("allowRunningInsecureContent") + _TRUE),
+    ),
+    (
+        "EGK-JS-NODE-INTEGRATION-EXTENDED",
+        "nodeIntegrationIn",
+        re.compile(_key("nodeIntegrationIn(?:SubFrames|Worker)") + _TRUE),
+    ),
+    ("EGK-JS-REMOTE-MODULE", "enableRemoteModule", re.compile(_key("enableRemoteModule") + _TRUE)),
+    ("EGK-JS-WEBVIEW-TAG", "webviewTag", re.compile(_key("webviewTag") + _TRUE)),
+    (
+        "EGK-JS-EXPERIMENTAL-FEATURES",
+        "experimentalFeatures",
+        re.compile(_key("experimentalFeatures") + _TRUE),
+    ),
+    ("EGK-JS-OPEN-EXTERNAL", "openExternal", re.compile(r"shell\s*\.\s*openExternal\s*\(")),
+)
+_WEB_PREFERENCES = re.compile(r"webPreferences")
+_SANDBOX_OFF = re.compile(_key("sandbox") + _FALSE)
+_WEB_PREFERENCES_WINDOW = 1200
+MAX_MATCHES_PER_RULE = 10
+
+
+def _boundary(text: str, start: int) -> bool:
+    """True when the match is not the tail of a longer identifier (an opening quote is skipped)."""
+    before = start - 1
+    if before >= 0 and text[before] in "\"'":
+        before -= 1
+    return before < 0 or not (text[before].isalnum() or text[before] in "_$")
+
+
+@dataclass(frozen=True)
+class FuseWire:
+    offset: int
+    version: int
+    states: dict[str, str]
+    raw: str
+
+
+def read_fuse_wires(data: Bytes, limit: int = 4) -> list[FuseWire]:
+    wires: list[FuseWire] = []
+    start = 0
+    while len(wires) < limit:
+        index = data.find(SENTINEL, start)
+        if index < 0:
+            break
+        start = index + 1
+        header = index + len(SENTINEL)
+        if header + 2 > len(data):
+            break
+        version = data[header]
+        length = data[header + 1]
+        wire = data[header + 2 : header + 2 + length]
+        states: dict[str, str] = {}
+        for position, value in enumerate(wire):
+            name = FUSE_NAMES[position] if position < len(FUSE_NAMES) else f"Fuse{position}"
+            states[name] = _STATES.get(value, f"unknown(0x{value:02x})")
+        raw = "".join(chr(value) if 0x20 < value < 0x7F else "?" for value in wire)
+        wires.append(FuseWire(offset=index, version=version, states=states, raw=raw))
+    return wires
+
+
+def find_electron_versions(data: Bytes) -> list[str]:
+    versions: set[str] = set()
+    start = 0
+    for _ in range(_MAX_VERSION_PROBES):
+        index = data.find(_VERSION_PREFIX, start)
+        if index < 0:
+            break
+        start = index + 1
+        match = _VERSION.match(data[index : index + 64])
+        if match:
+            versions.add(match.group(1).decode("ascii"))
+    return sorted(versions)
+
+
+_URL_HOST = re.compile(r"(?:https?|wss?)://([A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63})+)(?![A-Za-z0-9-])")
+# Namespace and spec URLs that appear in almost every bundle but are not network endpoints.
+_NOT_ENDPOINTS = {
+    "www.w3.org",
+    "w3.org",
+    "schemas.xmlsoap.org",
+    "schemas.microsoft.com",
+    "json-schema.org",
+}
+
+
+def find_endpoints(text: str) -> set[str]:
+    hosts: set[str] = set()
+    for match in _URL_HOST.finditer(text):
+        host = match.group(1).lower().rstrip(".")
+        if host in _NOT_ENDPOINTS or host.startswith(("localhost", "127.")) or host.endswith(".localhost"):
+            continue
+        if host.replace(".", "").isdigit():
+            continue
+        hosts.add(host)
+    return hosts
+
+
+def _locate(text: str, path: str, start: int, end: int) -> Location:
+    line = text.count("\n", 0, start) + 1
+    column = start - (text.rfind("\n", 0, start) + 1) + 1
+    snippet = clean_text(" ".join(text[max(0, start - 40) : end + 40].split()), 160)
+    return Location(path=path, line=line, column=column, snippet=snippet)
+
+
+def scan_javascript(text: str, path: str) -> list[tuple[str, Location]]:
+    hits: list[tuple[str, Location]] = []
+    for rule_id, keyword, pattern in JS_RULES:
+        if keyword not in text:
+            continue
+        count = 0
+        for match in pattern.finditer(text):
+            if not _boundary(text, match.start()):
+                continue
+            count += 1
+            if count > MAX_MATCHES_PER_RULE:
+                break
+            hits.append((rule_id, _locate(text, path, match.start(), match.end())))
+    if "sandbox" not in text:
+        return hits
+    sandbox_hits: set[int] = set()
+    for preferences in _WEB_PREFERENCES.finditer(text):
+        window = text[preferences.end() : preferences.end() + _WEB_PREFERENCES_WINDOW]
+        sandbox = next((m for m in _SANDBOX_OFF.finditer(window) if _boundary(window, m.start())), None)
+        if sandbox is None:
+            continue
+        absolute = preferences.end() + sandbox.start()
+        if absolute in sandbox_hits or len(sandbox_hits) >= MAX_MATCHES_PER_RULE:
+            continue
+        sandbox_hits.add(absolute)
+        end = preferences.end() + sandbox.end()
+        hits.append(("EGK-JS-SANDBOX-OFF", _locate(text, path, absolute, end)))
+    return hits