Эта статья будет полезна тем, кто знаком с технологиями Check Point по эмуляции файлов (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) после эмуляции.
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": "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://<service_address>/tecloud/api/v1/file/upload
Запрос состоит из двух частей (form-data): файла предназначенный для эмуляции/очистки и тела запроса с текстом.
Текстовый запрос не может быть пустым, но при этом может не содержать никакой конфигурации. Для того, чтобы запрос был успешным, нужно отправить минимум следующий текст в запросе:
Необходимый минимум для запроса upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
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 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 (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). Данные образы рекомендованы исходя из соображений наилучшего баланса производительности и catch rate.
reports — список отчетов, которые мы запрашиваем на случай, если файл окажется вредоносным. Доступны следующие варианты:
-
summary — .tar.gz архив, содержащий в себе отчет об эмуляции по всем запрошенным image’ам (как html страницу, так и такие компоненты как видеоролик из ОС эмулятора, дамп сетевого трафика, отчет в json, так и сам сэмпл в архиве под защитой пароля). В ответе ищем ключ — summary_report для последующей загрузки отчета.
-
pdf — документ об эмуляции в одном image, который многие привыкли получать через Smart Console. В ответе ищем ключ — pdf_report для последующей загрузки отчета.
-
xml — документ об эмуляции в одном image, удобный для последующего парсинга параметров в отчете. В ответе ищем ключ — xml_report для последующей загрузки отчета.
-
tar — .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 используется всего два ключа:
method — pdf(конвертация в pdf, используется по умолчанию) или clean(очистка активного содержимого).
extracted_parts_codes — список кодов для удаления активного содержимого, применимо только для метода clean
Коды для удаления содержимого из файлов
Code
Description
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
Database Queries
1019
Embedded Objects
1021
Fast Save Data
1017
Custom Properties
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 не требует дополнительного раздела с ключами, достаточно указать его в словаре features.
Вызов Query API
Используемый метод — POST
Адрес для вызова — https://<service_address>/tecloud/api/v1/file/query
Перед тем как отправлять файл на загрузку (запрос upload), желательно выполнить проверку кэша песочницы (запрос query) в целях оптимизации нагрузки на API сервер, так как возможно на API сервере уже есть информация и вердикт по загружаемому файлу. Вызов состоит только из текстовой части. Обязательная часть запроса — sha1/sha256/md5 hash сумма файла. Её кстати можно получить в ответе на запрос upload.
Необходимый минимум для запроса query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Body
{
«request»: {
«sha256»: <sha256 hash sum>
}
}
Пример ответа на запрос 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."
}
}
}
]
}Обратите внимание на поля 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": "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://<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 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 и extraction в данном 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"]
}
}
]
}Для компонента extraction предусмотрен словарь 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