Add post-build import-time behavioral monitor under network isolation

[LalatenduMohanty]

Problem

Fromager's existing network isolation (run_network_isolation.sh) blocks outbound access during PEP 517 build hooks, preventing build-time supply chain attacks from phoning home. However, some attacks deliberately place malicious code in the package's runtime paths (e.g., __init__.py) instead of build hooks, so it only executes on import, not during build.

The May 2026 "Mini Shai-Hulud" campaign (mistralai/client-python#523) demonstrated this: mistralai and guardrails-ai were compromised with backdoors in __init__.py that downloaded a credential-stealing payload via urllib.request.urlopen() and executed it as a detached process. This attack vector is invisible to build-time monitoring because the malicious code never runs during wheel compilation.

Proposal

After pep517_build_wheel() produces the .whl but before add_extra_metadata_to_wheels(), install the wheel into a temporary virtualenv and run python -c "import <package>" under the same run_network_isolation.sh used for builds.

Key design decision -- behavior-only monitoring: import failures (ImportError, ModuleNotFoundError, etc.) are expected and ignored. Many legitimate packages cannot import in a build environment (GPU packages needing CUDA runtime, packages with unmet optional dependencies). The monitor only flags anomalous behavior during the import attempt:

• Network access attempts (blocked by existing namespace isolation)
• Writes to sensitive filesystem paths (/tmp/, ~/.ssh/, ~/.config/)
• Unexpected subprocess spawning (curl, wget, detached processes)

This avoids false positives without needing a per-package allowlist. Real-world import-time backdoors use except: pass and execute their payload before any import-dependent code, so behavior monitoring catches them regardless of whether the import itself succeeds.

Why this works for downstream consumers

In downstream build pipelines, this runs transparently before the post_build hook fires -- compromised wheels are caught before upload to a package registry. No downstream changes needed, no allowlist to maintain.

Related issues

• Add framework for gating tests / sanity checks #371 -- gating test framework proposes post-build virtualenv infrastructure that this could reuse (but doesn't depend on)
• Add build isolation to sandbox build_sdist and build_wheel steps #1019 -- build isolation with mount/PID/IPC namespaces would strengthen the sandbox for this test

References

• SafeDep: Mini Shai-Hulud campaign analysis (May 2026)
• mistralai/client-python#523 -- mistralai 2.4.6 compromise details

[LalatenduMohanty]

Bigger picture: supply chain anomaly detection system

The import-time monitor above is one piece of a broader anomaly detection system that could be built into fromager. Here's the full vision — not all of this needs to land at once.

Build-time monitors

Extend external_commands.run() to observe what happens during each package build:

Monitor	What it detects
Network	Log destination IPs/hostnames from NetworkIsolationError instead of just failing. Flag packages that attempt network access when they historically haven't.
Filesystem	Pre/post build dir diff. Flag writes to sensitive paths (~/.ssh/, /tmp/, ~/.config/).
Resource	Track wall time, peak RSS, CPU time. Flag builds exceeding historical baselines.
Subprocess	Flag unexpected executables (curl, wget, ssh) vs allowlisted build tools (gcc, rustc, cmake).
Import-time	This issue — import <package> under network isolation after wheel build.

Graph-level analysis

Compare graph.json between runs:

• New/removed packages, new edges, changed source URLs
• Dependency count increases >20%
• Source provenance changes (different mirror, different GitHub org)

Metadata consistency checks

Inspect the built wheel for:

• .pth file injection — new .pth files in a patch/minor release (used in the LiteLLM compromise)
• Typosquatting — Levenshtein distance of new dep names against known packages
• Phantom deps — Requires-Dist lists packages not in the resolved graph
• Platform mismatch — py3-none-any tag but contains .so files

Risk scoring

Each signal gets a score (0-10). Scores aggregate per package. Configurable thresholds determine action:

• Block (default ≥8): network access, .pth injection, sensitive path writes
• Warn (default ≥5): new transitive deps, typosquat candidates, resource spikes
• Pass (<5): platform tag mismatch, minor metadata inconsistencies

Output is a JSON report per package with signals, scores, and recommended action.

Per-package overrides

Some packages trigger legitimate signals (e.g., /tmp writes for caching, /bin/sh for ./configure). Overrides in per-package settings YAML suppress specific signals with required justification, approver, and expiry. Overridden signals still appear in the report at score 0 for auditability.

Suggested phasing

1. Graph diff + metadata checks — fromager audit --baseline <graph.json> CLI command
2. Build-time + import-time monitors — integrated into the build flow (this issue)
3. Risk scoring + overrides — scoring engine, thresholds, per-package overrides

Happy to write up any of these as separate issues if there's interest.

[rd4398]

I like the current proposal and have following comments:

1. Import of wheel may trigger native code execution for C extension packages. A segfault or hang during the monitored import shouldn't block the entire bootstrap. We need a timeout and signal handling around the subprocess. Not sure how complicated it will be

2. The temp venv approach will add build time. Creating a venv + installing the wheel + running import for every package could add significant overhead for large dependency graphs. Can we consider making it opt-in initially (--import-monitor flag) rather than on by default?

For overall broader picture, I like the idea of a system that will make fromager more reliant and help enhancing the security of supply chain

[LalatenduMohanty]

Update: hooks-based architecture

After initial feedback (from @tiran ), the approach should keep fromager focused on building packages. Rather than adding detection logic directly into fromager, the idea is to expose hooks and structured data so 3rd-party packages can implement anomaly detection as an opt-in extension.

What fromager would provide:

Component	Description
pre_build hook	Fires before pep517_build_wheel() — lets plugins snapshot filesystem state
post_build_wheel hook	Fires after the .whl is produced but before add_extra_metadata_to_wheels() — lets plugins inspect the wheel, run import-time tests, diff filesystem
Structured NetworkIsolationError	Parse destination IPs/hostnames and attempt counts from error output instead of plain text
DependencyGraph.diff()	Compare two graphs, return added/removed/modified nodes and edges
fromager audit CLI	Thin command that loads audit hooks and invokes them against build artifacts

What a 3rd-party package would implement:

All detection logic: filesystem diffs, resource tracking, import-time behavioral testing, graph topology analysis, typosquatting detection, .pth file detection, risk scoring with configurable thresholds, per-package signal overrides, and JSON report generation.

The import-time monitor from the original issue description would live in this 3rd-party package — it registers a post_build_wheel hook, installs the wheel in a temp venv, runs import <package> under run_network_isolation.sh, and flags anomalous behavior (network access, sensitive path writes, unexpected subprocesses) while ignoring import failures.

This keeps fromager's scope clean and lets different consumers build their own detection policies on top of the same hooks.

[rd4398]

Okay, the hook-based architecture makes sense. This will keep fromager focused on building wheels

[LalatenduMohanty]

Implementation phases

Phase 1 — Fromager core (hooks + structured data)

Changes to fromager itself:

1. Add pre_build and post_build_wheel to GLOBAL_HOOK_NAMES in hooks.py
2. Fire pre_build in wheels.py before pep517_build_wheel()
3. Fire post_build_wheel after validate_wheel_filename(), before add_extra_metadata_to_wheels()
4. Enrich NetworkIsolationError with parsed destination IPs/hostnames and attempt count
5. Add DependencyGraph.diff() returning a GraphDiff dataclass (added/removed/modified nodes and edges)
6. Add fromager audit --baseline <graph.json> CLI command that loads audit hooks

Phase 2 — 3rd-party detection package

A separate package (e.g., fromager-anomaly-detect) that registers hooks:

1. pre_build handler — snapshot filesystem state before build
2. post_build_wheel handler — filesystem diff, resource tracking, wheel content inspection (.pth files, platform tags)
3. Import-time monitor — install wheel in temp venv, run import <package> under network isolation, flag anomalous behavior (not import failures)
4. audit handler — graph topology analysis, typosquatting detection, dependency count changes, source provenance checks
5. Risk scoring engine with configurable block/warn/pass thresholds
6. Per-package signal overrides (YAML config with version ranges, expiry dates, audit trail)
7. JSON report generation

Phase 3 — Deeper visibility and hardening

1. Subprocess monitoring — log invocations, allowlist build tools, flag unexpected executables
2. Historical baseline storage and comparison
3. CI/CD integration patterns (exit codes, artifact upload)