diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt index 319bd9ae9f..7505fc13b7 100644 --- a/.github/actions/spelling/allow.txt +++ b/.github/actions/spelling/allow.txt @@ -1,11 +1,3 @@ -refactoring -peb -conventionalcommits -nisamson -bhargavh -jerinjtitus -Molkree -Romi abhaykatheria ableabhinav accountsservice @@ -21,6 +13,7 @@ api apk Args asn +asottile autoescape autoextract autoextracts @@ -32,6 +25,7 @@ bcca bdbd bdist bestpractices +bhargavh bigbird binutils bksahu @@ -60,6 +54,7 @@ cmdline codecov conda config +conventionalcommits copyleft coreinfrastructure cpio @@ -90,6 +85,7 @@ distros dnsmasq docstring DOCTYPE +downloading dpkg dsa dtls @@ -157,6 +153,7 @@ INI irssi itertools javascript +jerinjtitus jquery json Kamdar @@ -194,6 +191,7 @@ libxml libxslt lifecycle lighttpd +linting linux logrotate lua @@ -211,6 +209,7 @@ metadata microsoft mkdir modulename +Molkree mozilla msgid msgstr @@ -226,6 +225,7 @@ netpbm nginx Niraj nirajkamdar +nisamson nitishsaini nlk noopener @@ -252,6 +252,7 @@ pcsc pdf pdftotext pdxjohnny +peb php pigz plotly @@ -272,6 +273,7 @@ pypi pytest pythex pythonapp +pyupgrade Qqe queryformat quickstart @@ -281,8 +283,9 @@ Rahul readme readthedocs realpython -downloading +refactoring regex +Romi rossburton rpmfile rst @@ -295,6 +298,7 @@ sbs sdk shreyamalviya somefile +sottile SPDX sqlite src diff --git a/doc/CONTRIBUTORS.md b/CONTRIBUTING.md similarity index 53% rename from doc/CONTRIBUTORS.md rename to CONTRIBUTING.md index 5611d31e76..5df1066902 100644 --- a/doc/CONTRIBUTORS.md +++ b/CONTRIBUTING.md @@ -2,7 +2,31 @@ The CVE Binary Tool team participates in a few events every year that are aimed at new people in open source. This guide is meant to help people get over the initial hurdle of figuring out how to use git and make a contribution. -If you've already contributed to other open source projects, contributing to the CVE Binary Tool project should be pretty similar and you can probably figure it out by guessing. But if you've never contributed to anything before, or you just want to see what we consider best practice before you start, this is the guide for you! +If you've already contributed to other open source projects, contributing to the CVE Binary Tool project should be pretty similar and you can probably figure it out by guessing. Experienced contributors might want to just skip ahead to the [checklist for a great pull request](#checklist-for-a-great-pull-request) But if you've never contributed to anything before, or you just want to see what we consider best practice before you start, this is the guide for you! + +- [CVE Binary Tool Contributor Guide](#cve-binary-tool-contributor-guide) + - [Imposter syndrome disclaimer](#imposter-syndrome-disclaimer) + - [Development Environment](#development-environment) + - [Getting and maintaining a local copy of the source code](#getting-and-maintaining-a-local-copy-of-the-source-code) + - [Setting up a virtualenv](#setting-up-a-virtualenv) + - [Installing dependencies](#installing-dependencies) + - [Running your local copy of CVE Binary Tool](#running-your-local-copy-of-cve-binary-tool) + - [Help, my checkers aren't loading](#help-my-checkers-arent-loading) + - [Running tests](#running-tests) + - [Running linters](#running-linters) + - [Using pre-commit to run linters automatically](#using-pre-commit-to-run-linters-automatically) + - [Running isort by itself](#running-isort-by-itself) + - [Running black by itself](#running-black-by-itself) + - [Other linting tools](#other-linting-tools) + - [Making a new branch & pull request](#making-a-new-branch--pull-request) + - [Commit message tips](#commit-message-tips) + - [Sharing your code with us](#sharing-your-code-with-us) + - [Checklist for a great pull request](#checklist-for-a-great-pull-request) + - [Code Review](#code-review) + - [Style Guide for cve-bin-tool](#style-guide-for-cve-bin-tool) + - [String Formatting](#string-formatting) + - [Making documentation](#making-documentation) + - [Where should I start?](#where-should-i-start) ## Imposter syndrome disclaimer @@ -30,7 +54,7 @@ Linux is the preferred operating system to use while contributing to CVE Binary ## Getting and maintaining a local copy of the source code -There are lots of different ways to use git, and it's so easy to get into a messy state that [there's a comic about it](https://xkcd.com/1597/). So... if you get stuck, remember, even experienced programmers sometimes just delete their trees and copy over the stuff they want manually. +There are lots of different ways to use git, and it's so easy to get into a messy state that [there's a comic about it](https://xkcd.com/1597/). So... if you get stuck, remember, even experienced programmers sometimes just delete their trees and copy over the stuff they want manually. If you're planning to contribute, first you'll want to [get a local copy of the source code (also known as "cloning the repository")](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) @@ -56,7 +80,7 @@ Replace MYUSERNAME with your own GitHub username. This section isn't required, but many contributors find it helpful, especially for running tests using different versions of python. -[virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool for setting up virtual python environments. This allows you to have all the dependencies for cve-binary-tool set up in a single environment, or have different environments set up for testing using different versions of Python. +[virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool for setting up virtual python environments. This allows you to have all the dependencies for cve-bin-tool set up in a single environment, or have different environments set up for testing using different versions of Python. To install it: @@ -64,16 +88,16 @@ To install it: pip install virtualenv ``` -To make a new venv using python 3.8: +To make a new venv using python 3.9: ```bash -virtualenv -p python3.8 ~/Code/venv3.8 +virtualenv -p python3.9 ~/Code/venv3.9 ``` Each time you want to use a virtualenv, you "activate" it using the activate script: ```bash -source ~/Code/venv3.8/bin/activate +source ~/Code/venv3.9/bin/activate ``` And when you're done with the venv, you can deactivate it using the `deactivate` command. @@ -82,44 +106,95 @@ While you're in a venv, the `python` command will point to whatever version you ## Installing dependencies -The packages you need to run CVE Binary Tool are listed in the `requirements.txt` file in the main cve-bin-tool directory. You can install all of them using the following pip command. +The packages you need to run CVE Binary Tool are listed in the `requirements.txt` file in the main cve-bin-tool directory. You can install all of them using the following pip command: ```bash -pip install -r requirements.txt +pip install -U -r requirements.txt +``` + +The `-U` in that line above will update you to the latest versions of packages as needed, which we recommend because people running security tools generally want to have all the latest updates if possible. The `-r requirements.txt` specifies the file with all the requirements. + +We also have a recommended list of dependencies just for developers that include things like the flake8 linter. You probably want to install them too if you're intending to be a developer. + +```bash +pip install -r dev-requirements.txt ``` +## Running your local copy of CVE Binary Tool + +One of the reasons we suggest virtualenv is that it makes it easier to do this section. + +If you want to run a local copy of cve-bin-tool, the recommended way is to install it locally. From the cve-bin-tool main directory, run: + +```console +python3 -m pip install --user -e . +``` + +Then you can type `cve-bin-tool` on the command line and it will do the right thing. This includes some special code intended to deal with adding new checkers to the list on the fly so things should work seamlessly for you while you're building new contributions. + +### Help, my checkers aren't loading + +CVE Binary Tool uses the installed egg file to figure out which checkers are installed. If you run it directly without installing it (e.g. you try to use `python -m cve_bin_tool.cli`), it will usually work fine but you may occasionally find that checkers aren't loading properly. Typically this happens with new checkers you are adding, but sometimes if you `git pull` it will cause a similar effect. If you get into this state, you can fix it by running the following command from the main cve-bin-tool directory: + +```bash +python setup.py egg_info +``` + +We recommend that you switch to having a local install (e.g. run `pip install --user -e .` in the main cve-bin-tool directory) to avoid this problem in the future. + ## Running tests -The CVE Binary Tool has a set of tests that can be run using `pytest` command. Usually all the short tests should pass, although sometimes internet connectivity issues will cause problems. +The CVE Binary Tool has a set of tests that can be run using `pytest` command. Typically you want to run `pytest` in the cve-bin-tool directory to run the short test suite and make sure tests pass. -[There is a README file in the tests directory](https://github.com/intel/cve-bin-tool/blob/main/test/README.md) which contains more info about how to run just specific tests, or how to run the longer tests which involve downloading full software packages to test the tool. The long tests sometimes fail due to package name changes, which may not be your fault unless you modified one of them. +[There is a README file in the tests directory](https://github.com/intel/cve-bin-tool/blob/main/test/README.md) which contains more info about how to run specific tests, or how to run the longer tests. -## Running isort and black +We have done our best to make tests stable and ensure that they pass at all times, but occasionally tests may fail due to factors outside your control (common causes: internet connectivity, rate limiting by NVD or new vulnerability data changing our test expectations). If a test doesn't pass, you should look at it to see if any changes you made caused the failure. If you're not sure, submit your code as a pull request and mention the issue and someone will try to help you sort it out. -CVE Binary Tool uses isort to sort imports alphabetically, and automatically separated into sections and by type. We also use Black as style formatter. Contributors are requested to format their code with isort and black before submitting, and the CI will warn you if your -code needs re-formatting. +When you submit your code as a pull request, the whole test suite will be run on windows and linux using the versions of python we support, including longer tests. We don't expect you to do all that yourself; usually trying for one version of python on whatever local OS you have is good enough and you can let Github Actions do the rest! -isort can be installed using pip. +## Running linters + +CVE Binary Tool uses a few tools to improve code quality and readability: + +- `isort` sorts imports alphabetically and by type +- `black` provides automatic style formatting. This will give you basic [PEP8](https://www.python.org/dev/peps/pep-0008/) compliance. (PEP8 is where the default python style guide is defined.) +- `flake8` provides additional code "linting" for more complex errors like unused imports. +- `pyupgrade` helps us be forward compatible with new versions of python. + +We provide a `dev-requirements.txt` file which includes all the precise versions of tools as they'll be used in GitHub Actions. You an install them all using pip: ```bash -pip install isort -``` +pip install -r dev-requirements.txt +``` -Black can be installed using pip. +### Using pre-commit to run linters automatically + +We've provided a pre-commit hook (in `.pre-commit.config.yaml`) so if you want +to run isort/Black locally before you commit, you can install +the hook as follows from the main `cve-bin-tool` directory: ```bash -pip install black -``` +pre-commit install +``` + +Once this is installed, all of those commands will run automatically when you run `git commit` and it won't let you commit until any issues are resolved. (You can also run them manually using `pre-commit` with no arguments.) This will only run on files staged for commit (e.g. things where you've already run `git add`). If you want to run on arbitrary files, see below: + +### Running isort by itself + To format the imports using isort, you run `isort --profile black` followed by the filename. You will have to add `--profile black` when calling isort to make it compatible with Black formatter. For formatting a particular file name filename.py. ```bash isort --profile black filename.py ``` + Alternatively, you can run isort recursively for all the files by adding `.` instead of filename ```bash isort --profile black . ``` + +### Running black by itself + To format the code, you run `black` followed by the filename you wish to reformat. For formatting a particular file name filename.py. ```bash @@ -131,16 +206,17 @@ files you've changed because you won't have to scroll through a pile of auto-formatting changes to find your own modifications. However, you can also specify a whole folder using ```./``` -### Using pre-commit to run isort and Black +### Other linting tools -We've provided a pre-commit hook (in `.pre-commit.config.yaml`) so if you want -to run isort/Black locally before you commit, you can install pre-commit and install -the hook as follows from the main cve-bin-tool directory: +As well as `black` for automatically making sure code adheres to the style guide, we use `flake8` to help us find things like unused imports. The [flake8 documentation](https://flake8.pycqa.org/en/latest/user/index.html) covers what you need to know about running it. -```bash -pip install pre-commit -pre-commit install -``` +We use [pyupgrade](https://github.com/asottile/pyupgrade) to make sure our syntax is updated to fit new versions of python. + +We also have a spell checker set up to help us avoid typos in documentation. The [spelling actions readme file](https://github.com/intel/cve-bin-tool/tree/main/.github/actions/spelling) gives more information including how to add new words to the dictionary if needed. + +We also have a tool to help make sure that new checkers are added to the tables in our documentation. [The format_checkers code is here](https://github.com/intel/cve-bin-tool/blob/main/cve_bin_tool/format_checkers.py), if you're curious. + +You can view all the config files for GitHub Actions (what we use for Continuous Integration (CI)) in [the .github/workflows directory](https://github.com/intel/cve-bin-tool/tree/main/.github/workflows). ## Making a new branch & pull request @@ -156,7 +232,15 @@ git checkout -b my_new_branch When you're ready to share that branch to make a pull request, make sure you've checked in all the files you're working on. You can get a list of the files you modified using `git status` and see what modifications you made using `git diff` -Use `git add FILENAME` to add the files you want to put in your pull request, and use `git commit` to check them in. Try to use [a clear commit message](https://chris.beams.io/posts/git-commit/). We usually merge pull requests into a single commit when we accept them, so it's fine if you have lots of commits in your branch while you figure stuff out. +Use `git add FILENAME` to add the files you want to put in your pull request, and use `git commit` to check them in. Try to use [a clear commit message](https://chris.beams.io/posts/git-commit/) and use the [Conventional Commits](https://www.conventionalcommits.org/) format. + +### Commit message tips + +We usually merge pull requests into a single commit when we accept them, so it's fine if you have lots of commits in your branch while you figure stuff out, and we can fix your commit message as needed then. But if you make sure that at least the title of your pull request follows the [Conventional Commits](https://www.conventionalcommits.org/) format that you'd like for that merged commit message, that makes our job easier! + +GitHub also has some keywords that help us link issues and then close them automatically when code is merged. The most common one you'll see us use looks like `fixes: #123456`. You can put this in the title of your PR (what usually becomes the commit message when we merge your code), another line in the commit message, or any comment in the pull request to make it work. You and read more about [linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) in the GitHub documentation. + +### Sharing your code with us Once your branch is ready and you've checked in all your code, push it to your fork: @@ -166,6 +250,27 @@ git push myfork From there, you can go to [our pull request page](https://github.com/intel/cve-bin-tool/pulls) to make a new pull request from the web interface. +### Checklist for a great pull request + +Here's a quick checklist to help you make sure your pull request is ready to go: + +1. Have I run the tests locally on at least one version of Python? + - Run the command `pytest` (See also [Running Tests](#running-tests)) + - GitHub Actions will run the tests for you, but you can often find and fix issues faster if you do a local run of the tests. +2. Have I run the code linters and fixed any issues they found? + - We recommend setting up `pre-commit` so these are run automatically (See also [Running Linters](#running-linters)) + - GitHub Actions will run the linters for you too if you forget! (And don't worry, even experienced folk forget sometimes.) + - You will be responsible for fixing any issue found by the linters before your code can be merged. +3. Have I added any tests I need to prove that my code works? + - This is especially important for new features or new checkers. +4. Have I added or updated any documentation if I changed or added a feature? + - New features are often documented in [MANUAL.md](https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md). (See [Making documentation](#making-documentation) for more information.) +5. Have I used [Conventional Commits](https://www.conventionalcommits.org/) to format the title of my pull request? +6. If I closed a bug, have I linked it using one of [Github's keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)? (e.g. include the text `fixed #1234`) +7. Have I checked on the results from GitHub Actions? + - GitHub Actions will run all the tests, linters and a spell check for you. If you can, try to make sure everything is running cleanly with no errors before leaving it for a human code reviewer! + - As of this writing, tests take less than 20 minutes to run once they start, but they can be queued for a while before they start. Go get a cup of tea or work on something else while you wait! + ## Code Review Once you have created a pull request (PR), GitHub Actions will try to run all the tests on your code. If you can, make any modifications you need to make to ensure that they all pass, but if you get stuck a reviewer will see if they can help you fix them. Remember that you can run the tests locally while you're debugging; you don't have to wait for GitHub to run the tests (see the [Running tests](#running-tests) section above for how to run tests). @@ -180,13 +285,13 @@ In rare cases, the code won't work for us and we'll let you know. Sometimes thi ## Style Guide for cve-bin-tool -This list contains all the style guide that one must follow while contributing so that code is consistent and maintainable. +Most of our "style" stuff is caught by the `black` and `flake8` linters, but we also recommend that contributors use f-strings for formatted strings: ### String Formatting Python provides many different ways to format the string(you can read about them [here](https://realpython.com/python-formatted-output/))and we use f-string formatting in our tool. -**Note: As f-strings are only supported in python 3.6+.** Please make sure you have version >=3.6 +> Note: f-strings are only supported in python 3.6+. - **Example:** Formatting string using f-string @@ -244,6 +349,7 @@ RestructuredText (.`rst`) files, you may want to try out Visual Studio Code, whi Many beginners get stuck trying to figure out how to start. You're not alone! Here's three things we recommend: + 1. Try something marked as a "[good first issue](https://github.com/intel/cve-bin-tool/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)" We try to mark issues that might be easier for beginners. 2. [Add tests to an existing checker](https://github.com/intel/cve-bin-tool/blob/main/test/README.md). This will give you some practice with the test suite. 3. [Add a new checker](https://github.com/intel/cve-bin-tool/blob/main/cve_bin_tool/checkers/README.md) This will give you some deeper understanding of how the tool works and what a signature looks like. We have a few new checker requests listed in the "good first issue" list, or any linux library that has known CVEs (preferably recent ones) is probably interesting enough. diff --git a/README.md b/README.md index 4b9dac4f28..f05e308424 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,75 @@ The CVE Binary Tool is a free, open source tool to help you find known vulnerabi The tool has two main modes of operation: 1. A binary scanner which helps you determine which packages may have been included as part of a piece of software. There are around 100 checkers which focus on common, vulnerable open source components such as openssl, libpng, libxml2 and expat. -2. Tools for scanning known component lists in various formats, including .csv, Python's requirements.txt, several linux distribution package lists, and several Software Bill of Materials (SBOM) formats. +2. Tools for scanning known component lists in various formats, including .csv, several linux distribution package lists, and several Software Bill of Materials (SBOM) formats. It is intended to be used as part of your continuous integration system to enable regular vulnerability scanning and give you early warning of known issues in your supply chain. -See our [documentation](https://cve-bin-tool.readthedocs.io/en/latest/) and [quickstart guide](https://cve-bin-tool.readthedocs.io/en/latest/README.html) +For more details, see our [documentation](https://cve-bin-tool.readthedocs.io/en/latest/) or this [quickstart guide](https://cve-bin-tool.readthedocs.io/en/latest/README.html) + +- [CVE Binary Tool quick start / README](#cve-binary-tool-quick-start--readme) + - [Installing CVE Binary Tool](#installing-cve-binary-tool) + - [Most popular usage options](#most-popular-usage-options) + - [Finding known vulnerabilities using the binary scanner](#finding-known-vulnerabilities-using-the-binary-scanner) + - [Finding known vulnerabilities in a list of components](#finding-known-vulnerabilities-in-a-list-of-components) + - [Scanning an SBOM file for known vulnerabilities](#scanning-an-sbom-file-for-known-vulnerabilities) + - [Full option list](#full-option-list) + - [Configuration](#configuration) + - [Using CVE Binary Tool in Github Actions](#using-cve-binary-tool-in-github-actions) + - [Binary checker list](#binary-checker-list) + - [Limitations](#limitations) + - [Requirements](#requirements) + - [Feedback & Contributions](#feedback--contributions) + - [Security Issues](#security-issues) + +## Installing CVE Binary Tool + +CVE Binary Tool can be installed using pip: + +```console +pip install cve-bin-tool +``` + +You can also do `pip install --user -e .` to install a local copy which is useful if you're trying the latest code from +[the cve-bin-tool github](https://github.com/intel/cve-bin-tool) or doing development. The [Contributor Documentation](https://github.com/intel/cve-bin-tool/blob/main/CONTRIBUTING.md) covers how to set up for local development in more detail. + +## Most popular usage options + +### Finding known vulnerabilities using the binary scanner + +To run the binary scanner on a directory or file: + +```bash +cve-bin-tool +``` + +### Finding known vulnerabilities in a list of components + +To scan a comma-delimited (CSV) or JSON file which lists dependencies and versions: + +```bash +cve-bin-tool --input-file +``` + +Note that the `--input-file` option can also be used to add extra triage data like remarks, comments etc. while scanning a directory so that output will reflect this triage data and you can save time of re-triaging (Usage: `cve-bin-tool -i=test.csv /path/to/scan`). + +### Scanning an SBOM file for known vulnerabilities + +To scan a software bill of materials file (SBOM): + +```bash +cve-bin-tool --sbom --sbom-file +``` + +Valid SBOM types are [SPDX](https://spdx.dev/specifications/), +[CycloneDX](https://cyclonedx.org/specification/overview/), and [SWID](https://csrc.nist.gov/projects/software-identification-swid/guidelines). + +The CVE Binary Tool provides console-based output by default. If you wish to provide another format, you can specify this and a filename on the command line using `--format`. The valid formats are CSV, JSON, console, HTML and PDF. The output filename can be specified using the `--output-file` flag. + +## Full option list Usage: -`cve-bin-tool ` +`cve-bin-tool ` optional arguments: -h, --help show this help message and exit @@ -89,52 +150,35 @@ Usage: -x, --extract autoextract compressed files CVE Binary Tool autoextracts all compressed files by default now +For further information about all of these options, please see [the CVE Binary Tool user manual](https://cve-bin-tool.readthedocs.io/en/latest/MANUAL.html). -You can also do `python -m cve_bin_tool.cli` -which is useful if you're trying the latest code from -[the cve-bin-tool github](https://github.com/intel/cve-bin-tool). - -Note that if the CVSS and Severity flags are both specified, the CVSS flag takes precedence. - -`--input-file` extends the functionality of *csv2cve* for other formats like JSON. It also allows cve-bin-tool to specify triage data so you can group issues which may have been mitigated (through patches, configuration, or other methods not detectable by our version scanning method) or mark false positives. Triage data can be re-used and applied to multiple scans. You can provide either CSV or JSON file as input_file with vendor, product and version fields. You can also add optional fields like remarks, comments, cve_number, severity. - -Note that you can use `-i` or `--input-file` option to produce list of CVEs found in given vendor, product and version fields (Usage: `cve-bin-tool -i=test.csv`) or supplement extra triage data like remarks, comments etc. while scanning directory so that output will reflect this triage data and you can save time of re-triaging (Usage: `cve-bin-tool -i=test.csv /path/to/scan`). - -`-n` or `--nvd` specify method used to fetch known vulnerability data from NVD. 'api' is the default. - -You can also use `-m` or `--merge` along with `-f --format` and `-o --output-file` to generate output from intermediate reports in different formats. -Use `-F --filter` along with `-m --merge`to filter out intermediate reports based on tag. - -> Note: For backward compatibility, we still support `csv2cve` command for producing CVEs from csv but we recommend using new `--input-file` command instead. +> Note: For backward compatibility, we still support `csv2cve` command for producing CVEs from csv but we recommend using the `--input-file` command going forwards. `-L` or `--package-list` option runs a CVE scan on installed packages listed in a package list. It takes a python package list (requirements.txt) or a package list of packages of systems that has dpkg, pacman or rpm package manager as an input for the scan. This option is much faster and detects more CVEs than the default method of scanning binaries. -You can get a package list of all installed packages in - - a system using dpkg package manager by running `dpkg-query -W -f '${binary:Package}\n' > pkg-list` - - a system using pacman package manager by running `pacman -Qqe > pkg-list` - - a system using rpm package manager by running `rpm -qa --queryformat '%{NAME}\n' > pkg-list` +You can get a package list of all installed packages in + +- a system using dpkg package manager by running `dpkg-query -W -f '${binary:Package}\n' > pkg-list` +- a system using pacman package manager by running `pacman -Qqe > pkg-list` +- a system using rpm package manager by running `rpm -qa --queryformat '%{NAME}\n' > pkg-list` in the terminal and provide it as an input by running `cve-bin-tool -L pkg-list` for a full package scan. +## Configuration + You can use `--config` option to provide configuration file for the tool. You can still override options specified in config file with command line arguments. See our sample config files in the [test/config](https://github.com/intel/cve-bin-tool/blob/main/test/config/) Specifying the `--offline` option when running a scan ensures that cve-bin-tool doesn't attempt to download the latest database files or to check for a newer version of the tool. -The 0.3.1 release is intended to be the last release to officially support -python 2.7; please switch to python 3.6+ for future releases and to use the -development tree. You can check [our CI configuration](https://github.com/intel/cve-bin-tool/blob/main/.github/workflows/pythonapp.yml) to see what versions of python we're explicitly testing. +## Using CVE Binary Tool in Github Actions If you want to integrate cve-bin-tool as a part of your github action pipeline. You can checkout our example [github action](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/cve_scanner_gh_action.yml). -This readme is intended to be a quickstart guide for using the tool. If you -require more information, there is also a [user manual](https://cve-bin-tool.readthedocs.io/en/latest/MANUAL.html) available. - -## How it works +## Binary checker list -This scanner looks at the strings found in binary files to see if they -match certain vulnerable versions of the following libraries and tools: +The following checkers are available for finding components in binary files: | | | | Available checkers | | | | @@ -173,32 +217,34 @@ This tool is meant to be used as a quick-to-run, easily-automatable check in a non-malicious environment so that developers can be made aware of old libraries with security issues that have been compiled into their binaries. +If you are using the binary scanner capabilities, be aware that we only have a limited number of binary checkers (see table above) so we can only detect those libraries. Contributions of new checkers are always welcome! You can also use an alternate way to detect components (for example, a bill of materials tool such as [tern](https://github.com/tern-tools/tern)) and then use the resulting list as input to cve-bin-tool to get a more comprehensive vulnerability list. + ## Requirements To use the auto-extractor, you may need the following utilities depending on the type of file you need to extract. The utilities below are required to run the full test suite on Linux: -- `file` -- `strings` -- `tar` -- `unzip` -- `rpm2cpio` -- `cpio` -- `ar` -- `cabextract` +- `file` +- `strings` +- `tar` +- `unzip` +- `rpm2cpio` +- `cpio` +- `ar` +- `cabextract` Most of these are installed by default on many Linux systems, but `cabextract` and `rpm2cpio` in particular might need to be installed. On windows systems, you may need: -- `ar` -- `7z` -- `Expand` -- `pdftotext` +- `ar` +- `7z` +- `Expand` +- `pdftotext` -Windows has `ar` and `Expand` installed in default, but `7z` in particular might need to be installed. +Windows has `ar` and `Expand` installed by default, but `7z` in particular might need to be installed. If you want to run our test-suite or scan a zstd compressed file, We recommend installing this [7-zip-zstd](https://github.com/mcmilk/7-Zip-zstd) fork of 7zip. We are currently using `7z` for extracting `jar`, `apk`, `msi`, `exe` and `rpm` files. @@ -212,6 +258,8 @@ compiler above should fix it. `pdftotext` is required for running tests. (users of cve-bin-tool may not need it, developers likely will.) The best approach to install it on Windows involves using [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html) (click [here](https://anaconda.org/conda-forge/pdftotext) for further instructions). +You can check [our CI configuration](https://github.com/intel/cve-bin-tool/blob/main/.github/workflows/pythonapp.yml) to see what versions of python we're explicitly testing. + ## Feedback & Contributions Bugs and feature requests can be made via [GitHub @@ -219,14 +267,10 @@ issues](https://github.com/intel/cve-bin-tool/issues). Be aware that these issu not private, so take care when providing output to make sure you are not disclosing security issues in other products. -Pull requests are also welcome via git. - -The CVE Binary Tool uses [the Black python code -formatter](https://github.com/python/black) and [isort](https://github.com/PyCQA/isort) to keep coding style consistent; -you may wish to have it installed to make pull requests easier. We've provided a pre-commit hook (in `.pre-commit.config.yaml`) so if you want to have the check run locally before you commit, you can install pre-commit and install the hook as follows from the main cve-bin-tool directory: +Pull requests are also welcome via git. - pip install pre-commit - pre-commit install +- New contributors should read the [contributor guide](https://github.com/intel/cve-bin-tool/blob/main/CONTRIBUTING.md) to get started. +- Folk who already have experience contributing to open source projects may not need the full guide but should still use the [pull request checklist](https://github.com/intel/cve-bin-tool/blob/main/CONTRIBUTING.md#checklist-for-a-great-pull-request) to make things easy for everyone. ## Security Issues diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md new file mode 120000 index 0000000000..eada936c1d --- /dev/null +++ b/doc/CONTRIBUTING.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index a96092d621..9239b4c839 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -17,7 +17,7 @@ The CVE Binary Tool helps you determine if your system includes known vulnerabil CSV2CVE.md how_to_guides/index RELEASE.md - CONTRIBUTORS.md + CONTRIBUTING.md Indices and tables ==================