openVulnQuery

A python-based module(s) to query the Cisco PSIRT openVuln API. openVulnQuery is supported in Python version 3.x.

The Cisco Product Security Incident Response Team (PSIRT) openVuln API is a RESTful API that allows customers to obtain Cisco Security Vulnerability information in different machine-consumable formats. APIs are important for customers because they allow their technical staff and programmers to build tools that help them do their job more effectively (in this case, to keep up with security vulnerability information). More information about the API can be found at: https://developer.cisco.com/psirt

PIP Installation

You can easily install openVulnQuery using pip:

pip3 install openVulnQuery

Alternatively, depending on your environment, you may need to specify the latest version (1.31), as demonstrated below:

python3 -m pip install openVulnQuery==1.31

If you are experiencing any difficulty installing openVulnQuery. Here is the link to common installation issues solutions.

Requirements

Tested on Python 3.7 and 3.9.2
argparse >= 1.4.0
requests >= 2.10.0

Config File

Obtain client ID and Secret:

Visit https://apiconsole.cisco.com/
Sign In
Select My Applications Tab
Register a New Application by:
- Enter an application name
- Enter a description of your application.
- Application Type field is Service.
- Grant Type is Client Credentials.
- Under Select APIs choose Cisco PSIRT openVuln API
- Agree to the terms and service and click Register
The openVuln API rate limits are shown in the https://apiconsole.cisco.com/apps/mykeys
Note the value of "Client ID" (a string like e.g. 'abc12abcd13abcdefabcde1a')
Note the value of "Client Secret" (a string like e.g. '1a2abcDEfaBcDefAbcDeFA3b')
Provide the credentials to the application at runtime via two preferred alternativev ways:
- Either export two matching environment variables (below the syntax for bash and assuming the values are as in steps 6. and 7.):

>> export CLIENT_ID="abc12abcd13abcdefabcde1a"
>> export CLIENT_SECRET="1a2abcDEfaBcDefAbcDeFA3b"

Or create a valid JSON file (e.g. credentials.json) with these personal credentials similar to the below given (assuming the values are as in steps 6. and 7.):

{
    "CLIENT_ID": "abc12abcd13abcdefabcde1a",
    "CLIENT_SECRET": "1a2abcDEfaBcDefAbcDeFA3b"
}

Do not distribute the credentials file resulting from previous step

Notes:

The resulting OAuth2 Token will be automatically generated on every call to the API.

Run OpenVulnQuery in the Terminal

If installed with pip run the program by typing

>> openVulnQuery --config PathToCredentialsFile --Advisory Type --API Filters --Parsing Fields --Output Format -Count

Or cd into the directory with the main.py file and run using

>> python main.py --config PathToCredentialsFile --Advisory Type --API Filters --Parsing Fields --Output Format -Count

Notes:

-- Used for whole word commands, - Used for single character commands

Configuration (Optional)

--config FILE
        Path to JSON file with credentials (as in above step 8)
        A sample has been provided in the same folder as main.py:
            sample:configuration.json
        The configuration will be tried first from config file,
        next from environemnt variables CLIENT_ID and CLIENT_SECRET,
        last from config.py variable values, or fail.

API Filters (Required)

--all
        Returns all advisories
        Example:
        >> openVulnQuery --all

--advisory
        Search by specific advisory id
        Example:
        >> openVulnQuery --advisory cisco-sa-20110201-webex

--bugid
        Search by specific Cisco Bug id
        Example:
        >> openVulnQuery --bugid CSCwb92675

--cve
        Search by specific cve id
        Example:
        >> openVulnQuery --cve CVE-2010-3043

--latest
        Search by the last number of advisories published
        Example:
        >> openVulnQuery  --latest 10

        Note: the latest option is limited to 100 maximum queries

--severity
        Search by severity (low, medium, high, critical)
        Examples:
        >> openVulnQuery  --severity critical
        >> openVulnQuery  --severity high
        >> openVulnQuery  --severity medium
        >> openVulnQuery  --severity low

--year
        Search by the year (1995 to present)
        Example:
        >> openVulnQuery  --year 2016

--product
         Search by the product name
         Example:
         >> openVulnQuery  --product Cisco

--ios
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by IOS version
        Examples:
        >> openVulnQuery --ios 15.6\(2\)SP  (*use \ to escape bracket in ios version)
        >> openVulnQuery --ios 15.6(\2\)SP

--ios_xe
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco IOS XE Software version.
        Example:
        >> openVulnQuery --ios_xe 3.16.1S

--nxos
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco NX-OS (standalone mode) Software version.
        Example:
        >> openVulnQuery --nxos 8.3(1)

--aci
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco NX-OS (ACI mode) Software version.
        Example:
        >> openVulnQuery --aci 11.0(2j)

--asa
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco ASA Software version.
        Example:
        >> openVulnQuery --asa 9.18.1

--fmc
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco FMC Software version.
        Example:
        >> openVulnQuery --fmc 7.0.1

--ftd
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco FTD Software version.
        Example:
        >> openVulnQuery --ftd 7.0.1

--fxos
        Cisco Software Checker has been integrated with openVulnAPI.
        Search by Cisco FXOS Software version.
        Example:
        >> openVulnQuery --fxos 2.6.1.131

--OS
        To obtain version information regarding the different Network Operating Systems.
        Examples:
        >> openVulnQuery --OS asa
        >> openVulnQuery --OS ios

--platform
        To obtain platform alias information regarding the different Network Operating Systems.
        Examples:
        >> openVulnQuery --platform asa
        >> openVulnQuery --platform nxos

NOTE: Cisco reserves the right to remove End-of-Support releases from the Cisco Software Checker (subsequently reflected in this API).

Client Application (Optional)

--user-agent APPLICATION
        Name of application to be sent as User-Agent header value in the request.
        Default is TestApp.

Parsing Fields (Optional)

Notes:

If no fields are passed in the default API fields will be returned

Any field that has no information will return with with the field name and NA

Available Fields

advisory_id
sir
first_published
last_updated
cves
bug_ids
cvss_base_score
advisory_title
publication_url
cwe
product_names
summary
vuln_title
cvrf_url
csafUrl

NOTE: CSAF is a specification for structured machine-readable vulnerability-related advisories and further refine those standards over time. CSAF is the new name and replacement for the Common Vulnerability Reporting Framework (CVRF). Cisco will support CVRF until December 31, 2023. More information at: https://csaf.io

-f or --fields

        API Fields
              Examples:
              openVulnQuery --config PathToCredentialsFile --any API filter -f  or --fields list of fields separated by space
              >> openVulnQuery --config PathToCredentialsFile  --all -f sir cves cvrf_url
              >> openVulnQuery --config PathToCredentialsFile  --severity critical -f last_updated cves

        CVRF XML Fields
              Examples:
              openVulnQuery --config PathToCredentialsFile  --any API filter -f or --fields list of fields separated by space
              >> openVulnQuery --config PathToCredentialsFile  --all -f bug_ids vuln_title product_names
              >> openVulnQuery --config PathToCredentialsFile  --severity critical -f bug_ids summary

        Combination
              Examples:
              openVulnQuery --config PathToCredentialsFile  --any API filter -f or --fields list of fields separated by space
              >> openVulnQuery --config PathToCredentialsFile  --all -f sir bug_ids cves vuln_title
              >> openVulnQuery --config PathToCredentialsFile  --year 2011 -f cves cvrf_url bug_ids summary product_names

Additional Filters

User can be more specific on filtering advisories when searching all advisories or by severity. They can filter based on last updated and first published dates providing start and end date as a search range. Dates should be entered in YYYY-MM-DD format.

>> # export CLIENT_ID and CLIENT_SECRET or write to config.py ... then:
>> openVulnQuery  --severity high --last_updated 2016-01-02:2016-04-02 --json filename.json
>> openVulnQuery  --all --last_updated 2016-01-02:2016-07-02
>> openVulnQuery  --severity critical --first_published 2015-01-02:2015-01-04

Output Format (Optional)

Default
        Table style printed to screen
        Example:
        >> openVulnQuery --config PathToCredentialsFile  --year 2016

--json file path
        Returns json in a file in the specified path
        Example:
        >> openVulnQuery --config PathToCredentialsFile  --year 2016 --json  /Users/bkorabik/Documents/2016_cvrf.json

--csv file path
        Creates a CSV file in the specified path
        Example:
        >> openVulnQuery --config PathToCredentialsFile  --year 2016 --csv  /Users/bkorabik/Documents/2016_cvrf.csv

Count (Optional)

Returns the count of fields entered with -f or --fields. If no fields are entered the base API fields are counted and displayed

-c

        Examples:
        >> openVulnQuery --config PathToCredentialsFile  --year 2016 -c
        >> # export CLIENT_ID and CLIENT_SECRET or write to config.py ... then:
        >> openVulnQuery  --severity low -f sir cves bug_ids -c

Developers

Update the config.py file with client id and secret
Directly interact with query_client.py to query the Open Vuln API
query_client.py returns Advisory Object
advisory.py module has Advisory object a abstract class
This abstraction hides the implementation details and the data source used to populate the data type. The data members of security advisories are populated from API results.

Disclosures:

No support for filtering based on --API fields, you can't use --year 2016 and --severity high

Filtering with Grep:

Finding the Number of CVRF Advisories with a "Critical" sir in 2013
>> openVulnQuery --config PathToCredentialsFile  --year 2013 -f sir | grep -c "Critical"
>> openVulnQuery --config PathToCredentialsFile  --severity critical -f first_published | grep -c "2013"

If more than one API filter is entered, the last filter will be used for the API call.

You can alternatively use the date range functionality, as shown below:

>> openVulnQuery --config PathToCredentialsFile  --severity critical --first_published 2017-01-02:2017-10-01

Run OpenVulnQuery as a Library

After you install openVulnQuery package, you can use the query_client module to make API-call which returns advisory objects. For each query to the API, you can pick the advisory format.

>> from openVulnQuery import query_client
>> query_client = query_client.OpenVulnQueryClient(client_id="", client_secret="")
>> advisories = query_client.get_by_year(year=2010, adv_format='default')
>> advisories = query_client.get_by_ios_xe('ios', '3.16.1S')

If you want to use the additional date filters based on first published and last updated date. You can pass the appropriate class

>> advisories = query_client.get_by_severity(adv_format='cvrf', severity='high', FirstPublished(2016-01-01, 2016-02-02))

Debugging Requests and Responses

If the run time environment has the variable CISCO_OPEN_VULN_API_DEBUG set (and the value evaluates to True) the data forming every request as well as raw and formatted variants of successful responses (HTTP 200/OK) will be written to files in JSON format.

The file names follow the pattern: ts-{ts}_id-{id}_snapshot-of-{kind}.json, where:

{ts} receives a date time stamp as ruled by the module variable DEBUG_TIME_STAMP_FORMAT (default %Y%m%dT%H%M%S.%f) and noted in local time,
{id} is a string holding a UUID4 generated for the request and useful to correlate request and response data files
{kind} is one of three strings speaking for themselves:
- request
- response-raw
- response-formated

The files will be written either to the current folder, or to a path stored in the environment variable CISCO_OPEN_VULN_API_PATH (if it is set).

Note: The folder at that later path is expected to exist and be writeable by the user. Please note also, that Filesystem and JSON serialization errors are ignored.

Here are the information stored in advisory object.

Advisory

  * advisory_id
  * sir
  * first_published
  * last_updated
  * cves
  * bug_ids
  * cvss_base_score
  * advisory_title
  * publication_url
  * cwe
  * product_names
  * summary

CVRF (inherits Advisory Abstract Class)

        * cvrf_url
        * vuln_title

After you install openVulnQuery package, you can use the query_client module to make API-call which returns advisory objects. For each query to the API, you can pick advisory format.

>> from openVulnQuery import query_client
>> query_client = query_client.OpenVulnQueryClient(client_id='', client_secret='')
>> advisories = query_client.get_by_year(year=2010, adv_format='default')

Here are the information stored in advisory object.

Advisory (Abstract Base Class)

   * advisory_id
   * sir
   * first_published
   * last_updated
   * cves
   * bug_ids
   * cvss_base_score
   * advisory_title
   * publication_url
   * cwe
   * product_names
   * summary

CVRF

    * cvrf_url

AdvisoryIOS

    * ios_release
    * first_fixed
    * cvrf_url

Running the tests

To run the tests in the tests folder, the additional required mock module should be installed inside the venvwith the usual:

pip3 install mock pytest

There are unit tests in tests/ and some sample like system level test (tests/test_query_client_cvrf.py) skipped in below sample runs, as it contacting the real API.

Sample run (expecting pytest has been installed e.g. via pip3 install pytest):

$ cd /www/github.com/CiscoPSIRT/openVulnAPI/openVulnQuery

$ pytest
=========================================================================================================== test session starts ============================================================================================================
platform darwin -- pytest-3.1.2, py-1.4.34, pluggy-0.4.0
rootdir: /www/github.com/CiscoPSIRT/openVulnAPI/openVulnQuery, inifile:
plugins: cov-2.5.1
collected 159 items

tests/test_advisory.py ......................
tests/test_authorization.py ...
tests/test_cli_api.py ..............................................
tests/test_config.py ....
tests/test_constants.py ...........
tests/test_main.py ...........................s......
tests/test_query_client.py ................
tests/test_query_client_cvrf.py ssssssss
tests/test_utils.py ...............

================================================================================================== 150 passed, 9 skipped in 1.16 seconds ===================================================================================================

Including coverage info (requires pip install pytest-cov which includes pip install coverage ):

$ pytest --cov=openVulnQuery --cov-report=term-missing --cov-report=html
=========================================================================================================== test session starts ============================================================================================================
platform darwin -- pytest-3.1.2, py-1.4.34, pluggy-0.4.0
rootdir: /www/github.com/CiscoPSIRT/openVulnAPI/openVulnQuery, inifile:
plugins: cov-2.5.1
collected 159 items

tests/test_advisory.py ......................
tests/test_authorization.py ...
tests/test_cli_api.py ..............................................
tests/test_config.py ....
tests/test_constants.py ...........
tests/test_main.py ...........................s......
tests/test_query_client.py ................
tests/test_query_client_cvrf.py ssssssss
tests/test_utils.py ...............

---------- coverage: platform darwin, python 2.7.13-final-0 ----------
Name                             Stmts   Miss  Cover   Missing
--------------------------------------------------------------
openVulnQuery/__init__.py            0      0   100%
openVulnQuery/advisory.py           90      1    99%   59
openVulnQuery/authorization.py       6      0   100%
openVulnQuery/cli_api.py            75      4    95%   294-297, 311
openVulnQuery/config.py              4      0   100%
openVulnQuery/constants.py          11      0   100%
openVulnQuery/main.py               38      6    84%   57, 60-65, 70
openVulnQuery/query_client.py      100     16    84%   128-134, 148-155, 160-167
openVulnQuery/rest_api.py            3      0   100%
openVulnQuery/utils.py              76     12    84%   109, 118-129
--------------------------------------------------------------
TOTAL                              403     39    90%
Coverage HTML written to dir htmlcov

================================================================================================== 150 passed, 9 skipped in 1.60 seconds ===================================================================================================

CiscoPSIRT / openVulnQuery

readme