Ochrona checks your open source dependencies for vulnerabilities and policy violations.
- Usage Examples
- Output Formats
Ochrona is a free solution for securing the dependencies used in Python projects. Ochrona also includes support for policies which give you additional control over what aspects of your dependency usage you'd like to be alerted on.
The Ochrona maintainers care deeply about Developer Experience (DX), if you have any feedback or run into issues please open an issue here.
Ochrona maintains its own database of vulnerabilities impacting Python packages. You're welcome to check out the database here. This database is updated frequently using data from NVD, Github, and other sources. Ochrona will update its local copy of the database if a new version exists.
Supported file types
pip install ochrona
pipenv install --dev ochrona
poetry add -D ochrona
via command line args
||Directory to recursively search for dependencies files to scan [.]||path||/User/me/my_project|
||Directory names that should be excluded from recursive search. Comma separated||str||build,dev|
||Single dependency file to scan||file||/User/me/my_project/requirements.txt|
||Enable debug logging [False]||bool||True|
||Silent mode [False]||bool||True|
||The report type that's desired [BASIC]||str||XML|
||Location for report output||path||/User/me/my_project/logs|
||Exit with Code 0 regardless of vulnerability findings. [False]||bool||True|
||Ignore a CVE or package||str||requests|
||Include develop dependencies from Pipfile.lock [False]||bool||True|
via environment variables
|Variable Name||Corresponding Arg|
There is an empty
.ochrona.yml file included in the repo.
| Key | Description | Type | Example |
dir | Directory to recursively search for dependencies files to scan [.] | path | /User/me/my_project |
exclude_dir | Directory names that should be excluded from recursive search. | list | build |
file | Single dependency file to scan | file | /User/me/my_project/requirements.txt |
debug | Enable debug logging [false] | bool | true |
silent | Silent mode [false] | bool | true |
report_type | The report type that's desired [BASIC] | str | XML |
report_location | Location for report output [.] | path | /User/me/my_project/logs |
exit | Exit with Code 0 regardless of vulnerability findings [false] | bool | true |
ignore | Ignore a CVE or package name | str | requests |
include_dev | Include develop dependencies from files that support dev/required dependencies [false] | bool | true |
color_output | Whether or not std out text should use color. Note: this is enabled by default when running in a non-Windows environment [true] | bool | false |
policies | Policies are a way of defining additional checks against your dependencies. See here for more details | array | details |
# debug: true # silent: false # dir: . # report_type: JSON # report_location: . # ignore: requests # include_dev: false # color_output: false # policies: # - license_type NIN APSL,GPL-PA,JSON
Policies are a way to add additional check to your Python dependency usage. Policies can be defined using conditional and logical syntax. These generic policy definitions allow you to define unique, custom policies to fit your need, and they can be extensible as new fields and capabilities are added.
Policy vioations are not the same as vulnerabilities, however violations will cause Ochrona to emit a failure exit code and the output will include details about the policy violation.
At their most basic, policies are defined using conditional statements and logical operators. A conditional statement is structured as
<field><operator><value>, for example,
license_type == MIT. Whitespace is always ignored during policy evaluation.
||The name of a package.|
||An (SPDX)[https://spdx.org/licenses/] license type for a package.|
||The most recent version of a package.|
||The timestamp for when a package was last updated. ISO-8601 Format
||The number of releases a package has on Pypi.|
Allowed Conditional Operators
||An equals operator for comparing exact string matches.|
||A NOT equals operators for non-matching strings.|
||Less than, for comparing numerical or string values.|
||Less than or equal to.|
||Greater than, for comparing numerical or string values.|
||Greater than or equal to.|
||For checking whether a value exists within a set.|
||For checking that a value does not exist within a set.|
Allowed Logical Operators
||For checking that all conditions are true.|
||For checking that at least one condition is true.|
||Shorthand for an ISO 8601 formatted date in the past.
# Policy to check that a license type is in my aproved list license_type IN MIT,ISC,Apache-2.0 # Policy to check that all packages have been updated this year latest_update >= NOW-365
Legacy policies can also be defined using their name and one or more conditions which are evaluated at scan time. Legacy policies will be removed in a future release and you are encouraged to use generic policies for all new policies.
For example, the
license_type policy allows you to be alerted if one of your dependency's open-source license is not part of your "Allow List" or if it uses a license from your "Deny List".
Legacy Policy Types
||Allows for checking whether the dependencies used are all from an
||Allows for checking whether the licenses of dependencies used are all from an
This will search for any supported dependency files recursively from the run location. It will output rules in the
format to stdout. The program will exit with an error exit code if any confirmed vulnerabilities are found.
Standard error code with Junit XML reporting saved to file
$ ochrona --exit --report_type XML --output ./output
Safe Import Mode
In this mode ochrona acts as a safe wrapper around standard pip installs to ensure that a package and it's dependencies are safe before installing. This action preemptively checks a package and only imports if no vulnerabilities are found. It can be used with a base package (i.e.
requests), or with a package pinned to an exact version (i.e.
requests==2.21.0). It also supports importing a
requirements.txt style, the pip equivalent of
pip install -r <file>.
$ ochrona --install <package_name>|<requirements.txt>
Ochrona supports supplying dependencies via stdin and can accept a PEP-508 complaint (i.e. requirements.txt) formated string, or a single dependency. Single dependencies can be supplied as the first argument or piped.
Single dependency via stdin
$ ochrona urllib3==1.26.4 $ echo "urllib3==1.26.4" | ochrona
Multi-dependency via stdin
$ pip freeze | ochrona $ pipenv lock -r | ochrona $ cat requirements.txt | ochrona
Ochrona can be run via Docker. This is useful for the paranoid who may worry that an installed module could have modified the Python package namespace and allow malicious packages to bypass Ochrona's security checks. We've added this support in response to CVE-2020-5252 which was disclosed prior to Ochrona and affects several other similar tools.
$ pip freeze | docker run -i --rm ochrona/ochrona ochrona
Dockerized Ochrona with environment variables
$ pip freeze | docker run -i -e OCHRONA_IGNORED_VULNS=requests --rm ochrona/ochrona ochrona
Ochrona supports several built in output options include a
FULL plaintext reports, as well as a Junit style
XML report or a
JSON style report for incorporating with other tools.
Let the world know you're keeping your project safe with Ochrona. Add our shield to your
README.md by adding the following line.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size ochrona-1.1.0-py3-none-any.whl (43.1 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size ochrona-1.1.0.tar.gz (33.8 kB)||File type Source||Python version None||Upload date||Hashes View|