Catching Phantom Transitive Imports and Slopsquatting in Python PRs with Pure-Stdlib AST
There is nothing inherently wrong with generating code using AI coding assistants. Most engineering teams rely on LLMs daily to draft service adapters, CLI glue, and test suites faster than manual typing allows. The ope
There is nothing inherently wrong with generating code using AI coding assistants. Most engineering teams rely on LLMs daily to draft service adapters, CLI glue, and test suites faster than manual typing allows.
The operational friction shows up at the dependency boundary during code review. When pull request volume doubles, two subtle supply-chain and reliability hazards routinely slip past human reviewers and warm developer virtualenvs:
-
Phantom Transitive Dependencies: A pull request adds
import anyioorimport certifidirectly in application code without adding it topyproject.toml. CI passes becausehttpxalready pulled that package intouv.lockorpoetry.lockas an indirect dependency. Six months later, an upstream minor release swaps its internal transport and production breaks on deploy. -
Undeclared & Slopsquatted Imports: Coding agents (and fast-typing humans) occasionally emit plausible-sounding package names or one-character typos (
import reqeusts,import pydantc, or hallucinated SDK names). If a developer or build script blindlypip installs an unresolved module name, a formatting slip turns into a supply-chain incident.
Existing tools like deptry are great, but in locked-down CI runners or pre-commit hooks I kept wanting a zero-dependency, single-purpose gate built strictly on Python 3.11+ standard library modules (ast, tomllib, sys.stdlib_module_names) that runs offline in ~40ms and supports PR diff gating (--diff origin/main) so legacy repos can adopt it without fixing five years of historical imports first.
So I built and open-sourced importgate (MIT).
Eliminating AST False Positives Before Checking Lockfiles
Naive regex or flat AST import scanners drown reviewers in false positives on real Python codebases because not every import statement executes unconditionally at runtime.
importgate tracks two structural AST contexts while walking each module:
from typing import TYPE_CHECKING
# 1. Type-only imports never execute at runtime -> skipped by default
if TYPE_CHECKING:
import mypy_boto3_s3
# 2. Intentional optional runtime features -> skipped unless --strict-optional
try:
import uvloop
except ImportError:
uvloop = None
In the AST visitor, guarding Try.body specifically when an ExceptHandler catches ImportError or ModuleNotFoundError (while still inspecting orelse and finalbody) keeps optional performance extras silent without requiring inline # noqa comments:
def _catches_import_error(handlers: list[ast.ExceptHandler]) -> bool:
import_err_names = {"ImportError", "ModuleNotFoundError", "Exception", "BaseException"}
def _matches(expr: ast.expr | None) -> bool:
if expr is None:
return True
if isinstance(expr, ast.Name):
return expr.id in import_err_names
if isinstance(expr, ast.Tuple):
return any(_matches(elt) for elt in expr.elts)
return False
return any(_matches(h.type) for h in handlers)
Cross-Referencing pyproject.toml Against uv.lock and poetry.lock
Because Python 3.11+ ships tomllib in the standard library, parsing both pyproject.toml (PEP 621 [project.dependencies], PEP 735 [dependency-groups], and [tool.poetry]) and lockfiles (uv.lock and poetry.lock both serialize resolved packages as [[package]] TOML tables) requires zero third-party packages.
Once local first-party modules (src/ layout, flat layout, sibling modules) and sys.stdlib_module_names are filtered out, every third-party import falls into one of four deterministic buckets:
-
TYPO_CANDIDATE: Undeclared in manifests/lockfiles, and within bounded Levenshtein edit distance<= 2of a locked repo package or common PyPI distribution. -
UNDECLARED_MISSING: Completely absent frompyproject.tomlandrequirements*.txt. -
PHANTOM_TRANSITIVE: Present inuv.lockorpoetry.lock, but missing from direct dependencies inpyproject.toml. -
DEV_ONLY_IN_PROD: Declared only in dev/test groups ([dependency-groups],requirements-dev.txt), but imported inside production modules outsidetests/.
Incremental Adoption on Legacy Repos with --diff
Dropping a strict dependency linter onto a large existing codebase usually fails hundreds of historical files on day one. Running importgate in Git diff mode restricts AST inspection strictly to added lines in the current branch or pull request:
# Audit an entire repository
importgate .
# Gate only newly added imports in a pull request
importgate . --diff origin/main
# Emit SARIF 2.1.0 for inline GitHub Code Scanning PR annotations
importgate . --diff origin/main --format sarif > importgate.sarif
Sample output on a synthetic service repo:
importgate v0.1.0 | scanned 14 files (49 imports) | manifests: pyproject.toml | lockfiles: uv.lock
----------------------------------------------------------------------------------------
[FAIL] TYPO_CANDIDATE api/client.py:4:1 Undeclared import 'reqeusts' is within edit distance <=2 of known package(s): requests (potential typo or slopsquatting).
[FAIL] PHANTOM_TRANSITIVE api/transport.py:7:1 Phantom transitive dependency: 'anyio' ('anyio') exists in uv.lock but is not declared in direct manifests.
[FAIL] DEV_ONLY_IN_PROD api/seed.py:2:1 Import 'faker' resolves to dev/optional dependency 'faker', which is not declared in runtime dependencies.
----------------------------------------------------------------------------------------
Total findings: 3 (DEV_ONLY_IN_PROD=1, PHANTOM_TRANSITIVE=1, TYPO_CANDIDATE=1)
Source & Feedback
The full source, 50+ built-in import-to-PyPI distribution aliases (PIL -> pillow, yaml -> pyyaml, cv2 -> opencv-python, google.cloud.*), and test suite are up on GitHub under MIT:
- Repository: github.com/evan-mercer-dev/importgate
If your team runs custom monorepo layouts or namespace packages that trip up import-to-distribution mapping, feel free to open an issue or PR with edge cases.
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.