Package: safety
IntroductionSafety CLI is a Python dependency vulnerability scanner designed to enhance software supply chain security by detecting packages with known vulnerabilities and malicious packages in local development environments, CI/CD, and production systems.
Safety CLI can be deployed in minutes and provides clear, actionable recommendations for remediation of detected vulnerabilities.Leveraging the industry's most comprehensive database of vulnerabilities and malicious packages, Safety CLI Scanner allows teams to detect vulnerabilities at every stage of the software development lifecycle.Key FeaturesVersatile, comprehensive dependency security scanning for Python packages.Leverages Safety DB, the most comprehensive vulnerability data available for Python.Clear output with detailed recommendations for vulnerability remediation.Automatically updates requirements files to secure versions of dependencies where available, guided by your project's policy settings.Scanning of individual requirements files and project directories or system-wide scans on developer machines, CI/CD pipelines, and Production systems to detect vulnerable or malicious dependencies.JSON, SBOM, HTML and text output.Easy integration with CI/CD pipelines, including GitHub Actions.Enterprise Ready: Safety CLI can be deployed to large teams with complex project setups with ease, on-premise or as a SaaS product.Getting StartedGitHub ActionTest Safety CLI in CI/CD using ourGitHub Action.Full documentation on theGitHub Actionis available on ourDocumentation Hub.Command Line Interface1. InstallationInstall Safety on your development machine.Runpip install safety.2. Log In or RegisterRun your first scan usingsafety scan.If not authenticated, Safety will prompt for account creation or login.Usesafety authto check authentication status.3. Running Your First ScanNavigate to a project directory and runsafety scan.Safety will perform a scan and present results in the Terminal.Basic Commandssafety --help: Access help and display all available commands.safety auth: Start authentication flow or display status.safety scan: Perform a vulnerability scan in the current directory.safety system-scan: Perform a scan across the entire development machine.safety scan --apply-fixes: Update vulnerable dependencies.Detailed DocumentationFull documentation is available athttps://docs.safetycli.com.Included in the documentation are the following key topics:Safety CLI 3Introduction to Safety CLI 3Quick Start GuideInstallation and AuthenticationScanning for Vulnerable and Malicious PackagesSystem-Wide Developer Machine ScanningViewing Scan ResultsAvailable Commands and InputsScanning in CI/CDLicense ScanningExit CodesVulnerability RemediationApplying FixesIntegrationSecuring Git RepositoriesGitHubGitHub ActionsGitLabGit Post-Commit HooksBitBucketPipenvDocker ContainersAdministrationPolicy ManagementOutputOutput Options and RecommendationsJSON OutputSBOM OutputHTML OutputMiscellaneousRelease NotesBreaking Changes in Safety 3Safety 2.x DocumentationSupportSystem status is available athttps://status.safetycli.comFurther support is available by emailingsupport@safetycli.com.LicenseSafety is released under the MIT License.Upon creating an account, a 7-day free trial of our Team plan is offered to new users, after which they will be downgraded to our Free plan. This plan is limited to a single user and is not recommended for commercial purposes.Our paidplans for commercial usebegin at just $25 per seat per month and allow scans to be performed using our full vulnerability database, complete with 3x more tracked vulnerabilities and malicious packages than our free plan and other providers. To learn more about our Team and Enterprise plans, please visithttps://safetycli.com/resources/plansor emailsales@safetycli.com.Supported Python VersionsSafety CLI 3 supports Python versions >=3.7. Further details on supported versions, as well as options to run Safety CLI on versions <3.7 using a Docker image are available in ourDocumentation Hub.We maintain a policy of supporting all maintained and secure versions of Python, plus one minor version below the oldest maintained and secure version. Details on Python versions that meet these criteria can be found here:https://endoflife.date/python.ResourcesSafety Cybersecurity websiteSafety Login PageDocumentationSecurity Research and BlogGitHub ActionSupportStatus PageChangelogAll notable changes to this project will be documented in this file.The format is partly based onKeep a Changelog,
and this project adheres toSemantic VersioningandPEP 440[3.0.1] - 2024-01-19fix: add back the license legacy cmd (#498)perf: unpin authlib and remove jwt[3.0.0] - 2024-01-17Safety 3.0.0 major version release!Safety 3.0.0 is a significant update to Safety CLI from 2.x versions, including enhancements to core features, new capabilities, and breaking changes from 2.x.See ourBlog article announcing Safety CLI 3for more details on Safety 3 and these changesSeeMigrating from Safety 2.x to Safety CLI 3for notes and steps to migrating from Safety 2 to Safety 3Main updatesAdded scan command, which scans a project’s directory for all Python dependencies and includes many improvements over thecheckcommand, including automatic Python project scanning, native support for Poetry and Pipenv files, Python virtual environment folders, and more granular configuration options.Added auth commands, enabling new browser-based authentication of Safety CLI.An updated safety policy file schema to support new scan and system-scan commands. This policy file schema is a breaking change from the policy schema used forsafety check. To migrate a Safety 2.x policy, seeMigrating from Safety 2.x to Safety CLI 3.Updated screen output to modern interactive interface, with new help interfaces.Updated to new JSON output structure to support new scan command, other ecosystems, and other security findings.Added a supportingsafety-schemas project dependency, also published and maintained by Safety, which defines Safety vulnerability database file, Safety CLI policy file, and Safety CLI JSON output schemas as pydantic models, formalizing these into testable and versioned schemas.New scan command:New scan command: scans a Python project directory for Python dependencies and security vulnerabilities. Safety scan replacessafety checkwith a more powerful and easier to use command. The scan command:Finds and scans Python dependency files and virtual environments inside the target directory without needing to specify file or environment locations.Adds native scanning and reporting for Poetry and Pipenv manifest files, and Python virtual environment folders.Adds configuration of scanning rules to;exclude files and folders from the scan using Unix shell-style wildcards onlyInclude files to be scannedMax folder depth settingReporting configuration rulesReporting rules defining which types and specific vulnerabilities to include or ignore stay the same as safety 2.x, although now in a slightly different structure.Failing rulesAdds ability to configure rules for when safety should return a non-zero (failing) exit code, which can be different from reporting rules under thereportfield.Auto-updating rulesAdds ability to easily update insecure package versions in pip requirements files.Other new commands:Added auth command: manages Safety CLI’s authentication in development environments, allowing easy authentication via the browser.auth login - adds ability to authenticate safety cli via the browserauth register - adds ability to register for a Safety account via the CLI, and get scanning within minutesauth status -auth logout -safety checkcommand can still be used with the API key --key argument, and scan and system-scan commands should also beAdded configure command: configures safety cli using a config.ini file, either saved to the user settings or system settings. This can be used to configure safety’s authentication methods and global proxy details.Added system-scan command (beta): Adds the system-scan command, which scans a machine for Python files and environments, reporting these to screen output. system-scan is an experimental beta feature that can scan an entire drive or machine for Python dependency files and Python virtual environments, reporting on packages found and their associated security vulnerabilities.Added check-updates command: Check for version updates to Safety CLI, and supports screen and JSON format outputs. Can be used in organizations to test and rollout new version updates as recommended by Safety Cybersecurity.New policy file schema for scan and system-scan commandsNew policy file schema to support safety scan and safety system-scan.
Adds scanning-settings root property, which contains settings to configure rules and settings for how safety traverses the directory and subdirectories being scanned, including “exclude” rules, “include” rules, the max directory depth to scan and which root directories safety system-scan should start from.Adds report root property, which defines which vulnerability findings safety should auto-ignore (exclude) in its reporting. Supports excluding vulnerability IDs manually, as well as vulnerability groups to ignore based on CVSS severity score.Adds new fail-scan-with-exit-code root property, which defines when safety should exit with a failing exit code. This separates safety’s reporting rules from its failing exit code rules, which is a departure from Safety 2.x which had combined rulesets for these. Failing exit codes can be configured based on CVSS severity score.Note that the oldsafety checkcommand still supports and relies on the policy schema from safety 2.3.5 and below, meaning no changes are required when migrating to safety 2.x to Safety 3.0.0 when only using thesafety checkcommand.New global options and configurationsAdded global --stage option, to set the development lifecycle stage for thescanandsystem-scancommands.Added global --key option, to set a Safety API key for any command, including scan, system-scan and check.OtherSafety now requires Python>=3.7. Python 3.7 doesn't have active security support from the Python foundation, and we recommend upgrading to at least Python >= 3.8 whenever possible. Safety’s 3.0.0 Docker image can still be used to scan and secure all Python projects, regardless of Python version. Refer to ourDocumentationfor details.Dropped support for the license command. This legacy command is being replaced by the scan command. Users relying on the license command should continue to use Safety 2.3.5 or 2.4.0b2 until Safety 3 adds license support in an upcoming 3.0.x release.Add deprecation notice tosafety checkcommand, since this is now replaced bysafety scan, a more comprehensive scanning command. The check command will continue receiving maintenance support until June 2024.Add deprecation notice tosafety alertcommand, which works in tandem with thesafety checkcommand. Safety alert functionality is replaced bySafety Platform. The alert command will continue receiving maintenance support until June 2024.safety validatewill assume 3.0 policy file version by default.Small updates/ bug fixesFixesa bugrelated to ignoring vulnerability IDs in Safety’s policy file.https://github.com/pyupio/safety/issues/480https://github.com/pyupio/safety/issues/478https://github.com/pyupio/safety/issues/455https://github.com/pyupio/safety/issues/447[2.4.0b2] - 2023-11-15Removed the upper clause restriction for the packaging dependency[2.4.0b1] - 2022-02-26Added support for coma separated ignore (--ignore=123,456) on top of existing --ignore=123 --ignore=456Added support for requirements per package. Safety can check, report, suggest, and apply remediations for unpinned requirements.Added support for unpinned requirements in the Safety GitHub action. This feature doesn't support old-version reports.Added support for HTML5 output and the ability to save the report as an HTML5 file.Started to use schema 2.0 of the PyUp vulnerability database.Fixed packaging dependency issue and their deprecation of LegacyVersion class.Narrowed down the allowed versions in the Safety dependencies.Added local announcements.This version makes changes in the JSON report, these aren't breaking changes, but these may need adjustment if you are ingesting the JSON report.Added ability to ignore unpinned requirements.[2.3.5] - 2022-12-08Pinned packaging dependency to a compatible range.Pinned the CI actions to the runner image with Python 3.6 support.[2.3.4] - 2022-12-07Removed LegacyVersion use; this fixes the issue with packaging 22.0.Fixed typos in the README.Added Python 3.11 to the classifiers in the setup.cfg.[2.3.3] - 2022-11-27Fixed recursive requirements issue when an unpinned package is found.[2.3.2] - 2022-11-21Fixed #423: Bare output includes extra line in non-screen output with no vulnerabilities.Fixed #422: ResourceWarning (unclosed socket) in safety v.2.3.1.Fixed telemetry data missing when the CLI mode is used.Fixed wrong database fetching when the KEY and the database arguments are used at the same time.AddedSAFETY_PURE_YAMLenv var, used for cases that require pure Python in the YAML parser.[2.3.1] - 2022-10-05Addsafety.alertsmodule to setup.cfg[2.3.0] - 2022-10-05Safety can now create GitHub PRs and Issues for vulnerabilities directly, with the newsafety alertsubcommand.Support for GitHub PR and Issue alerting has been added to the GitHub Action.[2.2.1] - 2022-10-04Fixed the use of the SAFETY_COLOR environment variableFixed bug in the case of vulnerabilities without a CVE linkedFixed GitHub version in the README[2.2.0] - 2022-09-19Safety starts to use dparse to parse files, now Safety supports mainly Poetry and Pipenv lock files plus other files supported by dparse.Added logic for custom integrations like pipenv check.The --db flag is compatible remote sources too.Added more loggingUpgrade dparse dependency to avoid a possible ReDos security issueRemoved Travis and Appveyor, the CI/CD was migrated to GitHub Actions[2.1.1] - 2022-07-18Fix crash when running on systems without git present (Thanks @andyjones)[2.1.0] - 2022-07-14Summary:Improved error messages & fixed issues with proxiesFixed license commandAdded the ability for scan outputs to be sent to pyup.io. This will only take effect if using an API key, the feature is enabled on your profile, and the--disable-audit-and-monitoris not setAdded the ability to have a Safety policy file set centrally on your pyup.io profile. This remote policy file will be used if there's no local policy file present, otherwise a warning will be issued.Updated outputs:Text & screen output: If a scan has been logged, this is now mentioned in the output.JSON output: The JSON output now includes git metadata about the folder Safety was run in. It also includes a version field, and telemetry information that would be sent separately. There are no breaking changes in the output.New inputs:New command line flagsThe--disable-audit-and-monitorflag can be set to disable sending a scan's result to pyup.ioThe--projectflag can be set to manually specify a project to associate these scans with. By default, it'll autodetect based on the current folder and git.[2.0.0] - 2022-06-28Summary:Compared to previous versions, Safety 2.0 will be a significant update that includes new features and refactors, resulting in breaking changes to some inputs and outputs.Updated outputs:Text & screen output: Upgraded the text and screen outputs, removing the old table style and adding new data and formats to vulnerabilities.JSON output: New and updated JSON output (breaking change). Safety adds all the possible information in the JSON report. The structure of this JSON file has been improved.Improved the support for exit codes. There are now custom exit codes with detailed information about the result. Examples include: VULNERABILITIES_FOUND and INVALID_API_KEY.Added remediations (fix recommendations) sections to outputs. Now, Safety will suggest the steps to fix a detected vulnerability when an API key is used.Added new summary meta-data data to the reports showing the Safety version used, the dependencies found, the timestamp, the target scanned, and more. These data are included in the text, screen, and JSON output for improved audit capabilities.Added more info per vulnerability, including URLs to read more about a vulnerability and/or a package.###New command line flags:New command line flagsThe--outputflag replaces--bare,--text,--screen, and--jsonflags. In this new release, examples would be:--output jsonor--output bare.The--continue-on-errorflag suppresses non-zero exit codes to force pass CI/CD checks, if required.The--debugflag allows for a more detailed output.The--disable-telemetryflag has been added to disable telemetry dataThe--policy-fileflag to include a local security policy file. This file (called.safety-policy.yml, found in either the root directory where Safety is being run or in a custom location) is based on YAML 1.2 and allows for:Ignoring individual vulnerabilities with optionally a note and an expiry date.Filtering vulnerabilities by their CVSS severity. (CVSS data is only available for some paid accounts.)OtherDropped support for Python < 3.6The free version of the Safety vulnerability database is downloaded from a public S3 bucket (via PyUp.io) and no longer from GitHub. This free database is only updated once a month and is not licensed for commercial use.Telemetry data will be sent with every Safety call. These data are anonymous and not sensitive. This includes the Python version, the Safety command used (check/license/review), and the Safety options used (without their values). Users can disable this functionality by adding the--disable-telemetryflag.Added validations to avoid the use of exclusive options.Added announcements feature to receive informative or critical messages from the PyUp Safety team.Increased test coverage.Now Safety can be used as a dependency in your codeAdded Safety as a Github ActionImproved the help text in the CLIAdded the --save-json flag[2.0b5] - 2022-06-24Summary:Removed the click context use, so Safety can be used in non-CLI casesAdded Safety as a Github ActionImproved the CLI help copyIncreased the coverage[2.0b4] - 2022-06-16Summary:Fixed issue with paddings and margins at specific console outputs like Github actions consoleAdded the --save-json flag and other aliasesAdded a fallback size for the terminal size function, related tohttps://bugs.python.org/issue42174Suppressed the announcements sent to stderr when it is running via 'run' environments[2.0b3] - 2022-05-30Summary:Fixed issue in the Screen and Text report due to the remediations rendering for the users using an API KeyImproved the handling exception in the generate command[2.0b2] - 2022-05-27Summary:This version of Safety is not stable; it is only a beta, pre-release version.Compared to previous versions, Safety 2.0 will be a significant update that includes new features and refactors, resulting in breaking changes to some inputs and outputs.Improved grammar and formatting in the whole codeImproved the exception handling in the .yml policy file parsingImproved the JSON output following the customers/users feedback - (This is a breaking change between beta releases)Added the generate commandAdded the validate command[2.0b1] - 2022-05-08Summary:This version of Safety is not stable; it is only a beta, pre-release version.Compared to previous versions, Safety 2.0 will be a significant update that includes new features and refactors, resulting in breaking changes to some inputs and outputs.Updated outputs:Text & screen output: Upgraded the text and screen outputs, removing the old table style and adding new data and formats to vulnerabilities.JSON output: New and updated JSON output (breaking change). Safety adds all the possible information in the JSON report. The structure of this JSON file has been improved.Improved the support for exit codes. There are now custom exit codes with detailed information about the result. Examples include: VULNERABILITIES_FOUND and INVALID_API_KEY.Added remediations (fix recommendations) sections to outputs. Now, Safety will suggest the steps to fix a detected vulnerability when an API key is used.Added new summary meta-data data to the reports showing the Safety version used, the dependencies found, the timestamp, the target scanned, and more. These data are included in the text, screen, and JSON output for improved audit capabilities.Added more info per vulnerability, including URLs to read more about a vulnerability and/or a package.New inputs:New command line flagsThe--outputflag replaces--bare,--text,--screen, and--jsonflags. In this new release, examples would be:--output jsonor--output bare.The--continue-on-errorflag suppresses non-zero exit codes to force pass CI/CD checks, if required.The--debugflag allows for a more detailed output.The--disable-telemetryflag has been added to disable telemetry dataThe--policy-fileflag to include a local security policy file. This file (called.safety-policy.yml, found in either the root directory where Safety is being run or in a custom location) is based on YAML 1.2 and allows for:Ignoring individual vulnerabilities with optionally a note and an expiry date.Filtering vulnerabilities by their CVSS severity. (CVSS data is only available for some paid accounts.)OtherDropped support for Python < 3.6The free version of the Safety vulnerability database is downloaded from a public S3 bucket (via PyUp.io) and no longer from GitHub. This free database is only updated once a month.Telemetry data will be sent with every Safety call. These data are anonymous and not sensitive. This includes the Python version, the Safety command used (check/license/review), and the Safety options used (without their values). Users can disable this functionality by adding the--disable-telemetryflag.Added validations to avoid the use of exclusive options.Added announcements feature to receive informative or critical messages from the PyUp Safety team.Increased test coverage.[1.10.3] - 2021-01-15Avoid 1.10.2post1 bug with pyup updates[1.10.2] - 2021-01-12Provide CVSS values on full report for CVEs (requires a premium PyUp subscription)Fixed used DB wrong infoSupport line breaks on advisories[1.10.1] - 2021-01-03Reduced Docker image and Binary sizeAdded bare and json outputs to license command[1.10.0] - 2020-12-20Added README information about Python 2.7 workaroundAdjusted some pricing informationFixed MacOS binary build through AppVeyorAdded the ability to check packages licenses (requires a premium PyUp subscription)[1.9.0] - 2020-04-27Dropped Python 2.7 support, requiring Python 3.5+Binary adjustments and enhancements on top of reported vulnerabilityUsing tox to help with local tests against different Python versions[1.8.7] - 2020-03-10Fixed a hidden import caused the binary to produce errors on Linux.[1.8.6] - 2020-03-10Safety is now available as a binary release for macOS, Windows and Linux.[1.8.5] - 2019-02-04Wrap 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-03Update cryptography dependency from version 1.9 to version 2.3 due to security vulnerability[1.8.3b] - 2018-07-24Allows both unicode and non-unicode type encoding when parsing requriment files[1.8.2] - 2018-07-10Fixed unicode error[1.8.1] - 2018-04-06Fixed a packaging error with the dparse dependency[1.8.0] - 2018-04-05Safety now support pip 10[1.7.0] - 2018-02-03Safety now shows a filename if it finds an unpinned requirement. Thanks @nnadeauRemoved official support for Python 2.6 and Python 3.3. Thanks @nnadeau[1.6.1] - 2017-10-20Fixed an error that caused the CLI to fail on requirement files/stdin.[1.6.0] - 2017-10-20Added an indicator which DB is currently usedAdded a package count how many packages have been checkedAllow multiple version of the same library. Thanks @thatarchguy[1.5.1] - 2017-07-20Fixed an error on unpinned VCS requirements. This is a regression, seehttps://github.com/pyupio/safety/issues/72[1.5.0] - 2017-07-19Internal refactoring. Removed dependency on setuptools and switched to the new dparse library.[1.4.1] - 2017-07-04Fixed a bug where absence ofsttywas causing a traceback insafety checkon Python 2.7 for Windows.[1.4.0] - 2017-04-21Added the ability to ignore one (or multiple) vulnerabilities by ID via the--ignore/-iflag.[1.3.0] - 2017-04-21Added--bareoutput 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-06Added JSON as an output format. Use it with the--jsonflag. Thanks @Stype.[1.1.1] - 2017-03-27Fixed terminal size detection when fed via stdin.[1.1.0] - 2017-03-23Compatibility 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-23Fixed another error on Python 2. The fallback function for get_terminal_size wasn't working correctly.[1.0.1] - 2017-03-23Fixed an error on Python 2, FileNotFoundError was introduced in Python 3.[1.0.0] - 2017-03-22Added 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-10Made 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-08Fixed a bug where not all requirement files were read correctly.[0.5.0] - 2016-11-08Added option to read requirements from files.[0.4.0] - 2016-11-07Filter out non-requirements when reading from stdin.[0.3.0] - 2016-10-28Added option to read from stdin.[0.2.2] - 2016-10-21Fix import errors on python 2.6 and 2.7.[0.2.1] - 2016-10-21Fix packaging bug.[0.2.0] - 2016-10-20Releasing first prototype.[0.1.0] - 2016-10-19First release on PyPI.MIT LicenseCopyright (c) 2016, safetycli.comPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.