diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a23adf4..d492f03 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -16,7 +16,7 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest] + os: [ubuntu-latest, windows-latest, macos-latest] python: ['3.10', '3.14'] steps: - name: Check out repository diff --git a/README.md b/README.md index d0eacbe..fb23514 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,58 @@ The reviewed fixed line is `4.x`; future lines remain unknown rather than extrap | `attacker_controlled_readable_git_configuration_file` | attacker-controlled readable Git configuration file | | `remote_operation_loads_unsafe_configuration` | remote operation loads unsafe configuration | -Each observation is boolean or null, is unverified, and never changes the package-version result. No source search, taint analysis, reachability test, or runtime evaluation is performed. Absent observations do not establish mitigation. +Each observation is boolean or null, is unverified, and never changes the package-version result. Optional lexical source inspection is separate. No taint analysis, reachability test or runtime evaluation is performed. Absent observations do not establish mitigation. + +## Dependency and source evidence + +```sh +python simplegit_rce_check.py --npm-lock examples/package-lock.example.json --format json +python simplegit_rce_check.py --source examples/source.example.js --source-root examples --format html +python simplegit_rce_check.py --installed-package path/to/node_modules/simple-git/package.json --format json +``` + +`--npm-lock` reads explicitly named npm lock/shrinkwrap v1/v2/v3 JSON. Nested +instances and aliases carrying an explicit package name remain separate. +Resolved versions are not proof of deployment; linked packages, missing/qualified +versions, conflicting primary/legacy lock records and unsupported coverage keep +uncertainty. Conflicting version candidates are retained. When no determinable +instance is found, the report includes an unknown coverage observation, never proof of absence. +`--installed-package` reads the name/version of an explicitly selected installed +simple-git manifest, without running scripts or importing the module. Manifest +metadata cannot attest that a serving process loads that package. + +`--source` explicitly selects JS/TS files and requires `--source-root` for +relative locations. No directory traversal or execution occurs. Simple literal +CommonJS/ES imports (default/named aliases and namespace `simpleGit`), factory +calls, directly assigned client spellings, and clone/mirror argument shapes +produce lexical review candidates. Factory `config` and actual call arguments +are inspected separately; an unrelated same-file `customArgs` or config object +cannot establish a flow. Argument labels describe literal containers/strings or +dynamic expressions, not input trust. Identifiers named trustedConfig or +request.body do not prove trusted input or attacker control. + +Shadowing, reassignment, computed syntax, templates (including interpolation), +callbacks, chained methods, execution order and regex/division ambiguity require +manual review. Source rows always remain `unknown` with `not_tested` +exploitability and unfilled operator observations; they never inherit the status +of a separately supplied version/manifest/lock instance. When no supported candidate +is found, the report includes an explicit unknown coverage row rather than an absence verdict. + +All new input modes share existing 4 MiB/file, 100-file and 10,000-result limits. +Lock traversal is limited to 64 dependency levels and 10,000 metadata entries; +source is limited to 200,000 tokens/file and 4,096 tokens per inspected argument +window. Source files must resolve within the selected root. Output protection +covers every new input and its aliases even with --force. Stable copies are +recommended; file checks are not a filesystem sandbox. The checker performs no +Git, npm, network, application or sandbox execution. + +JSON/CSV schema 1.1 adds `version_candidates`, `source_path`, `source_line`, +`source_operation`, `source_argument_shapes`, `source_factory_options`, +`source_config_argument` and `source_coverage`. HTML includes candidates and +locations in escaped evidence notes. Source strings/snippets, registry URLs and +manifest scripts are not included in reports. The standalone executable bundles +its lexer from vm2-nesting-check commit 1618874 under the same licensing; no +companion checkout is needed. Version rules and their date are unchanged. ## Evidence and reports @@ -58,3 +109,5 @@ CSV `record_type=result` rows are asset observations. A zero-result report has a CSV rejects NUL characters before writing a report. An interruption after a complete report is published preserves that report and exits 130. If an interrupt leaves file publication indeterminate, the checker exits 130 without retrying. Inspect the output before retrying; the diagnostic does not establish whether publication succeeded. + +Npm metadata grammar: [official package-lock reference](https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/), reviewed 2026-10-25. Lockfile URLs and scripts are not collected. diff --git a/SHA256SUMS b/SHA256SUMS index 0b530e1..730ab1c 100644 --- a/SHA256SUMS +++ b/SHA256SUMS @@ -1 +1 @@ -ee68fe79b82fcb34ddba2a877e2ae079e3da3589ab61401282de7857833cec14 simplegit_rce_check.py +7adf4d42a2e3a42873886e56420dd9240b9d44650685f69e2d4ec2f852a00640 simplegit_rce_check.py diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md index 90fc879..02c2ea2 100644 --- a/docs/IMPLEMENTATION.md +++ b/docs/IMPLEMENTATION.md @@ -5,3 +5,7 @@ Implemented offline package-version evidence checker, with independent source/se Local verification: 13 tests, CLI help, documented synthetic inputs, checksum validation and whitespace checks. Hosted CI must pass for the exact final PR head before merge; a local pass is not a hosted result. The advisory metadata now describes the implemented rule and preserves its original disabled research state under research_origin. No live traffic, application execution, exploit verification or deployed-target assessment is claimed. Reported fixed versions do not attest installed patches; unknown evidence remains unknown. + +## Dependency/source extension (2026-10-25) + +Adds explicit installed simple-git manifests, bounded npm locks v1/v2/v3 with instance/conflict/link uncertainty, and lexical import-associated clone/mirror candidates. Source evidence never establishes taint, runtime configuration or a patch verdict. Relative locations, argument/config shapes, output parity and protected standalone operation have synthetic tests. Schema 1.1 is documented in README/REFERENCE. Primary advisory bounds are unchanged. Exact-head hosted CI and review remain separate release evidence. diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 0721312..e0cde3a 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1,4 +1,4 @@ -# Evidence and CLI reference +# simplegit-rce-check Offline evidence checker for **CVE-2026-102826 — simple-git configuration include command injection**. Python 3.10+, standard library only. The executable can be copied alone. It never contacts websites, imports application code, runs a package manager, or executes exploit payloads. @@ -36,7 +36,58 @@ The reviewed fixed line is `4.x`; future lines remain unknown rather than extrap | `attacker_controlled_readable_git_configuration_file` | attacker-controlled readable Git configuration file | | `remote_operation_loads_unsafe_configuration` | remote operation loads unsafe configuration | -Each observation is boolean or null, is unverified, and never changes the package-version result. No source search, taint analysis, reachability test, or runtime evaluation is performed. Absent observations do not establish mitigation. +Each observation is boolean or null, is unverified, and never changes the package-version result. Optional lexical source inspection is separate. No taint analysis, reachability test or runtime evaluation is performed. Absent observations do not establish mitigation. + +## Dependency and source evidence + +```sh +python simplegit_rce_check.py --npm-lock examples/package-lock.example.json --format json +python simplegit_rce_check.py --source examples/source.example.js --source-root examples --format html +python simplegit_rce_check.py --installed-package path/to/node_modules/simple-git/package.json --format json +``` + +`--npm-lock` reads explicitly named npm lock/shrinkwrap v1/v2/v3 JSON. Nested +instances and aliases carrying an explicit package name remain separate. +Resolved versions are not proof of deployment; linked packages, missing/qualified +versions, conflicting primary/legacy lock records and unsupported coverage keep +uncertainty. Conflicting version candidates are retained. When no determinable +instance is found, the report includes an unknown coverage observation, never proof of absence. +`--installed-package` reads the name/version of an explicitly selected installed +simple-git manifest, without running scripts or importing the module. Manifest +metadata cannot attest that a serving process loads that package. + +`--source` explicitly selects JS/TS files and requires `--source-root` for +relative locations. No directory traversal or execution occurs. Simple literal +CommonJS/ES imports (default/named aliases and namespace `simpleGit`), factory +calls, directly assigned client spellings, and clone/mirror argument shapes +produce lexical review candidates. Factory `config` and actual call arguments +are inspected separately; an unrelated same-file `customArgs` or config object +cannot establish a flow. Argument labels describe literal containers/strings or +dynamic expressions, not input trust. Identifiers named trustedConfig or +request.body do not prove trusted input or attacker control. + +Shadowing, reassignment, computed syntax, templates (including interpolation), +callbacks, chained methods, execution order and regex/division ambiguity require +manual review. Source rows always remain `unknown` with `not_tested` +exploitability and unfilled operator observations; they never inherit the status +of a separately supplied version/manifest/lock instance. When no supported candidate +is found, the report includes an explicit unknown coverage row rather than an absence verdict. + +All new input modes share existing 4 MiB/file, 100-file and 10,000-result limits. +Lock traversal is limited to 64 dependency levels and 10,000 metadata entries; +source is limited to 200,000 tokens/file and 4,096 tokens per inspected argument +window. Source files must resolve within the selected root. Output protection +covers every new input and its aliases even with --force. Stable copies are +recommended; file checks are not a filesystem sandbox. The checker performs no +Git, npm, network, application or sandbox execution. + +JSON/CSV schema 1.1 adds `version_candidates`, `source_path`, `source_line`, +`source_operation`, `source_argument_shapes`, `source_factory_options`, +`source_config_argument` and `source_coverage`. HTML includes candidates and +locations in escaped evidence notes. Source strings/snippets, registry URLs and +manifest scripts are not included in reports. The standalone executable bundles +its lexer from vm2-nesting-check commit 1618874 under the same licensing; no +companion checkout is needed. Version rules and their date are unchanged. ## Evidence and reports @@ -51,6 +102,12 @@ Exit 0: completed run; 1: potentially affected with `--fail-on-finding`; 2: argu - https://github.com/steveukx/git-js/security/advisories/GHSA-g4wm-2vf7-vfgr - https://github.com/advisories/GHSA-g4wm-2vf7-vfgr -[Synthetic report](docs/example-report.html), [reference](docs/REFERENCE.md), [implementation status](docs/IMPLEMENTATION.md), [AGENTS](AGENTS.md), [contribution terms](CONTRIBUTING.md), [security policy](SECURITY.md), [license](LICENSE), [dual licensing](LICENSING.md). Bounded input and reporting helpers are bundled from the reviewed Node.js checker at `74aa57ba5df05c34d17ae67912cd26ec2335201b`, with package-specific range comparison and the mixed-whitespace CSV fix. No companion repository is needed at runtime. +[Synthetic report](example-report.html), [reference](REFERENCE.md), [implementation status](IMPLEMENTATION.md), [AGENTS](../AGENTS.md), [contribution terms](../CONTRIBUTING.md), [security policy](../SECURITY.md), [license](../LICENSE), [dual licensing](../LICENSING.md). Bounded input and reporting helpers are bundled from the reviewed Node.js checker at `74aa57ba5df05c34d17ae67912cd26ec2335201b`, with package-specific range comparison and the mixed-whitespace CSV fix. No companion repository is needed at runtime. CSV `record_type=result` rows are asset observations. A zero-result report has a `record_type=summary` row carrying completeness, schema, rule date, CVE and `not_tested`; it is not an asset finding. + +CSV rejects NUL characters before writing a report. An interruption after a complete report is published preserves that report and exits 130. + +If an interrupt leaves file publication indeterminate, the checker exits 130 without retrying. Inspect the output before retrying; the diagnostic does not establish whether publication succeeded. + +Npm metadata grammar: [official package-lock reference](https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/), reviewed 2026-10-25. Lockfile URLs and scripts are not collected. diff --git a/examples/package-lock.example.json b/examples/package-lock.example.json new file mode 100644 index 0000000..977a02e --- /dev/null +++ b/examples/package-lock.example.json @@ -0,0 +1 @@ +{"lockfileVersion":3,"packages":{"node_modules/simple-git":{"version":"3.36.0"}}} diff --git a/examples/source.example.js b/examples/source.example.js new file mode 100644 index 0000000..2f2bfb8 --- /dev/null +++ b/examples/source.example.js @@ -0,0 +1,4 @@ +// Synthetic text fixture; never executed. +import git from 'simple-git'; +const client = git({config: operatorSuppliedConfig}); +client.clone(repository, destination, customArgs); diff --git a/simplegit_rce_check.py b/simplegit_rce_check.py index 91abe23..f9b34f5 100644 --- a/simplegit_rce_check.py +++ b/simplegit_rce_check.py @@ -21,8 +21,8 @@ from pathlib import Path TOOL_NAME = "simplegit-rce-check" -TOOL_VERSION = "1.0.0" -REPORT_SCHEMA_VERSION = "1.0" +TOOL_VERSION = "1.1.0" +REPORT_SCHEMA_VERSION = "1.1" MAX_INPUT_BYTES = 4 * 1024 * 1024 MAX_ENTRIES = 10000 MAX_FIELD = 512 @@ -146,9 +146,11 @@ def assess_version(package_version="", *, version_candidates=None, build_source= PRECONDITION_KEYS = tuple(key for key, _ in PRECONDITIONS) OBSERVATIONS = {True: "reported_true", False: "reported_false", None: "not_reported"} INVENTORY_FIELDS = {"schema_version", "package", "label", "package_version", "build_source", *PRECONDITION_KEYS} +SOURCE_COLUMNS = ["source_path", "source_line", "source_operation", "source_argument_shapes", "source_factory_options", "source_config_argument", "source_coverage"] CSV_COLUMNS = ["record_type", "input_label", "input_source", "package_version", "build_source", "status", "version_status", "fixed_version", "exploitability", "evidence_type", "evidence_confidence", "cve", "rules_as_of", *[f"precondition_{key}" for key in PRECONDITION_KEYS], "recommendation", "notes", "sources", "report_schema_version", "report_complete"] +CSV_COLUMNS += SOURCE_COLUMNS + ["version_candidates"] STATUS_ORDER = {"potentially_affected": 0, "unknown": 2, "fixed_version_reported": 3} STATUS_LABELS = {"potentially_affected": "Potentially affected", "unknown": "Unknown", "fixed_version_reported": "Fixed version reported"} @@ -226,6 +228,356 @@ def _read_bounded(path): return raw.decode("utf-8-sig") +# Bounded lexer bundled from vm2-nesting-check 1618874; same CompleteTech licensing. +def _js_tokens(text): + """Bounded lexical hints, not a JavaScript parser. Never retain source strings.""" + tokens = [] + index, line = 0, 1 + while index < len(text): + start = index + char = text[index] + if char.isspace(): + line += char == "\n" + index += 1 + continue + if text.startswith("//", index): + end = text.find("\n", index) + index = len(text) if end < 0 else end + continue + if text.startswith("/*", index): + end = text.find("*/", index + 2) + if end < 0: + raise ValueError("Unterminated JavaScript comment") + line += text.count("\n", index, end + 2) + index = end + 2 + continue + token_line = line + if char in "\"'`": + index += 1 + while index < len(text): + if text[index] == "\\": + index += 2 + elif text[index] == char: + index += 1 + break + else: + index += 1 + else: + raise ValueError("Unterminated JavaScript string or template") + raw = text[start + 1:index - 1] + value = "@template" if char == "`" else "@" + raw if raw in {"simple-git", "config", "customArgs"} else "@string" + line += text.count("\n", start, index) + elif char == "/" and (not tokens or tokens[-1][0] in {"=", "(", "[", "{", ":", ",", ";", "return", "=>"}): + # Regex bodies are opaque. Templates (including interpolations) are + # also opaque; the report always states incomplete lexical coverage. + index += 1 + in_class = False + while index < len(text): + c = text[index] + if c == "\\": + index += 2 + continue + if c == "[": + in_class = True + elif c == "]": + in_class = False + elif c == "/" and not in_class: + index += 1 + break + elif c == "\n": + raise ValueError("Unterminated JavaScript regex candidate") + index += 1 + else: + raise ValueError("Unterminated JavaScript regex candidate") + value = "@regex" + elif char.isascii() and (char.isalpha() or char in "_$"): + index += 1 + while index < len(text) and text[index].isascii() and (text[index].isalnum() or text[index] in "_$"): + index += 1 + value = text[start:index] + elif text.startswith("...", index): + value, index = "...", index + 3 + else: + value, index = char, index + 1 + tokens.append((value, token_line)) + if len(tokens) > 200000: + raise ValueError("Source exceeds the 200,000 token limit") + return tokens + + + + +def _token_pairs(values): + stack, pairs = [], {} + for index, value in enumerate(values): + if value in {"{", "[", "("}: + stack.append(index) + elif value in {"}", "]", ")"}: + if not stack or values[stack[-1]] != {"}": "{", "]": "[", ")": "("}[value]: + raise ValueError("Unbalanced JavaScript delimiters") + opening = stack.pop() + pairs[opening] = index + if stack: + raise ValueError("Unbalanced JavaScript delimiters") + return pairs + + +def _segments(values, start, end, pairs): + """Top-level argument/property slices with a bounded inspection window.""" + if end - start > 4096: + return None + parts, index, first = [], start, start + while index < end: + if values[index] in {"(", "[", "{"} and index in pairs: + index = pairs[index] + 1 + continue + if values[index] == ",": + parts.append((first, index)) + first = index + 1 + index += 1 + if first < end: + parts.append((first, end)) + return parts + + +def _argument_shape(values, start, end, pairs): + if start >= end: + return "missing" + if end == start + 1 and values[start] == "@string": + return "literal_string" + if values[start] in {"[", "{"} and pairs.get(start) == end - 1: + if "..." in values[start:end]: + return "dynamic_or_unsupported" + return "array_literal" if values[start] == "[" else "object_literal" + return "dynamic_or_unsupported" + + +def _simplegit_factories(values): + factories, namespaces = set(), set() + ident = r"[A-Za-z_$][A-Za-z0-9_$]*" + for index, value in enumerate(values): + if value not in {"const", "let", "var", "import"}: + continue + end = index + 1 + while end < min(len(values), index + 100) and values[end] != ";": + end += 1 + statement = " ".join(values[index:end]) + if value == "import": + m = re.match(r"import (" + ident + r") from @simple-git(?: |$)", statement) + if m: + factories.add(m[1]) + m = re.match(r"import \* as (" + ident + r") from @simple-git(?: |$)", statement) + if m: + namespaces.add(m[1]) + m = re.match(r"import \{ (.*?) \} from @simple-git(?: |$)", statement) + if m: + for member in re.split(r"\s*,\s*", m[1]): + member = re.fullmatch(r"simpleGit(?: as (" + ident + r"))?", member) + if member: + factories.add(member[1] or "simpleGit") + else: + m = re.match(r"(?:const|let|var) (" + ident + r") = require \( @simple-git \)(.*)", statement) + if m and (not m[2].startswith(" .") or re.match(r" \. simpleGit(?: |$)", m[2])): + factories.add(m[1]) + m = re.match(r"(?:const|let|var) \{ (.*?) \} = require \( @simple-git \)", statement) + if m: + for member in re.split(r"\s*,\s*", m[1]): + member = re.fullmatch(r"simpleGit(?: : (" + ident + r"))?", member) + if member: + factories.add(member[1] or "simpleGit") + return factories, namespaces + + +def _factory_shapes(values, opening, pairs): + closing = pairs[opening] + args = _segments(values, opening + 1, closing, pairs) + if args is None: + return "dynamic_or_unsupported", "unknown" + if not args: + return "no_arguments", "not_observed" + start, end = args[0] + shape = _argument_shape(values, start, end, pairs) + if shape != "object_literal": + return shape, "unknown" + props = _segments(values, start + 1, end - 1, pairs) + keys, config = set(), "not_observed" + for first, last in props or []: + if last - first < 3 or values[first + 1] != ":": + return shape, "unknown" + key = values[first].removeprefix("@") + if key in keys: + return shape, "unknown" + keys.add(key) + if key == "config": + config = _argument_shape(values, first + 2, last, pairs) + return shape, config + + +def scan_source_text(text, relative_path): + tokens = _js_tokens(text) + values = [token[0] for token in tokens] + pairs = _token_pairs(values) + factories, namespaces = _simplegit_factories(values) + clients, direct = {}, {} + for index, value in enumerate(values[:-1]): + opening = None + if value in factories and values[index + 1] == "(": + opening = index + 1 + elif (index + 3 < len(values) and value in namespaces + and values[index + 1:index + 4] == [".", "simpleGit", "("]): + opening = index + 3 + elif index + 4 < len(values) and values[index:index + 5] == ["require", "(", "@simple-git", ")", "("]: + opening = index + 4 + if opening is None or opening not in pairs: + continue + shape = _factory_shapes(values, opening, pairs) + direct[pairs[opening]] = shape + if index >= 2 and values[index - 1] == "=": + clients[values[index - 2]] = shape + rows = [] + for index in range(len(values) - 3): + if values[index + 1] != "." or values[index + 2] not in {"clone", "mirror"} or values[index + 3] != "(": + continue + shape = direct.get(index) if values[index] == ")" else clients.get(values[index]) + if shape is None: + continue + args = _segments(values, index + 4, pairs[index + 3], pairs) + shapes = "unknown" if args is None else ",".join(_argument_shape(values, a, b, pairs) for a, b in args) or "no_arguments" + row = assess_entry(relative_path, "source", "") + row.update(evidence_type="lexical_source_candidate", source_path=relative_path, + source_line=tokens[index + 2][1], source_operation=values[index + 2], + source_argument_shapes=shapes, source_factory_options=shape[0], + source_config_argument=shape[1], source_coverage="limited_lexical") + row["notes"].append( + f"Source candidate {relative_path}:{tokens[index + 2][1]}: {values[index + 2]}; arguments={shapes}; " + f"factory_options={shape[0]}; config={shape[1]}. Constants, variables and object/array shapes do not prove trust or taint. " + "Shadowing, reassignment, execution order, templates, callbacks and unsupported syntax need manual review; no match is not absence.") + rows.append(row) + if len(rows) > MAX_ENTRIES: + raise ValueError("Too many source candidates") + if not rows: + row = assess_entry(relative_path, "source", "") + row.update(evidence_type="source_coverage", source_path=relative_path, source_line="", + source_operation="not_observed", source_argument_shapes="unknown", + source_factory_options="unknown", source_config_argument="unknown", source_coverage="limited_lexical") + row["notes"].append("No supported import-associated clone/mirror candidate found; package presence and input trust remain unknown.") + rows.append(row) + return rows + + +def load_source(path, root, budget, out): + budget.add_file() + relative = Path(path).resolve().relative_to(Path(root).resolve()).as_posix() + _bounded_text(relative, "Source relative path") + rows = scan_source_text(_read_bounded(path), relative) + budget.add_entries(len(rows)) + out.extend(rows) + + +def _metadata_json(path): + def unique(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError("Duplicate metadata key") + result[key] = value + return result + def reject(_): + raise ValueError("Non-finite metadata number") + result = json.loads(_read_bounded(path), object_pairs_hook=unique, parse_constant=reject) + if not isinstance(result, dict): + raise ValueError("Package metadata must be a JSON object") + return result + + +def load_installed_package(path, budget, out): + budget.add_file() + data = _metadata_json(path) + if data.get("name") != "simple-git": + raise ValueError("Installed manifest must identify simple-git") + version = _bounded_text(data.get("version", ""), "Package version") + budget.add_entries(1) + row = assess_entry("simple-git installed manifest", "installed_manifest", version) + row["evidence_type"] = "installed_manifest_version" + row["notes"].append("Explicitly selected installed package manifest; not evidence that a deployed process loads it. Scripts and URLs are not collected or executed.") + out.append(row) + + +def _legacy_instances(dependencies): + pending = [(dependencies, "", 0)] + result, count = {}, 0 + while pending: + entries, prefix, depth = pending.pop() + if not isinstance(entries, dict) or depth > 64: + raise ValueError("Unsupported dependency tree or depth") + for name, item in entries.items(): + count += 1 + if count > MAX_ENTRIES or not isinstance(item, dict): + raise ValueError("Invalid or excessive dependency metadata") + location = prefix + "node_modules/" + name + _bounded_text(location, "Dependency location") + if location.startswith("/") or "\\" in location or ":" in location or any(p in {".", ".."} for p in location.split("/")): + raise ValueError("Dependency location must be a relative npm path") + if name == "simple-git" or item.get("name") == "simple-git" or str(item.get("version", "")).startswith("npm:simple-git@"): + result[location] = item + if "dependencies" in item: + pending.append((item["dependencies"], location + "/", depth + 1)) + return result + + +def load_npm_lock(path, budget, out): + budget.add_file() + data = _metadata_json(path) + lock_version = data.get("lockfileVersion") + if type(lock_version) is not int or lock_version not in {1, 2, 3}: + raise ValueError("Only npm lockfile versions 1, 2 and 3 are supported") + legacy = _legacy_instances(data.get("dependencies", {})) + if lock_version == 1 and "packages" in data: + raise ValueError("Conflicting lockfile version and package metadata") + instances = legacy + conflict = False + if lock_version in {2, 3}: + packages = data.get("packages") + if not isinstance(packages, dict) or len(packages) > MAX_ENTRIES: + raise ValueError("Lockfile packages must be a bounded object") + instances = {} + for location, item in packages.items(): + if not isinstance(item, dict) or len(location) > MAX_FIELD: + raise ValueError("Invalid package metadata") + if location.startswith("/") or "\\" in location or ":" in location or any(p in {".", ".."} for p in location.split("/")): + raise ValueError("Package location must be a relative npm path") + if "link" in item and type(item["link"]) is not bool: + raise ValueError("Package link flag must be boolean") + if location == "node_modules/simple-git" or location.endswith("/node_modules/simple-git") or item.get("name") == "simple-git": + instances[location] = item + if legacy: + conflict = {k: v.get("version") for k, v in instances.items()} != {k: v.get("version") for k, v in legacy.items()} + if conflict: + instances = {**legacy, **instances} + rows = [] + for location, item in sorted(instances.items()): + if "name" in item and item["name"] != "simple-git": + raise ValueError("Conflicting simple-git package identity") + if "link" in item and type(item["link"]) is not bool: + raise ValueError("Package link flag must be boolean") + version = _bounded_text(item.get("version", ""), "Dependency version") + row = assess_entry(location, "npm_lockfile", "" if item.get("link") or conflict else version) + row["evidence_type"] = "npm_lockfile_resolved_version" + if item.get("link") or conflict: + row["notes"].append("Linked or conflicting lockfile metadata cannot establish a package version; inspect the installed manifest.") + row["version_candidates"] = sorted({version, _bounded_text(legacy.get(location, {}).get("version", ""), "Legacy dependency version")} - {""}) + if row["version_candidates"]: + row["notes"].append("Reported version candidates: " + ", ".join(row["version_candidates"])) + row["notes"].append("Lockfile-resolved instance, not deployed runtime attestation. Registry URLs, scripts and package data are not collected.") + rows.append(row) + if not rows: + row = assess_entry("npm lockfile coverage", "npm_lockfile", "") + row["notes"].append("No determinable simple-git instance found in supported lock metadata; package absence is not established.") + rows.append(row) + budget.add_entries(len(rows)) + out.extend(rows) + + class Budget: """Counts entries and files while loading, so limits hold before rows pile up.""" @@ -520,10 +872,19 @@ def _validate_arguments(args): _bounded_text(version, "--version") if len(args.package_version) > MAX_ENTRIES: raise ValueError(f"A run is limited to {MAX_ENTRIES:,} inputs") - if len(args.inventory) + len(args.csv_list) > MAX_FILES: + inputs = (*args.inventory, *args.csv_list, *args.source, *args.npm_lock, *args.installed_package) + if len(inputs) > MAX_FILES: raise ValueError(f"A run is limited to {MAX_FILES} input files") - for path in (*args.inventory, *args.csv_list): + if args.source and args.source_root is None: + raise ValueError("--source requires --source-root for relative evidence paths") + if args.source_root is not None and not args.source_root.is_dir(): + raise ValueError("--source-root must be a directory") + for path in inputs: _require_regular_file(path) + for path in args.source: + if path.suffix.lower() not in {".js", ".cjs", ".mjs", ".ts", ".cts", ".mts", ".jsx", ".tsx"}: + raise ValueError("Source must be an explicitly selected JS/TS file") + path.resolve().relative_to(args.source_root.resolve()) if args.output is not None: output = args.output parent = output.parent @@ -536,10 +897,10 @@ def _validate_arguments(args): raise ValueError("Output is a dangling or looping symbolic link") if output.is_dir() or (output.exists() and not stat.S_ISREG(os.stat(output).st_mode)): raise ValueError("Output must be a regular file path") - for path in (*args.inventory, *args.csv_list): + for path in inputs: if os.path.samefile(output, path): raise ValueError("--output must differ from every input file, even with --force") - for path in (*args.inventory, *args.csv_list): + for path in inputs: if os.path.realpath(output) == os.path.realpath(path): raise ValueError("--output must differ from every input file, even with --force") @@ -562,6 +923,14 @@ def main(argv=None): help="JSON object or array of entries (see docs/REFERENCE.md); repeatable") parser.add_argument("--csv-list", action="append", default=[], type=Path, metavar="FILE", help="CSV with a package_version column and optional label, build_source and precondition columns; repeatable") + parser.add_argument("--npm-lock", action="append", default=[], type=Path, metavar="FILE", + help="Explicit npm package-lock/shrinkwrap JSON (versions 1, 2, 3); never invokes npm") + parser.add_argument("--installed-package", action="append", default=[], type=Path, metavar="FILE", + help="Explicit installed simple-git package.json; reads only name/version metadata") + parser.add_argument("--source", action="append", default=[], type=Path, metavar="FILE", + help="Explicit JS/TS file for lexical clone/mirror candidates; repeatable, never executed") + parser.add_argument("--source-root", type=Path, metavar="DIR", + help="Required with --source; evidence paths are relative to this directory") parser.add_argument("--format", choices=("csv", "json", "html"), default="csv", help="Output format (default: csv)") parser.add_argument("--output", type=Path, help="Save report to a new file; default: stdout") parser.add_argument("--force", action="store_true", help="Replace an existing output file explicitly") @@ -569,8 +938,8 @@ def main(argv=None): parser.add_argument("--fail-on-finding", action="store_true", help="Exit 1 for potentially_affected results (errors still exit 2)") args = parser.parse_args(argv) - if not (args.package_version or args.inventory or args.csv_list): - parser.error("provide --version, --inventory or --csv-list") + if not (args.package_version or args.inventory or args.csv_list or args.npm_lock or args.installed_package or args.source): + parser.error("provide --version, --inventory, --csv-list, --npm-lock, --installed-package or --source") rows = [] state = {"validated": False, "published": False, "stdout_started": False} options = {"force": args.force, "format": args.format, "brand": args.brand, "state": state} @@ -587,6 +956,12 @@ def main(argv=None): load_inventory(path, budget, rows) for path in args.csv_list: load_csv_list(path, budget, rows) + for path in args.npm_lock: + load_npm_lock(path, budget, rows) + for path in args.installed_package: + load_installed_package(path, budget, rows) + for path in args.source: + load_source(path, args.source_root, budget, rows) save_report(args.output, rows, complete=True, **options) except KeyboardInterrupt: if not state["validated"]: diff --git a/test_evidence.py b/test_evidence.py new file mode 100644 index 0000000..89cec35 --- /dev/null +++ b/test_evidence.py @@ -0,0 +1,202 @@ +"""Synthetic installed dependency, lockfile and lexical source regressions.""" +import contextlib +import csv +import io +import json +from pathlib import Path +import subprocess +import sys +import tempfile +import unittest +from unittest import mock + +import simplegit_rce_check as c + + +class EvidenceTests(unittest.TestCase): + def cli(self, *args): + with contextlib.redirect_stdout(io.StringIO()) as out, contextlib.redirect_stderr(io.StringIO()) as err: + code = c.main(list(args)) + return code, out.getvalue(), err.getvalue() + + def scan(self, code): + return c.scan_source_text(code, "src/worker.ts") + + def test_import_aliases_instances_and_direct_factory_chains(self): + for declaration, factory in [ + ("import git from 'simple-git';", "git"), + ("import {simpleGit as git} from 'simple-git';", "git"), + ("import * as lib from 'simple-git';", "lib.simpleGit"), + ("const git=require('simple-git');", "git"), + ("const {simpleGit: git}=require('simple-git');", "git"), + ]: + with self.subTest(declaration=declaration): + rows = self.scan(declaration + "\nconst client=" + factory + "(); client.clone('repo','dest',customArgs);") + row = rows[0] + self.assertEqual("lexical_source_candidate", row["evidence_type"]) + self.assertEqual("clone", row["source_operation"]) + self.assertEqual("literal_string,literal_string,dynamic_or_unsupported", row["source_argument_shapes"]) + self.assertEqual(2, row["source_line"]) + self.assertEqual("unknown", row["status"]) + self.assertEqual("not_tested", row["exploitability"]) + self.assertTrue(all(row["precondition_" + k] == "not_reported" for k in c.PRECONDITION_KEYS)) + self.assertEqual("mirror", self.scan("import git from 'simple-git'; git().mirror(repo);")[0]["source_operation"]) + self.assertEqual("clone", self.scan("const client=require('simple-git')(); client.clone(repo);")[0]["source_operation"]) + + def test_factory_config_and_constants_are_shapes_not_trust(self): + cases = [ + ("{config:['constant']}", "array_literal"), + ("{config:request.options}", "dynamic_or_unsupported"), + ("{config:trustedConfiguration}", "dynamic_or_unsupported"), + ("{config:[] , ...options}", "unknown"), + ("{config:[], config:external}", "unknown"), + ] + for options, config in cases: + with self.subTest(options=options): + row = self.scan("import git from 'simple-git'; const client=git(" + options + "); client.clone(repo,dest,['constant']);")[0] + self.assertEqual(config, row["source_config_argument"]) + self.assertEqual("unknown", row["status"]) + row = self.scan("import git from 'simple-git'; const customArgs=req.body; const other={config:req.body}; git().clone('repo');")[0] + self.assertEqual("not_observed", row["source_config_argument"]) + self.assertEqual("literal_string", row["source_argument_shapes"]) + + def test_unrelated_clone_imports_comments_strings_and_regex(self): + source = r''' + import git from 'other'; + const client=git(); client.clone(repo); + // const git=require('simple-git'); git().clone(repo); + const text="require('simple-git'); git().clone(repo)"; + const regex=/git\(\)\.clone/; + const template=`git().clone(repo)`; + ''' + rows = self.scan(source) + self.assertEqual(["source_coverage"], [r["evidence_type"] for r in rows]) + self.assertEqual("source_coverage", self.scan("import git from 'simple-git'; other.clone(repo);")[0]["evidence_type"]) + + def test_source_never_publishes_literals_or_attests_shadowed_flow(self): + row = self.scan("import git from 'simple-git'; function f(git) {git().clone('PRIVATE-SYNTHETIC-TEXT');}")[0] + self.assertNotIn("PRIVATE-SYNTHETIC-TEXT", json.dumps(row)) + self.assertIn("Shadowing", " ".join(row["notes"])) + self.assertEqual("insufficient", row["evidence_confidence"]) + + def test_npm_lock_versions_transitive_instances_and_privacy(self): + for version in [1, 2, 3]: + with self.subTest(lockversion=version), tempfile.TemporaryDirectory() as directory: + path = Path(directory) / "lock.json" + data = {"lockfileVersion": version} + if version == 1: + data["dependencies"] = {"parent": {"version": "1.0.0", "dependencies": {"simple-git": {"version": "3.36.0", "resolved": "https://PRIVATE-SYNTHETIC.invalid/token"}}}, "simple-git": {"version": "4.0.0"}} + else: + data["packages"] = {"": {}, "node_modules/parent/node_modules/simple-git": {"version": "3.36.0"}, "node_modules/simple-git": {"version": "4.0.0", "resolved": "https://PRIVATE-SYNTHETIC.invalid/token"}} + path.write_text(json.dumps(data), encoding="utf-8") + code, out, err = self.cli("--npm-lock", str(path), "--format", "json", "--fail-on-finding") + self.assertEqual((1, ""), (code, err)) + self.assertEqual({"potentially_affected", "fixed_version_reported"}, {r["status"] for r in json.loads(out)["results"]}) + self.assertNotIn("PRIVATE-SYNTHETIC", out) + self.assertNotIn(directory, out) + + def test_lock_aliases_links_conflicts_and_absence_keep_uncertainty(self): + cases = [ + ({"node_modules/alias": {"name": "simple-git", "version": "4.0.0"}}, None, "fixed_version_reported"), + ({"node_modules/simple-git": {"version": "4.0.0", "link": True}}, None, "unknown"), + ({"node_modules/simple-git": {"version": "^4.0.0"}}, None, "unknown"), + ({"node_modules/simple-git": {"version": "4.0.0"}}, {"simple-git": {"version": "3.36.0"}}, "unknown"), + ({}, None, "unknown"), + ] + with tempfile.TemporaryDirectory() as directory: + path = Path(directory) / "lock.json" + for packages, legacy, status in cases: + data = {"lockfileVersion": 2, "packages": packages} + if legacy is not None: + data["dependencies"] = legacy + path.write_text(json.dumps(data), encoding="utf-8") + code, out, _ = self.cli("--npm-lock", str(path), "--format", "json") + self.assertEqual(0, code) + self.assertEqual({status}, {r["status"] for r in json.loads(out)["results"]}) + if legacy: + self.assertEqual(["3.36.0", "4.0.0"], json.loads(out)["results"][0]["version_candidates"]) + + def test_malformed_lock_types_keys_locations_and_links_reject_before_output(self): + cases = [ + '{"lockfileVersion":3,"packages":{},"packages":{}}', + '{"lockfileVersion":3,"packages":{},"x":NaN}', + json.dumps({"lockfileVersion": True, "packages": {}}), + json.dumps({"lockfileVersion": 3, "packages": []}), + json.dumps({"lockfileVersion": 3, "packages": {"../node_modules/simple-git": {"version": "4.0.0"}}}), + json.dumps({"lockfileVersion": 3, "packages": {"node_modules/simple-git": {"name": "other", "version": "4.0.0"}}}), + ] + for flag in [None, 0, "", [], {}]: + cases.append(json.dumps({"lockfileVersion": 3, "packages": {"node_modules/simple-git": {"version": "4.0.0", "link": flag}}})) + with tempfile.TemporaryDirectory() as directory: + path = Path(directory) / "lock.json" + for data in cases: + path.write_text(data, encoding="utf-8") + code, out, _ = self.cli("--npm-lock", str(path), "--format", "json") + self.assertEqual((2, ""), (code, out)) + + def test_installed_manifest_identity_and_version_evidence_only(self): + with tempfile.TemporaryDirectory() as directory: + path = Path(directory) / "package.json" + path.write_text(json.dumps({"name": "simple-git", "version": "4.0.0", "scripts": {"preinstall": "NEVER-EXECUTE"}}), encoding="utf-8") + with mock.patch.object(subprocess, "run", side_effect=AssertionError("must not execute")): + code, out, _ = self.cli("--installed-package", str(path), "--format", "json") + self.assertEqual(0, code) + self.assertEqual("fixed_version_reported", json.loads(out)["results"][0]["status"]) + self.assertNotIn("NEVER-EXECUTE", out) + path.write_text('{"name":"other","version":"4.0.0"}', encoding="utf-8") + self.assertEqual(2, self.cli("--installed-package", str(path))[0]) + + def test_output_protects_every_new_input_mode_even_with_force(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + for mode, name, data in [("--npm-lock", "lock.json", '{"lockfileVersion":3,"packages":{}}'), ("--installed-package", "package.json", '{"name":"simple-git","version":"4.0.0"}'), ("--source", "source.js", "import git from 'simple-git'; git().clone(repo);")]: + path = root / name + path.write_text(data, encoding="utf-8") + args = [mode, str(path), "--output", str(path), "--force"] + if mode == "--source": + args += ["--source-root", directory] + self.assertEqual(2, self.cli(*args)[0]) + self.assertEqual(data, path.read_text(encoding="utf-8")) + + def test_source_and_metadata_work_limits_and_missing_root(self): + for text in ["/*open", "'open", "({]", ";" * 200001]: + with self.assertRaises(ValueError): + self.scan(text) + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + source = root / "source.js" + source.write_text("import git from 'simple-git'; git().clone(repo);", encoding="utf-8") + self.assertEqual(2, self.cli("--source", str(source))[0]) + with mock.patch.object(c, "MAX_FILES", 1): + self.assertEqual(2, self.cli("--source", str(source), "--source", str(source), "--source-root", directory)[0]) + path = root / "lock.json" + tree = {"simple-git": {"version": "4.0.0"}} + for _ in range(66): + tree = {"p": {"dependencies": tree}} + path.write_text(json.dumps({"lockfileVersion": 1, "dependencies": tree}), encoding="utf-8") + self.assertEqual(2, self.cli("--npm-lock", str(path))[0]) + source.write_bytes(b" " * (c.MAX_INPUT_BYTES + 1)) + self.assertEqual(2, self.cli("--source", str(source), "--source-root", directory)[0]) + + def test_source_output_parity_relative_paths_and_standalone_copy(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + source = root / "source.ts" + source.write_text("import git from 'simple-git'; git().clone(repo,dest,options);", encoding="utf-8") + args = ["--source", str(source), "--source-root", directory] + code, out, _ = self.cli(*args, "--format", "json") + row = json.loads(out)["results"][0] + self.assertNotIn(directory, out) + self.assertEqual("source.ts", row["source_path"]) + _, out, _ = self.cli(*args, "--format", "csv") + self.assertEqual(row["source_argument_shapes"], list(csv.DictReader(io.StringIO(out)))[0]["source_argument_shapes"]) + _, out, _ = self.cli(*args, "--format", "html") + self.assertIn("source.ts:1", out) + checker = root / "checker.py" + checker.write_bytes(Path(c.__file__).read_bytes()) + result = subprocess.run([sys.executable, str(checker), *args, "--format", "json"], capture_output=True, text=True, check=True) + self.assertEqual("clone", json.loads(result.stdout)["results"][0]["source_operation"]) + + +if __name__ == "__main__": + unittest.main()