目次

サービスAPIとの統合

Application Security は、特定の管理タスクをCI / CDパイプラインなどの一部として自動化できるサービスAPIを提供します。

提供されるAPIを使用すると、次のことを実行できます。

  1. 特定のアカウントのアクティブなグループのリストを受信します。
  2. グループの保護の種類の設定をアップデートします。
  3. 指定したグループの保護の種類のポリシーをアップデートします。

いずれかのAPIエンドポイントを使用する場合は、次の2つの点を考慮する必要があります。

  1. APIコールの認証と承認。
  2. APIエンドポイントのバージョン管理。

API呼び出しの認証と承認

APIキーは Cloud One アカウント管理で管理されます。 APIキーの管理方法を学ぶ

APIのバージョン管理

APIは時間とともに進化すると予想されます。APIエンドポイントと統合する場合は、エンドポイントごとにバージョンを指定できます。コンテンツネゴシエーション時にバージョンが指定されている場合、エンドポイントは、サポートされている有効なバージョンであれば、指定されたバージョンを優先します。バージョンが指定されていない場合、エンドポイントは最新バージョンを使用して要求を処理します。

Application Security APIは、 api-version バージョンヘッダを使用しません。

Accept ヘッダと選択したバージョンでバージョンを指定します。

application/json; version=<version>

たとえば、次のとおりです。

application/json; version=1

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <Your API Key>
Accept: application/json; version=2
...

バージョンがacceptヘッダに指定されていない場合は、最新のAPIバージョンが使用されます。応答のContent-Typeは、API応答に関連付けられたバージョンを示します。

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <Your API Key>
Accept: application/json
...
-----------------------------------
HTTP/2 200
Content-Type: application/json; version=2

Application Security APIを使用する

ベースURL

特定のリージョンでApplication Security APIに接続して使用するためのベースURLは、次のとおりです。

https://application.<region>.cloudone.trendmicro.com

たとえば、米国のリージョンに接続するためのベースURLは次のようになります。 https://application.us-1.cloudone.trendmicro.com

エンドポイントの呼び出しはすべて、このベースURLを使用して実行されます。

グループリスト

すべてのグループは、 Application Security ダッシュボードで作成され、初期設定されます。詳細については、「 Group の追加」を参照してください。

グループを作成したら、次のエンドポイントを使用してアカウント内のアクティブなグループのリストを取得できます。

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <Your api_key>
Accept: application json

------------------------------------------------------

200 Ok
Content-Type: application/json; version=2
[
  {
    "account_id": "576dcc26-0c47-4d00-8b7d-a4a261d6afa5",
    "activated_on": "2019-04-10T17:38:26.880743+00:00",
    "group_id": "c24af1c0-bb76-40be-9e15-264e77d43739",
    "name": "group 1 name",
    "status": "active"
  },
  {
    "account_id": "576dcc26-0c47-4d00-8b7d-a4a261d6afa5",
    "activated_on": "2019-09-24T16:17:40.608811+00:00",
    "group_id": "e72e24da-db1c-447f-af63-01c1da2533d0",
    "name": "group 2 name",
    "status": "active"
  },
]

保護設定を取得してアップデートする

保護設定は、特定のグループに対して有効にする保護の種類、および検出されたポリシー違反を軽減するかレポートのみかを制御します。

ポリシー設定を取得するには、次の手順に従います。

GET /accounts/groups/<group id:uuid>/settings HTTP/1.1
Authorization: ApiKey <Your api_key>
Accept: application/json

<----------------------------------------------------->\

200 Ok
Content-Type: application/json; version=2
 {
   "rce": "report",
   "file_access": "disable",
   "malicious_payload": "mitigate",
   "malicious_file_upload": "report",
   "redirect": "report",
   "sqli": "report"
 }

保護の種類は、無効、レポート、または軽減のいずれかで設定できます。指定されたIDのグループが存在しない場合、API呼び出しは「404 Not Found」を返します。

保護設定は次のように更新できます。

PUT /accounts/groups/<group id:uuid>/settings
Authorization: ApiKey <Your api_key>
Content-Type: application/json; version=2
Content-Length: <length>

{
 "rce": "report",
 "file_access": "report",
 "malicious_file_upload": "mitigate",
 "malicious_payload": "report",
 "redirect": "report",
 "sqli": "report"
}

<----------------------------------------------->

204 No Content

指定されたIDのグループが見つからない場合、API呼び出しは「404 Not Found」を返します。

保護ポリシーの取得とアップデート

保護ポリシーには、保護の種類ごとに次のものが含まれます。

  • 適用するセキュリティアルゴリズム
  • セキュリティアルゴリズムのステータス
  • セキュリティアルゴリズムに関連付けられたルール(該当する場合)

セキュリティアルゴリズムは各保護の種類に固有です。次の表に、許可されるアルゴリズム名を示します。

保護ポリシー 保護ポリシーの構文 セキュリティアルゴリズム
SQL Injection 「sqli」

「always_false」

「always_true」

「bad_function」

「http_params」

「stacking_queries」

「syntax_error」

「trailing_comment」

「union_set」

Malicious Payload 「malicious_payload」 「malicious_pattern_match」
Illegal File Access 「file_access」

「read_control」

「write_control」

Open Redirect 「redirect」 「redirect_control」
Remote Command Execution 「rce」

「exec_control」

「http_params」

Malicious File Upload 「malicious_file_upload」

「av_scanning」

「size_check」

セキュリティアルゴリズムのステータスは、次のいずれかの値になります。

Status Description
「enabled」 セキュリティアルゴリズムが有効で、適用されています。
「disabled」 セキュリティアルゴリズムは無効で、適用されていません。

セキュリティアルゴリズムに関連付けられたルールおよびルール構文は、各保護の種類に固有です。次の表は、各保護の種類の形式を示しています。

保護ポリシー 保護ポリシーの構文 保護ポリシーの構文 備考
SQL Injection 「sqli」 アルゴリズムはルールを必要としません。
Malicious Payload 「malicious_payload」 「patterns」:

[

{

"cves":["CVE-ID"]、

"cvss_score": "5.0"、

"description":

"id":<ルールid>、

"name":<パターン名>、

「status」:「enabled」

},

{

"cves":["CVE-ID"]、

"cvss_score": "10.0"、

"description":

"id":<ルールid>、

"name":<パターン名>、

「enabled」:「enabled」

},

....

]

ルールはトレンドマイクロが設計および管理します。ポリシーエンドポイントによって提供されるルール、ID、および説明は、サポートされるルールのサブセットである必要があります。存在しないIDを使用してルールを更新しようとすると失敗します。同様に、ルールのステータス属性のみを「有効」または「無効」のいずれかの値に更新できます。名前などの他の属性を更新しようとしても効果はありません。
ファイルアクセス 「file_access」 "rules":[

{"action": "allow"、

"glob": "*。[eE][rR][bB]"

},

{"action": "allow"、

"glob": "*。[hH][aA][mM][lL]"

},

{"action": "allow"、

"glob": "*。[pP][hH][pP]"

},

...

]

処理は、「allow」または「block」の2つの値のいずれかになります。

「glob」属性の値は、PCREに準拠した表現である必要があります。

Open Redirect 「redirect」

"rules":[

{"action": "block"、

"glob": "*"

},

...

]

処理は、「allow」または「block」の2つの値のいずれかになります。

「glob」属性の値は、PCREに準拠した表現である必要があります。

Remote Command Execution 「rce」

"rules":[

{"action": "block"、

"command": ".*"

}

]

処理は、「allow」または「block」の2つの値のいずれかになります。

「command」属性の値はglob形式です。

Malicious File Upload 「malicious_file_upload」

"av_scanning":

"buffered_scanning_max_bytes":<バイト数:int>

"size_check":

"max_bytes":<バイト数:int>

Malicious Payload以外のすべての保護ポリシーでは、ポリシーを取得および更新するためのペイロード構文は対称です。 Malicious Payload ポリシーをアップデートする場合は、パターン内の idstatus のみが使用されます。これは、 id がルールの識別に必要であり、「status」のみをアップデートできるためです。名前やCVEなどの他の属性は無視されます。

すべての保護の種類のポリシーの一般的な構文は次のとおりです。

{
  <algorithm 1 name>:
   "configuration": {
     <algorithm rules syntax>
   },
   "status": "enabled" or "disabled"
  },
  <algorithm 2 name>: {
     "configuration": {
        <algorithm rules syntax>\
     },
     "status": "enabled" or "disabled"
    }
  }

SQL Injection ポリシー:

{
    "always_false": {
        "configuration": {},
        "status": "enabled"
    },
    "always_true": {
        "configuration": {},
        "status": "enabled"
    },
    "bad_function": {
        "configuration": {},
        "status": "enabled"
    },
    "http_params": {
        "configuration": {},
        "status": "enabled"
    },
    "stacking_queries": {
        "configuration": {},
        "status": "enabled"
    },
    "syntax_error": {
        "configuration": {},
        "status": "disabled"
    },
    "trailing_comment": {
        "configuration": {},
        "status": "enabled"
    },
    "union_set": {
        "configuration": {},
        "status": "enabled"
    }
}

Illegal File Access ポリシーのペイロード:

{
    "read_control": {
        "configuration": {
            "rules": [
                {
                    "action": "allow",
                    "glob": "*.[jJ][pP][gG]"
                },
                {
                    "action": "allow",
                    "glob": "/etc/mime.types"
                },
                {
                    "action": "block",
                    "glob": "/etc/*"
                },
            ]
        },
        "status": "enabled"
    },
    "write_control": {
        "configuration": {
            "rules": [
                {
                    "action": "block",
                    "glob": "/etc/*"
                },
                {
                    "action": "block",
                    "glob": "/proc/*"
                },
                {
                    "action": "allow",
                    "glob": "*"
                }
            ]
        },
        "status": "enabled"
    }
}

前述のように、 Malicious Payload ポリシーの場合、ポリシー取得時のポリシー構文にはすべての属性が含まれますが、ポリシーのアップデート時には idstatus のみが含まれます。たとえば、次のとおりです。

Getting policy
---------------
{
  "malicious_pattern_match": {
     "configuration": {
        "patterns": [
           {
             "cves": ["CVE-2007-1560"],
             "cvss_score": "5.0",
             "description": "The vulnerability is caused due to an error within the processing of TRACE requests in
             squid/src/client_side.c. This can be exploited to crash the service via a specially crafted TRACE request.",
             "id": 1000978,
             "name": "Squid Proxy TRACE Request DoS",
             "status": "enabled"
           },
           {
             "cves": ["CVE-2002-1654"],
             "cvss_score": "7.5",
             "description": "This rule blocks brute force attempt to web application by inspecting the number of error responses in
             a given time period. The IP address is blocked for 20 minutes after the brute force attempt is detected.\n\nNote:
             Configuration option should be used to enter custom error response.",
             "id": 1005208,
             "name": "Web Application Possible Brute Force Attempt (ATT&CK T1110)",
             "status": "enabled"
           }
         ]
     },
     "status": "enabled"
  }
}

Updating policy
----------------
{
  "malicious_pattern_match": {
     "configuration": {
        "patterns": [
           {
             "id": 1000978,
             "status": "enabled"
           },
           {
             "id": 1005208,
             "status": "disabled"
           }
         ]
     },
     "status": "enabled"
  }
}

特定の保護の種類と特定のグループのポリシーを取得します。

GET /security/<protection type>/<group id:uuid>/policy HTTP/1.1
Authorization: ApiKey <api_key>
Accept: application/json

<---------------------------------------------->

200 Ok
Content-Type: application/json; version=2
{
  <algorithm 1 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  },
  <algorithm 2 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  }
}

GET API呼び出しは、保護の種類に応じてペイロードの内容を含む「200 Ok」を返します。 group_id が存在しない場合は、404コードが返されます。

保護の種類のアップデートポリシー:

PUT /security/<protection type>/<group id:uuid>/policy HTTP/1.1
Content-Type: application/json; version=2
Content-Length: <length>
Authorization: ApiKey <Your api_key>

{
  <algorithm 1 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  },
  <algorithm 2 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  }
}

<------------------------------------------>

204 No Content

ポリシーをアップデートする際のペイロードの実際の構造は、保護の種類によって異なります。 group_id が存在しない場合、エンドポイントコールは404を返します。