Ця стаття буде корисна тим, хто знайомий з технологіями Пункт контролю з емуляції файлів (Емуляція загрози) та проактивного очищення файлів (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, без створення звіту.
Коментарі щодо основних полів у текстовому запиті:
ім'я файлу и тип файлу можна залишити порожніми або не відправляти зовсім, оскільки це не дуже корисна інформація при завантаженні файлу. В 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
Revision
Image OS and Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows,: XP - 32bit SP3
Office: 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
Office: 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
Office: 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
Office: 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
Office: 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
Office: 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
Office: 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
Зв'язані об'єкти
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 для 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