Metadata-Version: 2.4
Name: installtime-audit
Version: 0.1.0
Summary: Audit Python packaging files for install-time side effects (network, exec, credential theft, persistence, dependency confusion) that run during pip install. Complements Bandit.
Project-URL: Homepage, https://github.com/krc7169/installtime-audit
Project-URL: Issues, https://github.com/krc7169/installtime-audit/issues
Author-email: krc7169 <krc7169@gmail.com>
License: MIT License
        
        Copyright (c) 2026 krc7169
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: bandit,dependency-confusion,install-time,malware,pip,security,setup.py,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# installtime-audit

Audit Python packaging files for **install-time side effects** — code that runs
during `pip install` and that malicious packages abuse to phone home, steal
credentials, or establish persistence. It's the supply-chain gap Bandit doesn't
specifically target.

Code at module scope in `setup.py` (and `build.py`, `hatch_build.py`, …), or
inside a build hook like `setup()` / `install.run()`, executes on install.
`installtime-audit` statically flags dangerous operations reachable at that
point — **without importing or running any of the target code.**

## Install

```bash
pip install installtime-audit
```

## What it flags

| Rule | CWE | Kind | Pattern |
| --- | --- | --- | --- |
| `INSTALL-NET` | 829 | warning | network fetch/connect during install |
| `INSTALL-EXEC` | 78 | vuln | `subprocess` / `os.system` during install |
| `INSTALL-DYNAMIC-EXEC` | 94 | vuln | `exec()` / `eval()` during install |
| `INSTALL-OBFUSCATED-EXEC` | 506 | vuln | `exec()` on a base64/marshal-decoded payload |
| `INSTALL-NET-EXEC` | 494 | vuln | **network + execution both reachable** (download-and-run) |
| `INSTALL-CREDS-ENV` | 522 | warning | reads a sensitive env var (`PYPI_TOKEN`, `AWS_*`, …) |
| `INSTALL-CREDS-FILE` | 522 | vuln | opens `~/.aws/credentials`, `~/.pypirc`, `~/.ssh/id_rsa`, … |
| `INSTALL-PERSISTENCE` | 506 | vuln | writes to autostart / cron / shell-rc paths |
| `DEPCONF-EXTRA-INDEX` | 829 | warning | `--extra-index-url` (dependency confusion) |
| `DEPCONF-TRUSTED-HOST` | 295 | warning | `--trusted-host` disables TLS verification |
| `DEPCONF-DEP-LINKS` | 829 | warning | `dependency_links` fetches from arbitrary URLs |
| `DEPCONF-DIRECT-URL` | 829 | warning | `@ https://...` direct-URL dependency in pyproject |

Helper functions that the build system never calls are **not** flagged, to keep
noise low — only module scope and known hooks count as reachable.

## Library usage

```python
from installtime_audit import scan_source, scan_path

for f in scan_source(open("setup.py").read(), filename="setup.py"):
    print(f)   # setup.py:12: [vuln] INSTALL-NET-EXEC (494) ...

# Or scan a whole unpacked package
findings = scan_path("./unpacked_package/")
```

## CLI

```bash
installtime-audit ./unpacked_package/
installtime-audit setup.py requirements.txt --json
```

Exit code is non-zero when a `vuln`-kind finding exists (tune with `--fail-on
any|vuln|never`), so it drops into CI easily.

## Caveats

This is a heuristic linter for triage, not proof of maliciousness. Legitimate
packages sometimes compile extensions or fetch data at build time; review each
finding in context.

## License

MIT
