03-6417-9339

平日 9:30 ~ 12:00 / 13:00 ~ 17:30

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)
文字列 ソート対象
warning 要対応
statuses 対応状況
maxsri 最大SRI
maxcvss 最大CVSS
area 影響範囲
exploitable 攻撃コード
hostname ホスト名
categories カテゴリ名
q[prior_category]でsystemが設定されている場合は、ホストのシステムカテゴリ名が対象になります。
customが設定されている場合は、ホストのカスタムカテゴリのうち、昇順で一番先頭になるカテゴリ名が対象になります。
os OS名
duedates 対策予定日設定済(率)
finished 対処率
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 値の記号(文字列)を指定します。
絞り込み可能な記号と値は、下記の通りです。
記号 CVSS値
notreg 未登録
d4 10.0 ~ 9.0
d3 8.9 ~ 7.0
d2 6.9 ~ 4.0
d1 3.9 ~ 0.0
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キーを設定する必要があります。