Dev.to Security 🔐 Cybersecurity 👁 0 📖 4 min read

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:

  1. Phantom Transitive Dependencies: A pull request adds import anyio or import certifi directly in application code without adding it to pyproject.toml. CI passes because httpx already pulled that package into uv.lock or poetry.lock as an indirect dependency. Six months later, an upstream minor release swaps its internal transport and production breaks on deploy.
  2. 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 blindly pip 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 <= 2 of a locked repo package or common PyPI distribution.
  • UNDECLARED_MISSING: Completely absent from pyproject.toml and requirements*.txt.
  • PHANTOM_TRANSITIVE: Present in uv.lock or poetry.lock, but missing from direct dependencies in pyproject.toml.
  • DEV_ONLY_IN_PROD: Declared only in dev/test groups ([dependency-groups], requirements-dev.txt), but imported inside production modules outside tests/.

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:

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.

📰 Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.