# 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](https://pypi.org/project/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](<https://github.com/iamparas/openVulnAPI/blob/master/openVulnQuery/InstallationIssueSolutions.md>).
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:
1. Visit <https://apiconsole.cisco.com/>
2. Sign In
3. Select My Applications Tab
4. 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
5. The openVuln API rate limits are shown in the https://apiconsole.cisco.com/apps/mykeys
6. Note the value of "Client ID" (a string like e.g. 'abc12abcd13abcdefabcde1a')
7. Note the value of "Client Secret" (a string like e.g. '1a2abcDEfaBcDefAbcDeFA3b')
8. 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"
}
```
9. 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](https://csaf.io) 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 `venv`with 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 ===================================================================================================
```
Raw data
{
"_id": null,
"home_page": "https://github.com/CiscoPSIRT/openVulnQuery",
"name": "OpenVulnQuery",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Omar Santos",
"author_email": "os@cisco.com",
"download_url": "https://files.pythonhosted.org/packages/6f/b1/18d1b4089fa1c30acc8d7809b98c44604b0c11b75b889e9b48b1d625b679/OpenVulnQuery-1.34.tar.gz",
"platform": null,
"description": "# openVulnQuery\n\nA python-based module(s) to query the Cisco PSIRT openVuln API. openVulnQuery is supported in Python version 3.x.\n\nThe 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>\n\n## PIP Installation\n\nYou can easily install openVulnQuery using [pip](https://pypi.org/project/pip/):\n\n```\npip3 install openVulnQuery\n```\n\nAlternatively, depending on your environment, you may need to specify the latest version (1.31), as demonstrated below:\n\n```\npython3 -m pip install openVulnQuery==1.31\n```\n\nIf you are experiencing any difficulty installing openVulnQuery. Here is the link to [common installation issues solutions](<https://github.com/iamparas/openVulnAPI/blob/master/openVulnQuery/InstallationIssueSolutions.md>).\n\nRequirements\n\n- Tested on Python 3.7 and 3.9.2\n- `argparse >= 1.4.0`\n- `requests >= 2.10.0`\n\n## Config File\n\nObtain client ID and Secret:\n\n1. Visit <https://apiconsole.cisco.com/>\n2. Sign In\n3. Select My Applications Tab\n4. Register a New Application by:\n\n - Enter an application name\n - Enter a description of your application.\n - Application Type field is Service.\n - Grant Type is Client Credentials.\n - Under Select APIs choose Cisco PSIRT openVuln API\n - Agree to the terms and service and click Register\n\n5. The openVuln API rate limits are shown in the https://apiconsole.cisco.com/apps/mykeys\n6. Note the value of \"Client ID\" (a string like e.g. 'abc12abcd13abcdefabcde1a')\n7. Note the value of \"Client Secret\" (a string like e.g. '1a2abcDEfaBcDefAbcDeFA3b')\n8. Provide the credentials to the application at runtime via two preferred alternativev ways:\n\n - Either export two matching environment variables (below the syntax for bash and assuming the values are as in steps 6\\. and 7.):\n\n```\n>> export CLIENT_ID=\"abc12abcd13abcdefabcde1a\"\n>> export CLIENT_SECRET=\"1a2abcDEfaBcDefAbcDeFA3b\"\n```\n\n - 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.):\n\n```\n{\n \"CLIENT_ID\": \"abc12abcd13abcdefabcde1a\",\n \"CLIENT_SECRET\": \"1a2abcDEfaBcDefAbcDeFA3b\"\n}\n```\n\n9. Do not distribute the credentials file resulting from previous step\n\n**Notes**:\n\n- The resulting OAuth2 Token will be automatically generated on every call to the API.\n\n## Run OpenVulnQuery in the Terminal\n\n- If installed with pip run the program by typing\n\n```\n>> openVulnQuery --config PathToCredentialsFile --Advisory Type --API Filters --Parsing Fields --Output Format -Count\n```\n\n- Or cd into the directory with the main.py file and run using\n\n```\n>> python main.py --config PathToCredentialsFile --Advisory Type --API Filters --Parsing Fields --Output Format -Count\n```\n\n Notes:\n\n-- Used for whole word commands, - Used for single character commands\n\n## Configuration (Optional)\n\n```\n--config FILE\n Path to JSON file with credentials (as in above step 8)\n A sample has been provided in the same folder as main.py:\n sample:configuration.json\n The configuration will be tried first from config file,\n next from environemnt variables CLIENT_ID and CLIENT_SECRET,\n last from config.py variable values, or fail.\n```\n\n## API Filters (Required)\n\n```\n--all\n Returns all advisories\n Example:\n >> openVulnQuery --all\n\n\n--advisory\n Search by specific advisory id\n Example:\n >> openVulnQuery --advisory cisco-sa-20110201-webex\n \n--bugid\n Search by specific Cisco Bug id\n Example:\n >> openVulnQuery --bugid CSCwb92675\n\n--cve\n Search by specific cve id\n Example:\n >> openVulnQuery --cve CVE-2010-3043\n\n--latest\n Search by the last number of advisories published\n Example:\n >> openVulnQuery --latest 10\n\n Note: the latest option is limited to 100 maximum queries\n\n--severity\n Search by severity (low, medium, high, critical)\n Examples:\n >> openVulnQuery --severity critical\n >> openVulnQuery --severity high\n >> openVulnQuery --severity medium\n >> openVulnQuery --severity low\n\n--year\n Search by the year (1995 to present)\n Example:\n >> openVulnQuery --year 2016\n\n--product\n Search by the product name\n Example:\n >> openVulnQuery --product Cisco\n\n--ios\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by IOS version\n Examples:\n >> openVulnQuery --ios 15.6\\(2\\)SP (*use \\ to escape bracket in ios version)\n >> openVulnQuery --ios 15.6(\\2\\)SP\n\n\n--ios_xe\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco IOS XE Software version.\n Example:\n >> openVulnQuery --ios_xe 3.16.1S\n\n--nxos\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco NX-OS (standalone mode) Software version.\n Example:\n >> openVulnQuery --nxos 8.3(1)\n\n--aci\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco NX-OS (ACI mode) Software version.\n Example:\n >> openVulnQuery --aci 11.0(2j)\n \n--asa\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco ASA Software version.\n Example:\n >> openVulnQuery --asa 9.18.1\n \n--fmc\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco FMC Software version.\n Example:\n >> openVulnQuery --fmc 7.0.1\n \n--ftd\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco FTD Software version.\n Example:\n >> openVulnQuery --ftd 7.0.1\n \n--fxos\n Cisco Software Checker has been integrated with openVulnAPI.\n Search by Cisco FXOS Software version.\n Example:\n >> openVulnQuery --fxos 2.6.1.131\n \n--OS\n To obtain version information regarding the different Network Operating Systems.\n Examples:\n >> openVulnQuery --OS asa\n >> openVulnQuery --OS ios\n \n--platform\n To obtain platform alias information regarding the different Network Operating Systems.\n Examples:\n >> openVulnQuery --platform asa\n >> openVulnQuery --platform nxos \n```\n\n**NOTE**: Cisco reserves the right to remove End-of-Support releases from the Cisco Software Checker (subsequently reflected in this API).\n\n\n## Client Application (Optional)\n\n```\n--user-agent APPLICATION\n Name of application to be sent as User-Agent header value in the request.\n Default is TestApp.\n```\n\n## Parsing Fields (Optional)\n\nNotes:\n\nIf no fields are passed in the default API fields will be returned\n\nAny field that has no information will return with with the field name and NA\n\n### Available Fields\n\n- advisory_id\n- sir\n- first_published\n- last_updated\n- cves\n- bug_ids\n- cvss_base_score\n- advisory_title\n- publication_url\n- cwe\n- product_names\n- summary\n- vuln_title\n- cvrf_url\n- csafUrl\n\n**NOTE**: [CSAF](https://csaf.io) 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 \n\n```\n-f or --fields\n\n API Fields\n Examples:\n openVulnQuery --config PathToCredentialsFile --any API filter -f or --fields list of fields separated by space\n >> openVulnQuery --config PathToCredentialsFile --all -f sir cves cvrf_url\n >> openVulnQuery --config PathToCredentialsFile --severity critical -f last_updated cves\n\n CVRF XML Fields\n Examples:\n openVulnQuery --config PathToCredentialsFile --any API filter -f or --fields list of fields separated by space\n >> openVulnQuery --config PathToCredentialsFile --all -f bug_ids vuln_title product_names\n >> openVulnQuery --config PathToCredentialsFile --severity critical -f bug_ids summary\n\n Combination\n Examples:\n openVulnQuery --config PathToCredentialsFile --any API filter -f or --fields list of fields separated by space\n >> openVulnQuery --config PathToCredentialsFile --all -f sir bug_ids cves vuln_title\n >> openVulnQuery --config PathToCredentialsFile --year 2011 -f cves cvrf_url bug_ids summary product_names\n```\n\n### Additional Filters\n\nUser 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.\n\n```\n>> # export CLIENT_ID and CLIENT_SECRET or write to config.py ... then:\n>> openVulnQuery --severity high --last_updated 2016-01-02:2016-04-02 --json filename.json\n>> openVulnQuery --all --last_updated 2016-01-02:2016-07-02\n>> openVulnQuery --severity critical --first_published 2015-01-02:2015-01-04\n```\n\n## Output Format (Optional)\n\n```\nDefault\n Table style printed to screen\n Example:\n >> openVulnQuery --config PathToCredentialsFile --year 2016\n\n--json file path\n Returns json in a file in the specified path\n Example:\n >> openVulnQuery --config PathToCredentialsFile --year 2016 --json /Users/bkorabik/Documents/2016_cvrf.json\n\n--csv file path\n Creates a CSV file in the specified path\n Example:\n >> openVulnQuery --config PathToCredentialsFile --year 2016 --csv /Users/bkorabik/Documents/2016_cvrf.csv\n```\n\n## Count (Optional)\n\nReturns the count of fields entered with -f or --fields. If no fields are entered the base API fields are counted and displayed\n\n```\n-c\n\n Examples:\n >> openVulnQuery --config PathToCredentialsFile --year 2016 -c\n >> # export CLIENT_ID and CLIENT_SECRET or write to config.py ... then:\n >> openVulnQuery --severity low -f sir cves bug_ids -c\n```\n\n## Developers\n\n- Update the config.py file with client id and secret\n- Directly interact with query_client.py to query the Open Vuln API\n- query_client.py returns Advisory Object\n- advisory.py module has Advisory object a abstract class\n- 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.\n\n## Disclosures:\n\nNo support for filtering based on --API fields, you can't use --year 2016 and --severity high\n\nFiltering with Grep:\n\n```\nFinding the Number of CVRF Advisories with a \"Critical\" sir in 2013\n>> openVulnQuery --config PathToCredentialsFile --year 2013 -f sir | grep -c \"Critical\"\n>> openVulnQuery --config PathToCredentialsFile --severity critical -f first_published | grep -c \"2013\"\n```\n\nIf more than one API filter is entered, the last filter will be used for the API call.\n\nYou can alternatively use the date range functionality, as shown below:\n\n```\n>> openVulnQuery --config PathToCredentialsFile --severity critical --first_published 2017-01-02:2017-10-01\n```\n\n## Run OpenVulnQuery as a Library\n\nAfter 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.\n\n```\n>> from openVulnQuery import query_client\n>> query_client = query_client.OpenVulnQueryClient(client_id=\"\", client_secret=\"\")\n>> advisories = query_client.get_by_year(year=2010, adv_format='default')\n>> advisories = query_client.get_by_ios_xe('ios', '3.16.1S')\n```\n\nIf you want to use the additional date filters based on first published and last updated date. You can pass the appropriate class\n\n```\n>> advisories = query_client.get_by_severity(adv_format='cvrf', severity='high', FirstPublished(2016-01-01, 2016-02-02))\n```\n\n### Debugging Requests and Responses\n\nIf 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.\n\nThe file names follow the pattern: `ts-{ts}_id-{id}_snapshot-of-{kind}.json`, where:\n\n- `{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,\n- `{id}` is a string holding a UUID4 generated for the request and useful to correlate request and response data files\n- `{kind}` is one of three strings speaking for themselves:\n\n - `request`\n - `response-raw`\n - `response-formated`\n\nThe 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).\n\n_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.\n\nHere are the information stored in advisory object.\n\n### Advisory\n\n```\n * advisory_id\n * sir\n * first_published\n * last_updated\n * cves\n * bug_ids\n * cvss_base_score\n * advisory_title\n * publication_url\n * cwe\n * product_names\n * summary\n```\n\n### CVRF (inherits Advisory Abstract Class)\n\n```\n * cvrf_url\n * vuln_title\n```\n\n\n\nAfter 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.\n\n```\n>> from openVulnQuery import query_client\n>> query_client = query_client.OpenVulnQueryClient(client_id='', client_secret='')\n>> advisories = query_client.get_by_year(year=2010, adv_format='default')\n```\n\nHere are the information stored in advisory object.\n\n### Advisory (Abstract Base Class)\n\n```\n * advisory_id\n * sir\n * first_published\n * last_updated\n * cves\n * bug_ids\n * cvss_base_score\n * advisory_title\n * publication_url\n * cwe\n * product_names\n * summary\n```\n\n### CVRF\n\n```\n * cvrf_url\n```\n\n### AdvisoryIOS\n\n```\n * ios_release\n * first_fixed\n * cvrf_url\n```\n\n### Running the tests\n\nTo run the tests in the tests folder, the additional required `mock` module should be installed inside the `venv`with the usual:\n\n```\npip3 install mock pytest\n```\n\nThere 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.\n\nSample run (expecting `pytest` has been installed e.g. via `pip3 install pytest`):\n\n```\n$ cd /www/github.com/CiscoPSIRT/openVulnAPI/openVulnQuery\n\n$ pytest\n=========================================================================================================== test session starts ============================================================================================================\nplatform darwin -- pytest-3.1.2, py-1.4.34, pluggy-0.4.0\nrootdir: /www/github.com/CiscoPSIRT/openVulnAPI/openVulnQuery, inifile:\nplugins: cov-2.5.1\ncollected 159 items\n\ntests/test_advisory.py ......................\ntests/test_authorization.py ...\ntests/test_cli_api.py ..............................................\ntests/test_config.py ....\ntests/test_constants.py ...........\ntests/test_main.py ...........................s......\ntests/test_query_client.py ................\ntests/test_query_client_cvrf.py ssssssss\ntests/test_utils.py ...............\n\n================================================================================================== 150 passed, 9 skipped in 1.16 seconds ===================================================================================================\n```\n\nIncluding coverage info (requires `pip install pytest-cov` which includes `pip install coverage` ):\n\n```\n$ pytest --cov=openVulnQuery --cov-report=term-missing --cov-report=html\n=========================================================================================================== test session starts ============================================================================================================\nplatform darwin -- pytest-3.1.2, py-1.4.34, pluggy-0.4.0\nrootdir: /www/github.com/CiscoPSIRT/openVulnAPI/openVulnQuery, inifile:\nplugins: cov-2.5.1\ncollected 159 items\n\ntests/test_advisory.py ......................\ntests/test_authorization.py ...\ntests/test_cli_api.py ..............................................\ntests/test_config.py ....\ntests/test_constants.py ...........\ntests/test_main.py ...........................s......\ntests/test_query_client.py ................\ntests/test_query_client_cvrf.py ssssssss\ntests/test_utils.py ...............\n\n---------- coverage: platform darwin, python 2.7.13-final-0 ----------\nName Stmts Miss Cover Missing\n--------------------------------------------------------------\nopenVulnQuery/__init__.py 0 0 100%\nopenVulnQuery/advisory.py 90 1 99% 59\nopenVulnQuery/authorization.py 6 0 100%\nopenVulnQuery/cli_api.py 75 4 95% 294-297, 311\nopenVulnQuery/config.py 4 0 100%\nopenVulnQuery/constants.py 11 0 100%\nopenVulnQuery/main.py 38 6 84% 57, 60-65, 70\nopenVulnQuery/query_client.py 100 16 84% 128-134, 148-155, 160-167\nopenVulnQuery/rest_api.py 3 0 100%\nopenVulnQuery/utils.py 76 12 84% 109, 118-129\n--------------------------------------------------------------\nTOTAL 403 39 90%\nCoverage HTML written to dir htmlcov\n\n\n================================================================================================== 150 passed, 9 skipped in 1.60 seconds ===================================================================================================\n```",
"bugtrack_url": null,
"license": "The MIT License (MIT)",
"summary": "A python-based module(s) to query the Cisco PSIRT openVuln API.",
"version": "1.34",
"project_urls": {
"Homepage": "https://github.com/CiscoPSIRT/openVulnQuery"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6fb118d1b4089fa1c30acc8d7809b98c44604b0c11b75b889e9b48b1d625b679",
"md5": "f129b5507b7e3fe9a45237369fc2f0a5",
"sha256": "6d7728719667b2314b4a9ab9638899bdccaae497cac79d71f42fb7a3bb39fbac"
},
"downloads": -1,
"filename": "OpenVulnQuery-1.34.tar.gz",
"has_sig": false,
"md5_digest": "f129b5507b7e3fe9a45237369fc2f0a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19861,
"upload_time": "2023-08-06T03:17:21",
"upload_time_iso_8601": "2023-08-06T03:17:21.932579Z",
"url": "https://files.pythonhosted.org/packages/6f/b1/18d1b4089fa1c30acc8d7809b98c44604b0c11b75b889e9b48b1d625b679/OpenVulnQuery-1.34.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-06 03:17:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CiscoPSIRT",
"github_project": "openVulnQuery",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openvulnquery"
}
JSON
