safety 1.10.3

Checks installed dependencies for known vulnerabilities.

Safety checks your installed dependencies for known security vulnerabilities.

By default it uses the open Python vulnerability database Safety DB, but can be upgraded to use pyup.io's Safety API using the --key option.

Installation

Install safety with pip. Keep in mind that we support only Python 3.5 and up. Look at Python 2.7 section at the end of this document.

pip install safety

Usage

To check your currently selected virtual environment for dependencies with known security vulnerabilites, run:

safety check

You should get a report similar to this:

+==============================================================================+
|                                                                              |
|                               /$$$$$$            /$$                         |
|                              /$$__  $$          | $$                         |
|           /$$$$$$$  /$$$$$$ | $$  \__//$$$$$$  /$$$$$$   /$$   /$$           |
|          /$$_____/ |____  $$| $$$$   /$$__  $$|_  $$_/  | $$  | $$           |
|         |  $$$$$$   /$$$$$$$| $$_/  | $$$$$$$$  | $$    | $$  | $$           |
|          \____  $$ /$$__  $$| $$    | $$_____/  | $$ /$$| $$  | $$           |
|          /$$$$$$$/|  $$$$$$$| $$    |  $$$$$$$  |  $$$$/|  $$$$$$$           |
|         |_______/  \_______/|__/     \_______/   \___/   \____  $$           |
|                                                          /$$  | $$           |
|                                                         |  $$$$$$/           |
|  by pyup.io                                              \______/            |
|                                                                              |
+==============================================================================+
| REPORT                                                                       |
+==============================================================================+
| No known security vulnerabilities found.                                     |
+==============================================================================+

Now, let's install something insecure:

pip install insecure-package

Yeah, you can really install that.

Run safety check again:

+==============================================================================+
|                                                                              |
|                               /$$$$$$            /$$                         |
|                              /$$__  $$          | $$                         |
|           /$$$$$$$  /$$$$$$ | $$  \__//$$$$$$  /$$$$$$   /$$   /$$           |
|          /$$_____/ |____  $$| $$$$   /$$__  $$|_  $$_/  | $$  | $$           |
|         |  $$$$$$   /$$$$$$$| $$_/  | $$$$$$$$  | $$    | $$  | $$           |
|          \____  $$ /$$__  $$| $$    | $$_____/  | $$ /$$| $$  | $$           |
|          /$$$$$$$/|  $$$$$$$| $$    |  $$$$$$$  |  $$$$/|  $$$$$$$           |
|         |_______/  \_______/|__/     \_______/   \___/   \____  $$           |
|                                                          /$$  | $$           |
|                                                         |  $$$$$$/           |
|  by pyup.io                                              \______/            |
|                                                                              |
+==============================================================================+
| REPORT                                                                       |
+==========================+===============+===================+===============+
| package                  | installed     | affected          | source        |
+==========================+===============+===================+===============+
| insecure-package         | 0.1.0         | <0.2.0            | changelog     |
+==========================+===============+===================+===============+

Examples

Read requirement files

Just like pip, Safety is able to read local requirement files:

safety check -r requirements.txt

Read from stdin

Safety is also able to read from stdin with the --stdin flag set.

To check a local requirements file, run:

cat requirements.txt | safety check --stdin

or the output of pip freeze:

pip freeze | safety check --stdin

or to check a single package:

echo "insecure-package==0.1" | safety check --stdin

For more examples, take a look at the options section.

Scan a Python-based Docker image

To scan a docker image IMAGE_TAG, you can run

docker run -it --rm ${IMAGE_TAG} "/bin/bash -c \"pip install safety && safety check\"

Using Safety in Docker

Safety can be easily executed as Docker container. It can be used just as described in the examples section.

echo "insecure-package==0.1" | docker run -i --rm pyupio/safety safety check --stdin
cat requirements.txt | docker run -i --rm pyupio/safety safety check --stdin

Using the Safety binaries

The Safety binaries provide some extra security.

After installation, they can be used just like the regular command line version of Safety.

Using Safety with a CI service

Safety works great in your CI pipeline. It returns a non-zero exit status if it finds a vulnerability.

Run it before or after your tests. If Safety finds something, your tests will fail.

Travis

install:
  - pip install safety

script:
  - safety check

Gitlab CI

safety:
  script:
    - pip install safety
    - safety check

Tox

[tox]
envlist = py37

[testenv]
deps =
    safety
    pytest
commands =
    safety check
    pytest

Deep GitHub Integration

If you are looking for a deep integration with your GitHub repositories: Safety is available as a part of pyup.io, called Safety CI. Safety CI checks your commits and pull requests for dependencies with known security vulnerabilities and displays a status on GitHub.

Using Safety in production

Safety is free and open source (MIT Licensed). The underlying open vulnerability database is updated once per month.

To get access to all vulnerabilites as soon as they are added, you need a Safety API key that comes with a paid pyup.io account, starting at $99.

Options

--key

API Key for pyup.io's vulnerability database. Can be set as SAFETY_API_KEY environment variable.

Example

safety check --key=12345-ABCDEFGH

---

--db

Path to a directory with a local vulnerability database including insecure.json and insecure_full.json

Example

safety check --db=/home/safety-db/data

--proxy-host

Proxy host IP or DNS

--proxy-port

Proxy port number

--proxy-protocol

Proxy protocol (https or http)

---

--json

Output vulnerabilities in JSON format.

Example

safety check --json

[
    [
        "django",
        "<1.2.2",
        "1.2",
        "Cross-site scripting (XSS) vulnerability in Django 1.2.x before 1.2.2 allows remote attackers to inject arbitrary web script or HTML via a csrfmiddlewaretoken (aka csrf_token) cookie.",
        "25701"
    ]
]

---

--full-report

Full reports includes a security advisory. It also shows CVSS values for CVEs (requires a premium PyUp subscription).

Example

safety check --full-report

+==============================================================================+
|                                                                              |
|                               /$$$$$$            /$$                         |
|                              /$$__  $$          | $$                         |
|           /$$$$$$$  /$$$$$$ | $$  \__//$$$$$$  /$$$$$$   /$$   /$$           |
|          /$$_____/ |____  $$| $$$$   /$$__  $$|_  $$_/  | $$  | $$           |
|         |  $$$$$$   /$$$$$$$| $$_/  | $$$$$$$$  | $$    | $$  | $$           |
|          \____  $$ /$$__  $$| $$    | $$_____/  | $$ /$$| $$  | $$           |
|          /$$$$$$$/|  $$$$$$$| $$    |  $$$$$$$  |  $$$$/|  $$$$$$$           |
|         |_______/  \_______/|__/     \_______/   \___/   \____  $$           |
|                                                          /$$  | $$           |
|                                                         |  $$$$$$/           |
|  by pyup.io                                              \______/            |
|                                                                              |
+==============================================================================+
| REPORT                                                                       |
+============================+===========+==========================+==========+
| package                    | installed | affected                 | ID       |
+============================+===========+==========================+==========+
| CVSS v2 | BASE SCORE: 6.5 | IMPACT SCORE: 6.4                                |
+============================+===========+==========================+==========+
| django                     | 1.2       | <1.2.2                   | 25701    |
+==============================================================================+
| Cross-site scripting (XSS) vulnerability in Django 1.2.x before 1.2.2 allows |
|  remote attackers to inject arbitrary web script or HTML via a csrfmiddlewar |
| etoken (aka csrf_token) cookie.                                              |
+==============================================================================+

---

--bare

Output vulnerable packages only. Useful in combination with other tools.

Example

safety check --bare

cryptography django

---

--cache

Cache requests to the vulnerability database locally for 2 hours.

Example

safety check --cache

---

--stdin

Read input from stdin.

Example

cat requirements.txt | safety check --stdin

pip freeze | safety check --stdin

echo "insecure-package==0.1" | safety check --stdin

---

--file, -r

Read input from one (or multiple) requirement files.

Example

safety check -r requirements.txt

safety check --file=requirements.txt

safety check -r req_dev.txt -r req_prod.txt

---

--ignore, -i

Ignore one (or multiple) vulnerabilities by ID

Example

safety check -i 1234

safety check --ignore=1234

safety check -i 1234 -i 4567 -i 89101

--output, -o

Save the report to a file

Example

safety check -o insecure_report.txt

safety check --output --json insecure_report.json

---

Review

If you save the report in JSON format you can review in the report format again.

Options

--file, -f (REQUIRED)

Read an insecure report.

Example

safety review -f insecure.json

safety review --file=insecure.json

---

--full-report

Full reports include a security advisory (if available).

Example

safety review -r insecure.json --full-report

+==============================================================================+
|                                                                              |
|                               /$$$$$$            /$$                         |
|                              /$$__  $$          | $$                         |
|           /$$$$$$$  /$$$$$$ | $$  \__//$$$$$$  /$$$$$$   /$$   /$$           |
|          /$$_____/ |____  $$| $$$$   /$$__  $$|_  $$_/  | $$  | $$           |
|         |  $$$$$$   /$$$$$$$| $$_/  | $$$$$$$$  | $$    | $$  | $$           |
|          \____  $$ /$$__  $$| $$    | $$_____/  | $$ /$$| $$  | $$           |
|          /$$$$$$$/|  $$$$$$$| $$    |  $$$$$$$  |  $$$$/|  $$$$$$$           |
|         |_______/  \_______/|__/     \_______/   \___/   \____  $$           |
|                                                          /$$  | $$           |
|                                                         |  $$$$$$/           |
|  by pyup.io                                              \______/            |
|                                                                              |
+==============================================================================+
| REPORT                                                                       |
+============================+===========+==========================+==========+
| package                    | installed | affected                 | ID       |
+============================+===========+==========================+==========+
| django                     | 1.2       | <1.2.2                   | 25701    |
+==============================================================================+
| Cross-site scripting (XSS) vulnerability in Django 1.2.x before 1.2.2 allows |
|  remote attackers to inject arbitrary web script or HTML via a csrfmiddlewar |
| etoken (aka csrf_token) cookie.                                              |
+==============================================================================+

---

--bare

Output vulnerable packages only.

Example

safety review --file report.json --bare

django

---

License

Display packages licenses information (requires a premium PyUp subscription).

Options

--key (REQUIRED)

API Key for pyup.io's licenses database. Can be set as SAFETY_API_KEY environment variable.

Example

safety license --key=12345-ABCDEFGH

Shows the license of each package in the current environment

+==============================================================================+
|                                                                              |
|                               /$$$$$$            /$$                         |
|                              /$$__  $$          | $$                         |
|           /$$$$$$$  /$$$$$$ | $$  \__//$$$$$$  /$$$$$$   /$$   /$$           |
|          /$$_____/ |____  $$| $$$$   /$$__  $$|_  $$_/  | $$  | $$           |
|         |  $$$$$$   /$$$$$$$| $$_/  | $$$$$$$$  | $$    | $$  | $$           |
|          \____  $$ /$$__  $$| $$    | $$_____/  | $$ /$$| $$  | $$           |
|          /$$$$$$$/|  $$$$$$$| $$    |  $$$$$$$  |  $$$$/|  $$$$$$$           |
|         |_______/  \_______/|__/     \_______/   \___/   \____  $$           |
|                                                          /$$  | $$           |
|                                                         |  $$$$$$/           |
|  by pyup.io                                              \______/            |
|                                                                              |
+==============================================================================+
| Packages licenses                                                            |
+=============================================+===========+====================+
| package                                     |  version  | license            |
+=============================================+===========+====================+
| requests                                    | 2.25.0    | Apache-2.0         |
|------------------------------------------------------------------------------|
| click                                       | 7.1.2     | BSD-3-Clause       |
|------------------------------------------------------------------------------|
| safety                                      | 1.10.0    | MIT                |
+==============================================================================+

---

--db

Path to a directory with a local licenses database licenses.json

Example

safety license --key=12345-ABCDEFGH --db=/home/safety-db/data

---

--no-cache

Since PyUp.io licenses DB is updated once a week, the licenses database is cached locally for 7 days. You can use --no-cache to download it once again.

Example

safety license --key=12345-ABCDEFGH --no-cache

---

--file, -r

Read input from one (or multiple) requirement files.

Example

safety license --key=12345-ABCDEFGH -r requirements.txt

safety license --key=12345-ABCDEFGH --file=requirements.txt

safety license --key=12345-ABCDEFGH -r req_dev.txt -r req_prod.txt

---

--proxy-host, -ph

Proxy host IP or DNS

--proxy-port, -pp

Proxy port number

--proxy-protocol, -pr

Proxy protocol (https or http)

Example

safety license --key=12345-ABCDEFGH -ph 127.0.0.1 -pp 8080 -pr https

---

Python 2.7

This tool requires latest Python patch versions starting with version 3.5. We did support Python 2.7 in the past but, as for other Python 3.x minor versions, it reached its End-Of-Life and as such we are not able to support it anymore.

We understand you might still have Python 2.7 projects running. At the same time, Safety itself has a commitment to encourage developers to keep their software up-to-date, and it would not make sense for us to work with officially unsupported Python versions, or even those that reached their end of life.

If you still need to run Safety from a Python 2.7 environment, please use version 1.8.7 available at PyPi. Alternatively, you can run Safety from a Python 3 environment to check the requirements file for your Python 2.7 project.

======= History

1.10.3 (2021-01-15)

• Avoid 1.10.2post1 bug with pyup updates

1.10.2 (2021-01-12)

• Provide CVSS values on full report for CVEs (requires a premium PyUp subscription)
• Fixed used DB wrong info
• Support line breaks on advisories

1.10.1 (2021-01-03)

• Reduced Docker image and Binary size
• Added bare and json outputs to license command

1.10.0 (2020-12-20)

• Added README information about Python 2.7 workaround
• Adjusted some pricing information
• Fixed MacOS binary build through AppVeyor
• Added the ability to check packages licenses (requires a premium PyUp subscription)

1.9.0 (2020-04-27)

• Dropped Python 2.7 support, requiring Python 3.5+
• Binary adjustments and enhancements on top of reported vulnerability
• Using tox to help with local tests against different Python versions

1.8.7 (2020-03-10)

• Fixed a hidden import caused the binary to produce errors on Linux.

1.8.6 (2020-03-10)

• Safety is now available as a binary release for macOS, Windows and Linux.

1.8.5 (2019-02-04)

• Wrap words in full report (Thanks @mgedmin)
• Added Dockerfile and readme instructions (Thanks @ayeks)
• Remove API dependency on pip (Thanks @benjaminp)

1.8.4 (2018-08-03)

• Update cryptography dependency from verision 1.9 to version 2.3 due to security vulnerability

1.8.3b (2018-07-24)

• Allows both unicode and non-unicode type encoding when parsing requriment files

1.8.2 (2018-07-10)

• Fixed unicode error

1.8.1 (2018-04-06)

• Fixed a packaging error with the dparse dependency

1.8.0 (2018-04-05)

• Safety now support pip 10

1.7.0 (2018-02-03)

• Safety now shows a filename if it finds an unpinned requirement. Thanks @nnadeau
• Removed official support for Python 2.6 and Python 3.3. Thanks @nnadeau

1.6.1 (2017-10-20)

• Fixed an error that caused the CLI to fail on requirement files/stdin.

1.6.0 (2017-10-20)

• Added an indicator which DB is currently used
• Added a package count how many packages have been checked
• Allow multiple version of the same library. Thanks @thatarchguy

1.5.1 (2017-07-20)

• Fixed an error on unpinned VCS requirements. This is a regression, see https://github.com/pyupio/safety/issues/72

1.5.0 (2017-07-19)

• Internal refactoring. Removed dependency on setuptools and switched to the new dparse library.

1.4.1 (2017-07-04)

• Fixed a bug where absence of stty was causing a traceback in safety check on Python 2.7 for Windows.

1.4.0 (2017-04-21)

• Added the ability to ignore one (or multiple) vulnerabilities by ID via the --ignore/-i flag.

1.3.0 (2017-04-21)

• Added --bare output format.
• Added a couple of help text to the command line interface.
• Fixed a bug that caused requirement files with unpinned dependencies to fail when using a recent setuptools release.

1.2.0 (2017-04-06)

• Added JSON as an output format. Use it with the --json flag. Thanks @Stype.

1.1.1 (2017-03-27)

• Fixed terminal size detection when fed via stdin.

1.1.0 (2017-03-23)

• Compatibility release. Safety should now run on macOs, Linux and Windows with Python 2.7, 3.3-3.6. Python 2.6 support is available on a best-effort basis on Linux.

1.0.2 (2017-03-23)

• Fixed another error on Python 2. The fallback function for get_terminal_size wasn't working correctly.

1.0.1 (2017-03-23)

• Fixed an error on Python 2, FileNotFoundError was introduced in Python 3.

1.0.0 (2017-03-22)

• Added terminal size detection. Terminals with fewer than 80 columns should now display nicer reports.
• Added an option to load the database from the filesystem or a mirror that's reachable via http(s). This can be done by using the --db flag.
• Added an API Key option that uses pyup.io's vulnerability database.
• Added an option to cache the database locally for 2 hours. The default still is to not use the cache. Use the --cache flag.

0.6.0 (2017-03-10)

• Made the requirements parser more robust. The parser should no longer fail on editable requirements and requirements that are supplied by package URL.
• Running safety requires setuptools >= 16

0.5.1 (2016-11-08)

• Fixed a bug where not all requirement files were read correctly.

0.5.0 (2016-11-08)

• Added option to read requirements from files.

0.4.0 (2016-11-07)

• Filter out non-requirements when reading from stdin.

0.3.0 (2016-10-28)

• Added option to read from stdin.

0.2.2 (2016-10-21)

• Fix import errors on python 2.6 and 2.7.

0.2.1 (2016-10-21)

• Fix packaging bug.

0.2.0 (2016-10-20)

• Releasing first prototype.

0.1.0 (2016-10-19)

• First release on PyPI.