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

OpenVulnQuery

Install / Use

README