Package: cvelib
cvelibA library and a command line interface for the CVE Services API.Note: version 1.3.0 of cvelib is compatible with CVE Services 2.2.0.RequirementsPython version 3.7 or greaterpipInstallationLinux, MacOS, Windowspython3-mpipinstall--usercvelibFor more information on installing Python packages from PyPI, see thePython Packaging User Guide.If you are using Windows,pipmay not add the path to use thecvecommand to your environment.
If it was not added, you will most likely see the error:cve : The term 'cve' is not recognized as the name of a cmdlet, function, script file, or operable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.To resolve this error, add the file path for where yourcve.exefile resides (for example,C:\Users\<username>\AppData\Roaming\Python\Python39\Scripts) to yourPATHvariable. You can
edit your environment variables by searchingEdit the system environment variablesfrom the Start menu.Podman/DockerYou can fetch a specific version of thecveliblibrary installed in a container image athttps://quay.io/repository/prodsecdev/cvelib. You can set up an alias to run thecvecommand using this container
image:aliascve='podman run -it --rm quay.io/prodsecdev/cvelib'# ORaliascve='docker run -it --rm quay.io/prodsecdev/cvelib'Thelatestcontainer image tag will always point to the latest available version of thecvelibpackage in PyPI.CLI Setup and ConfigurationEach CLI command executed requires the user to authenticate to the CVE Services API. You can provide
the authentication details with every command (using options-u/--username,-o/--org, and-a/--api-key), or set them in the following environment variables:Linux & MacOS$exportCVE_USER=margo
$exportCVE_ORG=acme
$exportCVE_API_KEY=<api_key>Windows Command LineC:\> setx CVE_USER margo
C:\> setx CVE_ORG acme
C:\> setx CVE_API_KEY <api_key>Windows PowerShellPS C:\> $Env:CVE_USER="margo"
PS C:\> $Env:CVE_ORG="acme"
PS C:\> $Env:CVE_API_KEY="api_key"Podman/DockerTo pass the configuration variables to thecvelibcontainer, define them in an.envfile:CVE_USER=margo
CVE_ORG=acme
CVE_API_KEY=<api_key>Then, specify that file in your Podman/Docker command, for example:podmanrun-it--rm--env-file=.envquay.io/prodsecdev/cvelibpingAlternatively, you can set the environment variables as shown in the sections above and pass them to the container
using:podmanrun-it--rm-eCVE_ORG-eCVE_API_KEY-eCVE_USERquay.io/prodsecdev/cvelibpingAdditional ConfigurationAdditional options that have an accompanying environment variable include:-e/--environmentorCVE_ENVIRONMENT: allows you to configure the deployment environment
(that is, the URL at which CVE Services is available) to interface with. Allowed values:prod,test, anddev. Separate credentials are required for each environment. Thetestanddevenvironments may not be consistently available during the development life cycle of CVE Services.--api-urlorCVE_API_URL: allows you to override the URL for the CVE Services API that would
otherwise be determined by the deployment environment you selected. This is useful for local
testing to point to a CVE Services API instance running on localhost (for example,export CVE_API_URL=http://localhost:3000/api/).-i/--interactiveorCVE_INTERACTIVE: every create/update action will require confirmation
before a request is sent to CVE Services. Truthy values for the environment variable are:1,t,yes.Command AutocompletionAutocompletion of subcommands is supported for the following shells:BashAdd the following line to your~/.bashrcfile:eval"$(_CVE_COMPLETE=bash_sourcecve)"ZSHAdd the following line to your~/.zshrcfile:eval"$(_CVE_COMPLETE=zsh_sourcecve)"FishAdd the following line to a~/.config/fish/completions/cve.fishfile:eval(env_CVE_COMPLETE=fish_sourcecve)CLI Usage ExamplesAvailable options and commands can be displayed by runningcve --help. The following are
examples of some commonly used operations.Reserve one CVE ID in the current year (you will be prompted to confirm your action):cve--interactivereserveReserve three non-sequential CVE IDs for a specific year:cvereserve3--year2021--randomPublish a CVE record for an already-reserved CVE ID:cvepublishCVE-2022-1234--cve-json'{"affected": [], "descriptions": [], "providerMetadata": {}, "references": []}'For information on the required properties in a given CVE JSON record, see thecnaPublishedContainerschema in:https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json.List all rejected CVEs for year 2018:cvelist--year2018--staterejectAssuming you have theADMINrole (also called anOrg Admin), create a new user in your
organization with:cveusercreate-ufoo@bar.com--name-firstFoo--name-lastBarMark a user as inactive (again, assuming you have theADMINrole):cveuserupdate-ufoo@bar.com--mark-inactiveReset your own API key:cveuserreset-keyList all users in your organization:cveorgusersSee-h/--helpof any command for a complete list of sub-commands and options.Library Usage Examplecvelibalso exposes a Python interface to CVE Service that can be used within any Python application that includescvelibas its dependency. Here is an example Python function that fetches the CVE record for a given CVE ID:importosfromcvelib.cve_apiimportCveApideffetch_cve_record(cve_id:str)->dict:cve_api=CveApi(username=os.getenv("CVE_USER"),org=os.getenv("CVE_ORG"),api_key=os.getenv("CVE_API_KEY"),)cve=cve_api.show_cve_record(cve_id)returncveFor more information, see the individual methods defined in theCveApiinterface.Other CVE Services ClientsClient-side library written in JavaScript:https://github.com/xdrr/cve.jsA web-based client interface and a client library in JavaScript:https://github.com/CERTCC/cveClientA web-based tool for creating and editing CVE records in the CVE JSON v5 format:https://github.com/Vulnogram/VulnogramA hosted instance is available at:https://vulnogram.github.io/#editorDevelopment Setupgitclonehttps://github.com/RedHatProductSecurity/cvelib.gitcdcvelib
python3-mvenvvenv# Must be Python 3.6 or latersourcevenv/bin/activate
pipinstall--upgradepip
pipinstall-e.
pipinstalltox# If you want to use any of the dev dependencies outside of Tox, you can install them all with:pipinstall-e.[dev]To enable command autocompletion when using a virtual environment, add the line noted inCommand Autocompletionabove to yourvenv/bin/activatefile, for example:echo'eval "$(_CVE_COMPLETE=bash_source cve)"'>>venv/bin/activateThis project uses theBlackcode formatter. To reformat the entire code base after you make any changes, run:black.To sort all imports usingruff(which replicates the behavior ofisort, run:ruffcheck--selectI--fix.Running tests and linters:# Run all tests and format/lint checks (also run as a Github action)tox# Run format check onlytox-eblack# Run tests against Python 3.6 onlytox-epy36# Run a single test against Python 3.6 onlytox-epy36--tests/test_cli.py::test_cve_showAny changes in the commands, their options, or help texts must be reflected in the generated man pages. To refresh
them, run:pipinstallclick-man
click-mancve# ORtox-emanpagesCVEis a registered trademark ofThe MITRE Corporation.