setup.py is the legacy Python packaging file used to define package metadata and build behavior. Because it is executable Python, installers may run it during build, install, or metadata collection. That makes it a potential execution point for malicious code embedded in a package source distribution.
What setup.py actually does in Python packaging
setup.py is the legacy packaging entry point that declares metadata, dependencies, entry points, and custom build logic for a Python project. Because it is executable Python, it can do more than describe a package, it can run code during build, install, or metadata collection.
That dual role is the key reason setup.py has security significance. A package source distribution can hide behavior inside code that looks like ordinary packaging glue, so the file is both a build manifest and a potential execution surface.
Why executable packaging files create security exposure
The security concern is not that setup.py exists, but that install-time execution changes trust boundaries. A developer or automated build system may inspect a repository, assume it is only consuming metadata, and still trigger code paths that have access to the local environment, build secrets, or CI context.
That means the file can be used for benign customization, but it can also become a delivery mechanism for malicious side effects such as environment inspection, network calls, file reads, or dependency tampering. In practice, the risk rises when maintainers allow arbitrary logic in packaging code instead of keeping package definition declarative.
For a broader supply-chain view, the pattern is closely related to package provenance and build integrity concerns described by SLSA and to Python package hardening guidance in OWASP Cheat Sheet Series.
How modern packaging reduces reliance on setup.py
Python packaging has moved toward more declarative metadata, especially through pyproject.toml and standardized build backends. That shift matters because static configuration is easier to review, easier to lint, and less likely to hide side effects than executable packaging code.
Even so, many repositories still include setup.py for compatibility or custom build steps. The practical distinction is whether the file is a thin compatibility layer or a place where logic has accumulated over time. The more logic it contains, the more it behaves like code that must be reviewed for supply-chain risk, not merely like project metadata.
Build integrity guidance from SLSA is especially relevant when you need to reason about what was executed during a package build, while OWASP API Security Top 10 is useful whenever package tooling reaches out to internal services or automation APIs during installation.
Practical indicators that a setup.py file deserves extra scrutiny
A packaging file needs closer review when it does anything beyond static declarations. Common red flags include conditional execution, network activity, environment-variable dependence, file-system probing, dynamic downloads, and code paths that behave differently during metadata generation versus installation.
Those behaviors do not prove malicious intent, but they do change the trust model. A project that executes code as part of packaging is asking the consumer to trust not only the declared package contents, but also the installer path, the build context, and every hidden dependency that code may touch.
The most useful review lens is simple: if removing the executable logic would not change the package’s published metadata or build output, the logic probably belongs outside setup.py. If removing it would change behavior, then the file is part of the package’s attack surface.
Risk and Threat Considerations
setup.py can become a supply-chain attack point because installers may execute it before the package is fully trusted. That creates exposure to code execution, environment discovery, dependency manipulation, and secret access during build or install workflows.
Failure mechanism: An attacker embeds malicious logic in the packaging file or a package source distribution, then relies on routine build or install activity to trigger execution in a context that has access to developer machines, CI jobs, or repository credentials.
Impact: The result can be secret theft, unauthorized code execution, package tampering, or downstream compromise of build and release pipelines.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| CIS Controls v8 | CIS 2 — Inventory and Control of Software Assets | setup.py impacts trusted software intake and package inventory. |
| CIS 16 — Application Software Security | Executable packaging logic is part of software supply-chain hardening. | |
| CIS 14 — Security Awareness and Skills Training | Developers need training to recognize packaging-time execution risk. | |
| Recommendation — Inventory Python build inputs and block unreviewed package execution paths. Review packaging code for unsafe side effects before release. Train developers to treat packaging scripts as executable code. | ||
| NIST CSF 2.0 | GV.SC — Supply Chain Risk Management | setup.py is a supply-chain trust boundary in package delivery. |
| PR.IP — Information Protection Processes and Procedures | Reducing executable packaging logic is a secure process decision. | |
| DE.CM — Continuous Monitoring | Build-time execution needs monitoring for unexpected behavior. | |
| Recommendation — Apply supply-chain controls to package build and installation paths. Standardize declarative packaging and restrict custom install logic. Monitor builds for unexpected network, file, or process activity. | ||
| OWASP Non-Human Identity Top 10 | NHI-01 — Secrets Sprawl | Packaging code can expose secrets present in build environments. |
| NHI-05 — Third-Party Dependency Trust | A source distribution's setup.py is part of trusted dependency intake. | |
| NHI-07 — Privilege and Access Misuse | Build-time code can abuse the permissions of CI or developer contexts. | |
| Recommendation — Keep build secrets out of package execution paths and source trees. Verify dependency provenance before allowing packaging-time execution. Constrain build permissions so packaging code cannot reach sensitive assets. | ||
Practitioner Guidance
Why practitioners should care: Treat setup.py as executable code, not just packaging metadata. That means security review should focus on any side effects, dynamic behavior, and hidden dependencies, especially in dependencies pulled into automated builds.
What to watch for: If a project still uses setup.py, check whether it has been reduced to a minimal compatibility wrapper or whether it contains logic that could alter the build environment. The latter deserves the same scrutiny you would give any other untrusted code path.
Related resources from NHI Mgmt Group
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 17, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
