キャンセル
次の結果を表示 
次の代わりに検索 
もしかして: 
cancel
1900
閲覧回数
5
いいね!
0
コメント
Yuji Suzuki
Cisco Employee
Cisco Employee

 

はじめに

Cisco AMP for Endpointsでは、APIを用意しております。

APIをご利用いただくことで、ご利用者様側でご用意いただいている独自のApplicationの一部として、
AMP Cloudをご利用いただくことも可能です。

本ドキュメントでは、AMP APIの実行までの流れと、簡単なサンプルを案内させていただきます。

 

前提条件

本記事の記述内容は、以下の環境で確認をしております。バージョンアップに伴う仕様変更によって将来的に変更される場合もございますので、あらかじめご了承ください。

・AMP for Endpoints Console v5.4.2017110822

 

1.APIクレデンシャルの作成

Consoleにログイン後、以下の画面を表示させます。

Accounts > API Credentials

api-credential.png

APIクレデンシャルの画面にて[New API Credential]をクリックします。

  • [Application name] : APIを使うアプリケーション名を指定します。APIクレデンシャルを識別するためのものなので、特別な制約はございません。
  • [Scope] : APIクレデンシャルの権限を指定します。[Read & Write]を指定する場合は、Console(Policy等)への更新も可能となるため、ご利用および管理には十分にご注意ください。

new-credential.png

 

 

[Create]をクリックすると[3rd Party API Client ID]と[API Key]が発行され、以下のような画面が表示されます。

注意:

[API Key]はこの画面で表示される以外で、確認できる手段はございません。
このため、[API Key]は必ず控えていただき、適切な管理の元でご利用ください。

keys.png

 

APIクレデンシャルの作成が正常に終了すると、一覧に表示されるようになります。
after.png

 

2.APIの実行例(GET /v1/event_types)

API実行に際しては、まずはAPIドキュメントをご参照ください。

APIバージョンは現在2種類ありますが、主な差分は実装されているAPIの数となりますため、特別な理由が無い限りはv1をご利用いただければと存じます。

まずここでは、サンプルとして、Event一覧を取得するAPI(GET /v1/event_types)を紹介させていただきます。

APIドキュメントにもある通り、リクエストヘッダには以下を指定することができます。

  • accept: application/json
  • content-type: application/json
  • authorization: Basic FILTERED(*1)

*1 : [3rd Party API Client ID]:[API Key]をBase64エンコードした値。[3rd Party API Client ID]が'clientid', [API Key]が'apikey'の場合は'Y2xpZW50aWQ6YXBpa2V5'となります

以下は実行例となります。

$ curl -X GET \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'authorization: Basic Y2xpZW50aWQ6YXBpa2V5' \
'https://api.apjc.amp.cisco.com/v1/event_types'

また、cURLではauthorizationヘッダの代わりに-uオプションを利用することもできます。

$ curl -X GET \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-u 'clientid:apikey' \
'https://api.apjc.amp.cisco.com/v1/event_types'

認証に成功し、AMP APIとの疎通性があれば、以下のような応答が得られるはずです。

{"version":"v1.2.0","metadata":{"links":{"self":"https://api.apjc.amp.cisco.com/v1/event_types"},"results":{"total":92}},"data":[{"id":1090519084,"name":"DFC Threat Detected","description":"A connection has been detected by DFC."},(中略){"id":553648197,"name":"All Faults Cleared","description":"All faults have been cleared"}]}

成型すると、以下のとおり、Consoleで検知しているイベントの一覧が取得できていることがわかります。

{
    "version": "v1.2.0",
    "metadata": {
        "links": {
            "self": "https://api.apjc.amp.cisco.com/v1/event_types"
        },
        "results": {
            "total": 92
        }
    },
    "data": [
        {
            "id": 1090519084,
            "name": "DFC Threat Detected",
            "description": "A connection has been detected by DFC."
        },
======================中略======================
       {
            "id": 553648197,
            "name": "All Faults Cleared",
            "description": "All faults have been cleared"
        }
    ]
}

 

3.APIの実行例(GET /v1/events)

次に、上述のEvent一覧を取得するAPI(GET /v1/event_types)から取得したEvent IDを用いて、実際のEventを取得する方法を紹介させていただきます。

この場合には、GET /v1/eventsを用います。

APIドキュメントにもある通り、リクエストヘッダには以下を指定することができます。

  • accept: application/json
  • content-type: application/json
  • authorization: Basic FILTERED

また、この一方でQuery Parameterでは以下を指定することができます。

Name Type Example Values
limit Integer 2, 1, 10
detection_sha256 String f8a6a244138cb1e2f044f63f3dc42beeb555da892bbd7a121274498cbdfc9ad5
application_sha256 String 80ef843fa78c33b511394a9c7535a9cbace1deb2270e86ee4ad2faffa5b1e7d2
connector_guid[] GUID af73d9d5-ddc5-4c93-9c6d-d5e6b5c5eb01
group_guid[] GUID b077d6bc-bbdf-42f7-8838-a06053fbd98a
start_date String (Time ISO8601) 2015-10-01T00:00:00+00:00
offset Integer 10
event_type[] Array 1090519054, 1090519084

 

  • Event Id=1090519054、"Threat Detected" 
  • Event Id=2164260910、"File Fetch Failed" 
    例えば上記のEvent IDをクエリ条件として指定したい場合は、以下のような実行方法となります。
$  curl -X GET -H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'authorization: Basic Y2xpZW50aWQ6YXBpa2V5' \
'https://api.apjc.amp.cisco.com/v1/events?event_type\[\]=1090519054&event_type\[\]=2164260910'

※ cURLを使う都合上、'['と']'はエスケープ('\')しております。
その他REST Client等を使う場合は不要なときもありますため、エスケープ用の'\'は適宜読み捨ててご利用ください。

成功すれば実行結果として、以下のような情報が得られるはずです。

{
    "version": "v1.2.0",
    "metadata": {
        "links": {
            "self": "https://api.apjc.amp.cisco.com/v1/events?event_type[]=1090519054&event_type[]=2164260910",
            "next": "https://api.apjc.amp.cisco.com/v1/events?event_type%5B%5D=1090519054&event_type%5B%5D=2164260910&offset=500"
        },
        "results": {
            "total": 1520,
            "current_item_count": 500,
            "index": 0,
            "items_per_page": 500
        }
    },
    "data": [
        {
            "id": 6490710008286674951,
            "timestamp": 1511236189,
            "timestamp_nanoseconds": 214000000,
            "date": "2017-11-21T03:49:49+00:00",
            "event_type": "File Fetch Failed",
            "event_type_id": 2164260910,
            "group_guids": [
                "XXXXXXXX-XXXX-XXXX-XXXX-1dfa6efbd67b"
            ],
            "error": {
                "error_code": 3240099848,
                "description": "File not found"
            },
            "computer": {
                "connector_guid": "XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3",
                "hostname": "XXXXXXXXX",
                "external_ip": "X.X.X.X",
                "active": true,
                "network_addresses": [
                    {
                        "ip": "X.X.X.X",
                        "mac": "XX:XX:XX:XX:XX:XX"
                    }
                ],
                "links": {
                    "computer": "https://api.apjc.amp.cisco.com/v1/computers/"XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3",
                    "trajectory": "https://api.apjc.amp.cisco.com/v1/computers/"XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3/trajectory",
                    "group": "https://api.apjc.amp.cisco.com/v1/groups/XXXXXXXX-XXXX-XXXX-XXXX-1dfa6efbd67b"
                }
            },
            "file": {
                "disposition": "Unknown",
                "file_name": "setup.exe",
                "file_path": "\\\\?\\C:\\Users\\cisco\\AppData\\Local\\Temp\\7zS489A.tmp\\setup.exe",
                "identity": {
                    "sha256": "03ca0179caa9d524ab0f7152bf88aaf851f9382f07911f3425c03f4a92f5a24d"
                }
            }
        },
        {
            "id": 6490710003991707654,
            "timestamp": 1511236188,
            "timestamp_nanoseconds": 902000000,
            "date": "2017-11-21T03:49:48+00:00",
            "event_type": "File Fetch Failed",
            "event_type_id": 2164260910,
            "group_guids": [
                "XXXXXXXX-XXXX-XXXX-XXXX-1dfa6efbd67b"
            ],
            "error": {
                "error_code": 3240099848,
                "description": "File not found"
            },
            "computer": {
                "connector_guid": "XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3",
                "hostname": "XXXXXXXXX",
                "external_ip": "X.X.X.X",
                "active": true,
                "network_addresses": [
                    {
                        "ip": "X.X.X.X",
                        "mac": "XX:XX:XX:XX:XX:XX"
                    }
                ],
                "links": {
                    "computer": "https://api.apjc.amp.cisco.com/v1/computers/"XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3",
                    "trajectory": "https://api.apjc.amp.cisco.com/v1/computers/"XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3/trajectory",
                    "group": "https://api.apjc.amp.cisco.com/v1/groups/XXXXXXXX-XXXX-XXXX-XXXX-1dfa6efbd67b"
                }
            },
            "file": {
                "disposition": "Unknown",
                "file_name": "setup-stub.exe",
                "file_path": "\\\\?\\C:\\Users\\cisco\\AppData\\Local\\Temp\\7zS1EDC.tmp\\setup-stub.exe",
                "identity": {
                    "sha256": "7fb44beff5a513655019e97d333fc470c0fb0861ad80e9395bd5350daea8b262"
                }
            }
        },
        {
            "id": 6490345498707230724,
            "timestamp": 1511151320,
            "timestamp_nanoseconds": 974000000,
            "date": "2017-11-20T04:15:20+00:00",
            "event_type": "Threat Detected",
            "event_type_id": 1090519054,
            "detection": "W32.3E1813DA2D.Gen.A",
            "detection_id": "6490345498707230721",
            "group_guids": [
                "XXXXXXXX-XXXX-XXXX-XXXX-1dfa6efbd67b"
            ],
            "computer": {
                "connector_guid": "XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3",
                "hostname": "XXXXXXXXX",
                "external_ip": "X.X.X.X",
                "active": true,
                "network_addresses": [
                    {
                        "ip": "X.X.X.X",
                        "mac": "XX:XX:XX:XX:XX:XX"
                    }
                ],
                "links": {
                    "computer": "https://api.apjc.amp.cisco.com/v1/computers/"XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3",
                    "trajectory": "https://api.apjc.amp.cisco.com/v1/computers/"XXXXXXX-XXXX-XXXX-XXXX-8d2efbf652d3/trajectory",
                    "group": "https://api.apjc.amp.cisco.com/v1/groups/XXXXXXXX-XXXX-XXXX-XXXX-1dfa6efbd67b"
                }
            },
            "file": {
                "disposition": "Malicious",
                "file_name": "vYvRV5WQ.zip.part",
                "file_path": "\\\\?\\C:\\Users\\cisco\\AppData\\Local\\Temp\\vYvRV5WQ.zip.part",
                "identity": {
                    "sha256": "3e1813da2d561157df7667cde0117fdddd883c5b1272f76d1ae85ad889c38220",
                    "sha1": "5211ac4e7d8459f0db9aa19a03c55cb2063fee5f",
                    "md5": "fce365d60e13df34a6843894ac9be499"
                },
                "parent": {
                    "process_id": 4536,
                    "disposition": "Unknown",
                    "file_name": "firefox.exe",
                    "identity": {
                        "sha256": "04007be6f1e7f1b93f4c840d06fb35fb4224f9d4dc9b76acb9406abf6baa7519",
                        "sha1": "4f16bf6ee2804d020343a2edf079311fdf28b443",
                        "md5": "bfe1bfd65b75d4a804e201b8697b579d"
                    }
                }
            }
        },
======================中略======================

 

なお、AMP Consoleからでフィルタをかけた場合は以下のように見えます。

events.png

 

≡ 

Getting Started

検索バーにキーワード、フレーズ、または質問を入力し、お探しのものを見つけましょう

シスコ コミュニティをいち早く使いこなしていただけるよう役立つリンクをまとめました。みなさんのジャーニーがより良いものとなるようお手伝いします