pypiserver-fips

packaged by Chainguard

Chainguard Container for pypiserver-fips

Minimal PyPI server for uploading & downloading packages with pip/easy_install (FIPS)

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/pypiserver-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The Chainguard FIPS Image for pypiserver is a FIPS-enabled build of pypiserver — a minimal PyPI-compatible server for hosting and installing Python packages with pip — for environments that require FIPS 140 validated cryptography. It is built from the FIPS pypiserver package and runs against Chainguard's FIPS-validated system OpenSSL (openssl-config-fipshardened) on a FIPS build of Python. Like most other Chainguard Images, it has few-to-zero CVEs and does not run as the root user: it runs as the nonroot pypiserver user (uid/gid 9898) and serves on port 8080. Apart from the password-authentication change described under FIPS Support, it is a drop-in replacement for the standard pypiserver image.

FIPS Support

pypiserver's optional htpasswd authentication normally relies on passlib, whose password hashes include bcrypt — which is not FIPS-approved (bcrypt vendors its own Blowfish implementation and does not route through OpenSSL). For FIPS compliance this build removes passlib/bcrypt entirely and verifies htpasswd credentials with PBKDF2-HMAC (SHA-256 or SHA-512) via Python's standard-library hashlib.pbkdf2_hmac, which runs on the FIPS-validated OpenSSL. No other pypiserver functionality is affected — package upload, download, and index serving behave exactly as in the standard image.

What this means in practice:

• Password-file entries must be PBKDF2-HMAC hashes, one user per line, in the form:

  <username>:$pbkdf2-sha256$<iterations>$<salt_hex>$<hash_hex>
  <username>:$pbkdf2-sha512$<iterations>$<salt_hex>$<hash_hex>

• Non-PBKDF2 entries — bcrypt ($2b$…), apr1, crypt, or sha1, i.e. anything Apache's htpasswd utility produces — are rejected. Use the bundled pypiserver-htpasswd helper to generate valid entries.

• Anonymous / no-authentication operation is unchanged and needs no password file.

• Migrating from the standard image: existing bcrypt-hashed htpasswd files will not verify here, and there is no in-place hash upgrade (the FIPS build cannot read a bcrypt hash in order to re-hash it). Recreate each entry with pypiserver-htpasswd — a one-time password reset per user. A fresh deployment is unaffected.

Getting Started

The image serves packages from /data/packages and listens on port 8080. Because it runs as the nonroot pypiserver user (uid/gid 9898), mount host directories that user can read/write. Both a production and a -dev (shell + package manager) variant are published.

Serve packages and install with pip

mkdir -p packages
docker run -d --name pypiserver -p 8080:8080 \
  -v "$PWD/packages:/data/packages" \
  cgr.dev/ORGANIZATION/pypiserver-fips:latest

# install a package from the running server
pip install --index-url http://localhost:8080/simple/ --trusted-host localhost <package-name>

Add .whl/.tar.gz files to packages/ (or upload them, as shown below) to make them available under http://localhost:8080/simple/. --trusted-host is required because the example serves over plain HTTP; put pypiserver behind TLS (for example a reverse proxy) for real deployments.

Create a password file

Apache's htpasswd cannot emit PBKDF2 hashes and passlib was removed, so the image ships a small, dependency-free helper, pypiserver-htpasswd, with an htpasswd-like interface. Invoke it from the image (available in both the production and -dev variants):

# create (-c) a new file with a user, reading the password from the CLI (-b)
docker run --rm -v "$PWD:/work" --entrypoint /usr/bin/pypiserver-htpasswd \
  cgr.dev/ORGANIZATION/pypiserver-fips:latest -c -b /work/.htpasswd alice 's3cret'

# add or update another user in place (omit -c)
docker run --rm -v "$PWD:/work" --entrypoint /usr/bin/pypiserver-htpasswd \
  cgr.dev/ORGANIZATION/pypiserver-fips:latest -b /work/.htpasswd bob 's3cret'

Supported flags (mirroring htpasswd):

Omit -b to be prompted for the password interactively instead of passing it on the command line.

Serve with authentication

docker run -d --name pypiserver -p 8080:8080 \
  -v "$PWD/packages:/data/packages" \
  -v "$PWD/.htpasswd:/data/.htpasswd:ro" \
  cgr.dev/ORGANIZATION/pypiserver-fips:latest \
  run -a update,download -P /data/.htpasswd -p 8080 /data/packages

-a selects which actions require authentication (a comma-separated list of update, download, list, or . for none) and -P points at the password file. Clients then supply credentials:

# download/install with credentials
pip install --index-url http://alice:s3cret@localhost:8080/simple/ --trusted-host localhost <package-name>

# upload a built distribution with twine
twine upload --repository-url http://localhost:8080/ -u alice -p s3cret dist/*

Deploy on Kubernetes

The image runs as a nonroot user and serves on port 8080. Mount the packages volume and a password file (for example from a Secret created with pypiserver-htpasswd):

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pypiserver
spec:
  replicas: 1
  selector:
    matchLabels:
      app: pypiserver
  template:
    metadata:
      labels:
        app: pypiserver
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 9898
        runAsGroup: 9898
        fsGroup: 9898
      containers:
        - name: pypiserver
          image: cgr.dev/ORGANIZATION/pypiserver-fips:latest
          args: ["run", "-a", "update,download", "-P", "/data/.htpasswd", "-p", "8080", "/data/packages"]
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: packages
              mountPath: /data/packages
            - name: htpasswd
              mountPath: /data/.htpasswd
              subPath: .htpasswd
              readOnly: true
      volumes:
        - name: packages
          emptyDir: {}
        - name: htpasswd
          secret:
            secretName: pypiserver-htpasswd
---
apiVersion: v1
kind: Service
metadata:
  name: pypiserver
spec:
  selector:
    app: pypiserver
  ports:
    - port: 8080
      targetPort: 8080
EOF

Documentation and Resources

• pypiserver GitHub repository and documentation
• Standard (non-FIPS) Chainguard pypiserver image
• Installing packages with pip
• Uploading packages with twine
• Hosting your own Python package index

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.