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

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:

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

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:

   curl https://pyenv.run | bash

2. Add pyenv to your shell startup file.

   For Bash (~/.bashrc):

   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):

   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:

   exec $SHELL -l

4. Confirm installation:

   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:

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:

# 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:

   cd "$WORK_ROOT/$TARGET_NAME"

2. Clone the target repository into this directory (example):

   git clone https://github.com/aws/sagemaker-python-sdk.git
   cd sagemaker-python-sdk

3. Ensure the correct environment is active:

   pyenv activate "$ENV_NAME"

4. Install project dependencies (examples):

   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:

   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:

   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.