2017-11-21 07:50 PM 2017-11-22 12:07 AM 更新
APIをご利用いただくことで、ご利用者様側でご用意いただいている独自のApplicationの一部として、
AMP Cloudをご利用いただくことも可能です。
本ドキュメントでは、AMP APIの実行までの流れと、簡単なサンプルを案内させていただきます。
・AMP for Endpoints Console v5.4.2017110822
Accounts > API Credentials
APIクレデンシャルの画面にて[New API Credential]をクリックします。
[Create]をクリックすると[3rd Party API Client ID]と[API Key]が発行され、以下のような画面が表示されます。
注意:
[API Key]はこの画面で表示される以外で、確認できる手段はございません。
このため、[API Key]は必ず控えていただき、適切な管理の元でご利用ください。
APIクレデンシャルの作成が正常に終了すると、一覧に表示されるようになります。
API実行に際しては、まずはAPIドキュメントをご参照ください。
APIバージョンは現在2種類ありますが、主な差分は実装されているAPIの数となりますため、特別な理由が無い限りはv1をご利用いただければと存じます。
まずここでは、サンプルとして、Event一覧を取得するAPI(GET /v1/event_types)を紹介させていただきます。
APIドキュメントにもある通り、リクエストヘッダには以下を指定することができます。
*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" } ] }
次に、上述のEvent一覧を取得するAPI(GET /v1/event_types)から取得したEvent IDを用いて、実際のEventを取得する方法を紹介させていただきます。
この場合には、GET /v1/eventsを用います。
APIドキュメントにもある通り、リクエストヘッダには以下を指定することができます。
また、この一方で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 |
$ 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からでフィルタをかけた場合は以下のように見えます。
検索バーにキーワード、フレーズ、または質問を入力し、お探しのものを見つけましょう
シスコ コミュニティをいち早く使いこなしていただけるよう役立つリンクをまとめました。みなさんのジャーニーがより良いものとなるようお手伝いします