{
"info": {
"author": "VMware Inc",
"author_email": "nishak@vmware.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 3 - Alpha",
"Environment :: Console",
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Natural Language :: English",
"Operating System :: POSIX",
"Operating System :: POSIX :: Linux",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: Implementation :: CPython",
"Topic :: Software Development"
],
"description": "\n\n[](https://circleci.com/gh/vmware/tern)\n[](https://bestpractices.coreinfrastructure.org/projects/2689)\n[](https://opensource.org/licenses/BSD-2-Clause)\n\n# Welcome to the Tern Project\n\nTern is a software package inspection tool for containers. It's written in Python3 with a smattering of shell scripts.\n\n# Table of Contents\n- [Introduction](#what-is-tern)\n - [FAQ](/docs/faq.md)\n - [Glossary of Terms](/docs/glossary.md)\n - [Architecture](/docs/architecture.md)\n - [Navigating the Code](/docs/navigating-the-code.md)\n- [Getting Started](#getting-started)\n - [Getting Started with Docker](#getting-started-with-docker)\n - [Getting Started with Vagrant](#getting-started-with-vagrant)\n - [Getting Started on Linux](#getting-started-on-linux)\n- [Using Tern](#using-tern)\n - [Generating a BoM report for a Docker image](#bom-for-docker-image)\n - [Generating a BoM report from a Dockerfile](#bom-for-dockerfile)\n- [Report Formats](#report-formats)\n - [Human Readable Format](#report-human-readable)\n - [Summary Format](#report-summary)\n - [JSON Format](#report-json)\n - [YAML Format](#report-yaml)\n - [SPDX tag-value Format](#report-spdxtagvalue)\n- [Running tests](#running-tests)\n- [Project Status](#project-status)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n# What is Tern?\nTern is an inspection tool to find the metadata of the packages installed in a container image. The overall operation looks like this:\n1. It uses overlayfs to mount the first filesystem layer (also known as the BaseOS) used to build the container image\n2. It then executes scripts from the \"command library\" in a chroot environment to collect information about packages installed in that layer\n3. With that information as a starting point, it continues to iterate over steps 1 and 2 for the rest of the layers in the container image\n4. Once done, it generates a report in different formats. The default report is a verbose explanation of what layers brought in what software components. If a Dockerfile is provided then it will also provide what lines in the Dockerfile was used to create the layers.\n\nTern gives you a deeper understanding of your container's bill of materials so you can make better decisions about your container based infrastructure, integration and deployment strategies. It's also a good tool if you are curious about the contents of the container images you have built.\n\n\n\n\n# Getting Started\nTern is not distributed on PyPI or as Docker images yet. This is coming soon. See the [Project Status](#project-status) for details.\n\n## Getting Started with Docker\nDocker is the most widely used tool to build and run containers. If you already have Docker installed, you can run Tern by building a container with the Dockerfile provided and the `docker_run.sh` script:\n\nClone this repository:\n```\n$ git clone https://github.com/vmware/tern.git\n```\n\nBuild the Docker image (called `ternd` here):\n```\n$ docker build -t ternd .\n```\n\nRun the script `docker_run.sh`\n\n```\n$ ./docker_run.sh workdir ternd \"report -i debian:buster\" > output.txt\n```\n\nTo produce a json report run\n```\n$ ./docker_run.sh workdir ternd \"report -j -i debian:buster\"\n```\n\nWhat the `docker_run.sh` script does is create the directory `workdir` if not present in your current working directory and run the built container as privileged with `workdir` bind mounted to it.\n\n*WARNING:* privileged Docker containers are not secure. DO NOT run this container in production unless you have secured the node (VM or bare metal machine) that the docker daemon is running on.\n\n## Getting Started with Vagrant\nVagrant is a tool to setup an isolated virtual software development environment. If you are using Windows or Mac OSes, this is the best way to get started as Tern does not run natively in a Mac OS or Windows environment at this time.\n\n### Install\nFollow the instructions on the [VirtualBox](https://www.virtualbox.org/wiki/Downloads) website to download VirtualBox on your OS.\n\nFollow the instructions on the website to install [Vagrant](https://www.vagrantup.com/downloads.html) for your OS. \n\n### Create a Vagrant environment\nIn your terminal app, run the following commands.\n\nClone this repository:\n```\n$ git clone https://github.com/vmware/tern.git\n```\n\nBring up the Vagrant box: \n```\n$ cd tern/vagrant\n$ vagrant up\n```\n\nSSH into the created VM: \n```\n $ vagrant ssh\n```\n\nRun the program:\n```\n$ python3 -m tern -l report -i debian:buster -f output.txt\n```\n\n## Getting Started on Linux\nIf you have a Linux OS you will need a distro with a kernel version >= 4.0 (Ubuntu 16.04 or newer or Fedora 25 or newer are good selections) and will need to install the following requirements:\n\n- Git (Installation instructions can be found here: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n- attr (sudo apt-get install attr or sudo dnf install attr)\n- Python 3.6 or newer (sudo apt-get install python3.6(3.7) or sudo dnf install python36(37))\n- Pip (sudo apt-get install python3-pip). Note that you don't have to do this for Fedora OSs.\n\nFor Docker containers\n- Docker CE (Installation instructions can be found here: https://docs.docker.com/engine/installation/#server)\n\nMake sure the docker daemon is running.\n\n*NOTE:* Tern currently supports containers built with Docker but it is architected to support other container image formats.\n\nCreate a python3 virtual environment:\n```\n$ python3 -m venv ternenv\n$ cd ternenv\n```\n\n*NOTE:* Your OS might distribute each Python version separately. For example, on Ubuntu LTS, Python 2.7 is linked to `python2` and Python 3.6 is linked to `python3`. I develop with Python 3.7 which is installed separately with no symlinks. In this case, I use the binary. The binaries are usually installed in `/usr/bin/python`.\n\nClone this repository:\n```\n$ git clone https://github.com/vmware/tern.git\n```\n\nActivate the virtual environment:\n```\n$ source bin/activate\n```\n\nInstall requirements:\n```\n$ cd tern\n$ pip install .\n```\n\nRun Tern:\n```\n$ tern -l report -f output.txt -i debian:buster\n```\n\n# Using Tern\n\nTern creates a report containing the Bill of Materials (BoM) of a container image, including notes about how it collects this information, and files for which it has no information about. Currently, Tern supports only containers built using Docker. This is the most ubiquitous type of container image that exists so the project started with a focus on those. However, it is architected to support other images that closely follow the [OCI image spec](https://github.com/opencontainers/image-spec/blob/master/spec.md).\n\n## Generating a BoM report for a Docker image\nIf you have a Docker image pulled locally and want to inspect it\n```\n$ tern -l report -i debian:jessie\n```\nTake a look at report.txt to see what packages are installed in the Docker image and how Tern got this information. If you encounter any errors, please file an issue.\n\n## Generating a BoM report from a Dockerfile\nYou can provide a Dockerfile to Tern to figure out the Bill of Materials and other information. Tern will build the image, analyze it with respect to the Dockerfile and discard the image. This is useful to engineers who are developing a Dockerfile for their app or in a container build and release pipeline.\n```\n$ tern -l report -d samples/photon_git/Dockerfile\n```\nTake a look at report.txt to see what packages you would be shipping if you were to use the given Dockerfile. Feel free to try this out on the other sample Dockerfiles in the samples directory or on Dockerfiles you may be working with. If it doesn't work for you, please file an issue.\n\n\n# Report Formats\nTern creates BoM reports suitable to read over or to provide to another tool for consumption.\n\n## Human Readable Format\nThe default report Tern produces is a human readable report. The object of this report is to give the container developer a deeper understanding of what is installed in a container image during development. This allows a developer to glean basic information about the container such as what the true base operating system is, what the app dependencies are, if the container is using an official or personal repository for sources or binaries, whether the dependencies are at the correct versions, etc.\n```\n$ tern -l report -i golang:1.12-alpine -f output.txt\n```\n\n## Summary Format\nTo get just a list of packages, you can use the `-s` option to get a summary report. This is useful to provide to a legal or OSS compliance team.\n```\n$ tern -l report -s -i golang:1.12 -f output.txt\n```\nWARNING: Tern is meant to give guidance on what may be installed in a container image. We recommend that you use the default report format for the purpose of investigation.\n\n\n## JSON Format\nYou can get the results in a JSON file to pass around in a network.\n```\n$ tern report -j -i golang:1.12-alpine\n```\n\n## YAML Format\nYou can get the results in a YAML file to be consumed by a downstream tool or script.\n```\n$ tern -l report -y -i golang:1.12-alpine -f output.yaml\n```\n\n## SPDX tag-value Format\n[SPDX](https://spdx.org/) is a format developed by the Linux Foundation to provide a standard way of reporting license information. Many compliance tools are compatible with SPDX. Tern follows the [SPDX specifications](https://spdx.org/specifications) specifically the tag-value format which is the most compatible format with the toolkit the organization provides. The tag-value format is the only SPDX format Tern supports. There are conversion tools available [here](https://github.com/spdx/tools) (some still in development). You can read an overview of the SPDX tag-value specification [here](./docs/spdx-tag-value-overview) and about how Tern maps its properties to the keys mandated by the spec [here](./docs/spdx-tag-value-mapping.md).\n```\n$ tern -l report -m spdxtagvalue -i golang:1.12-alpine -f spdx.txt\n```\n\n# Running tests\nWARNING: The `test_util_*` tests are not up to date. We are working on it :). From the Tern repository root directory run:\n```\n$ python tests/.py\n```\n\n## Project Status\nRelease 0.4.0 is here!\n\nSee the [release notes](docs/releases/v0_4_0.md) for more information.\n\nWe try to keep the [project roadmap](./docs/project-roadmap.md) as up to date as possible. We are currently working on Release 0.5.0\n\n## Releases\n* [v0.1.0](docs/releases/v0_1_0.md)\n* [v0.2.0](docs/releases/v0_2_0.md)\n* [v0.3.0](docs/releases/v0_3_0.md)\n* [v0.4.0](docs/releases/v0_4_0.md)\n\n## Documentation\nArchitecture, function blocks, code descriptions and the project roadmap are located in the docs folder. Contributions to the documentation are welcome! See the [contributing guide](/CONTRIBUTING.md) to find out how to submit changes.\n\n## Get Involved\n\nDo you have questions about Tern? Do you think it can do better? Would you like to make it better? You can get involved by giving your feedback and contributing to the code, documentation and conversation!\n\nPlease read our [code of conduct](/CODE_OF_CONDUCT.md) first.\n\nNext, take a look at the [contributing guide](/CONTRIBUTING.md) to find out how you can start.\n\n\n",
"description_content_type": "text/markdown; charset=UTF-8",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/vmware/tern/",
"keywords": "Distribution,Container,Cloud-Native",
"license": "BSD-2.0",
"maintainer": "",
"maintainer_email": "",
"name": "tern",
"package_url": "https://pypi.org/project/tern/",
"platform": "",
"project_url": "https://pypi.org/project/tern/",
"project_urls": {
"Documentation": "https://github.com/vmware/tern/tree/master/docs",
"Homepage": "https://github.com/vmware/tern/",
"Issues": "https://github.com/vmware/tern/issues",
"Source Code": "https://github.com/vmware/tern"
},
"release_url": "https://pypi.org/project/tern/0.5.4/",
"requires_dist": [
"certifi (==2019.6.16)",
"chardet (==3.0.4)",
"docker (==4.0.2)",
"idna (==2.8)",
"pyyaml (==5.1.2)",
"requests (==2.22.0)",
"six (==1.12.0)",
"urllib3 (==1.25.3)",
"websocket-client (==0.56.0)",
"GitPython (~=2.1) ; extra == 'dev'",
"bandit (~=1.6) ; extra == 'dev'",
"prospector (>=1.1) ; extra == 'dev'"
],
"requires_python": "",
"summary": "An inspection tool to find the OSS compliance metadata of the packages installed in a container image.",
"version": "0.5.4"
},
"last_serial": 5739265,
"releases": {
"0.5.4": [
{
"comment_text": "",
"digests": {
"md5": "7b9470c708910e76f8adab9e7d0a52f8",
"sha256": "f2ef099df62cf2a87c1d8f1e5413d317a98e59613500a51fc8462a6de77fae12"
},
"downloads": -1,
"filename": "tern-0.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b9470c708910e76f8adab9e7d0a52f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 66062,
"upload_time": "2019-08-27T19:58:58",
"url": "https://files.pythonhosted.org/packages/44/3d/532d8dd97263a8549d787f7b8d57f2001ac917e0ba8486af74de1ef54f29/tern-0.5.4-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "79ae2c70efec3e3f502d7599b5d49651",
"sha256": "76195617f01cfe96300d292eeb750867ef13104dd59b742becdc9a25ecf2f234"
},
"downloads": -1,
"filename": "tern-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "79ae2c70efec3e3f502d7599b5d49651",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3234877,
"upload_time": "2019-08-27T19:59:02",
"url": "https://files.pythonhosted.org/packages/72/ee/fb19b768c2c8665c3b5aadcea5795e15b5f7be43422beaa2e83b52064832/tern-0.5.4.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "7b9470c708910e76f8adab9e7d0a52f8",
"sha256": "f2ef099df62cf2a87c1d8f1e5413d317a98e59613500a51fc8462a6de77fae12"
},
"downloads": -1,
"filename": "tern-0.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b9470c708910e76f8adab9e7d0a52f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 66062,
"upload_time": "2019-08-27T19:58:58",
"url": "https://files.pythonhosted.org/packages/44/3d/532d8dd97263a8549d787f7b8d57f2001ac917e0ba8486af74de1ef54f29/tern-0.5.4-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "79ae2c70efec3e3f502d7599b5d49651",
"sha256": "76195617f01cfe96300d292eeb750867ef13104dd59b742becdc9a25ecf2f234"
},
"downloads": -1,
"filename": "tern-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "79ae2c70efec3e3f502d7599b5d49651",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3234877,
"upload_time": "2019-08-27T19:59:02",
"url": "https://files.pythonhosted.org/packages/72/ee/fb19b768c2c8665c3b5aadcea5795e15b5f7be43422beaa2e83b52064832/tern-0.5.4.tar.gz"
}
]
}