From f03dbd277b17c8d919f39e236c5fb0c81b17d7e0 Mon Sep 17 00:00:00 2001 From: "Ioannis L." <44038245+blitzcrieg1@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:33:38 +0200 Subject: [PATCH] Inspect Python startup declarations in local wheels Surface executable .pth lines and .start declarations before installation. Bound archive reads, keep declaration contents out of the report, and report digest comparisons separately from publisher provenance. --- CHANGELOG.md | 5 + README.md | 3 +- apps/orchestrator/agentmetry/cli/__init__.py | 21 +- .../agentmetry/core/scanner/wheel.py | 309 ++++++++++++++++++ apps/orchestrator/tests/test_wheel_scanner.py | 180 ++++++++++ docs/scanner.md | 38 ++- 6 files changed, 550 insertions(+), 6 deletions(-) create mode 100644 apps/orchestrator/agentmetry/core/scanner/wheel.py create mode 100644 apps/orchestrator/tests/test_wheel_scanner.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e42732f..c7cff97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,11 @@ separately (currently `1.2.0`) and changes additively. It shows unresolved references and partial coverage without exposing command text or running repository code. +- **Python wheel startup check.** `agentmetry scan --wheel PATH` inventories + executable `.pth` lines and Python 3.15 `.start` declarations in a local + wheel. It reports SHA-256 and optionally checks an expected digest without + installing, extracting or executing the package. + ## [0.12.2] - 2026-11-16 A privacy release. Both fixes apply only with command logging or full-argument diff --git a/README.md b/README.md index a3038c6..dc9483f 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ agentmetry scan # MCP servers your agents launch, and AGENTS. agentmetry scan ~/.claude/skills # skills, rules and CLAUDE.md files: text that instructs the model instead of describing a tool agentmetry scan npm:NAME # one package name, before you install it agentmetry scan --preflight ./repo # startup hooks, project MCP and setup declarations +agentmetry scan --wheel ./example-1.0-py3-none-any.whl # Python startup declarations ``` It reads files and nothing else: it never starts a server or fetches a package. It exits 1 on a finding, and "no findings" means these checks found nothing, never that something is safe. The checks and their limits are in [docs/scanner.md](docs/scanner.md). @@ -157,7 +158,7 @@ These are the numbers from commands, not from a slide. That block is what `agentmetry benchmark` printed from the PyPI 0.9.4 package and from this tree. "Rules covered 13" counts rule ids named in corpus expectations. Twelve of those are published rules. The thirteenth is the experimental rule. Two published rules have no corpus case: `host-subagent-swarm-burst` and `off-hours-activity`. They are named in `apps/orchestrator/tools/generate_sigma_pack.py` so the Sigma pack still has them. -Expected collection: 2534 tests collected (`pytest --collect-only -q` from `apps/orchestrator`). The +Expected collection: 2545 tests collected (`pytest --collect-only -q` from `apps/orchestrator`). The [0.12.1 release PR's CI run](https://github.com/blitzcrieg1/agentmetry/actions/runs/43610018759) on Python 3.12 reported 2443 passed and 19 skipped on Linux and macOS, 2456 passed and 6 skipped on Windows, and 83% line coverage on Linux diff --git a/apps/orchestrator/agentmetry/cli/__init__.py b/apps/orchestrator/agentmetry/cli/__init__.py index a05eebd..2b32895 100644 --- a/apps/orchestrator/agentmetry/cli/__init__.py +++ b/apps/orchestrator/agentmetry/cli/__init__.py @@ -1205,9 +1205,9 @@ def cmd_mcp(args: argparse.Namespace) -> int: def cmd_scan(args: argparse.Namespace) -> int: - """Check agent dependencies or inventory repository execution declarations. + """Check agent dependencies and offline execution declarations. - Exits 1 when anything is found and 2 when nothing could be read. Unlike + A finding can exit 1 and an incomplete scan can exit 2. Unlike `mcp` and `posture`, which a health check runs in the background, this is run on purpose before something is installed, so a finding should stop the script that ran it. Preflight reports partial coverage with exit 2. @@ -1215,7 +1215,17 @@ def cmd_scan(args: argparse.Namespace) -> int: import json as _json from pathlib import Path as _Path - if args.preflight is not None: + if args.expected_sha256 is not None and args.wheel is None: + print("--expected-sha256 requires --wheel PATH", file=sys.stderr) + return 2 + if args.wheel is not None: + if args.target is not None or args.project is not None or args.known is not None: + print("--wheel PATH cannot be combined with a target, --project or --known", file=sys.stderr) + return 2 + from agentmetry.core.scanner.wheel import inspect_wheel + + report = inspect_wheel(_Path(args.wheel), expected_sha256=args.expected_sha256) + elif args.preflight is not None: if args.target is not None or args.project is not None or args.known is not None: print("--preflight PATH cannot be combined with a target, --project or --known", file=sys.stderr) return 2 @@ -1828,7 +1838,10 @@ def main(argv: list[str] | None = None) -> int: ) scan.add_argument("--project", default=None, help="project root whose MCP config to include (default: cwd)") scan.add_argument("--known", default=None, help="file of extra known package names, one per line (npm:/pypi: or bare)") - scan.add_argument("--preflight", metavar="PATH", help="inventory repository execution declarations") + scan_mode = scan.add_mutually_exclusive_group() + scan_mode.add_argument("--preflight", metavar="PATH", help="inventory repository execution declarations") + scan_mode.add_argument("--wheel", metavar="PATH", help="inspect Python startup declarations in a local wheel") + scan.add_argument("--expected-sha256", metavar="HEX", help="compare a local wheel with a SHA-256 you supply") scan.add_argument("--json", action="store_true", help="print the report as JSON") otel = sub.add_parser( "otel", help="receive Claude Code's native OpenTelemetry stream (no hooks needed)" diff --git a/apps/orchestrator/agentmetry/core/scanner/wheel.py b/apps/orchestrator/agentmetry/core/scanner/wheel.py new file mode 100644 index 0000000..761b718 --- /dev/null +++ b/apps/orchestrator/agentmetry/core/scanner/wheel.py @@ -0,0 +1,309 @@ +"""Inspect Python startup declarations in a wheel without installing it.""" + +from __future__ import annotations + +import hashlib +import json +import os +import re +import stat +import struct +import zipfile +import zlib +from dataclasses import asdict, dataclass, field +from io import StringIO +from pathlib import Path +from typing import Any, BinaryIO + +from agentmetry.core.scanner.preflight import _linked + +MAX_ARCHIVE_BYTES = 128 * 1024**2 +MAX_DIRECTORY_BYTES = 4 * 1024**2 +MAX_MEMBERS = 4096 +MAX_STARTUP_FILES = 128 +MAX_STARTUP_BYTES = 64 * 1024 +MAX_TOTAL_STARTUP_BYTES = 4 * 1024**2 +MAX_PRINTED_LINES = 32 +MAX_NOTICES = 64 +EOCD = struct.Struct("<4s4H2IH") +EOCD_SIGNATURE = b"PK\x05\x06" +SHA256_PATTERN = re.compile(r"[0-9a-fA-F]{64}") + + +class IncompleteWheel(ValueError): + """A stable report code for a format or limit the scan cannot handle.""" + + +@dataclass(frozen=True) +class StartupFile: + member: str + kind: str + path_entries: int + direct_imports: int + indented_imports: int + entry_points: int + declaration_lines: list[int] + + @property + def actionable(self) -> int: + return self.direct_imports + self.indented_imports + self.entry_points + + +@dataclass +class WheelReport: + target: str + sha256: str | None = None + hash_check: str = "not_requested" + files: list[StartupFile] = field(default_factory=list) + unobserved: list[dict[str, str]] = field(default_factory=list) + omitted_notices: int = 0 + + def note(self, reason: str, member: str | None = None) -> None: + if len(self.unobserved) == MAX_NOTICES: + self.omitted_notices += 1 + return + entry = {"reason": reason} + if member is not None: + entry["member"] = member + self.unobserved.append(entry) + + @property + def needs_review(self) -> bool: + return self.hash_check == "mismatch" or any(item.actionable for item in self.files) + + def exit_code(self) -> int: + if self.unobserved or self.omitted_notices: + return 2 + return 1 if self.needs_review else 0 + + def to_json(self) -> dict[str, Any]: + return {"mode": "wheel_startup", **asdict(self), "provenance": "not_verified", + "review_recommended": self.needs_review, + "coverage": "partial" if self.exit_code() == 2 else "supported_locations_inspected"} + + def lines(self) -> list[str]: + out = [f"Agentmetry wheel startup check: {json.dumps(self.target)}", + f" SHA-256: {self.sha256 or 'unavailable'}", + f" Expected hash: {self.hash_check} | Publisher provenance: not verified"] + for item in self.files: + counts = ( + f"{item.direct_imports} import lines, {item.indented_imports} indented import lines, " + f"{item.path_entries} path entries" if item.kind == "pth" + else f"{item.entry_points} startup entry points" + ) + markers = ", ".join(map(str, item.declaration_lines)) + where = f" | lines {markers}" if markers else "" + if item.actionable > len(item.declaration_lines): + where += f" (+{item.actionable - len(item.declaration_lines)} more)" + out.append(f" {json.dumps(item.member)} | {counts}{where}") + for entry in self.unobserved: + at = f" {json.dumps(entry['member'])}" if "member" in entry else "" + out.append(f" Unobserved:{at} | {entry['reason']}") + if self.omitted_notices: + out.append(f" {self.omitted_notices} additional notices omitted") + if self.needs_review: + out.append(" Review the declared startup behavior or the expected hash mismatch.") + out.append(" This check reads declarations. It does not establish what executes or whether the wheel is trusted.") + return out + + +def _directory_size(stream: BinaryIO, size: int) -> int: + """Bound the central directory before ZipFile indexes it.""" + max_tail = 65_535 + EOCD.size + 20 + stream.seek(max(0, size - max_tail)) + tail = stream.read(max_tail) + at = tail.rfind(EOCD_SIGNATURE) + if at < 0 or len(tail) - at < EOCD.size: + raise IncompleteWheel("invalid_archive") + _, disk, directory_disk, disk_count, count, byte_count, offset, comment_size = EOCD.unpack_from(tail, at) + if at + EOCD.size + comment_size != len(tail): + raise IncompleteWheel("invalid_archive") + if disk or directory_disk or disk_count != count: + raise IncompleteWheel("unsupported_archive_layout") + # Zip64 may override the fields above. Decline it before ZipFile reads a + # different directory. Ordinary wheels within these limits use classic ZIP. + if at >= 20 and tail[at - 20:at - 16] == b"PK\x06\x07": + raise IncompleteWheel("unsupported_archive_layout") + if count > MAX_MEMBERS or byte_count > MAX_DIRECTORY_BYTES: + raise IncompleteWheel("directory_limit_reached") + if offset + byte_count != size - len(tail) + at: + raise IncompleteWheel("unsupported_archive_layout") + return count + + +def _member_parts(info: zipfile.ZipInfo) -> list[str] | None: + raw = info.orig_filename + name = raw[:-1] if raw.endswith("/") else raw + parts = name.split("/") + if ( + not name or len(name) > 512 or "\\" in name or ":" in name + or any(ord(char) < 32 or ord(char) == 127 for char in name) + or any(part in ("", ".", "..") for part in parts) + ): + return None + return parts + + +def _startup_kind(parts: list[str]) -> str | None: + if len(parts) != 1 and not ( + len(parts) == 3 and parts[0].endswith(".data") and parts[1] in ("purelib", "platlib") + ): + return None + name = parts[-1] + if name.startswith("."): + return None + for extension in (".pth", ".start"): + if name.endswith(extension): + return extension[1:] + return None + + +def _read_startup(archive: zipfile.ZipFile, item: zipfile.ZipInfo) -> str: + if item.compress_type not in (zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED): + raise IncompleteWheel("unsupported_member_compression") + if item.flag_bits & 1: + raise IncompleteWheel("encrypted_startup_member") + mode = stat.S_IFMT(item.external_attr >> 16) if item.create_system == 3 else 0 + if mode not in (0, stat.S_IFREG): + raise IncompleteWheel("non_regular_startup_member") + with archive.open(item) as stream: + raw = stream.read(item.file_size + 1) + if len(raw) != item.file_size: + raise IncompleteWheel("invalid_startup_member_size") + return raw.decode("utf-8-sig") + + +def _count_lines( + text: str, member: str, kind: str, report: WheelReport, +) -> StartupFile: + paths = direct = indented = entry_points = 0 + marks: list[int] = [] + invalid_entry = False + for number, line in enumerate(StringIO(text, newline=None), 1): + trimmed = line.strip() + if not trimmed or trimmed.startswith("#"): + continue + if kind == "start": + module, separator, function = trimmed.partition(":") + if not separator or not all(part.isidentifier() for part in (module + "." + function).split(".")): + invalid_entry = True + continue + entry_points += 1 + elif line.startswith(("import ", "import\t")): + direct += 1 + elif trimmed.startswith(("import ", "import\t")): + # CPython 3.15 strips leading space before the prefix check. + indented += 1 + else: + paths += 1 + continue + if len(marks) < MAX_PRINTED_LINES: + marks.append(number) + if invalid_entry: + report.note("unsupported_start_entry", member) + return StartupFile(member, kind, paths, direct, indented, entry_points, marks) + + +def _inspect_directory( + archive: zipfile.ZipFile, count: int, prefix: str, report: WheelReport, +) -> None: + members = archive.infolist() + if len(members) != count or len(members) > MAX_MEMBERS: + report.note("directory_count_mismatch") + return + seen: set[str] = set() + startup: list[tuple[zipfile.ZipInfo, str]] = [] + for item in members: + parts = _member_parts(item) + if parts is None: + report.note("invalid_member_path") + continue + if item.filename in seen: + report.note("duplicate_member_path", item.filename) + continue + if item.is_dir(): + continue + seen.add(item.filename) + kind = _startup_kind(parts) + if kind is not None: + # pip also moves files from noncanonical .data directories. + if len(parts) == 3 and parts[0] != prefix + ".data": + report.note("unexpected_wheel_data_directory", item.filename) + startup.append((item, kind)) + if not all(f"{prefix}.dist-info/{name}" in seen for name in ("METADATA", "WHEEL", "RECORD")): + report.note("wheel_metadata_missing") + if len(startup) > MAX_STARTUP_FILES: + report.note("startup_file_limit_reached") + remaining = MAX_TOTAL_STARTUP_BYTES + for item, kind in sorted(startup, key=lambda row: row[0].filename)[:MAX_STARTUP_FILES]: + if item.file_size > min(MAX_STARTUP_BYTES, remaining): + report.note("startup_read_limit_reached", item.filename) + continue + remaining -= item.file_size + try: + text = _read_startup(archive, item) + except UnicodeDecodeError: + report.note("unknown_startup_text_encoding", item.filename) + except IncompleteWheel as exc: + report.note(str(exc), item.filename) + except (OSError, RuntimeError, zipfile.BadZipFile, zlib.error, EOFError, ValueError, struct.error): + report.note("startup_member_unreadable", item.filename) + else: + report.files.append(_count_lines(text, item.filename, kind, report)) + + +def inspect_wheel(target: Path, expected_sha256: str | None = None) -> WheelReport: + report = WheelReport(str(target)) + if expected_sha256 is not None: + report.hash_check = "unavailable" + if not SHA256_PATTERN.fullmatch(expected_sha256): + report.note("invalid_expected_sha256") + return report + fields = target.name.removesuffix(".whl").split("-") + if target.suffix != ".whl" or len(fields) not in (5, 6) or not all(fields): + report.note("expected_wheel_filename") + return report + try: + info = target.lstat() + if _linked(info) or not stat.S_ISREG(info.st_mode): + report.note("expected_regular_wheel") + return report + flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0) + with os.fdopen(os.open(target, flags), "rb") as stream: + before = os.fstat(stream.fileno()) + if not stat.S_ISREG(before.st_mode) or _linked(before): + report.note("expected_regular_wheel") + return report + if before.st_size > MAX_ARCHIVE_BYTES: + report.note("wheel_size_limit_reached") + return report + digest = hashlib.sha256() + remaining = before.st_size + while remaining: + chunk = stream.read(min(remaining, 1024**2)) + if not chunk: + report.note("wheel_changed_during_scan") + return report + digest.update(chunk) + remaining -= len(chunk) + report.sha256 = digest.hexdigest() + if expected_sha256 is not None: + report.hash_check = "match" if expected_sha256.lower() == report.sha256 else "mismatch" + try: + count = _directory_size(stream, before.st_size) + with zipfile.ZipFile(stream) as archive: + _inspect_directory(archive, count, "-".join(fields[:2]), report) + except IncompleteWheel as exc: + report.note(str(exc)) + except (OSError, RuntimeError, ValueError, zipfile.BadZipFile, zlib.error, EOFError, struct.error): + report.note("wheel_directory_unreadable") + after = os.fstat(stream.fileno()) + if (before.st_size, before.st_mtime_ns) != (after.st_size, after.st_mtime_ns): + report.sha256 = None + if expected_sha256 is not None: + report.hash_check = "unavailable" + report.files.clear() + report.note("wheel_changed_during_scan") + except OSError: + report.note("wheel_unreadable") + return report diff --git a/apps/orchestrator/tests/test_wheel_scanner.py b/apps/orchestrator/tests/test_wheel_scanner.py new file mode 100644 index 0000000..0039a94 --- /dev/null +++ b/apps/orchestrator/tests/test_wheel_scanner.py @@ -0,0 +1,180 @@ +"""Synthetic wheel startup declarations. The archives are never installed.""" + +import hashlib +import json +from zipfile import ZIP_DEFLATED, ZipFile + +from agentmetry.core.scanner import wheel + +PREFIX = "example-1.0" +WHEEL_NAME = f"{PREFIX}-py3-none-any.whl" + + +def make_wheel(tmp_path, files): + path = tmp_path / WHEEL_NAME + with ZipFile(path, "w", ZIP_DEFLATED) as archive: + archive.writestr(f"{PREFIX}.dist-info/METADATA", "Metadata-Version: 2.1\nName: example\nVersion: 1.0\n") + archive.writestr(f"{PREFIX}.dist-info/WHEEL", "Wheel-Version: 1.0\nRoot-Is-Purelib: true\nTag: py3-none-any\n") + archive.writestr(f"{PREFIX}.dist-info/RECORD", "") + for name, contents in files.items(): + archive.writestr(name, contents) + return path + + +def test_import_declarations_report_locations_without_code_or_paths(tmp_path): + path = make_wheel(tmp_path, {"example.pth": ( + "# header\r\nsynthetic-path-value\r\nimport sys # synthetic-private-text\r\n" + "import\tmath\r\n import random\r\n" + )}) + + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 1 + assert report.files == [wheel.StartupFile("example.pth", "pth", 1, 2, 1, 0, [3, 4, 5])] + assert report.to_json()["coverage"] == "supported_locations_inspected" + for rendered in (json.dumps(report.to_json()), "\n".join(report.lines())): + assert "synthetic-path-value" not in rendered + assert "synthetic-private-text" not in rendered + assert "import random" not in rendered + + +def test_path_only_entries_do_not_raise_review(tmp_path): + path = make_wheel(tmp_path, { + "paths.pth": b"\xef\xbb\xbf# comment\nfirst_path\n\nsecond_path\rthird_path\n" + b"path_with_vertical_tab\x0bimport sys", + ".hidden.pth": "import sys", + "example/nested.pth": "import sys", + f"{PREFIX}.data/scripts/script.pth": "import sys", + }) + + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 0 + assert report.files == [wheel.StartupFile("paths.pth", "pth", 4, 0, 0, 0, [])] + + +def test_detects_start_and_pth_in_wheel_site_directories(tmp_path): + pure = f"{PREFIX}.data/purelib/example.start" + platform = f"{PREFIX}.data/platlib/example.pth" + path = make_wheel(tmp_path, { + "example.start": "# Root\nexample.setup:initialize\n", + pure: "\nexample.setup:begin\n", + platform: "import sys\n", + }) + + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 1 + entries = {item.member: item for item in report.files} + assert entries["example.start"] == wheel.StartupFile("example.start", "start", 0, 0, 0, 1, [2]) + assert entries[pure].entry_points == 1 + assert entries[platform].direct_imports == 1 + assert "example.setup" not in json.dumps(report.to_json()) + + +def test_hash_check_does_not_establish_provenance(tmp_path): + path = make_wheel(tmp_path, {}) + digest = hashlib.sha256(path.read_bytes()).hexdigest() + + matching = wheel.inspect_wheel(path, digest.upper()) + assert matching.exit_code() == 0 + assert matching.to_json()["provenance"] == "not_verified" + assert matching.sha256 == digest + assert matching.hash_check == "match" + + mismatch = wheel.inspect_wheel(path, "a" * 64) + assert mismatch.exit_code() == 1 + assert mismatch.hash_check == "mismatch" + + invalid = wheel.inspect_wheel(path, "synthetic-invalid-digest") + assert invalid.exit_code() == 2 + assert invalid.hash_check == "unavailable" + assert "synthetic-invalid-digest" not in json.dumps(invalid.to_json()) + + +def test_malformed_archive_is_incomplete(tmp_path): + path = tmp_path / WHEEL_NAME + path.write_text("synthetic-not-a-zip", encoding="utf-8") + + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 2 + assert report.unobserved == [{"reason": "invalid_archive"}] + assert report.to_json()["coverage"] == "partial" + + +def test_missing_wheel_records_are_reported(tmp_path): + path = tmp_path / WHEEL_NAME + with ZipFile(path, "w") as archive: + archive.writestr("paths.pth", "synthetic_paths") + + assert wheel.inspect_wheel(path).unobserved == [{"reason": "wheel_metadata_missing"}] + + +def test_unexpected_data_directory_is_still_inspected(tmp_path): + member = "other-1.0.data/purelib/example.pth" + report = wheel.inspect_wheel(make_wheel(tmp_path, {member: "import sys"})) + + assert report.exit_code() == 2 + assert report.needs_review + assert report.files[0].member == member + assert report.unobserved == [{"reason": "unexpected_wheel_data_directory", "member": member}] + + +def test_invalid_startup_text_does_not_hide_valid_declarations(tmp_path): + path = make_wheel(tmp_path, { + "bad.pth": b"\xff", + "mixed.start": "synthetic-invalid-value\nexample.setup:initialize\n", + }) + + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 2 + assert report.needs_review + assert report.files[0].declaration_lines == [2] + assert report.unobserved == [ + {"reason": "unknown_startup_text_encoding", "member": "bad.pth"}, + {"reason": "unsupported_start_entry", "member": "mixed.start"}, + ] + + +def test_member_and_display_limits(tmp_path, monkeypatch): + monkeypatch.setattr(wheel, "MAX_STARTUP_BYTES", 80) + monkeypatch.setattr(wheel, "MAX_PRINTED_LINES", 2) + path = make_wheel(tmp_path, { + "large.pth": b"x" * 81, + "short.pth": "import sys\n" * 4, + }) + + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 2 + assert report.unobserved == [{"reason": "startup_read_limit_reached", "member": "large.pth"}] + assert report.files[0].direct_imports == 4 + assert report.files[0].declaration_lines == [1, 2] + + +def test_directory_limit_does_not_index_archive(tmp_path, monkeypatch): + path = make_wheel(tmp_path, {"paths.pth": "synthetic_paths"}) + monkeypatch.setattr(wheel, "MAX_MEMBERS", 3) + + def unexpected_archive(*args, **kwargs): + raise AssertionError("the directory exceeded the limit before indexing") + + monkeypatch.setattr(wheel.zipfile, "ZipFile", unexpected_archive) + report = wheel.inspect_wheel(path) + + assert report.exit_code() == 2 + assert report.unobserved == [{"reason": "directory_limit_reached"}] + + +def test_wheel_cli_supports_json_and_validates_options(tmp_path, capsys): + from agentmetry.cli import main + + path = make_wheel(tmp_path, {"example.pth": "import sys"}) + assert main(["scan", "--wheel", str(path), "--json"]) == 1 + result = json.loads(capsys.readouterr().out) + assert result["mode"] == "wheel_startup" + assert result["files"][0]["member"] == "example.pth" + assert main(["scan", "--wheel", str(path), "--project", str(tmp_path)]) == 2 + assert main(["scan", "--expected-sha256", result["sha256"]]) == 2 diff --git a/docs/scanner.md b/docs/scanner.md index e0ce855..df1fc1c 100644 --- a/docs/scanner.md +++ b/docs/scanner.md @@ -11,12 +11,14 @@ a server and never fetches a package. agentmetry scan # MCP servers, and instruction files in Downloads, Desktop and ~ agentmetry scan ./skills # a file or folder: skills, rules, a saved tools/list agentmetry scan --preflight ./repo # inventory declarations that can start execution +agentmetry scan --wheel ./example-1.0-py3-none-any.whl # inspect Python startup declarations agentmetry scan pypi:request # one package name agentmetry scan --json # the report as JSON agentmetry scan --known names.txt # add your own package names (npm:/pypi: or bare) ``` -Exit codes: **0** no findings, **1** findings, **2** nothing could be read. Unlike +The dependency and instruction scanner exits **0** for no findings, **1** for +findings and **2** if nothing could be read. Unlike `agentmetry mcp` and `agentmetry posture`, which a health check runs in the background and which exit 0 with findings, `scan` is run on purpose before an install, so a finding stops the script that ran it. @@ -60,6 +62,40 @@ none, and **2** on an incomplete inventory. Script reference statuses describe what could be located and do not change manifest coverage. This inventory cannot see hooks from an installed plugin, downloaded dependencies or child processes. +## Python wheel startup check + +Run `agentmetry scan --wheel PATH` on a local `.whl` before installing it. +Use `--json` for a structured report and `--expected-sha256 HEX` to compare +the artifact with an independently obtained digest. The report always labels +publisher provenance as unverified. A digest match establishes byte identity +with the artifact represented by the expected hash. [PyPI attestations](https://docs.pypi.org/attestations/) + +The scanner reads archive metadata and startup declarations at the wheel root +and directly under `.data/purelib` or `.data/platlib` directories. It reports +partial coverage if a startup file sits in a noncanonical `.data` directory. +It distinguishes executable `.pth` import lines from path entries and counts +`.start` entry points. Python 3.15 also recognizes indented import lines and +can ignore `.pth` imports when a matching `.start` file exists. The report +lists where declarations appear and leaves runtime behavior to the installed +interpreter and its configuration. [Wheel format](https://packaging.python.org/en/latest/specifications/binary-distribution-format/), [Python 3.14 site](https://docs.python.org/3.14/library/site.html), [Python 3.15 site](https://docs.python.org/3.15/library/site.html) + +The report includes archive member names, counts and up to 32 executable +declaration line numbers per file. It omits line contents. The scanner uses +bounded reads and leaves the wheel uninstalled and unextracted. Limits are +128 MiB per wheel, 4 MiB and 4,096 entries in its ZIP directory, 128 startup +files, 64 KiB per startup file and 4 MiB total startup text. Startup text is +read as UTF-8 with optional BOM. Archive layouts and startup content outside +the supported formats produce a partial report when encountered. + +The wheel check exits **0** after inspecting supported locations without an +executable declaration or hash mismatch, **1** when either requires review +and **2** when the report is incomplete. Incomplete reports can also contain +findings. Path-only entries are shown without raising a finding. Normal +packages can declare startup code. This check covers the two named startup +file formats, with package code, other auto-import mechanisms such as +`sitecustomize`, transitive dependencies and verification of attestations +outside its scope. + ## Existing scan checks ### Text that instructs the model (#188)