Red Hat Security Data API
API ドキュメント
secalert@redhat.com
概要
第1章 概要
Red Hat Product Security チームは、お客様がセキュリティーの脅威をより深く理解できるように、ツールやセキュリティーデータの提供に取り組んでいます。このようなデータは セキュリティーデータ ページで提供されてきましたが、今後は Security Data API を使用して、マシンで利用できる形式での提供も開始します。お客様は、このツールを使用することで、プログラム的に API にクエリーを実行して、これまではセキュリティーデータページのファイルからしか公開されていなかったデータを入手できるようになります。
セキュリティーデータ API によって提供されるデータは、セキュリティーデータページ (Common Security Advisory Framework (CSAF) ドキュメント、OVAL v2 (OVAL ストリーム)、および CVE データ) にあるデータと同じです。API を使用して、JSON または XML 形式でデータを取得できます。
こちらの作業は、お客様に使いやすい形式でセキュリティーデータを提供するために Red Hat Product Security チームが行っている取り組みの一部です。
注記: 保守のあるバージョンは 1 つだけで、変更点に関してはすべてドキュメントに記載される予定です。
Security Data API は、情報や計測用に提供されています。API または、API が提供するデータに関する質問や懸念については、Red Hat Product Security にお問い合わせください。
ベース URL
https://access.redhat.com/hydra/rest/securitydata
サポート対象の形式
この API は JSON、XML、および HTML 形式をサポートします。形式については、.json または .xml などの URL への拡張として指定できます。
非推奨のお知らせ
Common Vulnerability Reporting Framework (CVRF) 形式は非推奨となり、サポートされなくなりました。CVRF の互換性 FAQ を参照してください。この形式のユーザーは、Common Security Advisory Framework (CSAF) 形式に移行する必要があります。
OVAL v1 ファイルは非推奨となり、使用できなくなりました。詳細は 、OVAL v1 の非推奨のお知らせを 参照してください。この形式のユーザーは、OVAL v2 (OVAL ストリーム) に移行する必要があります。
第2章 CSAF
2.1. 全 CSAF の一覧表示
概要
パラメーターが指定されていない場合に、コンテンツの概要と合わせて、最新の全 CSAF ドキュメントへのインデックスを提供します。最小限の属性を含めて、便利なオブジェクトを応答として返します。
Red Hat Errata (RHSA、RHBA、および RHEA) の詳細は、Explaining Red Hat Errata を参照してください。
JSON
GET /csaf.json
XML
GET /csaf.xml
HTML
GET /csaf
2.2. パラメーター
| 名前 | 説明 | 例 |
|---|---|---|
| before | クエリーの日付より前の CSAF ドキュメントのインデックス [ISO 8601 が想定される形式です] | 2016-03-01 |
| after | クエリーの日付以降の CSAF ドキュメントのインデックス [ISO 8601 が想定される形式です] | 2016-02-01 |
| rhsa_ids | 指定した RHSA_ID (コンマ区切り) の CSAF ドキュメントのインデックス | RHSA-2018:2748,RHSA-2018:2791 |
| bug | Bugzilla Id の CSAF ドキュメントのインデックス | 1326598,1084875 |
| cve | 指定した CVE の CSAF ドキュメントのインデックス | CVE-2014-0160,CVE-2016-3990 |
| severity | 指定した重大度の CSAF ドキュメントのインデックス | low,moderate,important,critical |
| package | パッケージに影響する CSAF ドキュメントのインデックス | samba,thunderbird |
| page | 指定したページ数の CSAF ドキュメントのインデックス | デフォルト: 1 |
| per_page | 1 ページで返す CSAF ドキュメントのインデックス数 | デフォルト: 1000 |
| created_days_ago | 指定した日数より前に作成された CSAF ドキュメントのインデックス | 10 |
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.
上記のクエリーパラメーターはすべて、必要な結果を取得するために相互に組み合わせて使用できます。
2.3. CSAF の取得
概要
RHSA に関する CSAF の詳細です。
JSON
CSAF ドキュメントは JSON 形式です。XML ビューは、CSAF データを XML 形式で表現したものです。
GET /csaf/<RHSA_ID>.json
XML
GET /csaf/<RHSA_ID>.xml
注記:
Common Security Advisory Framework (CSAF) の JSON 形式は OASIS によって定義されています。GitHub リポジトリーについては ここ を、スキーマについては ここ を参照してください。
Red Hat が提供する CSAF/VEX データの詳細は、https://www.redhat.com/en/blog/csaf-vex-documents-now-generally-availableを参照してください。
クエリー URL のサンプル
https://access.redhat.com/hydra/rest/securitydata/securitydata/csaf
https://access.redhat.com/hydra/rest/securitydata/securitydata/csaf.xml
https://access.redhat.com/hydra/rest/securitydata/securitydata/csaf.json
https://access.redhat.com/hydra/rest/securitydata/csaf.json?after=2023-09-01
https://access.redhat.com/hydra/rest/securitydata/csaf.json?created_days_ago=10
https://access.redhat.com/hydra/rest/securitydata/csaf.json?cve=CVE-2023-1829,CVE-2023-3090,CVE-2023-3390
https://access.redhat.com/hydra/rest/securitydata/csaf.json?rhsa_ids=RHSA-2022:6155,RHSA-2023:2378
https://access.redhat.com/hydra/rest/securitydata/csaf.json?bug=2053532,2153399
https://access.redhat.com/hydra/rest/securitydata/csaf.json?severity=important&created_days_ago=30
https://access.redhat.com/hydra/rest/securitydata/csaf.json?package=thunderbird
https://access.redhat.com/hydra/rest/securitydata/csaf/RHSA-2022:6155
https://access.redhat.com/hydra/rest/securitydata/csaf/RHSA-2022:6155.xml
https://access.redhat.com/hydra/rest/securitydata/csaf/RHSA-2022:6155.json
第3章 CVE
3.1. 全 CVE のリスト表示
概要
パラメーターが指定されていない場合には、最近の CVE をすべてリスト表示します。応答として、最小限の属性を含めて、便利なオブジェクトを返します。
JSON
GET /cve.json
XML
GET /cve.xml
HTML
GET /cve
3.2. パラメーター
| 名前 | 説明 | 例 |
|---|---|---|
| before | クエリーの日付より前の CVE [ISO 8601 が想定される形式です] | 2016-03-01 |
| after | クエリーの日付以降の CVE [ISO 8601 が想定される形式です] | 2016-02-01 |
| ids | 指定した ID (コンマ区切り) の CVE | CVE-2017-8797,CVE-2014-0161 |
| bug | Bugzilla Id の CVE | 1326598,1084875 |
| advisory | アドバイザリーの CVE | RHSA-2016:0614,RHSA-2016:0610 |
| severity | 重大度の CVE | low,moderate,important |
| package | パッケージに影響する CVE | samba,thunderbird |
| product | 製品に影響する CVE。このパラメーターは、Perl と互換性のある正規表現をサポートします。 | Linux 7,openstack |
| cwe | CWE を含む CVE | 295,300 |
| cvss_score | CVSS スコアがこの値以上の CVE | 7.0 |
| cvss3_score | CVSSv3 スコアがこの値以上の CVE | 7.0 |
| page | 指定のページ番号に含まれる CVE | デフォルト: 1 |
| per_page | ページごとに返す CVE の数 | デフォルト: 1000 |
| created_days_ago | 指定した日数より前に作成された CVE 定義のインデックス | 10 |
| include_package_state | package_state 情報のある CVE | true, false |
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.
上記のクエリーパラメーターはすべて、必要な結果を取得するために相互に組み合わせて使用できます。
3.3. CVE の取得
概要
CVE の全詳細を取得します。
パス
GET /cve/<CVE>.json
例: /cve/CVE-2016-3706.json
CVE-2016-3706 の CVE データを JSON 表現で返します。
3.4. CVE 形式
概要
CSAF や OVAL とは異なり、CVE 表現は標準ではありません。次に、存在する可能性のあるフィールド、その意味について説明します。
| 名前 | 説明 | 追加情報 |
|---|---|---|
| ThreatSeverity | 不具合の重大度。 | 詳細は、本書 を参照してください。 |
| PublicDate | 不具合が公開されたタイミング。 | ISO 8601 形式。 |
| Bugzilla | Red Hat の Bugzilla のバグの ID、URL、および説明。 | |
| CVSS | CVSSv2 スコアおよびメトリック。 | 'status' 属性の許容値は draft または verified です。これは、不具合の調査の進捗を表します。詳細は、本書 を参照してください。 |
| CVSS3 | CVSSv3 スコアおよびメトリック。 | 'status' 属性の許容値は draft または verified です。これは、不具合の調査の進捗を表します。詳細は、本書 を参照してください。 |
| CWE | この不具合の CWE チェーン。 | mitre.org の説明と possible cwe values のリストを参照してください。 |
| Details | 不具合の詳細 (情報源は Red Hat または Mitre など)。 | |
| Statement | この問題についての Red Hat からの説明。 | |
| References | 問題に関する詳細情報へのリンク。 | |
| Acknowledgements | 謝辞を送る人または組織。 | |
| Mitigation | ソフトウェアを更新せずに問題を修正または軽減する方法。 | |
| AffectedRelease | 特定の製品の不具合を修正するための、リリース済みのエラータ。 | 製品名と CPE、および エラータのリンク、タイプ、リリース日が含まれます。オプションとして、問題を修正する src.rpm の名前およびバージョンが記載されたパッケージ情報が含まれます (複数の src.rpms が同じエンティティーにある場合はこれはありません)。 |
| PackageState | 現在修正がまだリリースされていないパッケージ/製品に関する情報 | プロダクト名と CPE、パッケージ (src.rpm) 名、および修正の状態が含まれます。これは ['Affected','Fix deferred','New','Not affected','Will not fix'] のいずれかです。 |
| UpstreamFix | 不具合を修正するアップストリームプロジェクトのバージョン。 |
第4章 OVALSTREAMS
4.1. OVAL ストリームの一覧表示
概要
ダウンロードできるすべての OVAL ストリームファイルのインデックスを提供します。パラメーターが渡されない場合は、すべての OVAL ストリームファイルのリストを返します。
JSON
GET oval/ovalstreams.json
XML
GET oval/ovalstreams.xml
HTML
GET oval/ovalstreams
4.2. パラメーター
| 名前 | 説明 | 例 |
|---|---|---|
| after | クエリー日以降に変更した OVAL ストリームファイルのインデックス。想定される形式は ISO 8601 です。 | 2016-02-01 |
| label | 製品バージョンラベルの OVAL ストリームファイルのインデックス。 | jboss-eap-6 |
By default, returned results are ordered by date.
上記のクエリーパラメーターはすべて、必要な結果を取得するために相互に組み合わせて使用できます。
4.3. OVAL ストリームの取得
概要
ベース名で識別される製品の OVAL ストリームデータを返します。
JSON
OVAL ストリームファイルは XML 形式で、JSON ビューは JSON 形式の OVAL データ表現です。
GET oval/ovalstreams/<BASE>.json
例: oval/ovalstreams/RHEL7.json
Red Hat Enterprise Linux 7 の OVAL ストリームの JSON 表現を返します。
XML
GET oval/ovalstreams/<BASE>.xml
OVAL 形式の詳細は FAQ を参照してください。
第5章 スクリプトの例
#!/usr/bin/env python
import sys
import requests
from datetime import datetime, timedelta
API_HOST = 'https://access.redhat.com/hydra/rest/securitydata'
PROXIES = {}
# uncomment lines below to specify proxy server
# HTTPS_PROXY = "http://yourproxy.example.com:8000"
# PROXIES = { "https" : HTTPS_PROXY }
def get_data(query):
full_query = API_HOST + query
r = requests.get(full_query, proxies=PROXIES)
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-2022:1988
endpoint = '/cve.json'
params = 'advisory=RHSA-2022:1988'
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 = '/csaf.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 = '/csaf/'
for advisory in kernel_advisories:
data = get_data(endpoint + advisory + '.json')
print(advisory)
for product_branch in data['product_tree']['branches']:
for inner_branch in product_branch['branches'][0]['branches']:
print('-', inner_branch['name'])