Policy File

Safety supports a local policy file to configure the security policies for each Python project you are securing.

Why use a policy file?

Using a policy file is recommended as a way to standardize your security policy for each Python project. This saves the configuration of Safety's vulnerabilities scans for each project and allows your development team to centrally share and configure rules, settings, and exceptions for your scans. You can:

• Set a vulnerability severity threshold to only report vulnerabilities above a certain severity threshold

• Ignore specific vulnerabilities your team knows do not impact your project

• suppress exit codes in scenarios you don't want to stop a build or test when vulnerabilities are found

This Safety policy file should be checked into your source control at the root of your Python project alongside other policy files such as .gitignore, requirements.txt, setup.py, etc.

Getting started, generating a policy file

You can generate a starting policy file from Safety itself by running the generate command. Run this from the root of your project (for example, or requirements.txt, pipenv or poetry.toml files should be in the same directory).

safety generate policy_file

This will create a default Safety policy file called .safety-policy.yml in that directory.

Structure of the policy file

Here is a generated default policy file:

YAML

# Safety Security and License Configuration file
security: # configuration for the `safety check` command
    ignore-cvss-severity-below: 0 # A severity number between 0 and 10. Some helpful reference points: 9=ignore all vulnerabilities except CRITICAL severity. 7=ignore all vulnerabilities except CRITICAL 
    ignore-cvss-unknown-severity: False # True or False. We recommend you set this to False.
    ignore-vulnerabilities: # Here you can list multiple specific vulnerabilities you want to ignore (optionally for a time period)
        # We recommend making use of the optional `reason` and `expires` keys for each vulnerability that you ignore.
        25853: # Example vulnerability ID
            reason: we do not use the vulnerable function # optional, for internal note purposes to communicate with your team. This reason will be reported in the Safety reports
            expires: '2022-10-21' # datetime string - date this ignore will expire, best practice to use this variable
    continue-on-vulnerability-error: False # Suppress non-zero exit codes when vulnerabilities are found. Enable this in pipelines and CI/CD processes if you want to pass builds that have vulnerabilities

ignore-cvss-severity-below is an integer between 0 and 10. You can use this variable to ignore vulnerabilities below a certain CVSS severity score. Some helpful reference points: 9 - only reports CRITICAL severity vulnerabilities 7 - only reports CRITICAL and HIGH severity vulnerabilities 4 - only reports CRITICAL, HIGH and MEDIUM severity vulnerabilities

ignore-cvss-unknown-severity some vulnerabilities found by Safety's Cybersecurity team do not have severity scores (either because they are yet to get a score, or there is not enough information to generate a CVSS score). You can use this variable to include or exclude these vulnerabilities from your report.

ignore-vulnerabilities allows you to ignore specific vulnerabilities using their vulnerability ID. For each vulnerability you are ignoring, we recommend you give a reason for the ignore, and also an expiry date after which this ignore will no longer apply.

continue-on-vulnerability-error allows you to suppress the default exit codes, and return a zero (success) exit code even if vulnerabilities are found. This can be used in pipeline CI/CD scenarios where you do not want to fail a build/test even if vulnerabilities are found.

Validating your policy file

You can validate your policy file by running the validate command

safety validate policy_file --path <path-to-your-policy-file>

For example:

safety validate policy_file --path .safety-policy.yml

Running a scan using your policy file

If your policy file is .safety-policy.yml and it is in the root of your project, then running safety from the same root of your project will by default use that policy file:

safety check --key <your-key>

If you want to place your policy file in a different location or run Safety from a different location, you can also specify the path to your policy file explicitly using the --policy-file argument:

safety check --key <your-api-key> --policy-file <path-to-custom-location-and-name>

You can check if the policy file is being found and used by safety in the top report section of the output (both in text, screen and json output). For example:

Text

Safety v2.0b3 is scanning for Vulnerabilities...
  Scanning using a security policy file /python-project/.safety-policy.yml
  Scanning dependencies in your environment:
  -> /usr/local/lib/python3.9/site-packages

...