pybom 0.2.0

Generate a bill of materials and vulnerability information for your python projects.

PyBOM

Generate a bill of materials and vulnerability information for your python projects.

About

PyBOM has two functions:

1. Aggregate a python project's license, package, and vulnerability information in one place by leveraging the GitHub dependency and vulnerability APIs and PyPI JSON API.
2. Report image vulnerability information for docker images pushed to a registry. (Currently in development; Google Container Registry will be the first supported.)

Getting Started

Installation

pip install pybom

...or add pybom to your requirements.txt and run pip install -r requirements.txt.

Usage

GitHub Personal Access Token

PyBOM uses GitHub's v4 GraphQL API to get dependency and vulnerability information. To use the API, you must have a Personal Access Token (PAT).

To get a PAT:

1. Navigate to the Personal access tokens page in GitHub's Settings (Settings > Developer settings > Personal access tokens)
2. Click Generate new token.
3. Add a note explaining what the token is for, and under Scopes, select Repo.
4. Click Generate Token.
5. Copy the token. You won't be able to see it again.

PyBOM reads the token from the GITHUB_PERSONAL_ACCESS_TOKEN environment variable. To set this variable for all bash sessions, include the following in your .bash_profile (on macOS):

export GITHUB_PERSONAL_ACCESS_TOKEN=<your-token-here>

...then source ~/.bash_profile in your current session to set the variable.

Python BOM

To get a list of components in your Python project hosted in Github: (Note: You must have the Dependency Graph API turned on for this to work.)

from pybom.repository import get_components

repo_name = "pybom"
repo_owner = "carbonrelay"

components = get_components(repo_name, repo_owner)
type(components)  # <class 'list'>
type(components[0])  # <class 'pybom.application_component.ApplicationComponent'>

Python Vulnerabilities

To get a list of vulnerabilities in your Python project hosted on Github:

from pybom.repository import get_vulnerabilities

repo_name = "pybom"
repo_owner = "carbonrelay"

vulnerabilities = get_vulnerabilities(repo_name, repo_owner)
type(vulnerabilities)  # <class 'list'>
type(vulnerabilities[0])  # <class 'pybom.vulnerability.Vulnerability'>

Image Vulnerabilities

Image vulnerability reporting is not yet fully implemented. It will be finished in a future release.

Contributing

PyBOM is developed and tested against Python 3.6. I recommend using pyenv to manage your python versions and venv to manage project dependencies.

After cloning the repository:

python -m venv venv
. venv/bin/activate
pip install -r requirements.txt

# run tests with coverage report
./coverage.sh

To build the project wheels:

# adapted from https://packaging.python.org/tutorials/packaging-projects/
pip install --user --upgrade setuptools wheel
python setup.py sdist bdist_wheel

If you bump a requirement version in requirements.txt, freeze the new dependencies to requirements-freeze.txt:

pip freeze > requirements-freeze.txt

License

This project is licensed under the Apache license. See LICENSE.md.