Skip to content

Commit 2cd662b

Browse files
authored
Updating documentation for 0.3.0 release (#204)
1 parent 95c1db6 commit 2cd662b

File tree

2 files changed

+162
-141
lines changed

2 files changed

+162
-141
lines changed

MANUAL.md

Lines changed: 131 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -9,32 +9,51 @@ system includes common libraries with known vulnerabilities, known as CVEs
99
Usage:
1010
`cve-bin-tool <flags> <path to directory>`
1111

12-
Possible output levels:
13-
-v (verbose): print scan results as they're found
14-
(regular): print only final summary
15-
-q (quiet): suppress all output but exit with error
16-
number indicating number of files with CVE
12+
Possible output levels:
13+
```
14+
-v, --verbose details on found issues as script runs
15+
-q, --quiet suppress output
16+
-l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
17+
log level
18+
```
19+
Other options:
20+
```
21+
-h, --help show help message and exit
22+
-x, --extract autoextract compressed files
23+
-s SKIPS, --skips SKIPS
24+
comma-separated list of checkers to disable
25+
-m, --multithread enable multithread
26+
-u {now,daily,never}, --update {now,daily,never}
27+
update schedule for NVD database. Default is daily.
28+
```
1729

18-
Other options:
19-
-x (extract): Autoextract compressed files
30+
Available checkers: `curl, expat, icu, kerberos, libcurl, libgcrypt, libjpeg,
31+
libnss, libtiff, node, openssl, png, sqlite, systemd, xerces, xml2, zlib
32+
`
2033

2134
For a quick overview of usage and how it works, you can also see [the readme file](README.md).
2235

2336

2437
Table of Contents
2538
-----------------
26-
- [CVE checker for binary code User Manual](#cve-checker-for-binary-code-user-manual)
27-
- [Table of Contents](#table-of-contents)
28-
- [How it works](#how-it-works)
29-
- [Installing](#installing)
30-
- [Fixing Known Issues / What should I do if it finds something?](#fixing-known-issues--what-should-i-do-if-it-finds-something)
31-
- [Limitations](#limitations)
32-
- [Output Samples](#output-samples)
33-
- [Default Mode](#default-mode)
34-
- [Verbose Mode](#verbose-mode)
35-
- [Quiet Mode](#quiet-mode)
36-
- [Feedback & Contributions](#feedback--contributions)
37-
- [Security Issues](#security-issues)
39+
- [CVE checker for binary code User Manual](#CVE-checker-for-binary-code-User-Manual)
40+
- [Table of Contents](#Table-of-Contents)
41+
- [How it works](#How-it-works)
42+
- [Installing](#Installing)
43+
- [Fixing Known Issues / What should I do if it finds something?](#Fixing-Known-Issues--What-should-I-do-if-it-finds-something)
44+
- [Limitations](#Limitations)
45+
- [Options:](#Options)
46+
- [-x, --extract](#x---extract)
47+
- [-s SKIPS, --skips SKIPS](#s-SKIPS---skips-SKIPS)
48+
- [-m, --multithread enable multithread](#m---multithread-enable-multithread)
49+
- [-u {now,daily,never}, --update {now,daily,never}](#u-nowdailynever---update-nowdailynever)
50+
- [Output modes](#Output-modes)
51+
- [Default Mode](#Default-Mode)
52+
- [Verbose Mode](#Verbose-Mode)
53+
- [Quiet Mode](#Quiet-Mode)
54+
- [Logging modes](#Logging-modes)
55+
- [Feedback & Contributions](#Feedback--Contributions)
56+
- [Security Issues](#Security-Issues)
3857

3958
How it works
4059
------------
@@ -86,6 +105,12 @@ on GNU/Linux systems but you may need to install.
86105
- ar
87106
- cabextract
88107

108+
On Windows, it requires
109+
- Extract
110+
- ar
111+
- 7zip
112+
113+
89114
Fixing Known Issues / What should I do if it finds something?
90115
-------------------------------------------------------------
91116

@@ -102,24 +127,37 @@ even though it may now be safely mitigated and the result a false positive.
102127
Limitations
103128
-----------
104129

105-
When running this script, Python 3 is preferred over Python 2.7. This tool
106-
was developed for Linux and expects a number of common Linux utilities. It
107-
can be run on Windows using cygwin or other option to ensure these utilities
108-
are installed.
130+
When running this script, Python 3 is preferred over Python 2.7, as python 2.7 support will be ending soon. Linux and Windows are supported, as is usage within cygwin on windows.
109131

110132
This tool does not scan for all possible known public vulnerabilities, it only
111133
scans for specific commonly vulnerable open source components. A complete
112134
list of currently supported library checkers can be found in [the checkers
113135
directory](https://github.com/intel/cve-bin-tool/tree/master/checkers).
114136

115137
As the name implies, this tool is intended for use with binaries. If you have
116-
access to a known list of package names and versions, you may wish to use
117-
another tool such as the [CVE check tool
118-
here](https://github.com/ikeydoherty/cve-check-tool) which covers a larger
119-
database of known public issues.
138+
access to a known list of package 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).
139+
140+
Options:
141+
--------
142+
143+
### -x, --extract
144+
145+
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.
146+
147+
### -s SKIPS, --skips SKIPS
148+
149+
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.
150+
151+
### -m, --multithread enable multithread
152+
153+
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.
154+
155+
### -u {now,daily,never}, --update {now,daily,never}
120156

121-
Output Samples
122-
--------------
157+
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.
158+
159+
Output modes
160+
------------
123161

124162
The tool has several different output modes, from most information to least as follows:
125163

@@ -129,122 +167,102 @@ The tool has several different output modes, from most information to least as f
129167

130168
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.
131169

132-
### Default Mode
170+
#### Default Mode
133171

134172
The default mode for the cve-bin-tool prints only a final summary of results,
135173
without CVE descriptions or information while the scan is progressing. It
136174
outputs a CSV with the results to stdout. In the form of `package name, version,
137-
CVE number, CVE severity`. Below is an example of it being run on curl:
175+
CVE number, CVE severity`. Below is an example of it being run on our expat test file:
138176

139177
```
140-
terri@sandia:~/Code/cve-bin-tool$ cve-bin-tool /usr/bin/curl
141-
Connecting to NVD database and extracting the CVE list ... Please hold on.. This
142-
will take few minutes...
143-
Last Update: 2019-01-18
178+
(venv3.6) terri@sandia:~/Code/cve-bin-tool$ python -m cve_bin_tool.cli test/binaries/test-expat-2.0.1.out
179+
Updating CVE data. This will take a few minutes.
180+
Last Update: 2019-08-09
144181
Local database has been updated in the past 24h.
145-
New data not downloaded. Remove old files to force the update.
182+
New data not downloaded. Use "-u now" to force an update
146183
147-
Overall CVE summary:
184+
Overall CVE summary:
148185
There are 1 files with known CVEs detected
149-
Known CVEs in curl 7.58.0:
150-
curl,7.58.0,CVE-2018-0500,CRITICAL
151-
curl,7.58.0,CVE-2018-1000120,CRITICAL
152-
curl,7.58.0,CVE-2018-1000121,HIGH
153-
curl,7.58.0,CVE-2018-1000122,CRITICAL
154-
curl,7.58.0,CVE-2018-1000300,CRITICAL
155-
curl,7.58.0,CVE-2018-1000301,CRITICAL
156-
curl,7.58.0,CVE-2018-16839,CRITICAL
157-
curl,7.58.0,CVE-2018-16842,CRITICAL
186+
Known CVEs in expat 2.0.1:
187+
expat,2.0.1,CVE-2012-6702,MEDIUM
188+
expat,2.0.1,CVE-2016-0718,CRITICAL
189+
expat,2.0.1,CVE-2016-5300,HIGH
190+
expat,2.0.1,CVE-2018-20843,HIGH
191+
expat,2.0.1,CVE-2012-0876,MEDIUM
192+
expat,2.0.1,CVE-2012-1147,MEDIUM
193+
expat,2.0.1,CVE-2012-1148,MEDIUM
194+
expat,2.0.1,CVE-2013-0340,MEDIUM
158195
```
159196

160197
This mode is meant to give the user enough information that they can
161-
investigate further, but it omits the severity information so that the tool can
162-
run more quickly without the additional database lookups.
198+
investigate further.
163199

164200
### Verbose Mode
165201
The verbose mode is another human-friendly mode. Unlike default mode, it
166202
prints results per file as they're found, as well as printing the final
167-
summary, so you can see its progress as it traverses directories. It also
168-
provides detailed descriptions of the CVEs found including severity so that
169-
users can make educated decisions about the risks of a given out-of-date
170-
library.
171-
172-
> `1/18/2019` Verbose mode currently omits CVE descriptions
173-
174-
Sample output on openssl1.0.2.g:
203+
summary, so you can see its progress as it traverses directories.
175204

205+
Sample output on a directory containing vulnerable curl and sqlite rpms:
176206
```
177-
terri@sandia:~/Code/cve-bin-tool$ cve-bin-tool -v /usr/bin/openssl
178-
/usr/bin/openssl contains openssl 1.0.2g
179-
Known CVEs in version 1.0.2g
180-
CVE-2017-3731 CVE-2017-3732 CVE-2016-7055 CVE-2016-7052 CVE-2016-6304 CVE-2016-2183 CVE-2016-6303 CVE-2016-6302 CVE-2016-2182 CVE-2016-2180 CVE-2016-2177 CVE-2016-2178 CVE-2016-2179 CVE-2016-2181 CVE-2016-6306 CVE-2016-2107 CVE-2016-2105 CVE-2016-2106 CVE-2016-2109 CVE-2016-2176
181-
CVE-2016-2105 (7.5-H)
182-
Integer overflow in the EVP_EncodeUpdate function in crypto/evp/encode.c in OpenSSL before 1.0.1t and 1.0.2 before 1.0.2h allows remote attackers to cause a denial of service (heap memory corruption) via a large amount of binary data.
183-
CVE-2016-2106 (7.5-H)
184-
Integer overflow in the EVP_EncryptUpdate function in crypto/evp/evp_enc.c in OpenSSL before 1.0.1t and 1.0.2 before 1.0.2h allows remote attackers to cause a denial of service (heap memory corruption) via a large amount of data.
185-
CVE-2016-2107 (5.9-M)
186-
The AES-NI implementation in OpenSSL before 1.0.1t and 1.0.2 before 1.0.2h does not consider memory allocation during a certain padding check, which allows remote attackers to obtain sensitive cleartext information via a padding-oracle attack against an AES CBC session, NOTE: this vulnerability exists because of an incorrect fix for CVE-2013-0169.
187-
CVE-2016-2109 (7.5-H)
188-
The asn1_d2i_read_bio function in crypto/asn1/a_d2i_fp.c in the ASN.1 BIO implementation in OpenSSL before 1.0.1t and 1.0.2 before 1.0.2h allows remote attackers to cause a denial of service (memory consumption) via a short invalid encoding.
189-
CVE-2016-2176 (8.2-H)
190-
The X509_NAME_oneline function in crypto/x509/x509_obj.c in OpenSSL before 1.0.1t and 1.0.2 before 1.0.2h allows remote attackers to obtain sensitive information from process stack memory or cause a denial of service (buffer over-read) via crafted EBCDIC ASN.1 data.
191-
CVE-2016-2177 (5.9-M)
192-
OpenSSL through 1.0.2h incorrectly uses pointer arithmetic for heap-buffer boundary checks, which might allow remote attackers to cause a denial of service (integer overflow and application crash) or possibly have unspecified other impact by leveraging unexpected malloc behavior, related to s3_srvr.c, ssl_sess.c, and t1_lib.c.
193-
CVE-2016-2178 (5.5-M)
194-
The dsa_sign_setup function in crypto/dsa/dsa_ossl.c in OpenSSL through 1.0.2h does not properly ensure the use of constant-time operations, which makes it easier for local users to discover a DSA private key via a timing side-channel attack.
195-
CVE-2016-2179 (7.5-H)
196-
The DTLS implementation in OpenSSL before 1.1.0 does not properly restrict the lifetime of queue entries associated with unused out-of-order messages, which allows remote attackers to cause a denial of service (memory consumption) by maintaining many crafted DTLS sessions simultaneously, related to d1_lib.c, statem_dtls.c, statem_lib.c, and statem_srvr.c.
197-
CVE-2016-2180 (7.5-H)
198-
The TS_OBJ_print_bio function in crypto/ts/ts_lib.c in the X.509 Public Key Infrastructure Time-Stamp Protocol (TSP) implementation in OpenSSL through 1.0.2h allows remote attackers to cause a denial of service (out-of-bounds read and application crash) via a crafted time-stamp file that is mishandled by the "openssl ts" command.
199-
CVE-2016-2181 (7.5-H)
200-
The Anti-Replay feature in the DTLS implementation in OpenSSL before 1.1.0 mishandles early use of a new epoch number in conjunction with a large sequence number, which allows remote attackers to cause a denial of service (false-positive packet drops) via spoofed DTLS records, related to rec_layer_d1.c and ssl3_record.c.
201-
CVE-2016-2182 (9.8-C)
202-
The BN_bn2dec function in crypto/bn/bn_print.c in OpenSSL before 1.1.0 does not properly validate division results, which allows remote attackers to cause a denial of service (out-of-bounds write and application crash) or possibly have unspecified other impact via unknown vectors.
203-
CVE-2016-2183 (5.3-M)
204-
The DES and Triple DES ciphers, as used in the TLS, SSH, and IPSec protocols and other protocols and products, have a birthday bound of approximately four billion blocks, which makes it easier for remote attackers to obtain cleartext data via a birthday attack against a long-duration encrypted session, as demonstrated by an HTTPS session using Triple DES in CBC mode, aka a "Sweet32" attack.
205-
CVE-2016-6302 (7.5-H)
206-
The tls_decrypt_ticket function in ssl/t1_lib.c in OpenSSL before 1.1.0 does not consider the HMAC size during validation of the ticket length, which allows remote attackers to cause a denial of service via a ticket that is too short.
207-
CVE-2016-6303 (9.8-C)
208-
Integer overflow in the MDC2_Update function in crypto/mdc2/mdc2dgst.c in OpenSSL before 1.1.0 allows remote attackers to cause a denial of service (out-of-bounds write and application crash) or possibly have unspecified other impact via unknown vectors.
209-
CVE-2016-6304 (7.5-H)
210-
Multiple memory leaks in t1_lib.c in OpenSSL before 1.0.1u, 1.0.2 before 1.0.2i, and 1.1.0 before 1.1.0a allow remote attackers to cause a denial of service (memory consumption) via large OCSP Status Request extensions.
211-
CVE-2016-6306 (5.9-M)
212-
The certificate parser in OpenSSL before 1.0.1u and 1.0.2 before 1.0.2i might allow remote attackers to cause a denial of service (out-of-bounds read) via crafted certificate operations, related to s3_clnt.c and s3_srvr.c.
213-
CVE-2016-7052 (7.5-H)
214-
crypto/x509/x509_vfy.c in OpenSSL 1.0.2i allows remote attackers to cause a denial of service (NULL pointer dereference and application crash) by triggering a CRL operation.
215-
CVE-2016-7055 (Error)
216-
217-
CVE-2017-3731 (Error)
218-
219-
CVE-2017-3732 (Error)
220-
207+
(venv3.6) terri@sandia:~/Code/cve-bin-tool$ python -m cve_bin_tool.cli -v -x ~/output_test_verbose/
208+
Updating CVE data. This will take a few minutes.
209+
Last Update: 2019-08-09
210+
Local database has been updated in the past 24h.
211+
New data not downloaded. Use "-u now" to force an update
212+
Checkers: curl, expat, icu, kerberos, libcurl, libgcrypt, libjpeg, libnss, libtiff, node, openssl, png, sqlite, systemd, xerces, xml2, zlib
213+
./usr/bin/sqlite3
214+
./usr/lib/libsqlite3.so.0
215+
./usr/lib/libsqlite3.so.0.8.6
216+
./usr/share/doc/sqlite-3.1.2
217+
./usr/share/doc/sqlite-3.1.2/README
218+
./usr/share/man/man1/sqlite3.1.gz
219+
780 blocks
220+
/tmp/cve-bin-tool-2qyr5nh7/sqlite-3.1.2-2.99_2.el4.at.i386.rpm.extracted/usr/lib/libsqlite3.so.0.8.6 is sqlite 3.1.2
221+
Known CVEs in version 3.1.2
222+
CVE-2018-20346, CVE-2018-20506
223+
/tmp/cve-bin-tool-2qyr5nh7/sqlite-3.1.2-2.99_2.el4.at.i386.rpm.extracted/usr/bin/sqlite3 is sqlite 3.UNKNOWN
224+
./usr/bin/curl
225+
./usr/share/doc/curl
226+
./usr/share/doc/curl/BUGS
227+
./usr/share/doc/curl/CHANGES
228+
./usr/share/doc/curl/COPYING
229+
./usr/share/doc/curl/FAQ
230+
./usr/share/doc/curl/FEATURES
231+
./usr/share/doc/curl/MANUAL
232+
./usr/share/doc/curl/README
233+
./usr/share/doc/curl/RESOURCES
234+
./usr/share/doc/curl/TODO
235+
./usr/share/doc/curl/TheArtOfHttpScripting
236+
./usr/share/man/man1/curl.1.gz
237+
1092 blocks
238+
/tmp/cve-bin-tool-2qyr5nh7/curl-7.32.0-3.fc20.x86_64.rpm.extracted/usr/bin/curl is curl 7.32.0
239+
Known CVEs in version 7.32.0
240+
CVE-2018-1000007, CVE-2014-8150, CVE-2017-7407, CVE-2016-9586, CVE-2016-8615, CVE-2016-8617, CVE-2016-8618, CVE-2016-8624, CVE-2016-5419, CVE-2016-5420, CVE-2015-3153, CVE-2014-3613, CVE-2014-0139, CVE-2016-8619, CVE-2017-1000254, CVE-2016-8616, CVE-2015-3148, CVE-2015-3143, CVE-2014-0015, CVE-2016-8623, CVE-2016-0755, CVE-2014-0138, CVE-2016-7167, CVE-2016-4802, CVE-2016-8625, CVE-2016-8621, CVE-2018-1000120, CVE-2018-16842, CVE-2017-1000100, CVE-2018-14618, CVE-2014-3707, CVE-2013-4545, CVE-2019-5436, CVE-2016-7141, CVE-2018-1000301, CVE-2018-1000122, CVE-2017-1000257, CVE-2016-0754, CVE-2018-1000121, CVE-2017-8817, CVE-2016-3739, CVE-2013-6422, CVE-2016-8622, CVE-2014-2522, CVE-2014-1263, CVE-2016-9952, CVE-2016-9953, CVE-2015-3145, CVE-2014-8151, CVE-2014-3620, CVE-2016-5421
221241
222242
Overall CVE summary:
223-
There are 1 files with known CVEs detected
224-
Known cves in ['openssl1.0.2g'] :
225-
['CVE-2016-2105', 'CVE-2016-2106', 'CVE-2016-2107', 'CVE-2016-2109', 'CVE-2016-2176', 'CVE-2016-2177', 'CVE-2016-2178', 'CVE-2016-2179', 'CVE-2016-2180', 'CVE-2016-2181', 'CVE-2016-2182', 'CVE-2016-2183', 'CVE-2016-6302', 'CVE-2016-6303', 'CVE-2016-6304', 'CVE-2016-6306', 'CVE-2016-7052', 'CVE-2016-7055', 'CVE-2017-3731', 'CVE-2017-3732']
243+
There are 2 files with known CVEs detected
244+
Known CVEs in sqlite 3.1.2, sqlite 3.UNKNOWN, curl 7.32.0:
245+
sqlite,3.1.2,CVE-2018-20346,HIGH
246+
sqlite,3.1.2,CVE-2018-20506,HIGH
247+
... (Curl results omitted to save space)
226248
```
227249

228-
Note that the ones listed as "Error" are new items where the database has not yet been updated with vulnerability information. This information could easily be found by searching for the CVE numbers using a regular search engine or through a CVE website such as http://cvedetails.com
229-
230-
Also, please note that the severities shown are the ones from the public CVE
231-
databases. The actual severity for a given product may be different based on
232-
what parts of the library are used and what other mitigating factors may be in
233-
effect.
234-
235-
236250
### Quiet Mode
237251

238252
As the name implies, quiet mode has no console output, and one must check the
239-
return code to see if any issues were found.
253+
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
240254

241255
Below is what it returns on bash when one file is found to have CVEs:
242256
```
243-
terri@sandia:~/Code/cve-bin-tool$ cve-bin-tool -q /usr/bin/openssl
257+
terri@sandia:~/Code/cve-bin-tool$ cve-bin-tool -q ~/output_test_quiet/openssl
244258
terri@sandia:~/Code/cve-bin-tool$ echo $?
245259
1
246260
```
247261

262+
### Logging modes
263+
264+
The logging modes provide additional fine-grained control for debug information.
265+
248266
Feedback & Contributions
249267
------------------------
250268

0 commit comments

Comments
 (0)