Skip to content

Commit a134f8d

Browse files
terrikoterriko
committed
Add documentation to 1.1 branch
1 parent 3b00eee commit a134f8d

File tree

8 files changed

+1071
-0
lines changed

8 files changed

+1071
-0
lines changed

‎doc/CSV2CVE.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
CSV2CVE
2+
=======
3+
4+
This tool takes a comma-delimited file (.csv) with the format `vendor,product,version` and queries the locally stored CVE data (the same data used by the CVE Binary Tool) to give you a list of CVEs that affect each version listed.
5+
6+
This is meant as a helper tool for folk who know the list of product being used in their software, so that you don't have to rely on binary detection heuristics. There exist other tools that do this, but it seemed potentially useful to provide both in the same suite of tools, and it also saves users from having to download two copies of the same data.
7+
8+
At the moment, you must use the exact vendor and product strings used in the National Vulnerability Database. You can read more on how to find the correct string in [the checker documentation](https://github.com/intel/cve-bin-tool/blob/master/cve_bin_tool/checkers/README.md). Future work could extend this to use the mappings already in the CVE Binary Tool or to use other mappings such as common linux package names for a given distribution. (Contributions welcome!)
9+
10+
11+
Running the tool:
12+
----------------
13+
`csv2cve <csv_file>`
14+
15+
If you are trying to run a local copy from source, you can also use `python -m cve_bin_tool.csv2cve <csv_file>`
16+
17+
Additional Options:
18+
------------------
19+
```
20+
Output options:
21+
-l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
22+
log level. The default log level is info
23+
Functional options:
24+
-u {now,daily,never}, --update {now,daily,never}
25+
update schedule for NVD database. Default is daily.
26+
```
27+
28+
Example .csv file:
29+
------------------
30+
31+
Note that this *does* require that the first row be `vendor,product,version` so that the csv parser can do the right thing. You can have the columns in a different order and/or include other information, but it needs those 3 columns to work.
32+
33+
```python
34+
vendor,product,version
35+
libjpeg-turbo,libjpeg-turbo,2.0.1
36+
haxx,curl,7.59.0
37+
haxx,libcurl,7.59.0
38+
wontwork,no,7.7
39+
```
40+
41+
Example output:
42+
---------------
43+
```console
44+
(venv3.7) [terri@cedar cve-bin-tool]$ python -m cve_bin_tool.csv2cve test/csv/test.csv
45+
cve_bin_tool.CVEDB - INFO - Using cached CVE data (<24h old). Use -u now to update immediately.
46+
+=================================================================+
47+
| ___ _ __ ____ ___ ___ _ _ _____ ___ ___ _ |
48+
| / __| \ / /| ___] | )[ ]| \ | | [_ _]| _ || _ || | |
49+
| | |__ \ \/ / | _]_ = | < | | | |\| | = | | ||_||||_||| |__ |
50+
| \___| \__/ |___ ] |___)[___]|_| \_| |_| |___||___||____| |
51+
| |
52+
+=================================================================+
53+
| CVE Binary Tool Report Generated: 2020-04-30 11:04:24 |
54+
+=================================================================+
55+
56+
+=================================================================+
57+
| MODULE NAME | VERSION | CVE NUMBER | SEVERITY |
58+
+=================================================================+
59+
| libjpeg-turbo | 2.0.1 | CVE-2018-19664 | MEDIUM |
60+
+--------------------+-----------+--------------------+-----------+
61+
| libjpeg-turbo | 2.0.1 | CVE-2018-20330 | HIGH |
62+
+--------------------+-----------+--------------------+-----------+
63+
| curl | 7.59.0 | CVE-2018-0500 | CRITICAL |
64+
+--------------------+-----------+--------------------+-----------+
65+
| curl | 7.59.0 | CVE-2018-1000300 | CRITICAL |
66+
+--------------------+-----------+--------------------+-----------+
67+
| curl | 7.59.0 | CVE-2018-1000301 | CRITICAL |
68+
+--------------------+-----------+--------------------+-----------+
69+
| curl | 7.59.0 | CVE-2018-14618 | CRITICAL |
70+
+--------------------+-----------+--------------------+-----------+
71+
| curl | 7.59.0 | CVE-2018-16839 | CRITICAL |
72+
+--------------------+-----------+--------------------+-----------+
73+
| curl | 7.59.0 | CVE-2018-16840 | CRITICAL |
74+
+--------------------+-----------+--------------------+-----------+
75+
| curl | 7.59.0 | CVE-2018-16842 | CRITICAL |
76+
+--------------------+-----------+--------------------+-----------+
77+
| curl | 7.59.0 | CVE-2018-16890 | HIGH |
78+
+--------------------+-----------+--------------------+-----------+
79+
| curl | 7.59.0 | CVE-2019-3822 | CRITICAL |
80+
+--------------------+-----------+--------------------+-----------+
81+
| curl | 7.59.0 | CVE-2019-3823 | HIGH |
82+
+--------------------+-----------+--------------------+-----------+
83+
| curl | 7.59.0 | CVE-2019-5436 | HIGH |
84+
+--------------------+-----------+--------------------+-----------+
85+
| curl | 7.59.0 | CVE-2019-5443 | HIGH |
86+
+--------------------+-----------+--------------------+-----------+
87+
| curl | 7.59.0 | CVE-2019-5481 | CRITICAL |
88+
+--------------------+-----------+--------------------+-----------+
89+
| curl | 7.59.0 | CVE-2019-5482 | CRITICAL |
90+
+--------------------+-----------+--------------------+-----------+
91+
| libcurl | 7.59.0 | CVE-2018-14618 | CRITICAL |
92+
+--------------------+-----------+--------------------+-----------+
93+
| libcurl | 7.59.0 | CVE-2018-16890 | HIGH |
94+
+--------------------+-----------+--------------------+-----------+
95+
| libcurl | 7.59.0 | CVE-2019-3822 | CRITICAL |
96+
+--------------------+-----------+--------------------+-----------+
97+
| libcurl | 7.59.0 | CVE-2019-3823 | HIGH |
98+
+--------------------+-----------+--------------------+-----------+
99+
| libcurl | 7.59.0 | CVE-2019-5436 | HIGH |
100+
+--------------------+-----------+--------------------+-----------+
101+
| no | 7.7 | UNKNOWN | UNKNOWN |
102+
+--------------------+-----------+--------------------+-----------+
103+

‎doc/MANUAL.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
Table of Contents
2+
-----------------
3+
- [CVE checker for binary code User Manual](#CVE-checker-for-binary-code-User-Manual)
4+
- [How it works](#How-it-works)
5+
- [Installing](#Installing)
6+
- [Fixing Known Issues / What should I do if it finds something?](#Fixing-Known-Issues--What-should-I-do-if-it-finds-something)
7+
- [Limitations](#Limitations)
8+
- [Options:](#Options)
9+
- [-x, --extract](#-x---extract)
10+
- [-s SKIPS, --skips SKIPS](#-s-SKIPS---skips-SKIPS)
11+
- [-r CHECKERS, --runs CHECKERS](#-r-CHECKERS---runs-CHECKERS)
12+
- [-m, --multithread enable multithread](#-m---multithread-enable-multithread)
13+
- [-u {now,daily,never}, --update {now,daily,never}](#-u-nowdailynever---update-nowdailynever)
14+
- [Output modes](#Output-modes)
15+
- [Default Mode](#Default-Mode)
16+
- [Quiet Mode](#Quiet-Mode)
17+
- [Logging modes](#Logging-modes)
18+
- [Feedback & Contributions](#Feedback--Contributions)
19+
- [Security Issues](#Security-Issues)
20+
21+
22+
CVE checker for binary code User Manual
23+
=======================================
24+
25+
This tool scans for a number of common, vulnerable open source components
26+
(openssl, libpng, libxml2, expat and a few others) to let you know if your
27+
system includes common libraries with known vulnerabilities, known as CVEs
28+
(Common Vulnerabilities and Exposures).
29+
30+
Usage:
31+
`cve-bin-tool <flags> <path to directory>`
32+
33+
Possible output levels:
34+
```
35+
-q, --quiet suppress output
36+
-l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
37+
log level
38+
-o OUTPUT_FILE, --output-file OUTPUT_FILE
39+
provide output filename (default: output to stdout)
40+
-f {csv,json,console}, --format {csv,json,console}
41+
update output format (default: console)
42+
```
43+
Other options:
44+
```
45+
-h, --help show help message and exit
46+
-V, --version show program's version number and exit
47+
-x, --extract autoextract compressed files
48+
-s SKIPS, --skips SKIPS
49+
comma-separated list of checkers to disable
50+
-r CHECKERS, --runs CHECKERS
51+
comma-separated list of checkers to enable
52+
-m, --multithread enable multithread
53+
-u {now,daily,never}, --update {now,daily,never}
54+
update schedule for NVD database. Default is daily.
55+
```
56+
57+
Available checkers: `bluez, curl, expat, ffmpeg, gnutls, icu, kerberos, libcurl, libdb, libgcrypt, libjpeg,
58+
libnss, libtiff, node, openssh, openssl, png, python, sqlite, systemd, xerces, xml2, zlib
59+
`
60+
61+
For a quick overview of usage and how it works, you can also see [the readme file](README.md).
62+
63+
64+
How it works
65+
------------
66+
This scanner looks at the strings found in binary files to see if they
67+
match vulnerable versions of a small set of popular open source libraries.
68+
69+
It does not attempt to exploit issues or examine code in greater detail.
70+
As such, it cannot tell if someone has backported fixes to an otherwise
71+
vulnerable version, it merely provides a mapping between strings, versions, and
72+
known CVEs.
73+
74+
A [list of currently available checkers](https://github.com/intel/cve-bin-tool/tree/master/cve_bin_tool/checkers) can be found in the checkers
75+
directory, as can the [instructions on how to add a new
76+
checker](cve_bin_tool/checkers/README.md). Support for new checkers can be requested
77+
via [GitHub
78+
issues](https://github.com/intel/cve-bin-tool/issues).
79+
(Please note, you will need to be logged in to add a new issue.)
80+
81+
82+
This tool gives a list of CVE numbers. For those not familiar with the process, these can be looked up using a number of different tools, such as the [vulnerability search on the CVE Details website](https://www.cvedetails.com/vulnerability-search.php). Each CVE filed contains a short summary of the issue, a set of severity scores that are combined to make a CVSS score, a list of products known to be affected, and links to more information (which may include links to sample exploits as well as patches to fix the issue).
83+
84+
Installing
85+
----------
86+
87+
`cve-bin-tool` can be installed via pip. If your `PATH` environment variable is
88+
properly configured, installation will result in `cve-bin-tool` being accessible
89+
globally. If not you can treat `cve-bin-tool` as `python -m cve_bin_tool.cli` in
90+
the documentation.
91+
92+
```console
93+
pip install -U cve-bin-tool
94+
```
95+
96+
If you want the latest and greatest between releases you can grab from GitHub.
97+
98+
```console
99+
pip install -U git+https://github.com/intel/cve-bin-tool
100+
```
101+
102+
CVE Binary Tool relies on a few command line utilities which are usually present
103+
on GNU/Linux systems but you may need to install.
104+
105+
- file
106+
- strings
107+
- tar
108+
- unzip
109+
- rpm2cpio
110+
- cpio
111+
- ar
112+
- cabextract
113+
114+
On Windows, it requires
115+
- Extract
116+
- ar
117+
- 7zip
118+
119+
120+
Fixing Known Issues / What should I do if it finds something?
121+
-------------------------------------------------------------
122+
123+
The most recommended way to fix a given CVE is to upgrade the package to a
124+
non-vulnerable version. Ideally, a CVE is only made public after a fix is
125+
available, although this is not always the case.
126+
127+
If this is not possible for some reason, search for the CVE number to get
128+
information on possible workarounds and patches that could be backported to
129+
other versions. Note that neither workarounds nor backported fixes can be
130+
detected by this tool, so your binary will continue to show up as vulnerable
131+
even though it may now be safely mitigated and the result a false positive.
132+
133+
Limitations
134+
-----------
135+
136+
The last release of this tool to support python 2.7 is 0.3.1. Please use
137+
python 3.6+ for development and future versions. Linux and Windows are
138+
supported, as is usage within cygwin on windows.
139+
140+
This tool does not scan for all possible known public vulnerabilities, it only
141+
scans for specific commonly vulnerable open source components. A complete
142+
list of currently supported library checkers can be found in [the checkers
143+
directory](https://github.com/intel/cve-bin-tool/tree/master/cve_bin_tool/checkers).
144+
145+
As the name implies, this tool is intended for use with binaries. If you have
146+
access to a known list of product names and versions, we do have a helper tool called [CSV2CVE](https://github.com/intel/cve-bin-tool/blob/master/CSV2CVE.md) that can be used to look up known vulnerabilities given a comma-delimited file. See the [documentation for CSV2CVE for more details](https://github.com/intel/cve-bin-tool/blob/master/CSV2CVE.md).
147+
148+
Options:
149+
--------
150+
151+
### -x, --extract
152+
153+
This option allows the CVE Binary Tool to extract compressed files into a temporary directory so the contents can be scanned. If the quiet flag is not used, the list of extracted files will be printed.
154+
155+
### -s SKIPS, --skips SKIPS
156+
157+
This option allows one to skip (disable) a comma-separated list of checkers. This can be useful for improving the performance of the tool when you have some prior knowledge about what checkers may apply to the binary you are scanning.
158+
159+
### -r CHECKERS, --runs CHECKERS
160+
161+
This option allows one to enable a comma-separated list of checkers.
162+
163+
### -m, --multithread enable multithread
164+
165+
This options allows one to enable multithread mode, so that the scanner can run in parallel on many files at once. This can be used to improve performance, particularly if you are scanning a large directory or a compressed file with many files in it.
166+
167+
### -u {now,daily,never}, --update {now,daily,never}
168+
169+
This option controls the frequency of updates for the CVE data from the National Vulnerability Database. By default, the tool checks the staleness of the data with every run, and if the data is more than one day old, it gets an update from NVD. You may also choose to update the data `now` (in which case all cached data is deleted and a full new download is done) or `never` in which case the staleness check is not done and no update is requested. The `now` and `never` modes can be combined to produce alternative update schedules if daily is not the desired one.
170+
171+
Output modes
172+
------------
173+
174+
Although the examples in this section show results for a single library to make them shorter and easier to read, the tool was designed to be run on entire directories and will scan all files in a directory if one is supplied.
175+
176+
### -o OUTPUT_FILE, --output-file OUTPUT_FILE
177+
178+
This option allows you to specify the filename for the report, rather than having CVE Binary Tool generate it by itself.
179+
180+
### -f {csv,json,console}, --format {csv,json,console}
181+
182+
This option allows the CVE Binary Tool to produce a report in an alternate format. This is useful if you have other tools which only take a specific format. The default is `console` which pretty-prints the information.
183+
1. `--format csv` - prints in csv (comma separated) format.
184+
```
185+
libgcrypt,1.6.0,CVE-2017-9526,MEDIUM
186+
libgcrypt,1.6.0,CVE-2018-0495,MEDIUM
187+
libgcrypt,1.6.0,CVE-2018-6829,HIGH
188+
```
189+
2. `--format json` - prints in json (javascript object notation) format.
190+
```json
191+
[
192+
{
193+
"package": "libgcrypt",
194+
"version": "1.6.0",
195+
"cve_number": "CVE-2017-9526",
196+
"severity": "MEDIUM"
197+
},
198+
{
199+
"package": "libgcrypt",
200+
"version": "1.6.0",
201+
"cve_number": "CVE-2018-0495",
202+
"severity": "MEDIUM"
203+
},
204+
{
205+
"package": "libgcrypt",
206+
"version": "1.6.0",
207+
"cve_number": "CVE-2018-6829",
208+
"severity": "HIGH"
209+
}
210+
]
211+
```
212+
3. `--format console` - prints in nice tabular format.
213+
```console
214+
+=================================================================+
215+
| CVE Binary Tool Report Generated: 2020-04-29 10:04:06 |
216+
+=================================================================+
217+
218+
+=================================================================+
219+
| MODULE NAME | VERSION | CVE NUMBER | SEVERITY |
220+
+=================================================================+
221+
| bzip2 | 1.0.2 | CVE-2005-0953 | LOW |
222+
+--------------------+-----------+--------------------+-----------+
223+
| bzip2 | 1.0.2 | CVE-2005-1260 | MEDIUM |
224+
+--------------------+-----------+--------------------+-----------+
225+
| bzip2 | 1.0.2 | CVE-2008-1372 | MEDIUM |
226+
+--------------------+-----------+--------------------+-----------+
227+
228+
```
229+
230+
### Output verbosity
231+
232+
As well as the modes above, there are two other output options to decrease or increase the number of messages printed:
233+
234+
1. Quiet mode (-q) suppresses all output but exits with an error number indicating the number of files with known CVEs. This is intended for continuous integration and headless tests, while the other modes are all more human-friendly.
235+
2. Log mode (-l log_level) prints logs of the specified log_level and above. The default log level is info. The logs can be suppressed by using quiet mode.
236+
237+
### Quiet Mode
238+
239+
As the name implies, quiet mode has no console output, and one must check the
240+
return code to see if any issues were found. The return value will be the number of files that have been found to have CVEs
241+
242+
Below is what it returns on bash when one file is found to have CVEs:
243+
244+
```console
245+
terri@sandia:~/Code/cve-bin-tool$ cve-bin-tool -q ~/output_test_quiet/openssl
246+
terri@sandia:~/Code/cve-bin-tool$ echo $?
247+
1
248+
```
249+
250+
Note that errors are returned as negative numbers. Any positive number
251+
indicates that CVEs may be present in the code. A good result here is 0.
252+
253+
### Logging modes
254+
255+
The logging modes provide additional fine-grained control for debug information.
256+
257+
Feedback & Contributions
258+
------------------------
259+
260+
Bugs and feature requests can be made via [GitHub
261+
issues](https://github.com/intel/cve-bin-tool). Be aware that these issues are
262+
not private, so take care when providing output to make sure you are not
263+
disclosing security issues in other products.
264+
265+
Pull requests are also welcome via git.
266+
267+
268+
Security Issues
269+
---------------
270+
271+
Security issues with the tool itself can be reported to Intel's security
272+
incident response team via
273+
[https://intel.com/security](https://intel.com/security).
274+
275+
If in the course of using this tool you discover a security issue with someone
276+
else's code, please disclose responsibly to the appropriate party.

0 commit comments

Comments
 (0)