Тази статия ще бъде полезна на тези, които са запознати с технологиите Check Point по емулация на файлове (Emulatio на заплахи) и проактивно почистване на файлове (Извлечение на заплахи) и желаят да направят стъпка към автоматизация на тези задачи. Check Point предлага , който работи както в облака, така и на локални устройства, и функционално е идентичен на проверката на файлове в потоковете web/smtp/ftp/smb/nfs трафик. Тази статия отчасти е авторска трактовка на набор от статии от официалната документация, но изградена на собствения опит и примери. В същото време в статията ще намерите авторски колекции Postman за работа с Threat Prevention API.
Основни съкращения
Threat Prevention API работи с три основни компонента, които в API се извикват чрез следните текстови стойности:
av — компонент Anti-Virus, отговарящ за сигнатурния анализ на известни заплахи.
te — компонент Threat Emulation, отговарящ за проверката на файлове в пясъчник и издаването на присъди злонамерен (malicious)/чист (benign) след емулацията.
extraction — компонент Threat Extraction, отговорен за бързата конверсия на офис документи в безопасен вид (от който се премахва целият потенциално вреден съдържащ), с цел бърза доставка на потребителите/системите.
Структура на API-то и основни ограничения
Threat Prevention API използва само 4 заявки — upload, query, download и quota. В заглавието на всички четири заявки трябва да се предаде API ключ, използвайки параметъра Authorization. На пръв поглед структурата може да изглежда много по-проста, отколкото в , но броят на полетата в заявките 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": "Запитът бе напълно обработен."
},
"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": "Запитът бе напълно обработен."
}
}
}
]
}А ето и запитването без грешка в ключа 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": "Запитът бе напълно обработен."
},
"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": "Запитът бе напълно обработен."
}
}
}
]
}Ако изпратите неправилен/изтекъл 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://<service_address>/tecloud/api/v1/file/upload
Заявката се състои от две части (form-data): файл, предназначен за емуляция/очистване и тяло на заявката с текста.
Текстовата заявка не може да е празна, но може да не съдържа никаква конфигурация. За да бъде заявката успешна, трябва да се изпрати поне следния текст в заявката:
Необходимият минимум за заявката upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Заглавия:
Authorization: <api_key>
Body
{
"request": {
}
}
File
File
В такъв случай файлът за обработка ще попадне в съответствие с параметрите по подразбиране: компонент — te, образи на ОС — Win XP и Win 7, без генериране на отчет.
Коментари по основните полета в текстовата заявка:
file_name и file_type може да останат празни или да не се изпращат изобщо, тъй като не е особено полезна информация при качването на файл. В отговора на API тези полета ще се запълнят автоматично въз основа на името на качвания файл, а информацията в кеша все пак ще трябва да се търси по md5/sha1/sha256 hash суми.
Пример на заявка с празни file_name и file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — списък, в който се посочва необходимият функционал при обработката в пясъчника — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Ако този параметър не бъде подаден изобщо, ще бъде задействан само компонентът по подразбиране — te(Threat Emulation).
За да включите проверката в трите налични компонента, трябва да посочите тези компоненти в API заявката.
Пример на заявка с проверка в av, te и extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Ключове в раздела te
images — списък, в който трябва да бъдат посочени речници с 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 и 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 (Plugin& 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 (Plugin & 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 (Plugin & 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 (Plugin & 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 (Plugin & 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 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
Ако ключът images не бъде указан, емулцията ще протече с образите, препоръчани от Check Point (в момента това са Win XP и Win 7). Тези образи са препоръчани с оглед оптимално балансиране на производителността и улов на заплахи.
reports — списък с отчети, които изискваме в случай, че файлът се окаже злонамерен. Достъпни са следните опции:
summary — .tar.gz архив, съдържащ отчет за емулцията по от всичко запросените образи (както html страница, така и компоненти като видео от операционната система на емулатора, дамп на мрежовия трафик, отчет в json, както и самия сample в архив под защита с парола). В отговора търсим ключ — summary_report за последващо изтегляне на отчета.
pdf — документ за емулцията в единичен образ, който много хора свикнаха да получават чрез Smart Console. В отговора търсим ключ — pdf_report за последващо изтегляне на отчета.
xml — документ за емулцията в единичен образ, удобен за последващо извличане на параметри в отчета. В отговора търсим ключ — xml_report за последващо изтегляне на отчета.
tar — .tar.gz архив, съдържащ отчет за емулцията в единичен запросените образи (както html страница, така и компоненти като видео от операционната система на емулатора, дамп на мрежовия трафик, отчет в json, както и самия сample в архив под защита с парола). В отговора търсим ключ — full_report за последващо изтегляне на отчета.
Какво има в отчета summary
Ключовете full_report, pdf_report, xml_report са налични в речника за всяка ОС
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Запитването е напълно отговорено."
},
"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": "Запитването е напълно отговорено."
}
}
}
]
}А ключът summary_report — е един за емулцията като цяло
{
"response": [
{
"status": {
"code": 1001,
"label": "НАМЕРЕНО",
"message": "Запитът е бил напълно отговорен."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "зловреден",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "намерено",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "зловреден",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "намерено",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "зловреден",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "НАМЕРЕНО",
"message": "Запитът е бил напълно отговорен."
}
}
}
]
}Можете да поискате отчети tar и xml и pdf едновременно; можете да поискате summary и tar и xml. Няма да можете да поискате summary отчет и pdf едновременно.
Ключовете в раздела extraction
За извличане на заплахи се използват само два ключа:
метод — pdf(конвертиране в pdf, използва се по подразбиране) или clean(изчистване на активно съдържание).
кодове_на_извлечени_части — списък с кодове за премахване на активно съдържание, прилагано само за метода clean
Кодове за премахване на съдържание от файлове
Code
Описание
1025
Свързани обекти
1026
Макроси и код
1034
Чувствителни хипервръзки
1137
PDF GoToR действия
1139
PDF Launch действия
1141
PDF URI действия
1142
PDF Sound действия
1143
PDF Movie действия
1150
PDF JavaScript действия
1151
PDF Submit Form действия
1018
Заявки към база данни
1019
Вмъкнати обекти
1021
Бързи данни за запазване
1017
Потребителски свойства
1036
Статистически свойства
1037
Собствени свойства
За да изтеглите почистена копия, ще е необходимо да направите и запитване query (за което ще говорим по-късно) след няколко секунди, посочвайки хеш сума на файла и компонент 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": "НАЙДЕНО",
"message": "Запросът е бил напълно отговорен."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"екстракция"
],
"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": "Макроси и код",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Извлечено потенциално злонамерено съдържание",
"protection_type": "Конвертиране в PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Намерено активно съдържание - XLS файлът е бил конвертиран в PDF",
"scrub_method": "Конвертиране в PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Макроси и код"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "НАЙДЕНО",
"message": "Запросът е бил напълно отговорен."
}
}
}
]
}Общи сведения
В един API повикване може да се изпрати само един файл за проверка.
Компонентът av не изисква допълнителен раздел с ключове, достатъчно е да бъде посочен в речника. features.
Повикване на Query API
Използваният метод е — POST
Адрес за извикване — https://<service_address>/tecloud/api/v1/file/query
Преди да изпратите файл за качване (запрос upload), е желателно да извършите проверка на кеша на песочницата (запрос query) с цел оптимизация на натоварването на API сървъра, тъй като е възможно на API сървъра вече да има информация и решение относно качвания файл. Повикването се състои само от текстовата част. Задължителната част на заявката е sha1/sha256/md5 хеша на файла. Той всъщност може да бъде получен в отговора на запрос upload.
Необходимият минимум за запитване query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Заглавия:
Authorization: <api_key>
Body
{
"request": {
«sha256»: <sha256 hash sum>
}
}
Пример за отговор на запитване upload, където са видими sha1/md5/sha256 хешовете
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Файлът е качен успешно."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "неизвестно"
},
"status": "не е намерен",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Файлът е качен успешно."
}
}
}
}Запитът от query, освен хеш сумата, в идеалния случай трябва да бъде идентичен на запитването upload, или дори „вече“ (да съдържа по-малко полета от запитването upload). В случай, че запитът от query съдържа повече полета от запитването upload, ще получите в отговора непълна информация.
Ето пример за отговор на запитването query, където не са намерени всички изисквани данни.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Запитването не може да бъде напълно обработено в момента."
},
"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": "Запитването е напълно обработено."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Не беше намерен исканият файл. Моля, качете го."
}
}
}
]
}Обърнете внимание на полетата code и label. Тези полета се срещат три пъти в речниците 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": "Заявката е била напълно отговорена."
},
"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": "Заявката е била напълно отговорена."
}
}
}
]
}Ако няма никаква информация в кеша, отговорът ще бъде «label»: «NOT_FOUND»
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Не можа да намери поисканото файлово. Моля, качете го."
},
"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": "Не можа да намери поисканото файлово. Моля, качете го."
}
}
}
]
}В един API вызов можете да изпратите няколко хеш суми за проверка. В отговора ще бъдат върнати данни в същия ред, в който са били изпратени в заявката.
Пример на заявка query с няколко sha256 суми
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Отговор на заявката query с няколко sha256 суми
{
"response": [
{
"status": {
"code": 1001,
"label": "Намерено",
"message": "Заявката е напълно обработена."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "зловреден"
},
"status": "намерен",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "зловреден",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "Намерено",
"message": "Заявката е напълно обработена."
}
}
},
{
"status": {
"code": 1004,
"label": "НЕ НАМЕРЕНО",
"message": "Не можа да намери заявения файл. Моля, качете го."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "неизвестен"
},
"status": "не е намерен",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "НЕ НАМЕРЕНО",
"message": "Не можа да намери заявения файл. Моля, качете го."
}
}
}
]
}Запитването на множество хеш суми в заявката query също така ще има положителен ефект върху производителността на API сървъра.
Повикване на Download API
Използваният метод е — POST (според документацията), ИЗИСКВАНЕ също така работи (и може да изглежда по-логично)
Адрес за извикване — https://<service_address>/tecloud/api/v1/file/download?id=<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://<service_address>/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:///UserCheck/TPAPI , тъй като в случай на отрицателен резултат по-нататъшната конфигурация няма смисъл. На този URL ще бъдат изпращани всички API повиквания. Типът на повикването (upload/query) се регулира от ключа на тялото на повикването — request_name. Също така задължителните ключове са — api_key (необходимо е да бъде запомнен по време на конфигурацията) и protocol_version (в момента актуална версия е 1.1). Официалната документация за този API можете да намерите в . К относителните предимства можем да включим възможността да се изпратят няколко файла за емулиране при зареждане, тъй като файловете се изпращат под формата на текстова строка base64. За кодиране/декодиране на файлове в/от base64 може да се използва за демонстрационни цели онлайн конвертер в Postman, например — . В практическите цели при написване на код трябва да се използват вградени методи encode и decode.
Сега ще се спрем по-подробно на функциите te и extraction в този API.
За компонента te е предвиден речник te_options в заявките upload/query, а ключовете в тази заявка напълно съвпадат с ключовете te в .
Пример на заявка за емултиране на файл в Win10 с отчети
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "",
"te_options": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": ["summary", "xml"]
}
}
]
}За компонента extraction е предвиден речник scrub_options. В този запитване се посочва методът на почистване: конвертиране в PDF, почистване от активно съдържание или изберете режим в съответствие с профила за предотвратяване на заплахи (посочете името на профила). Отличителна черта на отговора на API запитване с extraction за файл е, че получавате почистена копие в отговора на това запитване под формата на шифрована низ base64 (не е нужно да правите запитване за търсене и да търсите id за изтегляне на документа)
Пример за запитване за почистване на файл
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Отговор на запитването
{
"response": [{
"protocol_version": "1.1",
"src_ip": "",
"scrub": {
"file_enc_data": "",
"input_real_extension": "js",
"message": "OK",
"orig_file_url": "",
"output_file_name": "hi.cleaned.pdf",
"protection_name": "Извличане на потенциално злонамерено съдържание",
"protection_type": "Конвертиране в PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT файлът беше конвертиран в PDF",
"scrub_method": "Конвертиране в PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Въпреки че за получаване на почистена копия са необходими по-малко API запитвания, считам такъв вариант за по-малко предпочитан и удобен в сравнение с запитването form-data, използвано в .
Колекции Postman
Създадох колекции в Postman както за Threat Prevention API, така и за Threat Prevention API за Security Gateway, в които са представени най-широко използваните API запитвания. За да се поставят ip/url на API сървъра и ключът автоматично в запитванията, а sha256 хеш сумата след качването на файла също да се запомня, в колекциите са създадени три променливи (можете да ги намерите, като отидете в настройките на колекцията Edit -> Variables): te_api (изисква попълване), api_key (изисква попълване, освен в случая на използване на TP API с локални устройства), sha256 (оставете празно, не се използва в TP API за SG).
Примери за използване
В общността са представени скриптове, написани на Python, които проверяват файлове от необходимата директория чрез , така и . Чрез взаимодействието с Threat Prevention API вашите възможности за проверка на файлове значително се разширяват, тъй като сега можете да проверявате файлове едновременно в няколко платформи (интересно е проверката в , а след това в Check Point песочница), и файловете да се получават не само от мрежовия трафик, но и да се извлекат от всякакви мрежови дискове и, например, CRM системи.
Източник: habr.com
