hosts
SIDfm VM サーバに登録されているホスト一覧を取得するためのエンドポイントです。
ホスト別状況画面のサマリー表に相当するデータを取得します。
エンドポイント | hosts |
機能 | ホスト一覧取得 |
実装バージョン | 2.7.0 |
認証 | 有り |
HTTPメソッド | GET/POST |
パラメータ
入力値 | 機能 | 入力値の型 | デフォルト値 | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
q[api_key] |
パラメータで認証を行う場合に API キーを指定します。 X-API-Key としてリクエストヘッダに API キーを設定した場合は、このパラメータは X-API-Key での認証に失敗した場合にのみ参照されます。 |
String | なし | ||||||||||||||||||||||||
q[offset] | 取得するデータの先頭位置を指定します。 | Number | 0 | ||||||||||||||||||||||||
q[per_page] |
1~200 の値で、1 度に取得するデータの数を指定します。指定した値が 1~200 を超えている場合は 10 として扱われます。 ※全データ数の指定は不可です。 |
Number | 10 | ||||||||||||||||||||||||
q[index] |
対象とする評価指標を指定します。 sri または cvss を指定します。 |
String | sri | ||||||||||||||||||||||||
q[category] |
対象とするカテゴリです。 取得する一覧のデータを、指定したカテゴリのホストに限定します。 |
String | なし | ||||||||||||||||||||||||
q[prior_category] |
ホスト一覧データのカテゴリの並び順に、優先するカテゴリを指定します。 system を指定するとシステムカテゴリを優先し、custom を指定するとカスタムカテゴリを優先します。 |
String | system | ||||||||||||||||||||||||
q[order] |
一覧データのソート順を指定します。
下記の文字列に _asc を付けると昇順、_desc を付けると降順となります。(例: hostname_asc)
|
String | hostname_asc | ||||||||||||||||||||||||
q[filters][warning] | 取得するホストを、warning なら要対応のホストに、others なら要対応以外のホストに絞り込みます。 | String | なし | ||||||||||||||||||||||||
q[filters][products][product_all_version_names] |
SIDfm プロダクト名で、取得するホストを絞り込みます。 指定したプロダクトのいずれかのバージョンが、手動登録プロダクトに設定されているホストに絞り込みます。 複数検索可能です。 この絞り込みは、q[filters][products]* に限り OR 条件で絞り込みを行います。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][products][product_names] |
SIDfm プロダクト名で、取得するホストを絞り込みます。 指定したプロダクトの「全て」が、手動登録プロダクトに設定されているホストに絞り込みます。 複数検索可能です。 この絞り込みは、q[filters][products]* に限り OR 条件で絞り込みを行います。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][products][version_names] |
SIDfm プロダクトのバージョン名で、取得するホストを絞り込みます。 指定したバージョンが、手動登録プロダクトに設定されているホストに絞り込みます。 複数検索可能です。 この絞り込みは、q[filters][products]* に限り OR 条件で絞り込みを行います。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][products][lproduct_all_version_names] |
ローカルプロダクト名で、取得するホストを絞り込みます。 指定したローカルプロダクトのいずれかのバージョンが、手動登録プロダクトに設定されているホストに絞り込みます。 複数検索可能です。 この絞り込みは、q[filters][products]* に限り OR 条件で絞り込みを行います。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][products][lproduct_names] |
ローカルプロダクト名で、取得するホストを絞り込みます。 指定したローカルプロダクトの「全て」が、手動登録プロダクトに設定されているホストに絞り込みます。 複数検索可能です。 この絞り込みは、q[filters][products]* に限り OR 条件で絞り込みを行います。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][products][lversion_names] |
ローカルプロダクトのバージョン名で、取得するホストを絞り込みます。 指定したバージョンが、手動登録プロダクトに設定されているホストに絞り込みます。 複数検索可能です。 この絞り込みは、q[filters][products]* に限り OR 条件で絞り込みを行います。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][status] |
対応状況で、取得するホストを絞り込みます。 配列で複数指定すると、指定したいずれかの対応状況のホストに絞り込みます。 1 つ指定する場合は、文字列でも指定可能です。 絞り込み可能な対応状況は、下記の通りです。
|
String/Array<String> | なし | ||||||||||||||||||||||||
q[filters][sris] |
最大 SRI が、指定した危険度のいずれかであるホストに絞り込みます。複数検索可能です。 絞り込み可能な危険度は、下記の通りです。
|
Array<String> | なし | ||||||||||||||||||||||||
q[filters][cvsses] |
最大 CVSS が、指定した CVSS 値のいずれかであるホストに絞り込みます。複数検索可能です。 絞り込みには、CVSS 値の記号(文字列)を指定します。 絞り込み可能な記号と値は、下記の通りです。
|
Array<String> | なし | ||||||||||||||||||||||||
q[filters][area] |
影響範囲で、取得するホストを絞り込みます。 絞り込み可能な影響範囲は、下記の通りです。
|
String | なし | ||||||||||||||||||||||||
q[filters][exploitable] | true を指定すると、取得するホストを攻撃コードがある脆弱性を有するホストに絞り込みます。 | Boolean | なし | ||||||||||||||||||||||||
q[filters][categories][names] |
カテゴリ名で、取得するホストを絞り込みます。 指定したカテゴリのいずれかが設定されているホストに絞り込みます。 q[filters][categories][ids] と併用して絞り込みすることはできません。 |
Array<String> | なし | ||||||||||||||||||||||||
q[filters][categories][ids] |
カテゴリ ID で、取得するホストを絞り込みます。 指定したカテゴリのいずれかが設定されているホストに絞り込みます。 q[filters][categories][names] と併用して絞り込みすることはできません。 |
Array<Number> | なし | ||||||||||||||||||||||||
q[filters][categories][is_and] | true を指定すると、q[filters][categories][names]またはq[filters][categories][ids] での絞り込み時に、指定したカテゴリが全て設定されているホストに絞り込みます。 | Boolean | なし | ||||||||||||||||||||||||
q[filters][categories][is_except] | true を指定すると、q[filters][categories][names]またはq[filters][categories][ids] での絞り込み時に、指定したカテゴリが設定されていないホストに絞り込みます。 | Boolean | なし | ||||||||||||||||||||||||
q[filters][os] |
OS 名で、取得するホストを絞り込みます。 指定した OS のホストに絞り込みます。 |
String | なし | ||||||||||||||||||||||||
q[filters][date_begin] |
ホストの脆弱性の検出日で、取得するホストを絞り込みます。 検出日が指定した日付以降のホストに絞り込みます。(例: 2022/11/01) |
String | なし | ||||||||||||||||||||||||
q[filters][date_end] |
ホストの脆弱性の検出日で、取得するホストを絞り込みます。 検出日が指定した日付以前のホストに絞り込みます。(例: 2022/11/01) |
String | なし | ||||||||||||||||||||||||
q[filters][date_outside_period] | true を指定すると、取得するホストをq[filters][date_begin]またはq[filters][date_end] あるいはその両方で指定した期間外のホストに絞り込みます。 | Boolean | なし | ||||||||||||||||||||||||
q[filters][keyword] | 取得するホストを、指定した文字列がホスト名または表示名に部分一致するホストに絞り込みます。 | String | なし |
レスポンス
key | value の内容 | value の型 |
---|---|---|
success | 認証の成否 | Boolean |
response | エラー等の補足情報 | Hash |
total_size | 取得したホストの数 | Number |
hosts | ホスト一覧 | Array<Hash> |
id | ホストID | Number |
hostname | ホスト名 | String |
ext_name | 表示名 | String/Null |
display_name | 実際に表示に使用される名称 | String |
url | ホスト詳細画面のURL | String |
warning |
要対応 true の場合: 要対応 false の場合: 非要対応 |
Boolean |
min_status | 対応状況 | String |
max_sri | 最大 SRI | String |
max_cvss_score | 最大 CVSS | String/Null |
area | 影響範囲 | String |
exploitable |
攻撃コードの有無 true の場合: 有り false の場合: 無し null の場合: 出力不可 |
Boolean/Null |
categories | ホストのカテゴリ | Array<Hash> |
id | カテゴリ ID | Number |
name | カテゴリ名 | String |
desc | 概要 | String |
hostlim | ホスト登録上限数 | Number/Null |
is_system |
true の場合: システムカテゴリ false の場合: カスタムカテゴリ |
Boolean |
os | OS 名 | String |
duedates_percent | 対策予定日設定済 | String |
finished_percent | 対処率 | String |
レスポンス例
{ "success": true, "response": {}, "total_size": 157, "hosts": [ { "id": 114, "hostname": "sample1", "ext_name": "sample_host", "display_name": "sample_host", "url": "http://example.com/redmine/sidfm/host/114", "warning": true, "min_status": "未対策", "max_sri": "重大", "max_cvss_score": "10.0", "area": "リモート", "exploitable": true, "categories": [ { "id": 1, "name": "公開サーバ", "desc": "信頼できない人間がアクセス可能なネットワークに配置された、信頼できる人間のみがログインできるシステム。 基本的にファイアウォールの外側や DMZ, クラウドにあるサーバシステムを意味します。\n(具体例:公開 Web サーバ、公開 DNS サーバ、公開 SMTP サーバ)", "hostlim": null, "is_system": true }, { "id": 16, "name": "サンプルA", "desc": "カテゴリサンプルA", "hostlim": 10, "is_system": false } ], "os": "PHP 7.3.6", "duedates_percent": "7.5%", "finished_percent": "80.7%" } ] }
サンプルコード
※ 実際にサンプルコードを試す場合は、色のついている箇所をご自身の環境に合わせて変更しご利用ください。
サンプルコードを試す場合、変更箇所の「http(s)://hostname/redmine」は、システム設定の「メール通知設定用のURL」を、「apikey」は、VM
APIキー設定画面で登録済みのAPIキーを設定する必要があります。