> For the complete documentation index, see [llms.txt](https://martian1337.gitbook.io/notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://martian1337.gitbook.io/notes/notes/security-research/portable-pyenv-setup-for-python-vulnerability-research.md). # Portable pyenv Setup for Python Vulnerability Research This guide describes a repeatable, cross‑Linux workflow for setting up isolated Python environments with pyenv for security and CVE research. It assumes basic terminal familiarity and a non‑privileged user account. *** ### Overview This guide has three goals: * Make environments **reproducible** across machines and distros. * Keep each target’s tooling **isolated** from others. * Provide a **standard pattern** you can reuse for every Python security research project. The workflow: 1. Install system build dependencies (per Linux family). 2. Install pyenv and pyenv‑virtualenv. 3. Use a standard “research environment template” for each target project. *** ### Prerequisites * A Linux host (VM or physical), using one of: * Debian / Ubuntu * Fedora / RHEL / CentOS * Arch / Manjaro * A regular non‑root user account with `sudo` access. * Basic familiarity with a shell (`bash` or `zsh`). For security work, using a dedicated research VM or container is strongly recommended. *** ### Step 1: Install OS Build Dependencies Install the libraries required to build Python from source. Run the block that matches your distribution family. ### Debian / Ubuntu ```bash sudo apt update sudo apt install -y \ build-essential curl \ libssl-dev zlib1g-dev libbz2-dev libreadline-dev \ libsqlite3-dev libncursesw5-dev xz-utils tk-dev \ libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev ``` ### Fedora / RHEL / CentOS For Fedora or newer RHEL/CentOS that use `dnf`: ```bash sudo dnf groupinstall -y "Development Tools" sudo dnf install -y \ curl openssl-devel zlib-devel bzip2 bzip2-devel \ readline-devel sqlite sqlite-devel \ ncurses-devel xz xz-devel tk-devel \ libffi-devel ``` For older RHEL/CentOS that use `yum`, replace `dnf` with `yum` in the commands above. ### Arch / Manjaro ```bash sudo pacman -Syu --noconfirm sudo pacman -S --noconfirm \ base-devel curl \ openssl zlib xz tk \ sqlite ncurses bzip2 \ libffi ``` If a package name is missing on your specific distro/version, install the closest `*-dev` or `*-devel` equivalent for: * OpenSSL * zlib * bz2 * readline * sqlite * ncurses * tk * libffi * lzma (xz) *** ### Step 2: Install pyenv (Any Linux) This section is distro‑agnostic. 1. Install pyenv with the official installer: ```bash curl https://pyenv.run | bash ``` 2. Add pyenv to your shell startup file. For Bash (`~/.bashrc`): ```bash echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc echo 'eval "$(pyenv init -)"' >> ~/.bashrc echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc ``` For Zsh (`~/.zshrc`): ```bash echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc echo 'eval "$(pyenv init -)"' >> ~/.zshrc echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc ``` 3. Reload your shell: ```bash exec $SHELL -l ``` 4. Confirm installation: ```bash pyenv --version ``` If this prints a version, pyenv is installed correctly. *** ### Step 3: Standard Research Environment Template Use the same pattern for each Python target you analyze. Only update a few variables per project. ### Template Variables Pick values per target: ```bash TARGET_NAME="sagemaker-python-sdk" # descriptive project name PY_VERSION="3.11.8" # Python version under test ENV_NAME="${TARGET_NAME}-${PY_VERSION}" WORK_ROOT="$HOME/sec-research" # root directory for all research ``` * `TARGET_NAME` should match the project or repo. * `PY_VERSION` is the Python version you want to test (you can repeat this for multiple versions). * `ENV_NAME` combines both for clarity. * `WORK_ROOT` is a single directory where all security work lives. ### Environment Creation Script Run this block in a shell after setting the variables: ```bash # 1) Ensure the desired Python version is available (idempotent) pyenv install -s "$PY_VERSION" # 2) Create an isolated virtualenv for this target pyenv virtualenv "$PY_VERSION" "$ENV_NAME" # 3) Create and enter a workspace directory for this target mkdir -p "$WORK_ROOT/$TARGET_NAME" cd "$WORK_ROOT/$TARGET_NAME" # 4) Pin the virtualenv to this directory pyenv local "$ENV_NAME" # 5) Activate the environment pyenv activate "$ENV_NAME" # 6) Install global research tools you want on every project python -m pip install -U pip wheel setuptools python -m pip install -U \ pytest coverage \ bandit pip-audit \ black isort \ mypy # 7) Freeze the baseline toolset for reproducibility pip freeze > tools-baseline.txt ``` At this point: * Entering `"$WORK_ROOT/$TARGET_NAME"` will automatically select `"$ENV_NAME"` (due to `pyenv local`). * The environment contains a consistent set of security and dev tools. * You can now clone and install the target project into this environment. *** ### Step 4: Using the Environment for a Target Project Once the environment is ready: 1. Go to the workspace: ```bash cd "$WORK_ROOT/$TARGET_NAME" ``` 2. Clone the target repository into this directory (example): ```bash git clone https://github.com/aws/sagemaker-python-sdk.git cd sagemaker-python-sdk ``` 3. Ensure the correct environment is active: ```bash pyenv activate "$ENV_NAME" ``` 4. Install project dependencies (examples): ```bash python -m pip install -r requirements.txt 2>/dev/null || true python -m pip install -r dev-requirements.txt 2>/dev/null || true ``` (Adjust filenames according to the project.) From here, run tests, static analysis tools, proof‑of‑concept scripts, and exploit code in this environment without affecting other projects. *** ### Step 5: Rebuilding an Environment Later On a new machine or VM: 1. Repeat **Step 1** and **Step 2** for the new system. 2. Recreate the environment with the same variables: ```bash TARGET_NAME="sagemaker-python-sdk" PY_VERSION="3.11.8" ENV_NAME="${TARGET_NAME}-${PY_VERSION}" WORK_ROOT="$HOME/sec-research" ``` 3. Rebuild the environment: ```bash pyenv install -s "$PY_VERSION" pyenv virtualenv "$PY_VERSION" "$ENV_NAME" mkdir -p "$WORK_ROOT/$TARGET_NAME" cd "$WORK_ROOT/$TARGET_NAME" pyenv local "$ENV_NAME" pyenv activate "$ENV_NAME" # restore baseline tools pip install -r tools-baseline.txt # restore project-specific dependencies if you saved them pip install -r project-requirements.txt 2>/dev/null || true ``` If you keep `tools-baseline.txt`, `project-requirements.txt`, and the scripts in version control (for example, a private “security-envs” or “research-environments” repo), you can reconstruct setups with high fidelity. *** ### Python Security tooling Alongside pyenv and virtualenv, a base Python tooling set that you can install into each project’s env is: * Static analysis / SAST: `bandit`, `pip-audit`, and optionally `safety` for dependency checks, plus `mypy` for type checking.​ * Testing and coverage: `pytest`, `coverage`, and `hypothesis` for property‑based testing and fuzz‑like input generation.​ * General dev utilities: `black`, `isort`, `flake8` or `ruff` to keep your own scripts consistent and easier to maintain across projects.​ *** ### Good Practices for Security Research * Use dedicated VMs or containers per project or per group of related projects. * Avoid using the system Python for any research tasks. * Snapshot your VM after completing this setup so future projects can start from a clean baseline. * Prefer non‑privileged users and minimal permissions, especially when running proof‑of‑concept exploits.