Safety v3.5.1 is now available. Upgrade using "pip install -U safety"
Safety Firewall
LogoLogo
Safety PlatformResearchSign Up
  • Introduction to Safety
  • Safety Firewall
    • Introduction to Safety Firewall
    • Installation and Configuration
      • Uninstalling Firewall
    • Using Firewall
      • Working with Codebases
      • Firewall Monitoring and Management
      • Firewall Policy Management
      • Troubleshooting
  • SAFETY CLI
    • Introduction to Safety CLI Vulnerability Scanning
      • Quick Start Guide
      • Migrating from Safety CLI 2.x to Safety CLI 3.x
    • Installation and Authentication
    • Scanning for Vulnerable and Malicious Packages
      • Viewing Scan Results
      • Available Commands and Inputs
      • Scanning in CI/CD
      • Securing Development Environments
      • License Scanning
      • Exit Codes
      • Scanning in Production
    • Safety Telemetry
  • Vulnerability Remediation
    • Applying Fixes
  • Integration
    • Securing Git Repositories
      • GitHub
        • GitHub Actions
      • GitLab
      • BitBucket
      • Git Post-Commit Hooks
    • Pipenv
    • Docker Containers
  • Administration
    • Safety Policy Files
    • Project Policies
  • Output
    • Output Options and Recommendations
    • JSON Output
    • SBOM Output
    • HTML Output
    • Detecting Vulnerabilities and Sharing Results via Email
  • Support
    • Support
    • Invalid API Key Error
    • Headless Authentication
    • Implementation Support
    • Global proxy and identity configuration
    • Using Safety in Conda Environments
  • Miscellaneous
    • Understanding Vulnerability Scoring Systems: CVSS and EPSS
    • Release Notes
      • Breaking Changes in Safety 3
    • Research and Blog
    • Changelogs
    • Trust Center
    • Terms of Service
    • Safety 2.x Documentation
Powered by GitBook
LogoLogo

Safety Platform

  • Sign Up
  • Login

Research

  • Security Research & Blog

Resources

  • GitHub Action
  • GitHub

© Safety CLI Cybersecurity Inc.

On this page
  • Installing Safety 3.x
  • Switching to the new `scan` command:
  • Configuration files: Convert to the new policy file format
  • Updating your scan target(s)
  • New JSON output format
  • Upgrading from safety 2.x to safety 3.x while using safety check's JSON output
  • Using both safety check and safety scan in the same project

Was this helpful?

  1. SAFETY CLI
  2. Introduction to Safety CLI Vulnerability Scanning

Migrating from Safety CLI 2.x to Safety CLI 3.x

PreviousQuick Start GuideNextInstallation and Authentication

Last updated 9 days ago

Was this helpful?

Safety CLI 3 is a significant update from Safety CLI 2.x versions, including enhancements to core features, new capabilities, and .

Here's a step-by-step guide covering everything you need to know when upgrading.

Installing Safety 3.x

  1. Start by opening your Terminal and uninstall the current version of Safety CLI installed in your environment:

pip uninstall safety
  1. Install the latest version of Safety using the following command:

pip install safety

Safety CLI 3.x should now be installed on your machine. To check which version is currently installed:

safety --version

If this returns a version other than 3.x, there could be more than one installation of Safety on your machine. To check where Safety is being run from, run the which safety command.

Switching to the new `scan` command:

The most significant change is Safety CLI 3's scan command, which replaces the old safety check command as the main security scanning command. safety scan is more powerful, configurable, and easier to use compared to safety check, and differs in the following key ways:

  • it searches the target directory being scanned recursively, finding and reporting all Python dependency manifest files and virtual environments automatically, without any need for specifying where these files are

  • it natively supports requirements.txt, poetry.lock, and Pipfile.lock files as well as Python virtual environment directories

  • it is configured with a differently structured .safety-policy.yml file, which is incompatible with the .safety-policy.yml file used with the older `safety check` command, and visa versa. This new configuration file is more flexible and powerful

  • it can be configured for how it searches the project directory, which vulnerabilities it reports on, and separately defines rules for which vulnerabilities will return a failing (non-zero) exit code, for use within CI/CD pipelines and build scripts

We highly recommend switching to safety scan as soon as possible.

Configuration files: Convert to the new policy file format

If you are not currently using a .safety-policy.yml file with safety check, you can skip this section!

If you have been using a .safety-policy.yml file with safety check, you'll need to convert this to safety scan's new policy file format to use it to maintain the same policies with safety scan. To do this:

  • Navigate to the root of your existing project

  • Move your existing policy file to a different location within your project, so that you can reference it later. (If you want to continue using safety check while also the new safety scan command, see instructions below [link])

  • Using Safety CLI 3 (run safety --version to confirm your Safety CLI version), run safety generate policy_file to generate a new policy file with the updated format.

  • Open both policy files, and translate the relevant parts from your old policy file into the new one. The key configurations that move are:

    • Any specific vulnerabilities you have ignored in security:ignore-vulnerabilities move to report:auto-ignore-in-report:vulnerabilities which contains the same list of ignores.

    • security:ignore-cvss-severity-below and security:ignore-cvss-unknown-severity move to a combined report:auto-ignore-in-report:cvss-severity which is now a YAML list with options: critical, high, medium, low, and unknown.

    • The boolean security:continue-on-vulnerability-error:True property is now removed. To suppress exit codes in the new policy file, use the fail-scan-with-exit-code:dependency-vulnerabilities:enabled:False property.

    • The alert section of the old policy file is no longer supported and must be removed. This functionality is being replaced by Safety Platform.

  • With these changes your policies are now translated to the new policy format, ready to be used with safety scan

  • When using the validate command, Safety CLI 3 will validate a 3.0 policy file by default.

Updating your scan target(s)

If you were using Safety check with the -r flag to specify requirements.txt files to scan, you no longer need these with safety scan - they should be found automatically.

New JSON output format

Upgrading from safety 2.x to safety 3.x while using safety check's JSON output

Safety CLI 3 still supports the safety check command, which is almost identical to safety check from Safety 2.x. If you are upgrading from Safety CLI 2 to Safety CLI 3, you can do so without needing to make any changes. The only breaking changes in this case may be the JSON output structure. Safety 3.0's JSON output from safety check uses the same structure as Safety CLI 2.4.0b. If you are upgrading from safety<=2.3.5 to safety>=3.x the JSON output from safety check will differ.

Using both safety check and safety scan in the same project

You can use Safety CLI 3 to run both safety check and safety scan commands, each with their own policy files. To achieve this, keep your old safety check policy file in your project directory under a new name, for example .safety-check-policy.yml, and run the check command using safety check --policy-file .safety-check-policy.yml to specify the policy file's path. This will allow you to shift to using safety scan and the new policy file format at the default .safety-policy.yml location.

Safety CLI 3's scan and system-scan commands are configured using a new and updated configuration file. See for full details on the new structure and features of this policy file.

If safety scan is finding dependency files or virtual environments you do not want to include in your reports, use the new scanning-settings:exclude property in your .safety-policy.yml file to exclude specific files, file types or folders from the scan.

Safety scan has a new format that differs substantially from the JSON output of safety check.

Safety 3's policy file documentation page
See more details on excluding here.
JSON output
breaking changes