Red Hat Security Data API

Red Hat Security Data API 0.1

API Documentation

Red Hat Product Security

Abstract

The Red Hat Security Data API exposes a list of endpoints to query security data with certain parameters and retrieve CVRF, CVE and OVAL data easily.

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: At this time, the API is in beta and may change at any time without warning. 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.

Note

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

NameDescriptionExample

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.
Note

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
Note

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
Note

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

NameDescriptionExample

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.
Note

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.

NameDescriptionAdditional 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.

Note

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

NameDescriptionExample

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.
Note

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
Note

For more information about the OVAL format see the FAQ.

Chapter 5. IAVA

5.1. List all IAVAs

Abstract

List all the Red Hat IAVAs when no parameter is passed. Returns an object as response with Title, Severity and CVElist.

JSON

GET /iava.json

XML

GET /iava.xml

HTML

GET /iava

5.2. Parameters

NameDescriptionExample

number

IAVAs for number

2016-A-0353

severity

IAVAs for severity

CAT I, CAT II

title

IAVAs for title

Multiple Security Vulnerabilities in ImageMagick

cvelist

IAVAs for cvelist

CVE-2016-9559

page

IAVAs for page number

Default: 1

per_page

Number of IAVAs to return per page

Default: 1000

By default, search will return the first page of 1000 results. To change the page size use the 'per_page' param, and then iterate through pages using the 'page' param.
Note

All the above query parameters can be used in combination with each other to retrieve the desired result.

5.3. Retrieve a IAVA

Abstract

Retrieve full IAVA details.

JSON

GET /iava/<IAVA>.json

Example: /iava/2016-A-0353.json

Returns a JSON representation of the IAVA data for 2016-A-0353.

XML

GET /iava/<IAVA>.xml

Chapter 6. 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']))