Гэты артыкул будзе карысны тым, хто знаёмы з тэхналогіямі Пункт кантролю па эмуляцыі файлаў (Threat Emulation) і проактивной ачыстцы файлаў (Threat Extraction) і жадае зрабіць крок у бок аўтаматызацыі дадзеных задач. У Check Point ёсць , які працуе як у воблаку , так і на лакальных прыладах, і функцыянальна ён ідэнтычны праверцы файлаў у струменях web/smtp/ftp/smb/nfs трафіку. Дадзены артыкул збольшага з'яўляецца аўтарскай трактоўкай набору артыкулаў з афіцыйнай дакументацыі, але пабудаваны на сваім досведзе эксплуатацыі і на ўласных прыкладах. Таксама ў артыкуле вы знойдзеце аўтарскія калекцыі Postman для працы з Threat Prevention API.
Асноўныя скарачэнні
Threat Prevention API працуе з трыма асноўнымі кампанентамі, якія ў API выклікаюцца праз наступныя тэкставыя значэнні:
av - кампанент Anti-Virus, адказвае за сігнатурны аналіз вядомых пагроз.
te - кампанент Threat Emulation, адказвае за праверку файлаў у пясочніцы, і вынясенне вердыкта шкодны (malicious) / чысты (benign) пасля эмуляцыі.
здабыча - кампанент Threat Extraction, які адказвае за хуткую канвертаванне офісных дакументаў у бяспечны выгляд (у якім выдаляецца ўвесь патэнцыйна шкоднасны кантэнт), у мэтах іх хуткай дастаўкі карыстальнікам / сістэмам.
Структура API і асноўныя абмежаванні
Threat Prevention API выкарыстоўвае ўсяго 4 запыты upload, query, download і quota. У загалоўку для ўсіх чатырох запытаў трэба перадаць API ключ, выкарыстоўваючы параметр аўтарызацыя. На першы погляд, структура можа здацца значна прасцей, чым у , Але колькасць палёў у запытах upload і query і структура гэтых запытаў дастаткова комплексныя. Іх можна функцыянальна параўнаць з профілямі Threat Prevention у палітыцы бяспекі шлюза/пясочніцы.
На дадзены момант, выпушчана адзіная версія Threat Prevention API - 1.0, у URL для API выклікаў варта паказваць v1 у той частцы, дзе патрабуецца пазначыць версію. У адрозненні ад Management API, паказваць версію API у URL адрасе абавязкова, інакш запыт не выканаецца.
Кампанент Anti-Virus пры выкліку без іншых кампанентаў (te, extraction) на дадзены момант падтрымлівае толькі запыты query з md5 хэш сумамі. Threat Emulation і Threat Extraction падтрымлівае таксама sha1 і sha256 хэш сумы.
Вельмі важна не рабіць памылак у запытах! Запыт можа быць выкананы без памылкі, але не поўнасцю. Ледзь забягаючы наперад разгледзім што можа адбывацца пры памылках / памылках друку ў запытах.
Запыт з памылкай друку з слове reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}У адказе памылкі не будзе, але пры гэтым інфармацыі аб справаздачах не будзе зусім
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}А вось на запыт без памылкі друку ў ключы reports
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Мы атрымліваем адказ, у якім ужо змяшчаюцца id для загрузкі справаздач
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
"pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
"xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Калі ж адправіць няправільны/пратэрмінаваны API ключ, то ў адказ атрымаем памылку 403.
SandBlast API: у воблаку і на лакальных прыладах
API запыты можна адпраўляць на прылады Check Point, на якіх уключаны кампанент (blade) Threat Emulation. У якасці адраса для запытаў трэба выкарыстоўваць ip/url прылады і порт 18194 (напрыклад - https://10.10.57.19:18194/tecloud/api/v1/file/query). Таксама трэба пераканацца ў тым, што палітыкай бяспекі на прыладзе дазволена такое падлучэнне. Аўтарызацыя праз API ключ на лакальных прыладах па змаўчанні выключана і ключ Authorization у загалоўках запытаў можна не адпраўляць зусім.
API запыты ў воблака CheckPoint трэба адпраўляць на адрас te.checkpoint.com (напрыклад - https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можна атрымаць у выглядзе трыяльнай ліцэнзіі на 60 дзён, звярнуўшыся да партнёраў Check Point ці ў лакальны офіс кампаніі.
На лакальных прыладах Threat Extraction пакуль не падтрымліваецца ў стандартным і трэба выкарыстоўваць (пра яго мы пагаворым падрабязней у канцы артыкула).
Лакальныя прылады не падтрымліваюць запыт quota.
У астатнім адрозненняў паміж запытамі да лакальных прылад і да воблака няма.
Выклік Upload API
Выкарыстоўваны метад - POST
Адрас для выкліку https:///tecloud/api/v1/file/upload
Запыт складаецца з двух частак (form-data): файла прызначаны для эмуляцыі/ачысткі і целы запыту з тэкстам.
Тэкставы запыт не можа быць пустым, але пры гэтым можа не змяшчаць ніякай канфігурацыі. Для таго, каб запыт быў паспяховым, трэба адправіць мінімум наступны тэкст у запыце:
Неабходны мінімум для запыту upload
HTTP POST
https:///tecloud/api/v1/file/upload
Загалоўкі:
аўтарызацыя:
Цела
{
"request": {
}
}
Размовы
Размовы
У такім выпадку файл на апрацоўку патрапіць у адпаведнасці з параметрамі па змаўчанні: кампанент te, вобразы АС - Win XP і Win 7, без генерацыі справаздачы.
Каментары па асноўных палях у тэкставым запыце:
імя файла и file_type можна пакінуць пустымі ці не адпраўляць зусім, бо гэта не асоба карысная інфармацыя пры загрузцы файла. У API адказе дадзеныя палі запоўняцца аўтаматычна на аснове імя загружанага файла, а інфармацыю ў кэшы ўсё роўна прыйдзецца шукаць па md5/sha1/sha256 hash сумам.
Прыклад запыту з пустымі file_name і file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}Асаблівасці - Спіс, у якім паказваецца неабходны функцыянал пры апрацоўцы ў пясочніцы - av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Калі дадзены параметр не перадаць зусім, тое будзе задзейнічаны толькі кампанент па змаўчанні - te(Threat Emulation).
Каб уключыць праверку ў трох даступных кампанентах, трэба пазначыць гэтыя кампаненты ў API запыце.
Прыклад запыту з праверкай у av, te і extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Ключы ў раздзеле te
малюнкаў - спіс, унутры якога павінны быць указаны слоўнікі з id і нумарам рэвізіі аперацыйных сістэм, у якіх будзе выконвацца праверка. ID і нумары рэвізій аднолькавыя для ўсіх лакальных прылад і аблокі.
Спіс аперацыйных сістэм і рэвізій
Available OS Image ID
Перагляд
Image OS and Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP - 32bit SP3
Офіс:: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 and ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 - 32bit
Офіс:: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (убудова& ActiveX)
Java Runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 - 32bit
Офіс:: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (убудова & ActiveX)
Java Runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 - 32bit
Офіс:: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (убудова & ActiveX)
Java Runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 - 64bit
Офіс:: 2013 (32bit)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (убудова & ActiveX)
Java Runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 - 64bit
Офіс:: 2013 (64bit)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (убудова & ActiveX)
Java Runtime: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Офіс:: Professional Plus 2016 en-us
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (убудова & ActiveX)
Java Runtime: 1.7.0u9
Калі ключ images не паказаць зусім, то эмуляцыя будзе праходзіць у выявах, рэкамендаваных Check Point (на дадзены момант гэта Win XP і Win 7). Дадзеныя выявы рэкамендаваны зыходзячы з меркаванняў найлепшага балансу прадукцыйнасці і catch rate.
справаздачы - Спіс справаздач, якія мы запытваем на выпадак, калі файл апынецца шкоднасным. Даступныя наступныя варыянты:
-
рэзюмэ - .tar.gz архіў, які змяшчае ў сабе справаздачу аб эмуляцыі па ўсім запытаным image'ам (як html старонку, так і такія кампаненты як відэаролік з АС эмулятара, дамп сеткавага трафіку, справаздача ў json, так і сам сэмпл у архіве пад абаронай пароля). У адказе шукаем ключ - summary_report для наступнай загрузкі справаздачы.
-
PDF - Дакумент аб эмуляцыі ў адным image, які многія прывыклі атрымліваць праз Smart Console. У адказе шукаем ключ - pdf_report для наступнай загрузкі справаздачы.
-
XML - Дакумент аб эмуляцыі ў адным image, зручны для наступнага парсінгу параметраў у справаздачы. У адказе шукаем ключ - xml_report для наступнай загрузкі справаздачы.
-
дзёгаць - .tar.gz архіў, які змяшчае ў сабе справаздачу аб эмуляцыі ў адным запытаным image'ам (як html старонку, так і такія кампаненты як відэаролік з АС эмулятара, дамп сеткавага трафіку, справаздача ў json, так і сам сэмпл у архіве пад абаронай пароля). У адказе шукаем ключ - full_report для наступнай загрузкі справаздачы.
Што ўнутры справаздачы summary
Ключы full_report, pdf_report, xml_report ёсць у слоўніку для кожнай АС
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicious",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "found",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}А вось ключ summary_report - ёсць адзін для эмуляцыі ў цэлым
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicious",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "found",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Можна запытаць адначасова справаздачы tar і xml і pdf, можна summary і tar і xml. Адначасова запытаць summary справаздачу і pdf не атрымаецца.
Ключы ў раздзеле extraction
Для threat extraction выкарыстоўваецца ўсяго два ключы:
метад - pdf (канвертацыя ў pdf, выкарыстоўваецца па змаўчанні) або clean (ачыстка актыўнага змесціва).
extracted_parts_codes - спіс кодаў для выдалення актыўнага змесціва, дастасавальна толькі для метаду clean
Коды для выдалення змесціва з файлаў
код
Апісанне
1025
Linked Objects
1026
Macros and Code
1034
Sensitive Hyperlinks
1137
PDF GoToR Actions
1139
PDF Launch Actions
1141
PDF URI Actions
1142
PDF Sound Actions
1143
PDF Movie Actions
1150
PDF JavaScript Actions
1151
PDF Submit Form Actions
1018
Запыты да базы дадзеных
1019
Убудаваныя аб'екты
1021
Fast Save Data
1017
Карыстальніцкія ўласцівасці
1036
Statistic Properties
1037
Summary Properties
Для загрузкі вычышчанай копіі запатрабуецца зрабіць яшчэ і запыт query (пра яго пайдзе прамову далей) праз некалькі секунд, паказаўшы hash суму файла і кампанент extraction у тэксце запыту. Забраць вычышчаны файл можна будзе з дапамогай id з адказу на запыт query - extracted_file_download_id. Яшчэ раз, ледзь забягаючы наперад, прыводжу прыклады запыту і адказу query для пошуку id на загрузку вычышчанага дакумента.
Запыт query для пошуку ключа extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Адказ на запыт query (знайдзіце ключ extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extraction"
],
"extraction": {
"method": "pdf",
"extract_result": "CP_EXTRACT_RESULT_SUCCESS",
"extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"time": "0.013",
"extract_content": "Macros and Code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potential malicious content extracted",
"protection_type": "Conversion to PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Active content was found - XLS file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros and Code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Агульныя звесткі
У адным выкліку API можна адправіць толькі адзін файл на праверку.
Кампанент av не патрабуе дадатковай часткі з ключамі, дастаткова паказаць яго ў слоўніку Асаблівасці.
Выклік Query API
Выкарыстоўваны метад - POST
Адрас для выкліку https:///tecloud/api/v1/file/query
Перад тым як адпраўляць файл на загрузку (запыт upload), пажадана выканаць праверку кэша пясочніцы (запыт query) у мэтах аптымізацыі нагрузкі на API сервер, бо магчыма на API серверы ўжо ёсць інфармацыя і вердыкт па загружаным файле. Выклік складаецца толькі з тэкставай часткі. Абавязковая частка запыту - sha1/sha256/md5 hash сума файла. Яе дарэчы можна атрымаць у адказе на запыт upload.
Неабходны мінімум для запыту query
HTTP POST
https:///tecloud/api/v1/file/query
Загалоўкі:
аўтарызацыя:
Цела
{
"request": {
"sha256":
}
}
Прыклад адказу на запыт upload, дзе бачныя sha1/md5/sha256 hash сумы
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "The file was uploaded successfully."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "The file was uploaded successfully."
}
}
}
}Запыт query апроч hash сумы ў ідэале павінен быць такім жа, як быў (ці плануецца быць) запыт upload, ці нават «ужо» (утрымоўваць у запыце query менш палёў чым у запыце upload). У выпадку, калі запыт query утрымоўвае ў сабе больш палёў, чым было ў запыце upload, вы атрымаеце ў адказе не ўсю патрабаваную інфармацыю.
Вось прыклад адказу на запыт query, дзе былі знойдзеныя не ўсе запатрабаваныя дадзеныя
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "The request cannot be fully answered at this time."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}Звярніце ўвагу на палі код и этыкетка. Дадзеныя палі сустракаюцца тры разы ў слоўніках status. Спачатку бачым глабальны ключ "code": 1006 і "label": "PARTIALLY_FOUND". Далей дадзеныя ключы сустракаюцца па кожным асобным кампаненце, якія мы запыталі - te і extraction. І калі для te зразумела, што дадзеныя знойдзены, то для extraction інфармацыя адсутнічае.
Вось так выглядаў запыт query для прыкладу вышэй
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Калі адправіць запыт query без кампанента extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}То і ў адказе будзе поўная інфармацыя (code: 1001, label: FOUND)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Калі ніякай інфармацыі ў кэшы няма зусім, то ў адказе будзе "label": "NOT_FOUND"
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}У адным API выкліку можна адправіць адразу некалькі хэш сум на праверку. У адказе будуць вернуты дадзеныя ў тым жа самым парадку, як яны былі адпраўленыя ў запыце.
Прыклад запыту query з некалькімі sha256 сумамі
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Адказ на запыт query з некалькімі sha256 сумамі
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}Запыт адразу некалькіх hash суму ў запыце query таксама спрыяльна адаб'ецца на прадукцыйнасці API сервера.
Выклік Download API
Выкарыстоўваны метад - POST (згодна з дакументацыяй), GET таксама працуе (і можа здацца больш лагічным)
Адрас для выкліку https:///tecloud/api/v1/file/download?id=
У загалоўку патрабуецца перадаць API ключ, цела запыту - пустое, id для загрузкі перадаецца ў url адрасе.
У адказ на query запыт, у выпадку, калі эмуляцыя завершана і пры загрузцы файла былі запытаны справаздачы, будуць бачныя id для загрузкі справаздач. У выпадку, калі запытваецца вычышчаная копія, тое варта шукаць id для загрузкі вычышчанага дакумента.
Разам, ключамі ў адказе на запыт query, утрымоўвальнымі значэнне id для загрузкі могуць быць:
-
summary_report
-
full_report
-
pdf_report
-
xml_report
-
extracted_file_download_id
Безумоўна, каб у адказе на запыт query былі атрымана гэтыя ключы, іх трэба пазначыць у запыце (для справаздач) ці не забыцца зрабіць запыт па функцыі extraction (для вычышчаных дакументаў)
Выклік Quota API
Выкарыстоўваны метад - POST
Адрас для выкліку https:///tecloud/api/v1/file/quota
Для праверкі пакінутай квоты ў воблаку выкарыстоўваецца запыт quota. Цела запыту пустое.
Прыклад адказу на запыт quota
{
"response": [
{
"remain_quota_hour": 1250,
"remain_quota_month": 10000000,
"assigned_quota_hour": 1250,
"assigned_quota_month": 10000000,
"hourly_quota_next_reset": "1599141600",
"monthly_quota_next_reset": "1601510400",
"quota_id": "TEST",
"cloud_monthly_quota_period_start": "1421712300",
"cloud_monthly_quota_usage_for_this_gw": 0,
"cloud_hourly_quota_usage_for_this_gw": 0,
"cloud_monthly_quota_usage_for_quota_id": 0,
"cloud_hourly_quota_usage_for_quota_id": 0,
"monthly_exceeded_quota": 0,
"hourly_exceeded_quota": 0,
"cloud_quota_max_allow_to_exceed_percentage": 1000,
"pod_time_gmt": "1599138715",
"quota_expiration": "0",
"action": "ALLOW"
}
]
}Threat Prevention API for Security Gateway
Дадзены API быў распрацаваны раней, чым Threat Prevention API і прызначаны толькі для лакальных прылад. На дадзены момант ён можа быць карысны толькі ў тым выпадку, калі вам патрэбен Threat Extraction API. Для Threat Emulation лепш выкарыстоўваць звычайны Threat Prevention API. Каб уключыць TP API for SG і сканфігураваць API ключ патрабуецца выканаць дзеянні з . Рэкамендую звярнуць увагу на крок 6b і праверыць даступнасць старонкі https://<IPAddressofSecurityGateway>/UserCheck/TPAPI таму што ў выпадку адмоўнага выніку далейшая канфігурацыя не мае сэнсу. На дадзены url будуць адпраўляцца ўсе выклікі API. Тып выкліку (upload/query) рэгулюецца ў ключы цела выкліку request_name. Таксама абавязковымі ключамі з'яўляюцца - api_key (трэба запомніць яго ў працэсе канфігурацыі) і protocol_version (на дадзены момант актуальная версія 1.1). Афіцыйную дакументацыю для дадзенага API вы можаце знайсці ў . Да адносных пераваг можна аднесці магчымасць адпраўляць адразу некалькі файлаў на эмуляцыю пры іх загрузцы, бо файлы адпраўляюцца ў выглядзе тэкставага радка base64. Каб кадзіраваць/дэкадаваць файлы ў/з base64 можна выкарыстоўваць для мэт дэманстрацыі ў Postman онлайн канвэртар, напрыклад — . У практычных мэтах пры напісанні кода варта выкарыстоўваць убудаваныя метады encode і decode.
Цяпер спынімся падрабязней на функцыях te и здабыча у дадзеным API.
Для кампанента te прадугледжаны слоўнік te_options у запытах upload/query, а ключы ў дадзеным запыце цалкам супадаюць з ключамі te у .
Прыклад запыту для эмуляцыі файла ў Win10 са справаздачамі
{
"request": [{
"protocol_version": "1.1",
"api_key": "<api_key>",
"request_name": "UploadFile",
"file_enc_data": "<base64_encoded_file>",
"file_orig_name": "<filename>",
"te_options": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": ["summary", "xml"]
}
}
]
}Для кампанента здабыча прадугледжаны слоўнік scrub_options. У дадзеным запыце паказваецца метад ачысткі: канвертаванне ў PDF, ачыстка ад актыўнага змесціва ці ж абраць рэжым у адпаведнасці з профілем Threat Prevention (паказваецца імя профіля). Адметнай асаблівасцю адказу на API запыт з extraction для файла з'яўляецца тое, што вы атрымліваеце вычышчаную копію ў адказе на гэты запыт у выглядзе шыфраванага радка base64 (вам не трэба рабіць запыт query і шукаць id для загрузкі дакумента)
Прыклад запыту на ачыстку файла
{
"request": [{
"protocol_version": "1.1",
"api_key": "<API_KEY>",
"request_name": "UploadFile",
"file_enc_data": "<base64_encoded_file>",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Адказ на запыт
{
"response": [{
"protocol_version": "1.1",
"src_ip": "<IP_ADDRESS>",
"scrub": {
"file_enc_data": "<base64_encoded_converted_to_PDF_file>",
"input_real_extension": "js",
"message": "OK",
"orig_file_url": "",
"output_file_name": "hi.cleaned.pdf",
"protection_name": "Extract potentially malicious content",
"protection_type": "Conversion to PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Нягледзячы на тое, што для атрымання вычышчанай копіі патрабуецца менш API запытаў, я лічу такі варыянт менш пераважным і зручным, чым запыт form-data, выкарыстоўваны ў .
Калекцыі Postman
Мною былі створаны калекцыі ў Postman як для Threat Prevention API, так і для Threat Prevention API for Security Gateway, дзе прадстаўлены найболей распаўсюджаныя API запыты. Для таго, каб ip/url API сервера і ключ падстаўляліся ў запыты аўтаматычна, а hash сума sha256 пасля загрузкі файла таксама запаміналася, усярэдзіне калекцый створаны тры зменныя(знайсці іх можна пяройдучы ў наладах калекцыі Edit -> Variables): te_api(патрабуецца запоўніць), api_key(патрабуецца запоўніць, акрамя выпадку выкарыстання TP API з лакальнымі прыладамі), sha256 (пакінуць пустым, у TP API for SG не выкарыстоўваецца).
прыклады выкарыстання
У супольнасці прадстаўлены скрыпты, напісаныя на Python, якія правяраюць файлы з патрэбнай дырэкторыі як праз , так і . Праз узаемадзеянне з Threat Prevention API вашы магчымасці па праверцы файлаў значна пашыраюцца, бо зараз вы можаце правяраць файлы адразу ў некалькіх платформах (цікавым выглядае праверка ў , а затым у пясочніцы Check Point), а файлы атрымліваць не толькі з сеткавага трафіку, але і забіраць іх з любых сеткавых дыскаў і, напрыклад, CRM сістэм.
Крыніца: habr.com