Взаимодействие с Check Point SandBlast через API

oldflint — Fri, 11 Sep 2020 11:46:38 GMT

Взаимодействие с Check Point SandBlast через API

Эта статья будет полезна тем, кто знаком с технологиями Check Point по эмуляции файлов (Threat Emulation) и проактивной очистке файлов (Threat Extraction) и желает сделать шаг в сторону автоматизации данных задач. У Check Point есть Threat Prevention API, который работает как в облаке , так и на локальных устройствах, и функционально он идентичен проверке файлов в потоках 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. На первый взгляд, структура может показаться гораздо проще, чем в Management 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 пока не поддерживается в стандартном Threat Prevention API и следует использовать Threat Prevention API for Security Gateway (о нем мы поговорим подробнее в конце статьи).

Локальные устройства не поддерживают запрос 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 ключ требуется выполнить действия из sk113599. Рекомендую обратить внимание на шаг 6b и проверить доступность страницы https://<IPAddressofSecurityGateway>/UserCheck/TPAPI потому как в случае отрицательного результата дальнейшая конфигурация не имеет смысла. На данный url будут отправляться все API вызовы. Тип вызова (upload/query) регулируется в ключе тела вызова - request_name. Также обязательными ключами являются - api_key (нужно запомнить его в процессе конфигурации) и protocol_version (на данный момент актуальная версия 1.1). Официальную документацию для данного API вы можете найти в sk137032. К относительным преимуществам можно отнести возможность отправлять сразу несколько файлов на эмуляцию при их загрузке, так как файлы отправляются в виде текстовой строки base64. Чтобы кодировать/декодировать файлы в/из base64 можно использовать для целей демонстрации в Postman онлайн конвертер, например - https://base64.guru. В практических целях при написании кода следует использовать встроенные методы encode и decode.

Теперь остановимся подробнее на функциях te и extraction в данном API.

Для компонента te предусмотрен словарь te_options в запросах upload/query, а ключи в данном запросе полностью совпадают с ключами te в Threat Prevention API.

Пример запроса для эмуляции файла в 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, используемый в Threat Prevention API.

Коллекции 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 не используется).

Скачать коллекцию Postman для Threat Prevention API

Скачать коллекцию Postman для Threat Prevention for Security Gateway API

Примеры использования

В сообществе Check Mates представлены скрипты, написанные на Python, которые проверяют файлы из нужной директории как через TP API, так и TP API for SG. Через взаимодействие с Threat Prevention API ваши возможности по проверке файлов значительно расширяются, так как теперь вы можете проверять файлы сразу в нескольких платформах (интересным выглядит проверка в VirusTotal API, а затем в песочнице Check Point), а файлы получать не только из сетевого трафика, но и забирать их из любых сетевых дисков и, например, CRM систем.

topic Взаимодействие с Check Point SandBlast через API in Russian

Взаимодействие с Check Point SandBlast через API

Взаимодействие с Check Point SandBlast через API

Основные сокращения

Структура API и основные ограничения

SandBlast API: в облаке и на локальных устройствах

Вызов Upload API

Ключи в разделе te

Ключи в разделе extraction

Общие сведения

Вызов Query API

Вызов Download API

Вызов Quota API

Threat Prevention API for Security Gateway

Коллекции Postman

Примеры использования