You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+44-44
Original file line number
Diff line number
Diff line change
@@ -82,47 +82,47 @@ Once installed, make sure the docker daemon is running.
82
82
83
83
Create a python3 virtual environment:
84
84
```
85
-
$ python3 -m venv ternenv
86
-
$ cd ternenv
85
+
python3 -m venv ternenv
86
+
cd ternenv
87
87
```
88
88
89
89
*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`.
90
90
91
91
Activate the virtual environment:
92
92
```
93
-
$ source bin/activate
93
+
source bin/activate
94
94
```
95
95
NOTE: This specific activate script only works for Bash shells. If you need to activate a Fish Shell or C Shell you should use `source bin/activate.fish` or `source bin/activate.csh`, respectively.
96
96
97
97
Install tern:
98
98
```
99
-
$ pip install tern
99
+
pip install tern
100
100
```
101
101
102
102
Run Tern:
103
103
```
104
-
$ tern report -o output.txt -i debian:buster
104
+
tern report -o output.txt -i debian:buster
105
105
```
106
106
107
107
## Getting Started with Docker<aname="getting-started-with-docker">
108
108
Docker 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.
Build the Docker image (called `ternd` here). You may need to use sudo:
116
116
```
117
-
$ docker build -f docker/Dockerfile -t ternd .
117
+
docker build -f docker/Dockerfile -t ternd .
118
118
```
119
119
120
120
This will install the latest release of tern using pip.
121
121
122
122
If you want to build a Docker image containing the latest changes to tern, run:
123
123
```
124
-
$ python setup.py sdist
125
-
$ docker build -f ci/Dockerfile -t ternd .
124
+
python setup.py sdist
125
+
docker build -f ci/Dockerfile -t ternd .
126
126
```
127
127
128
128
**NOTE**: By default, Tern will run with logging turned on. If you would like to silent the terminal output when running the ternd container, make the following change to the Dockerfile ENTRYPOINT before building:
If you are using this container to analyze Dockerfiles and to use the "lock" feature, then you must volume mount the docker socket. We have a convenience script which will do that for you.
Once build has completed, you should see the image by running `minikube image ls`. It should look something like `docker.io/library/tern:test`.
@@ -210,7 +210,7 @@ spec:
210
210
211
211
We can now deploy Tern on Kubernetes
212
212
```
213
-
$ minikube kubectl -- apply -f tern-example.yaml
213
+
minikube kubectl -- apply -f tern-example.yaml
214
214
```
215
215
216
216
To check the status of the Job, you can run `minikube kubectl -- describe job.batch/tern`. You should be able to see `report.txt` in `/path/to/tern/reports/`.
@@ -230,23 +230,23 @@ In your terminal app, run the following commands.
@@ -258,25 +258,25 @@ Tern creates a report containing the Software Bill of Materials (SBOM) of a cont
258
258
## Generating an SBOM report for a Docker image<aname="sbom-for-docker-image">
259
259
If you have a Docker image pulled locally and want to inspect it
260
260
```
261
-
$ tern report -i debian:jessie
261
+
tern report -i debian:jessie
262
262
```
263
263
The SBOM of packages that are installed in the Docker image and how Tern got this information will be printed to the console. To direct this output to a file, use the `-o file_name` command line option. If you encounter any errors, please file an issue.
264
264
265
265
## Generating an SBOM report from a Dockerfile<aname="sbom-for-dockerfile">
266
266
You can provide a Dockerfile to Tern to figure out the Software 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.
267
267
```
268
-
$ tern report -d samples/photon_git/Dockerfile
268
+
tern report -d samples/photon_git/Dockerfile
269
269
```
270
270
The SBOM of packages you would be shipping if you were to use the given Dockerfile will print to the console. To direct the output to a file, use the `-o file_name` command line option. 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.
271
271
272
272
## Generating a locked Dockerfile<aname="dockerfile-lock">
273
273
Because of the way Docker builds containers, Dockerfiles are generally not declarative or reflective of what ultimately gets included in the container image that gets produced. Pinning information in your Dockerfile (base OS, packages, etc.) can help create more reproducible container images should your Dockerfile be distributed to other parties. If you have a Dockerfile that you would like to lock to a more reproducible version, Tern can help.
274
274
```
275
-
$ tern lock Dockerfile
275
+
tern lock Dockerfile
276
276
```
277
277
The locked Dockerfile will be created in `Dockerfile.lock` unless an output file is otherwise specified. To specify an output file
278
278
```
279
-
$ tern lock Dockerfile -o output.txt
279
+
tern lock Dockerfile -o output.txt
280
280
```
281
281
If the packages are not pinned in the resulting `Dockerfile.lock` or output file that gets produced, it is because 1) Tern does not know the version of the packages to pin (i.e. unable to get this information from the package manager) or 2) your Dockerfile failed to build. In the case of a failed Dockerfile build, Tern only builds the base image and tries to pin what it can. If you encounter any errors, please file an issue.
282
282
@@ -295,49 +295,49 @@ The default report Tern produces is a human readable, high-level overview. The o
295
295
296
296
While the packages found in each layer and their associated version and license are listed on a per layer basis, there is also a summary of licenses found in the container printed at the bottom of the report which is unique to the default human readable format.
297
297
```
298
-
$ tern report -i golang:1.12-alpine -o output.txt
298
+
tern report -i golang:1.12-alpine -o output.txt
299
299
```
300
300
301
301
## JSON Format<aname="report-json">
302
302
You can get the results in a JSON file to pass around in a network. The JSON report contains the most amount of container metadata compared to the default report and because of this, is often a very large file. If you are planning to look for information in this file manually, we recommend using the `jq` utility to better display and understand the information in the report.
303
303
304
304
In terms of general container information, the JSON report provides detailed "created by" information including docker container config information, layer `created_by` information and layer creation time stamps. It also provides the `diff_id` and tar file information for each layer, including each layer's unique package set and the packages metadata. The JSON report will also provide more detailed package metadata (if found) including the project URL information, files found in each package when run with scancode and package licenses (`pkg_licenses`) for containers based on Debian OSes where license information is parsed from Copyright text instead of declared by the package manager (`pkg_license`).
305
305
```
306
-
$ tern report -f json -i golang:1.12-alpine
306
+
tern report -f json -i golang:1.12-alpine
307
307
```
308
308
309
309
## HTML Format<aname="report-html">
310
310
You can get an html rendering of the JSON results. An output file with `.html` suffix should be provided in order to properly view the report in your browser. The HTML report will include all of the same information found in a JSON report. See above for details about the JSON report.
311
311
```
312
-
$ tern report -f html -i golang:1.12-alpine -o report.html
312
+
tern report -f html -i golang:1.12-alpine -o report.html
313
313
```
314
314
315
315
## YAML Format<aname="report-yaml">
316
316
You can get the results in a YAML file to be consumed by a downstream tool or script. The YAML information will be the same information found in the JSON report. See above for details about the JSON report.
[SPDX](https://spdx.org/) is a format developed by the Linux Foundation to provide a standard way of reporting license information. It is now an [ISO standard](https://www.iso.org/standard/81870.html). The National Telecommunications and Information Administration (NTIA) [recognizes SPDX](https://www.ntia.gov/files/ntia/publications/sbom_options_and_decision_points_20210427-1.pdf) as one of three valid SBOM formats that satisfies the minimum viable requirements for an SBOM in accordance with President Biden's [Executive Order on Improving the Nation's Cybersecurity](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/).
323
323
324
324
Many compliance tools are compatible with SPDX. Tern follows the [SPDX specifications](https://spdx.org/specifications). The tag-value format is most compatible with the toolkit the organization provides. 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).
The SPDX JSON format contains the same information that an SPDX Tag-value document does. The only difference between these two formats is the way the information is represented. The 'spdxjson' format represents the container information as a collection of key-value pairs. In some cases, the SPDX JSON format may be more interoperable between cloud native compliance tools.
[OWASP CycloneDX](https://cyclonedx.org/) is a lightweight software bill of materials standard designed for use in application security contexts and supply chain component analysis. The National Telecommunications and Information Administration (NTIA) [recognizes CycloneDX](https://www.ntia.gov/files/ntia/publications/sbom_options_and_decision_points_20210427-1.pdf) as one of three valid SBOM formats that satisfies the minimum viable requirements for an SBOM in accordance with President Biden's [Executive Order on Improving the Nation's Cybersecurity](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/).
337
337
338
338
Many tools for producing and consuming CycloneDX SBOMs are listed in the [CycloneDX Tool Center](https://cyclonedx.org/tool-center/).
@@ -354,21 +354,21 @@ NOTE: Neither the Docker container nor the Vagrant image has any of the extensio
354
354
355
355
2. Setup a python virtual environment
356
356
```
357
-
$ python3 -m venv scanenv
358
-
$ cd scanenv
359
-
$ source bin/activate
357
+
python3 -m venv scanenv
358
+
cd scanenv
359
+
source bin/activate
360
360
```
361
361
3. Install tern and scancode
362
362
```
363
-
$ pip install tern scancode-toolkit
363
+
pip install tern scancode-toolkit
364
364
```
365
365
<br> If you are using macOS on M1 or Linux on ARM, run:</br>
366
366
```
367
-
$ pip install tern scancode-toolkit-mini
367
+
pip install tern scancode-toolkit-mini
368
368
```
369
369
4. Run tern with scancode
370
370
```
371
-
$ tern report -x scancode -i golang:1.12-alpine
371
+
tern report -x scancode -i golang:1.12-alpine
372
372
```
373
373
374
374
If you are running Scancode for the first time, depending on the size of the container image, it takes anywhere between 10 minutes to a few hours to run due to the number of files needed to be analyzed. Once completed, subsequent runs will be much faster as the data will be cached for future use.
@@ -380,23 +380,23 @@ If you are running Scancode for the first time, depending on the size of the con
0 commit comments