patchsight 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. patchsight/__init__.py +5 -0
  2. patchsight/cli.py +130 -0
  3. patchsight/db.py +221 -0
  4. patchsight/eval/__init__.py +1 -0
  5. patchsight/eval/confidence.py +169 -0
  6. patchsight/eval/metrics.py +134 -0
  7. patchsight/eval/parity.py +96 -0
  8. patchsight/eval/safety.py +54 -0
  9. patchsight/names.py +76 -0
  10. patchsight/pipeline/__init__.py +4 -0
  11. patchsight/pipeline/__main__.py +863 -0
  12. patchsight/pipeline/benchmarks/__init__.py +1 -0
  13. patchsight/pipeline/benchmarks/bundle.py +108 -0
  14. patchsight/pipeline/benchmarks/changedfuncs.py +275 -0
  15. patchsight/pipeline/benchmarks/dunlap.py +135 -0
  16. patchsight/pipeline/benchmarks/extraction.py +242 -0
  17. patchsight/pipeline/benchmarks/replay.py +187 -0
  18. patchsight/pipeline/benchmarks/splits.py +121 -0
  19. patchsight/pipeline/build_db.py +227 -0
  20. patchsight/pipeline/diffs/__init__.py +1 -0
  21. patchsight/pipeline/diffs/commits.py +109 -0
  22. patchsight/pipeline/diffs/github.py +177 -0
  23. patchsight/pipeline/diffs/hunks.py +120 -0
  24. patchsight/pipeline/diffs/mapping.py +203 -0
  25. patchsight/pipeline/diffs/paths.py +127 -0
  26. patchsight/pipeline/extract/__init__.py +1 -0
  27. patchsight/pipeline/extract/extractor.py +156 -0
  28. patchsight/pipeline/extract/prompt.py +219 -0
  29. patchsight/pipeline/extract/schema.py +40 -0
  30. patchsight/pipeline/extract/validate.py +81 -0
  31. patchsight/pipeline/fix_sample.py +384 -0
  32. patchsight/pipeline/http.py +143 -0
  33. patchsight/pipeline/ingest/__init__.py +1 -0
  34. patchsight/pipeline/ingest/aliases.py +76 -0
  35. patchsight/pipeline/ingest/ghsa_repo.py +80 -0
  36. patchsight/pipeline/ingest/osv.py +253 -0
  37. patchsight/pipeline/ingest/references.py +189 -0
  38. patchsight/pipeline/ingest/snapshot.py +146 -0
  39. patchsight/pipeline/llm/__init__.py +1 -0
  40. patchsight/pipeline/llm/client.py +288 -0
  41. patchsight/pipeline/llm/config.py +68 -0
  42. patchsight/pipeline/llm/tokens.py +74 -0
  43. patchsight/pipeline/pypi.py +64 -0
  44. patchsight/pipeline/week1.py +314 -0
  45. patchsight/py.typed +0 -0
  46. patchsight/scan/__init__.py +4 -0
  47. patchsight/scan/ast_scanner.py +270 -0
  48. patchsight/scan/dbcache.py +119 -0
  49. patchsight/scan/lockfiles/__init__.py +1 -0
  50. patchsight/scan/lockfiles/requirements.py +116 -0
  51. patchsight/scan/osv_client.py +80 -0
  52. patchsight/scan/report.py +90 -0
  53. patchsight/scan/run.py +43 -0
  54. patchsight/scan/verdicts.py +178 -0
  55. patchsight-0.1.0.dist-info/METADATA +104 -0
  56. patchsight-0.1.0.dist-info/RECORD +59 -0
  57. patchsight-0.1.0.dist-info/WHEEL +4 -0
  58. patchsight-0.1.0.dist-info/entry_points.txt +3 -0
  59. patchsight-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,119 @@
1
+ """Fetch and cache the published symbol database.
2
+
3
+ Releases are immutable files attached to GitHub releases. A small pointer,
4
+ ``releases/latest.json`` in the repository, names the current one with its SHA-256, so
5
+ rolling back is one commit that moves the pointer back.
6
+
7
+ ``update`` downloads over HTTPS only, verifies the SHA-256, checks the schema version by
8
+ opening the file, and only then replaces the cached copy, so a failed or tampered download
9
+ never takes the place of a working database.
10
+ """
11
+
12
+ import gzip
13
+ import hashlib
14
+ import os
15
+ import shutil
16
+ from datetime import datetime
17
+ from pathlib import Path
18
+ from typing import Literal
19
+
20
+ import httpx
21
+ from pydantic import BaseModel, ConfigDict
22
+
23
+ from patchsight.db import SCHEMA_VERSION, DatabaseError, SymbolDatabase
24
+
25
+ POINTER_URL = "https://raw.githubusercontent.com/professor3333/PatchSight/main/releases/latest.json"
26
+ _CHUNK = 1 << 20
27
+
28
+
29
+ class Pointer(BaseModel):
30
+ model_config = ConfigDict(frozen=True)
31
+
32
+ db_version: str
33
+ schema_version: int
34
+ url: str
35
+ sha256: str
36
+ size: int
37
+ built_at: datetime
38
+ records: int
39
+
40
+
41
+ def cache_dir() -> Path:
42
+ configured = os.environ.get("PATCHSIGHT_CACHE")
43
+ return Path(configured) if configured else Path.home() / ".cache" / "patchsight"
44
+
45
+
46
+ def default_db_path() -> Path:
47
+ configured = os.environ.get("PATCHSIGHT_DB")
48
+ return Path(configured) if configured else cache_dir() / "patchsight.sqlite"
49
+
50
+
51
+ def _https(url: str) -> str:
52
+ if not url.startswith("https://"):
53
+ raise DatabaseError(f"refusing a non-HTTPS database URL: {url}")
54
+ return url
55
+
56
+
57
+ def fetch_pointer(client: httpx.Client, url: str = POINTER_URL) -> Pointer:
58
+ response = client.get(_https(url))
59
+ if response.status_code == 404:
60
+ raise DatabaseError("no database has been published yet")
61
+ response.raise_for_status()
62
+ pointer = Pointer.model_validate_json(response.content)
63
+ if pointer.schema_version != SCHEMA_VERSION:
64
+ raise DatabaseError(
65
+ f"the published database uses schema {pointer.schema_version}, but this version of "
66
+ f"PatchSight reads schema {SCHEMA_VERSION}; upgrade PatchSight"
67
+ )
68
+ return pointer
69
+
70
+
71
+ def update(
72
+ client: httpx.Client | None = None,
73
+ pointer_url: str = POINTER_URL,
74
+ target: Path | None = None,
75
+ ) -> tuple[Literal["updated", "current"], Pointer]:
76
+ owns = client is None
77
+ client = client or httpx.Client(
78
+ timeout=httpx.Timeout(60.0, connect=15.0), follow_redirects=True
79
+ )
80
+ target = target or default_db_path()
81
+ record = target.with_name(target.name + ".json")
82
+ try:
83
+ pointer = fetch_pointer(client, pointer_url)
84
+ if target.exists() and record.exists():
85
+ current = Pointer.model_validate_json(record.read_text(encoding="utf-8"))
86
+ if current.sha256 == pointer.sha256:
87
+ return "current", pointer
88
+
89
+ target.parent.mkdir(parents=True, exist_ok=True)
90
+ download = target.with_name(target.name + ".download")
91
+ digest = hashlib.sha256()
92
+ with client.stream("GET", _https(pointer.url)) as response:
93
+ response.raise_for_status()
94
+ with download.open("wb") as handle:
95
+ for chunk in response.iter_bytes(_CHUNK):
96
+ handle.write(chunk)
97
+ digest.update(chunk)
98
+ if digest.hexdigest() != pointer.sha256:
99
+ download.unlink(missing_ok=True)
100
+ raise DatabaseError("the downloaded database does not match the published SHA-256")
101
+
102
+ unpacked = target.with_name(target.name + ".new")
103
+ if pointer.url.endswith(".gz"):
104
+ with gzip.open(download, "rb") as source, unpacked.open("wb") as sink:
105
+ shutil.copyfileobj(source, sink)
106
+ download.unlink()
107
+ else:
108
+ download.replace(unpacked)
109
+ try:
110
+ SymbolDatabase(unpacked).close() # checks the format and schema version
111
+ except DatabaseError:
112
+ unpacked.unlink(missing_ok=True)
113
+ raise
114
+ unpacked.replace(target)
115
+ record.write_text(pointer.model_dump_json(indent=2) + "\n", encoding="utf-8")
116
+ return "updated", pointer
117
+ finally:
118
+ if owns:
119
+ client.close()
@@ -0,0 +1 @@
1
+ """Lockfile parsers. Each returns the pinned dependencies, and the unpinned ones with why."""
@@ -0,0 +1,116 @@
1
+ """Parse ``requirements.txt`` files.
2
+
3
+ Only an exact ``==`` (or ``===``) pin gives a version that can be checked. Everything else
4
+ is reported as unpinned with the reason, never guessed. Includes (``-r``, ``-c``) are
5
+ followed relative to the including file; options, hashes and comments are ignored.
6
+ Environment markers are not evaluated, so a pin behind a marker is still checked.
7
+ """
8
+
9
+ from pathlib import Path
10
+
11
+ from packaging.requirements import InvalidRequirement, Requirement
12
+ from pydantic import BaseModel, ConfigDict
13
+
14
+ from patchsight.names import canonical_package_name
15
+
16
+
17
+ class Dependency(BaseModel):
18
+ model_config = ConfigDict(frozen=True)
19
+
20
+ name: str
21
+ raw_name: str
22
+ version: str | None
23
+ source: str
24
+ line: int
25
+ unpinned_reason: str | None = None
26
+
27
+
28
+ def _logical_lines(text: str) -> list[tuple[int, str]]:
29
+ """Join backslash continuations and strip comments, keeping the first line number."""
30
+ lines: list[tuple[int, str]] = []
31
+ buffer, start = "", 0
32
+ for number, raw in enumerate(text.splitlines(), 1):
33
+ stripped = raw.split(" #", 1)[0].rstrip() if not raw.lstrip().startswith("#") else ""
34
+ if not buffer:
35
+ start = number
36
+ if stripped.endswith("\\"):
37
+ buffer += stripped[:-1] + " "
38
+ continue
39
+ buffer += stripped
40
+ if buffer.strip():
41
+ lines.append((start, buffer.strip()))
42
+ buffer = ""
43
+ if buffer.strip():
44
+ lines.append((start, buffer.strip()))
45
+ return lines
46
+
47
+
48
+ def _pin(requirement: Requirement) -> tuple[str | None, str | None]:
49
+ specifiers = list(requirement.specifier)
50
+ if len(specifiers) == 1 and specifiers[0].operator in ("==", "==="):
51
+ version = specifiers[0].version
52
+ if "*" in version:
53
+ return None, f"wildcard pin {specifiers[0]}"
54
+ return version, None
55
+ if not specifiers:
56
+ return None, "no version specified"
57
+ return None, f"not an exact pin ({requirement.specifier})"
58
+
59
+
60
+ def parse(path: Path, _seen: frozenset[Path] = frozenset()) -> list[Dependency]:
61
+ """Every dependency in ``path`` and the files it includes, in file order."""
62
+ resolved = path.resolve()
63
+ if resolved in _seen:
64
+ return []
65
+ seen = _seen | {resolved}
66
+ source = path.as_posix()
67
+ found: list[Dependency] = []
68
+ for number, line in _logical_lines(path.read_text(encoding="utf-8")):
69
+ if line.startswith(("-r ", "-c ", "--requirement", "--constraint")):
70
+ target = line.split(maxsplit=1)[1] if " " in line else line.split("=", 1)[1]
71
+ include = path.parent / target.strip()
72
+ if include.exists():
73
+ found.extend(parse(include, seen))
74
+ continue
75
+ editable = line.startswith(("-e ", "--editable"))
76
+ if line.startswith("-") and not editable:
77
+ continue # --index-url, --hash continuation, --trusted-host and other options
78
+ if editable or "://" in line.split(";")[0] or line.startswith(("git+", ".", "/")):
79
+ found.append(
80
+ Dependency(
81
+ name=line,
82
+ raw_name=line,
83
+ version=None,
84
+ source=source,
85
+ line=number,
86
+ unpinned_reason="URL, path or editable install",
87
+ )
88
+ )
89
+ continue
90
+ text = line.split(" --hash", 1)[0].strip()
91
+ try:
92
+ requirement = Requirement(text)
93
+ except InvalidRequirement:
94
+ found.append(
95
+ Dependency(
96
+ name=text,
97
+ raw_name=text,
98
+ version=None,
99
+ source=source,
100
+ line=number,
101
+ unpinned_reason="could not parse this line",
102
+ )
103
+ )
104
+ continue
105
+ version, reason = _pin(requirement)
106
+ found.append(
107
+ Dependency(
108
+ name=canonical_package_name(requirement.name),
109
+ raw_name=requirement.name,
110
+ version=version,
111
+ source=source,
112
+ line=number,
113
+ unpinned_reason=reason,
114
+ )
115
+ )
116
+ return found
@@ -0,0 +1,80 @@
1
+ """Match pinned dependencies to advisories with OSV's batch API.
2
+
3
+ This is the scan path's only network call apart from downloading the database. It sends
4
+ package names and versions, never code. ``querybatch`` returns only vulnerability IDs,
5
+ which is all the scanner needs to look records up in the local database.
6
+ """
7
+
8
+ from collections.abc import Sequence
9
+ from typing import Any
10
+
11
+ import httpx
12
+ from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
13
+
14
+ OSV_QUERYBATCH = "https://api.osv.dev/v1/querybatch"
15
+ BATCH_SIZE = 1000 # OSV's documented maximum queries per batch
16
+
17
+
18
+ class OsvError(RuntimeError):
19
+ """OSV could not be reached or returned an unexpected response."""
20
+
21
+
22
+ class _Retryable(Exception):
23
+ pass
24
+
25
+
26
+ @retry(
27
+ retry=retry_if_exception_type(_Retryable),
28
+ stop=stop_after_attempt(4),
29
+ wait=wait_exponential(multiplier=1, max=10),
30
+ reraise=True,
31
+ )
32
+ def _post(client: httpx.Client, queries: list[dict[str, Any]]) -> list[dict[str, Any]]:
33
+ try:
34
+ response = client.post(OSV_QUERYBATCH, json={"queries": queries})
35
+ except httpx.TransportError as error:
36
+ raise _Retryable(str(error)) from error
37
+ if response.status_code >= 500 or response.status_code == 429:
38
+ raise _Retryable(f"OSV returned HTTP {response.status_code}")
39
+ if response.status_code != 200:
40
+ raise OsvError(f"OSV returned HTTP {response.status_code}")
41
+ results = response.json().get("results")
42
+ if not isinstance(results, list) or len(results) != len(queries):
43
+ raise OsvError("OSV returned a malformed batch response")
44
+ return results
45
+
46
+
47
+ def query(
48
+ packages: Sequence[tuple[str, str]], client: httpx.Client | None = None
49
+ ) -> dict[tuple[str, str], list[str]]:
50
+ """Vulnerability IDs for each ``(package, version)`` pair, following pagination."""
51
+ owns = client is None
52
+ client = client or httpx.Client(timeout=httpx.Timeout(30.0, connect=10.0))
53
+ found: dict[tuple[str, str], list[str]] = {pair: [] for pair in packages}
54
+ pending: list[tuple[tuple[str, str], str | None]] = [
55
+ (pair, None) for pair in dict.fromkeys(packages)
56
+ ]
57
+ try:
58
+ while pending:
59
+ batch, pending = pending[:BATCH_SIZE], pending[BATCH_SIZE:]
60
+ queries = []
61
+ for (name, version), token in batch:
62
+ q: dict[str, Any] = {
63
+ "package": {"name": name, "ecosystem": "PyPI"},
64
+ "version": version,
65
+ }
66
+ if token:
67
+ q["page_token"] = token
68
+ queries.append(q)
69
+ try:
70
+ results = _post(client, queries)
71
+ except _Retryable as error:
72
+ raise OsvError(f"OSV is unreachable: {error}") from None
73
+ for (pair, _), result in zip(batch, results, strict=True):
74
+ found[pair].extend(v["id"] for v in result.get("vulns") or [])
75
+ if result.get("next_page_token"):
76
+ pending.append((pair, result["next_page_token"]))
77
+ finally:
78
+ if owns:
79
+ client.close()
80
+ return {pair: sorted(set(ids)) for pair, ids in found.items()}
@@ -0,0 +1,90 @@
1
+ """Render scan results for the terminal and as JSON."""
2
+
3
+ import json
4
+ from collections.abc import Sequence
5
+ from datetime import UTC, datetime, timedelta
6
+
7
+ from patchsight.scan.lockfiles.requirements import Dependency
8
+ from patchsight.scan.verdicts import DISPLAY_ORDER, Alert, order
9
+
10
+ STALE_AFTER = timedelta(days=7)
11
+ _HEADINGS = {
12
+ "CALLED": "CALLED (fix first)",
13
+ "IMPORTED_NOT_CALLED": "IMPORTED, NOT CALLED",
14
+ "NOT_IMPORTED": "NOT IMPORTED (transitive only)",
15
+ "UNKNOWN": "UNKNOWN (no symbol data, low confidence, or dynamic use)",
16
+ }
17
+ FOOTNOTE = (
18
+ "'Not called' covers direct, statically resolvable use in your code only. Transitive "
19
+ "use through other dependencies is not analysed, and no alert is hidden."
20
+ )
21
+
22
+
23
+ def stale_warning(db_meta: dict[str, str], now: datetime | None = None) -> str | None:
24
+ built = db_meta.get("built_at")
25
+ if not built:
26
+ return "the database has no build date; it may be stale"
27
+ age = (now or datetime.now(UTC)) - datetime.fromisoformat(built)
28
+ if age > STALE_AFTER:
29
+ return f"the database is {age.days} days old; download a newer one"
30
+ return None
31
+
32
+
33
+ def render_text(
34
+ alerts: Sequence[Alert],
35
+ dependencies: Sequence[Dependency],
36
+ lockfile: str,
37
+ db_meta: dict[str, str],
38
+ now: datetime | None = None,
39
+ ) -> str:
40
+ pinned = [d for d in dependencies if d.version]
41
+ unpinned = [d for d in dependencies if not d.version]
42
+ lines = [
43
+ f"Lockfile: {lockfile} ({len(pinned)} pinned, {len(unpinned)} unpinned) "
44
+ f"Alerts: {len(alerts)} ({sum(1 + len(a.aliases) for a in alerts)} advisory IDs) "
45
+ f"DB: {db_meta.get('db_version', '?')} "
46
+ f"({db_meta.get('builder', '?')})",
47
+ ]
48
+ if warning := stale_warning(db_meta, now):
49
+ lines.append(f"Warning: {warning}")
50
+ ordered = order(alerts)
51
+ for verdict in DISPLAY_ORDER:
52
+ group = [a for a in ordered if a.verdict == verdict]
53
+ lines += ["", f"{_HEADINGS[verdict]} {len(group)}"]
54
+ for alert in group:
55
+ also = f" (also {', '.join(alert.aliases)})" if alert.aliases else ""
56
+ lines.append(f" {alert.advisory}{also} {alert.package} {alert.version}")
57
+ lines.append(f" {alert.reason}")
58
+ if alert.matched:
59
+ lines.append(f" matched: {', '.join(alert.matched)}")
60
+ if verdict != "CALLED" and alert.referenced:
61
+ lines.append(f" your code uses: {', '.join(alert.referenced[:8])}")
62
+ if alert.evidence:
63
+ shown = ", ".join(f"{e.path}:{e.line}" for e in alert.evidence[:5])
64
+ more = f" (+{len(alert.evidence) - 5} more)" if len(alert.evidence) > 5 else ""
65
+ lines.append(f" at: {shown}{more}")
66
+ if alert.confidence:
67
+ lines.append(f" symbol data: {alert.confidence} confidence")
68
+ if unpinned:
69
+ lines += ["", f"Not checked (no exact pin) {len(unpinned)}"]
70
+ lines += [f" {d.raw_name}: {d.unpinned_reason} ({d.source}:{d.line})" for d in unpinned]
71
+ lines += ["", FOOTNOTE]
72
+ return "\n".join(lines)
73
+
74
+
75
+ def render_json(
76
+ alerts: Sequence[Alert],
77
+ dependencies: Sequence[Dependency],
78
+ lockfile: str,
79
+ db_meta: dict[str, str],
80
+ ) -> str:
81
+ return json.dumps(
82
+ {
83
+ "lockfile": lockfile,
84
+ "database": db_meta,
85
+ "alerts": [a.model_dump(mode="json") for a in order(alerts)],
86
+ "unpinned": [d.model_dump(mode="json") for d in dependencies if not d.version],
87
+ "note": FOOTNOTE,
88
+ },
89
+ indent=2,
90
+ )
patchsight/scan/run.py ADDED
@@ -0,0 +1,43 @@
1
+ """One scan: lockfile, then OSV, then the database, then the code. No LLM and no server."""
2
+
3
+ from pathlib import Path
4
+
5
+ import httpx
6
+
7
+ from patchsight.db import SymbolDatabase
8
+ from patchsight.scan import osv_client
9
+ from patchsight.scan.ast_scanner import scan
10
+ from patchsight.scan.lockfiles import requirements
11
+ from patchsight.scan.verdicts import Alert, decide
12
+
13
+
14
+ def run_scan(
15
+ code: Path,
16
+ lockfile: Path,
17
+ database: Path,
18
+ client: httpx.Client | None = None,
19
+ ) -> tuple[list[Alert], list[requirements.Dependency], dict[str, str]]:
20
+ dependencies = requirements.parse(lockfile)
21
+ pinned = [(d.name, d.version) for d in dependencies if d.version]
22
+ matches = osv_client.query([(n, v) for n, v in pinned if v], client=client)
23
+ usage = scan(code)
24
+ symbols = SymbolDatabase(database)
25
+ try:
26
+ alerts: list[Alert] = []
27
+ for (package, version), advisory_ids in sorted(matches.items()):
28
+ # OSV returns every ID of a vulnerability (GHSA, PYSEC, ...): one alert per
29
+ # vulnerability. IDs the database does not know stay separate.
30
+ groups: dict[str, list[str]] = {}
31
+ for advisory in advisory_ids:
32
+ groups.setdefault(symbols.vulnerability_for(advisory) or advisory, []).append(
33
+ advisory
34
+ )
35
+ for key, ids in sorted(groups.items()):
36
+ ordered = sorted(ids, key=lambda i: (not i.startswith("GHSA-"), i))
37
+ known = symbols.vulnerability_for(ids[0]) is not None
38
+ record = symbols.record(key, package) if known else None
39
+ alert = decide(ordered[0], package, version, record, usage)
40
+ alerts.append(alert.model_copy(update={"aliases": tuple(ordered[1:])}))
41
+ return alerts, dependencies, symbols.meta
42
+ finally:
43
+ symbols.close()
@@ -0,0 +1,178 @@
1
+ """Decide one verdict per alert. Uncertainty always lands on UNKNOWN, never on "not called".
2
+
3
+ Rules, in order:
4
+
5
+ 1. No record in the database: UNKNOWN.
6
+ 2. A reference in user code matches a vulnerable symbol or entry point: CALLED. This holds
7
+ at any confidence; low-confidence data may raise an alert's priority.
8
+ 3. The package is never imported: NOT_IMPORTED (transitive use is not analysed), unless an
9
+ unparsable file mentions it or a dynamic import has a computed name: UNKNOWN.
10
+ 4. Dynamic use of the package (``getattr`` with a computed name, ``importlib``, a module
11
+ used as a value, a star import): UNKNOWN.
12
+ 5. Low-confidence symbol data, no symbols, or an unparsable file that mentions the
13
+ package: UNKNOWN. Low confidence can never lower an alert.
14
+ 6. Otherwise: IMPORTED_NOT_CALLED, a claim about statically resolvable use only.
15
+
16
+ A reference matches a symbol when it is the same name; when it names the class or module
17
+ that directly contains the symbol; when it reaches into the symbol (``yaml.Loader.x`` for
18
+ ``yaml.Loader``); or when it has the same top-level package and the same final name, which
19
+ catches re-exports such as ``pkg.load`` for ``pkg.loader.load``. False matches only raise
20
+ priority.
21
+ """
22
+
23
+ import re
24
+ from collections.abc import Sequence
25
+ from typing import Literal
26
+
27
+ from pydantic import BaseModel, ConfigDict
28
+
29
+ from patchsight.db import Record
30
+ from patchsight.names import import_names
31
+ from patchsight.scan.ast_scanner import Location, Usage
32
+
33
+ Verdict = Literal["CALLED", "IMPORTED_NOT_CALLED", "NOT_IMPORTED", "UNKNOWN"]
34
+ DISPLAY_ORDER: tuple[Verdict, ...] = ("CALLED", "IMPORTED_NOT_CALLED", "NOT_IMPORTED", "UNKNOWN")
35
+
36
+
37
+ class Alert(BaseModel):
38
+ model_config = ConfigDict(frozen=True)
39
+
40
+ advisory: str
41
+ aliases: tuple[str, ...] = ()
42
+ package: str
43
+ version: str
44
+ verdict: Verdict
45
+ reason: str
46
+ evidence: tuple[Location, ...] = ()
47
+ matched: tuple[str, ...] = ()
48
+ referenced: tuple[str, ...] = ()
49
+ confidence: str | None = None
50
+ vulnerable: tuple[str, ...] = ()
51
+
52
+
53
+ def matches(reference: str, symbol: str) -> bool:
54
+ r, s = reference.split("."), symbol.split(".")
55
+ if r == s:
56
+ return True
57
+ if len(r) >= 2 and len(s) == len(r) + 1 and s[: len(r)] == r:
58
+ return True # the containing class or module of a vulnerable member
59
+ if len(r) > len(s) and r[: len(s)] == s:
60
+ return True # reaching into a vulnerable class
61
+ return len(r) >= 2 and r[0] == s[0] and r[-1] == s[-1] # re-exported name
62
+
63
+
64
+ def _mentions(sources: dict[str, str], roots: set[str]) -> list[str]:
65
+ return sorted(
66
+ path
67
+ for path, text in sources.items()
68
+ if any(re.search(rf"\b{re.escape(root)}\b", text) for root in roots)
69
+ )
70
+
71
+
72
+ def decide(advisory: str, package: str, version: str, record: Record | None, usage: Usage) -> Alert:
73
+ base = {"advisory": advisory, "package": package, "version": version}
74
+ if record is None:
75
+ return Alert(**base, verdict="UNKNOWN", reason="no symbol data for this advisory")
76
+
77
+ names = import_names(package, record.import_roots)
78
+ roots = {n.split(".")[0] for n in names}
79
+ targets = [s.qualified_name for s in record.symbols if s.module] + list(record.entry_points)
80
+ bare = [s.name.split(".")[-1] for s in record.symbols if not s.module]
81
+ context = {"confidence": record.confidence, "vulnerable": tuple(sorted(set(targets + bare)))}
82
+
83
+ into_package = [r for r in usage.references if r.name.split(".")[0] in roots]
84
+ hits = [
85
+ r
86
+ for r in into_package
87
+ if any(matches(r.name, t) for t in targets) or r.name.split(".")[-1] in bare
88
+ ]
89
+ if hits:
90
+ return Alert(
91
+ **base,
92
+ **context,
93
+ verdict="CALLED",
94
+ reason="your code references a vulnerable symbol",
95
+ evidence=tuple(
96
+ sorted({h.location for h in hits}, key=lambda loc: (loc.path, loc.line))
97
+ ),
98
+ matched=tuple(sorted({h.name for h in hits})),
99
+ )
100
+
101
+ unparsable = _mentions(usage.unparsable, roots)
102
+ computed = [d for d in usage.dynamic if d.root == "?"]
103
+ imported = usage.imported(names)
104
+ if not imported:
105
+ if unparsable:
106
+ return Alert(
107
+ **base,
108
+ **context,
109
+ verdict="UNKNOWN",
110
+ reason=f"could not parse {', '.join(unparsable)}, which mention {package}",
111
+ )
112
+ if computed:
113
+ return Alert(
114
+ **base,
115
+ **context,
116
+ verdict="UNKNOWN",
117
+ reason="a dynamic import with a computed name could load it",
118
+ evidence=tuple(d.location for d in computed),
119
+ )
120
+ return Alert(
121
+ **base,
122
+ **context,
123
+ verdict="NOT_IMPORTED",
124
+ reason=f"your code never imports {' or '.join(names)}; transitive use is not analysed",
125
+ )
126
+
127
+ referenced = tuple(sorted({r.name for r in into_package}))
128
+ dynamic = [d for d in usage.dynamic if d.root in roots] + computed
129
+ if dynamic:
130
+ first = dynamic[0]
131
+ return Alert(
132
+ **base,
133
+ **context,
134
+ verdict="UNKNOWN",
135
+ reason=f"dynamic use the scanner cannot follow: {first.reason}",
136
+ evidence=tuple(d.location for d in dynamic),
137
+ referenced=referenced,
138
+ )
139
+ if record.confidence == "low":
140
+ return Alert(
141
+ **base,
142
+ **context,
143
+ verdict="UNKNOWN",
144
+ reason="symbol data is low confidence, so 'not called' cannot be claimed",
145
+ evidence=tuple(imported),
146
+ referenced=referenced,
147
+ )
148
+ if not targets and not bare:
149
+ return Alert(
150
+ **base,
151
+ **context,
152
+ verdict="UNKNOWN",
153
+ reason="the record lists no symbols",
154
+ evidence=tuple(imported),
155
+ referenced=referenced,
156
+ )
157
+ if unparsable:
158
+ return Alert(
159
+ **base,
160
+ **context,
161
+ verdict="UNKNOWN",
162
+ reason=f"could not parse {', '.join(unparsable)}, which mention {package}",
163
+ evidence=tuple(imported),
164
+ referenced=referenced,
165
+ )
166
+ return Alert(
167
+ **base,
168
+ **context,
169
+ verdict="IMPORTED_NOT_CALLED",
170
+ reason="imported, but no vulnerable symbol is referenced (static, direct use only)",
171
+ evidence=tuple(imported),
172
+ referenced=referenced,
173
+ )
174
+
175
+
176
+ def order(alerts: Sequence[Alert]) -> list[Alert]:
177
+ rank = {v: i for i, v in enumerate(DISPLAY_ORDER)}
178
+ return sorted(alerts, key=lambda a: (rank[a.verdict], a.package, a.advisory))