Package: ochrona
OverviewVulnerability DataSupported file typesInstallationvia pipvia pipenvvia poetryConfigurationvia command line argsvia environment variablesvia .ochrona.ymlPoliciesPolicy SyntaxAllowed FieldsAllowed Conditional OperatorsAllowed Logical OperatorsSpecial ValuesPolicy ExamplesSBOMStatic Analysis BetaSAST ChecksUsage ExamplesDefault ModeStandard error code with Junit XML reporting saved to fileSafe Import Modestdin SupportSingle dependency via stdinMulti-dependency via stdinDocker SupportDockerized OchronaDockerized Ochrona with environment variablesOutput FormatsBasicFullXML (Junit)JSONHTMLRepresent!OverviewOchrona is a free solution for securing the dependencies used in Python projects. Ochrona also includes support forpolicieswhich 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 issuehere.Vulnerability DataOchrona maintains its own database of vulnerabilities impacting Python packages. You're welcome to check out the databasehere. 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*requirements*.txtPipfile.lockpoetry.locksetup.py*constraints*.txtenvironment.ymltox.iniInstallationvia pippip install ochronavia pipenvpipenv install --dev ochronavia poetrypoetry add -D ochronaConfigurationvia command line argsArgDescriptionTypeExample--dirDirectory to recursively search for dependencies files to scan [.]path/User/me/my_project--exclude_dirDirectory names that should be excluded from recursive search. Comma separatedstrbuild,dev--fileSingle dependency file to scanfile/User/me/my_project/requirements.txt--debugEnable debug logging [False]boolTrue--silentSilent mode [False]boolTrue--report_typeThe report type that's desired [BASIC]strXML--outputLocation for report outputpath/User/me/my_project/logs--exitExit with Code 0 regardless of vulnerability findings. [False]boolTrue--ignoreIgnore a CVE or packagestrrequests--include_devInclude develop dependencies from Pipfile.lock [False]boolTrue--sbomMust be provided, along with--outputto generate an SBOM [False]boolTrue--sbom_formatWhether the generated SBOM should be a JSON or XML file. [JSON]strJSON--enable_sastWhether SAST checks should be run [False]boolTrue--sast_id_excludeWhether a SAST check should be ignoredstrO001--sast_dirWhich directory should SAST checks run againstpath/User/me/my_project/srcvia environment variablesVariable NameCorresponding ArgOCHRONA_DEBUG_LOGGING--debugOCHRONA_IGNORED_VULNS--ignorevia .ochrona.ymlThere is an empty.ochrona.ymlfile included in the repo.KeyDescriptionTypeExampledirDirectory to recursively search for dependencies files to scan [.]path/User/me/my_projectexclude_dirDirectory names that should be excluded from recursive search.arraybuildfileSingle dependency file to scanfile/User/me/my_project/requirements.txtdebugEnable debug logging [false]booltruesilentSilent mode [false]booltruereport_typeThe report type that's desired [BASIC]strXMLreport_locationLocation for report output [.]path/User/me/my_project/logsexitExit with Code 0 regardless of vulnerability findings [false]booltrueignoreIgnore a CVE or package name. Supports multiple values.strrequestsinclude_devInclude develop dependencies from files that support dev/required dependencies [false]booltruecolor_outputWhether or not std out text should use color. Note: this is enabled by default when running in a non-Windows environment [true]boolfalsepoliciesPolicies are a way of defining additional checks against your dependencies. Seeherefor more detailsarraydetailssbomSBOM will only be generated if this argument is supplied.report_locationalso must be specified to generate an SBOM. Seeherefor more details about SBOMs [false]boolfalsesbom_formatWhether the generated SBOM should be a JSON or XML file. [JSON]strJSONenable_sastWhether SAST checks should be run [False]booltruesast_id_excludeWhether a SAST check should be ignored. See list of SAST IDshere. Supports multiple values.strO001sast_dirWhich directory should SAST checks run against. [.]path/User/me/my_project/srcExample:# 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
# sbom: true
# sbom_format: JSON
# enable_sast: true
# sast_id_exclude:
#  - O001
# sast_dir: ./srcPoliciesPolicies 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.Policy SyntaxAt 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.Allowed FieldsNameDescriptionnameThe name of a package.license_typeAnSPDXlicense type for a package.latest_versionThe most recent version of a package.latest_updateThe timestamp for when a package was last updated. ISO-8601 FormatYYYY-MM-DDTHH:MM-SS.ffffffZrelease_countThe number of releases a package has on Pypi.Allowed Conditional OperatorsOperatorDescription==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.INFor checking whether a value exists within a set. Values used withINshould be comma separated.NINFor checking that a value does not exist within a set. Values used withNINshould be comma separated.Allowed Logical OperatorsOperatorDescriptionANDFor checking that both adjacent conditions are true.ORFor checking that at least one adjacent condition is true.Special ValuesValueDescriptionNOW-NShorthand for an ISO 8601 formatted date in the past.Nwill be an integer number of days.*Match ANY value, only works with==operator.PrecedencePolicies allow the usage of(and)to indicate evaluation precedence and grouping.
Example(license_type==Apache-2.0 OR license_type==MIT) AND latest_update < NOW-30Policy Examples# 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-365SBOMSoftware Bill-of-Materials (SBOM) are a list of the components used to build a piece of software. They aim to make the delivery and composition of software components more transparent. These documents can be useful for understanding software supply chains and ensuring license complaince.Ochrona has opted to support (CycloneDX)[https://cyclonedx.org/] as our SBOM standard of choice. CycloneDX is a lightweight software bill of materials (SBOM) standard designed for use in application security contexts and supply chain component analysis. CycloneDX is developed and support by (OWASP)[https://owasp.org/www-project-cyclonedx/].To enable sbom generation, the--sbomand--outputarguements needs to be provided.Static Analysis BetaOchrona has introduced limited Static Application Security Testing (SAST) in version 2.0.0 as a beta feature. These check are run if the--enable_sastargument is provided. It will run recursively against all.pyfiles found in the current working directory.SAST ChecksIDDescriptionO001Checks for use of "exec" from the Standard Library.O002Checks for use of "eval" from the Standard Library.O003Checks for use of the "assert" keyword.O004Checks for use of "tarfile.extractall" from the Standard Library.O005Checks for use of "pickle.loads" from the Standard Library.O006Checks for use of "xml.etree.ElementTree.parse" from the Standard Library.O101Checks for use of "load" from PyYAML.O102Checks for usage of Requests with verify=False.O103Checks for usage of Flask with debug=True.Usage ExamplesDefault Mode$ ochronaThis will search for any supported dependency files recursively from the run location. It will output rules in theBASICformat 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 ./outputSafe Import ModeIn 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 arequirements.txtstyle, the pip equivalent ofpip install -r <file>.$ ochrona --install <package_name>|<requirements.txt>stdin SupportOchrona 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" | ochronaMulti-dependency via stdin$ pip freeze | ochrona
$ pipenv lock -r | ochrona
$ cat requirements.txt | ochronaDocker SupportOchrona 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 toCVE-2020-5252which was disclosed prior to Ochrona and affects several other similar tools.Dockerized Ochrona$ pip freeze | docker run -i --rm ochrona/ochrona ochronaDockerized Ochrona with environment variables$ pip freeze | docker run -i -e OCHRONA_IGNORED_VULNS=requests --rm ochrona/ochrona ochronaOutput FormatsOchrona supports several built in output options include aBASICandFULLplaintext reports, a Junit styleXMLreport, aJSONstyle report for incorporating with other tools, and andHTMLsummarized report.BasicFullXML (Junit)JSONHTMLRepresent!Let the world know you're keeping your project safe with Ochrona. Add our shield to yourREADME.mdby adding the following line.[![Ochrona](https://img.shields.io/badge/secured_by-ochrona-blue)](https://ochrona.dev)