Red Hat Security Data API
API Documentation
Abstract
Chapter 1. Overview
Red Hat Product Security is committed to providing tools and security data to help you better understand security threats. This data has been available on our Security Data page and will now also be available in a machine-consumable format with the Security Data API. This tool will allow customers to programmatically query the API for data that was previously exposed only through files on our Security Data page.
The data provided by the Security Data API is the same as what is found on the Security Data page: OVAL definitions, Common Vulnerability Reporting Framework (CVRF) documents and CVE data. All data is available in its native XML format or in a representative JSON format.
This effort is a part of Red Hat Product Security’s commitment to providing security data to customers in an easy-to-use format.
Please Note: Only one version will be maintained and any changes will be noted in the documentation.
The Security Data API is provided for information and metrics purposes. For any questions or concerns with the API or the data it provides, please contact Red Hat Product Security.
Base URL
https://access.redhat.com/labs/securitydataapi
Supported Formats
The API supports JSON, XML, and HTML formats. The format can be specified as an extension to the url like .json or .xml. If no format is specified, the default HTML format will be rendered.
Chapter 2. CVRF
2.1. List all CVRFs
Abstract
Provides an index to all recent CVRF documents with a summary of their contents, when no parameter is passed. Returns a convenience object as the response with minimal attributes.
It does not return an index of published RHSAs as not all RHSA errata have a corresponding CVRF document.
JSON
GET /cvrf.json
XML
GET /cvrf.xml
HTML
GET /cvrf
2.2. Parameters
| Name | Description | Example |
|---|---|---|
| before | Index of CVRF documents before the query date. [ISO 8601 is the expected format] | 2016-03-01 |
| after | Index of CVRF documents after the query date. [ISO 8601 is the expected format] | 2016-02-01 |
| bug | Index of CVRF documents for Bugzilla Ids | 1326598,1084875 |
| cve | Index of CVRF documents for CVEs | CVE-2014-0160,CVE-2016-3990 |
| severity | Index of CVRF documents for severity | low,moderate,important,critical |
| package | Index of CVRF documents which affect package | samba,thunderbird |
| page | Index of CVRF documents for page number | Default: 1 |
| per_page | Number of index of CVRF documents to return per page | Default: 1000 |
By default, search will return the first page of 1000 results, ordered by date. To change the page size use the 'per_page' param, and then iterate through pages using the 'page' param.
All the above query parameters can be used in combination with each other to retrieve the desired result.
2.3. Retrieve a CVRF
Abstract
CVRF details for the RHSA.
JSON
CVRF documents are in XML format, the JSON view is a representation of the CVRF data in JSON format.
GET /cvrf/<RHSA_ID>.json
XML
GET /cvrf/<RHSA_ID>.xml
For more information about the CVRF format see the FAQ.
2.4. Oval
Abstract
OVAL details for the RHSA.
JSON
OVAL documents are in XML format, the JSON view is a representation of the OVAL data in JSON format.
GET /cvrf/<RHSA_ID>/oval.json
Example: /cvrf/RHSA-2016:0685/oval.json
Returns a JSON representation of the OVAL data for RHSA-2016:0685.
XML
GET /cvrf/<RHSA_ID>/oval.xml
For more information about the OVAL format see the FAQ.
Chapter 3. CVE
3.1. List all CVEs
Abstract
List all the recent CVEs when no parameter is passed. Returns a convenience object as response with very minimum attributes.
JSON
GET /cve.json
XML
GET /cve.xml
HTML
GET /cve
3.2. Parameters
| Name | Description | Example |
|---|---|---|
| before | CVEs before the query date. [ISO 8601 is the expected format] | 2016-03-01 |
| after | CVEs after the query date. [ISO 8601 is the expected format] | 2016-02-01 |
| bug | CVEs for Bugzilla Ids | 1326598,1084875 |
| advisory | CVEs for advisory | RHSA-2016:0614,RHSA-2016:0610 |
| severity | CVEs for severity | low,moderate,important |
| package | CVEs which affect the package | samba,thunderbird |
| product | CVEs which affect the product. The parameter supports Perl compatible regular expressions. | linux 7,openstack |
| cwe | CVEs with CWE | 295,300 |
| cvss_score | CVEs with CVSS score greater than or equal to this value | 7.0 |
| cvss3_score | CVEs with CVSSv3 score greater than or equal to this value | 7.0 |
| page | CVEs for page number | Default: 1 |
| per_page | Number of CVEs to return per page | Default: 1000 |
By default, search will return the first page of 1000 results, ordered by date. To change the page size use the 'per_page' param, and then iterate through pages using the 'page' param.
All the above query parameters can be used in combination with each other to retrieve the desired result.
3.3. Retrieve a CVE
Abstract
Retrieve full CVE details.
Path
GET /cve/<CVE>.json
Example: /cve/CVE-2016-3706.json
Returns a JSON representation of the CVE data for CVE-2016-3706.
3.4. CVE format
Abstract
Unlike CVRF or OVAL, the CVE representation is not a standard. Notes on what fields may exist and what they mean follow.
| Name | Description | Additional Information |
|---|---|---|
| ThreatSeverity | The Severity of the flaw. | See this document for more information. |
| PublicDate | When the flaw became public. | ISO 8601 format. |
| Bugzilla | Id, URL, and Description of the bug in Red Hat’s Bugzilla. | |
| CVSS | CVSSv2 score and metrics. | The 'status' attribute may have a value of 'draft' or 'verified', indicating how far along the investigation of the flaw has progressed. See this document for more information. |
| CVSS3 | CVSSv3 score and metrics. | The 'status' attribute may have a value of 'draft' or 'verified', indicating how far along the investigation of the flaw has progressed. See this document for more information. |
| CWE | The CWE chain for this flaw. | See the mitre.org description and our list of possible cwe values. |
| Details | Details about the flaw, possibly from Red Hat or Mitre. | |
| Statement | A statement from Red Hat about the issue. | |
| References | Links to more information about the issue. | |
| Acknowledgements | People or organizations that are being recognized. | |
| Mitigation | A way to fix or reduce the problem without updated software. | |
| AffectedRelease | A released Erratum that fixes the flaw for a particular product. | Contains product name and CPE, and Erratum link, type, and release date. Optionally also includes "Package" information that describes the name and version of the src.rpm that fixes the issue (will not exist if multiple src.rpms are in the same Erratum). |
| PackageState | Information about a package / product where no fix has been released yet. | Contains product name and CPE, package (src.rpm) name, and fix state, which is one of ['Affected','Fix deferred','New','Not affected','Will not fix']. |
| UpstreamFix | The version of the upstream project that fixes the flaw. |
Chapter 4. OVAL
4.1. List all OVALs
Abstract
Provides an index to all recent OVAL definitions with a summary of their contents, when no parameter is passed. Returns a convenience object as the response with minimal attributes.
It does not return an index of published RHSAs as not all RHSA errata have a corresponding OVAL definition.
JSON
GET /oval.json
XML
GET /oval.xml
HTML
GET /oval
4.2. Parameters
| Name | Description | Example |
|---|---|---|
| before | Index of OVAL definitions before the query date. [ISO 8601 is the expected format] | 2016-03-01 |
| after | Index of OVAL definitions after the query date. [ISO 8601 is the expected format] | 2016-02-01 |
| bug | Index of OVAL definitions for Bugzilla Ids | 1326598,1084875 |
| cve | Index of OVAL definitions for CVEs | CVE-2014-0160,CVE-2016-3990 |
| severity | Index of OVAL definitions for severity | low,moderate,important |
| page | Index of OVAL definitions for page number | Default: 1 |
| per_page | Number of index of OVAL definitions to return per page | Default: 1000 |
By default, search will return the first page of 1000 results, ordered by date. To change the page size use the 'per_page' param, and then iterate through pages using the 'page' param.
All the above query parameters can be used in combination with each other to retrieve the desired result.
4.3. Retrieve an OVAL
Abstract
OVAL details for the RHSA.
JSON
OVAL definitions are in XML format, the JSON view is a representation of the OVAL data in JSON format.
GET /oval/<RHSA_ID>.json
Example: /oval/RHSA-2016:0695.json
Returns a JSON representation of the OVAL data for RHSA-2016:0695.
XML
GET /oval/<RHSA_ID>.xml
For more information about the OVAL format see the FAQ.
Chapter 5. Example Script
#!/usr/bin/env python
from __future__ import print_function
import sys
import requests
from datetime import datetime, timedelta
API_HOST = 'https://access.redhat.com/labs/securitydataapi'
def get_data(query):
full_query = API_HOST + query
r = requests.get(full_query)
if r.status_code != 200:
print('ERROR: Invalid request; returned {} for the following '
'query:\n{}'.format(r.status_code, full_query))
sys.exit(1)
if not r.json():
print('No data returned with the following query:')
print(full_query)
sys.exit(0)
return r.json()
# Get a list of issues and their impacts for RHSA-2016:1847
endpoint = '/cve.json'
params = 'advisory=RHSA-2016:1847'
data = get_data(endpoint + '?' + params)
for cve in data:
print(cve['CVE'], cve['severity'])
print('-----')
# Get a list of kernel advisories for the last 30 days and display the
# packages that they provided.
endpoint = '/cvrf.json'
date = datetime.now() - timedelta(days=30)
params = 'package=kernel&after=' + str(date.date())
data = get_data(endpoint + '?' + params)
kernel_advisories = []
for advisory in data:
print(advisory['RHSA'], advisory['severity'], advisory['released_on'])
print('-', '\n- '.join(advisory['released_packages']))
kernel_advisories.append(advisory['RHSA'])
print('-----')
# From the list of advisories saved in the previous example (as
# `kernel_advisories`), get a list of affected products for each advisory.
endpoint = '/cvrf/'
for advisory in kernel_advisories:
data = get_data(endpoint + advisory + '.json')
print(advisory)
product_branch = data['cvrfdoc']['product_tree']['branch']
for product_branch in data['cvrfdoc']['product_tree']['branch']:
if product_branch['type'] == 'Product Family':
if type(product_branch['branch']) is dict:
print('-', product_branch['branch']['full_product_name'])
else:
print('-', '\n- '.join(pr['full_product_name'] for
pr in product_branch['branch']))