environment subcommand: inherited PYTHONPATH pollutes target venv's sys.path

[btschwertfeger]

Summary

When cyclonedx-py environment <venv> is invoked from a process that has
PYTHONPATH set, the PYTHONPATH is inherited by the subprocess that
cyclonedx-py spawns to enumerate sys.path of the target interpreter. As a
result, packages from outside the target venv appear in the generated SBOM -
packages that are not installed in the environment being scanned at all.

Root cause (probably)

In cyclonedx_py/_internal/environment.py, the __path4python method spawns a
subprocess to read the target interpreter's sys.path:

# cyclonedx_py/_internal/environment.py, __path4python()
res = run(cmd, capture_output=True, encoding='utf8', shell=False)  # nosec

subprocess.run is called without an explicit env= argument, so it inherits the
full environment of the calling process including PYTHONPATH. When
PYTHONPATH is set in the caller (e.g. by a build tool, test runner, or task
runner that places its own packages there), those paths are prepended to
sys.path inside the spawned interpreter. The resulting path list is then used
by importlib.metadata.distributions(path=...) to discover packages, so any
package reachable via the inherited PYTHONPATH is included in the SBOM as if
it were installed in the target venv.

Minimal reproducible example

uv tool install cyclonedx-bom

# Create the venv to be scanned (install only 'requests')
uv venv /tmp/scan_venv
uv pip install --python=/tmp/scan_venv/bin/python requests

# Create a separate directory with an unrelated package visible via PYTHONPATH
uv venv /tmp/outer_venv
uv pip install --python=/tmp/outer_venv/bin/python flask

# Run cyclonedx-py with PYTHONPATH pointing at the outer package directory
PYTHONPATH=$(/tmp/outer_venv/bin/python -c "import sysconfig; print(sysconfig.get_path('purelib'))") \
cyclonedx-py environment /tmp/scan_venv -o /tmp/sbom.json

# Inspect the result -> 'Flask' (and its dependencies) appear in the SBOM
# even though it is NOT installed in /tmp/scan_venv
uv run python -c "
import json
data = json.load(open('/tmp/sbom.json'))
names = [c['name'] for c in data.get('components', [])]
print('flask in SBOM:', 'Flask' in names)
print('All components:', sorted(names))
"

Expected: SBOM contains only requests (and its dependencies).

Actual: SBOM also contains flask (and its dependencies), which were never
installed in the scanned venv.

Why it matters

Any tool that invokes cyclonedx-py in-process or as a subprocess after setting
PYTHONPATH including build systems, task runners, and CI pipelines that add
their own directories to PYTHONPATH will silently produce an inaccurate
SBOM. The SBOM over-reports dependencies that are not actually present in the
scanned environment, which undermines the entire purpose of SBOM generation for
supply-chain auditing and compliance.

Suggested fix

Strip PYTHONPATH (and, for robustness, VIRTUAL_ENV and PYTHONHOME) from the
environment passed to the subprocess in __path4python:

import os

def __path4python(self, python: str, import_site: bool) -> list[str]:
    cmd = [self.__py_interpreter(python),
            '-c', 'import json,sys;json.dump(sys.path,sys.stdout)']
    if not import_site:
        cmd.insert(1, '-S')

    # Explicitly clear env vars that would pollute the target interpreter's
    # sys.path and cause packages from outside the target venv to appear in
    # the discovered distributions.
    clean_env = {
        k: v for k, v in os.environ.items()
        if k not in ('PYTHONPATH', 'PYTHONHOME', 'VIRTUAL_ENV')
    }

    self._logger.debug('fetch `path` from python interpreter cmd: %r', cmd)
    res = run(cmd, capture_output=True, encoding='utf8', shell=False, env=clean_env)
    ...

Environment

• Package version: cyclonedx-bom 7.3.0
• Python version: 3.10+
• Platform: Ubuntu 24.04

Contribution

• I am willing to provide a fix
• I will wait until somebody else fixes it

[jkowalleck]

Thanks for raising this and for the detailed analysis.

You’re correct that cyclonedx-py environment <venv> inherits PYTHONPATH from the parent process. From the project’s perspective, this has historically been intentional: the tool delegates environment discovery to the interpreter exactly as invoked, including any customizations the user has explicitly configured via environment variables. This allows workflows where PYTHONPATH is part of how the environment is meant to function.

Because of that, I would currently consider this behavior a feature rather than a bug. Changing it would alter long‑standing assumptions and could break setups that rely on PYTHONPATH being passed through.

That said, I understand your use case — especially in CI — where you want the SBOM to reflect only what is installed inside the target venv, regardless of the parent process environment. That’s a valid need, and it might make sense to support it explicitly.

Before we discuss implementation details:

What behavior would you expect from the CLI in your scenario?
For example:

• Should cyclonedx-py environment always sanitize PYTHONPATH?
• Should this be opt‑in via a flag (e.g., --ignore-parent-env)?
• Should the tool warn when external paths are detected?
• Or should it attempt to detect “foreign” paths and filter them?

Understanding your preferred UX will help us evaluate whether this should be a new feature, a mode, or a change in defaults.

Happy to discuss further.

[btschwertfeger]

Thanks for the detailed explanation, that context helps a lot.

You're right that inheriting the environment is a reasonable design choice, and I can see how it covers workflows where PYTHONPATH is a meaningful part of the environment being described. I didn't have that framing when I filed the issue, so I appreciate the clarification.

The case I'm running into is a bit more specific: a build tool/task runner sets PYTHONPATH for its own internal reasons and then invokes cyclonedx-py environment <venv> as a subprocess. The PYTHONPATH there isn't meant to describe the environment being scanned as it's just ambient noise from the parent process to access the cyclonedx-py CLI. The result is a quietly inflated SBOM with no indication that anything unusual happened.

That said, there is one aspect of the current behavior that feels slightly at odds with the explicit environment <venv> interface: hen a user passes a virtual environment path, that's a fairly strong signal of intent: "scan this environment, not whatever happens to be in my parent process". If an inherited PYTHONPATH can silently override that, the explicit path argument becomes unreliable. I'm not saying that's a bug, but it might be worth surfacing so users are at least aware when it happens.

After becoming aware of that, I'm no longer suggesting changing the default. What would help in my scenario is an opt-in flag something like --isolated-env that strips PYTHONPATH, PYTHONHOME, and VIRTUAL_ENV from the subprocess environment before probing the target interpreter. Existing setups stay completely unaffected, and tooling integrations that want a clean scan can explicitly ask for one. A stderr warning when paths outside the target venv are detected could also be a low-effort middle ground.

Happy to put together a PR for either direction if it seems like a reasonable addition.