{"id":25452618,"url":"https://github.com/jeremylong/open-vulnerability-cli","last_synced_at":"2025-11-17T13:03:49.121Z","repository":{"id":65958831,"uuid":"563343661","full_name":"jeremylong/open-vulnerability-cli","owner":"jeremylong","description":"A cli that can be used to query various online vulnerability sources such as the NVD or GHSA. The CLI and docker images can be used to mirror the NVD.","archived":false,"fork":false,"pushed_at":"2025-03-24T12:12:35.000Z","size":4786,"stargazers_count":141,"open_issues_count":3,"forks_count":44,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-28T13:14:50.016Z","etag":null,"topics":["github-security-advisories","nvd-api"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeremylong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/contributing.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"jeremylong"}},"created_at":"2022-11-08T12:22:10.000Z","updated_at":"2025-03-24T12:12:39.000Z","dependencies_parsed_at":"2023-09-29T12:43:49.298Z","dependency_job_id":"6b288585-66a6-4b80-a38c-097bd316d117","html_url":"https://github.com/jeremylong/open-vulnerability-cli","commit_stats":null,"previous_names":["jeremylong/open-vulnerability-cli","jeremylong/open-vulnerability-project"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremylong%2Fopen-vulnerability-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremylong%2Fopen-vulnerability-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremylong%2Fopen-vulnerability-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremylong%2Fopen-vulnerability-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeremylong","download_url":"https://codeload.github.com/jeremylong/open-vulnerability-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280190,"owners_count":20912966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-security-advisories","nvd-api"],"created_at":"2025-02-17T23:32:45.822Z","updated_at":"2025-11-17T13:03:49.102Z","avatar_url":"https://github.com/jeremylong.png","language":"Java","funding_links":["https://github.com/sponsors/jeremylong"],"categories":[],"sub_categories":[],"readme":"# open-vulnerability-cli\n\nThe open-vulnerability-cli is a command line utility that can be used to\nquery various online vulnerability sources such as the NVD or GHSA. The\nCLI and docker images can be used to mirror the NVD (instructions below).\n\nNote that the CLI is called `vulnz` because open-vulnerability-cli is cumbersome.\n`vulnz` is a spring-boot command line utility built with picocli.\n\n## Setup\n\nAs of the 8.0.0 release, Java 17 is required; alternatively, you can use the\ndocker image. The `vulnz` CLI can be downloaded from the releases page.\n\nThe example below does run the setup - which creates both the `vulnz` symlink\n(in `/usr/local/bin`) and a completion script. If using zsh, the completion\nwill be added to `/etc/bash_completion.d` or `/usr/local/etc/bash_completion.d`\n(depending on if they exist); see [permanently installing completion](https://picocli.info/autocomplete.html#_installing_completion_scripts_permanently_in_bashzsh)\nfor more details.\n\nAfter running `install` you may need to restart your shell for the completion to work.\n\n```bash\n./gradlew vulnz:build\ncd vulnz/build/libs\n./vulnz-9.0.1.jar install\nvulnz cve --cveId CVE-2021-44228 --prettyPrint\n```\n\nExample of using the CLI with an API key stored in [1password](https://1password.com/) using\nthe `op` CLI (see [getting started with op](https://developer.1password.com/docs/cli/get-started/)):\n\n```bash\nexport NVD_API_KEY=op://vaultname/nvd-api/credential\neval $(op signin)\nop run -- vulnz cve --requestCount 40 \u003e cve-complete.json\n```\n\n## Mirroring the NVD CVE Data\n\nThe vulnz cli can create a cache of the NVD CVE data obtained from the API. The\ndata is stored in `json` files with the data saved in the traditional yearly groupings\nstarting with 2002 and going to the current year. In addition, a `cache.properties` is\ncreated that contains the `lastModifiedDate` datetime as well as the prefix used for the\ngenerated JSON files (by default `nvdcve-` is used). Additionally, a `modified` JSON file\nis created that will hold the CVEs that have been modified in the last 8 days. After running\nthe below command you will end up with a directory with:\n\n- `cache.properties`\n- `nvdcve-modified.json.gz`\n- `nvdcve-modified.meta`\n- `nvdcve-2002.json.gz`\n- `nvdcve-2002.meta`\n- `nvdcve-2003.json.gz`\n- `nvdcve-2003.meta`\n- ...\n- `nvdcve-2025.json.gz`\n- `nvdcve-2025.meta`\n\n### API Key is used and a 403 or 404 error occurs\n\nIf an API Key is used and you receive a 404 error:\n\n```\nERROR\nio.github.jeremylong.openvulnerability.client.nvd.NvdApiException: NVD Returned Status Code: 404\n```\n\nThere is a good chance that the API Key is set incorrectly or is invalid. To check if the API Key works\nthe following `curl` command should return JSON:\n\n```\ncurl -H \"Accept: application/json\" -H \"apiKey: ########-####-####-####-############\" -v https://services.nvd.nist.gov/rest/json/cves/2.0\\?cpeName\\=cpe:2.3:o:microsoft:windows_10:1607:\\*:\\*:\\*:\\*:\\*:\\*:\\*\n```\n\nIf no JSON is returned and you see a 404 error the API Key is invalid and you should request a new one.\n\n### Out-of-Memory Errors\n\nCreate the local cache may result in an out-of-memory error. To resolve the\nerror simply increase the available memory for Java:\n\n```bash\nexport JAVA_OPTS=\"-Xmx2g\"\n```\n\nAlternatively, run the CLI using the `-Xmx2g` argument:\n\n```bash\njava -Xmx2g -jar ./vulnz-9.0.1.jar\n```\n\nAn option to save memory would be: `-XX:+UseStringDeduplication`:\n```bash\nexport JAVA_OPTS=\"-Xmx2g -XX:+UseStringDeduplication\"\n```\n\n### Creating the Mirror\n\nTo create a local mirror of the NVD CVE Data you can execute the following command\nvia a daily schedule to keep the cached data current:\n\n```bash\nvulnz cve --cache --directory ./cache \n```\n\nAlternatively, without using the above install command:\n\n```bash\n./vulnz-9.0.1.jar cve --cache --directory ./cache\n```\n\nWhen creating the cache all other arguments to the vulnz cli\nwill still work except the `--lastModEndDate` and `--lastModStartDate`.\nAs such, you can create `--prettyPrint` the cache or create a cache\nof only \"application\" CVE using the `--virtualMatchString=cpe:2.3:a`.\n\n## Docker image\n\n### Configuration\n\nThere are a couple of ENV vars\n\n- `NVD_API_KEY`: define your API key\n- `DELAY`: override the delay - given in milliseconds. If you do not set an API KEY, the delay will be `10000`\n- `MAX_RETRY_ARG` Using max retry attempts\n- `MAX_RECORDS_PER_PAGE_ARG` Using max records per page\n- `METRICS_ENABLE` If is set to `true`, OpenMetrics data for the vulnz cli can be retrieved via the endpoint http://.../metrics\n- `METRICS_WRITE_INTERVAL` Sets the update interval for generating metrics, in milliseconds. Default: `5000`\n- `METRICS_WRITER_FORMAT` Sets the output format for the metrics. Either `openmetrics` or `prometheus` format. Default: `openmetrics`\n- `CACERT` Path to a custom Certificate Authority (CA) certificate file that should be used for secure SSL/TLS connections with curl. Example: `/cacert.pem`\n\n\n### Run\n\n```bash\n# replace the NVD_API_KEY with your NVD api key\ndocker run --name vulnz -e NVD_API_KEY=myapikey jeremylong/open-vulnerability-data-mirror:v9.0.1 \n\n# if you like use a volume \ndocker run --name vulnz -e NVD_API_KEY=myapikey -v cache:/usr/local/apache2/htdocs jeremylong/open-vulnerability-data-mirror:v9.0.1\n\n# adjust the memory usage\ndocker run --name vulnz -e JAVA_OPT=-Xmx2g jeremylong/open-vulnerability-data-mirror:v9.0.1\n\n# you can also adjust the delay \ndocker run --name vulnz -e NVD_API_KEY=myapikey -e DELAY=3000 jeremylong/open-vulnerability-data-mirror:v9.0.1 \n\n# mounts the custom Java `cacerts` file from your local machine into the container for secure SSL/TLS connections with java\n# and mounts the custom `cafile` from your local machine into the container for secure SSL/TLS connections with curl\ndocker run --name vulnz -v /path/to/java/cacerts:/etc/ssl/certs/java/cacerts -v /path/to/cacert.pem:/cacert.pem jeremylong/open-vulnerability-data-mirror:v9.0.1\n```\n\nIf you like, run this to pre-populate the mirror right away\n\n```bash\ndocker exec -u mirror vulnz /mirror.sh\n```\n\n### Build\n\nAssuming the current version is `9.0.1`\n\n```bash\nexport TARGET_VERSION=9.0.1\n./gradlew vulnz:build -Pversion=$TARGET_VERSION\ndocker build vulnz/ -t ghcr.io/jeremylong/vulnz:$TARGET_VERSION --build-arg BUILD_VERSION=$TARGET_VERSION\n```\n\n### Release\n\n```bash\n# checkout the repo\ngit tag -a 'v9.0.1'' -m 'release 9.0.1'\ngit push --tags\n# this will build vulnz 9.0.1 on publish the docker image tagged 9.0.1 \n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremylong%2Fopen-vulnerability-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremylong%2Fopen-vulnerability-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremylong%2Fopen-vulnerability-cli/lists"}