Взаимодействие с 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 можно оставить пустыми или не отправлять вовсе, так как это не особо полезная информация при загрузке файла. В API ответе данные поля заполнятся автоматически на основе имени загружаемого файла, а информацию в кэше все равно придется искать по md5/sha1/sha256 hash суммам. file_type следует либо не отправлять в запросе вовсе или верно указать его при отправке файла, так как этот параметр учитывается при выборе сценариев эмуляции, таких как, например, статический или динамический анализ.
Пример запроса с пустым file_name
{
"request": {
"file_name": "",
}
}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 |
7e6fe36e-889e-4c25-8704-56378f0830df | 1 | Microsoft Windows: 7 - 32bit |
8d188031-1010-4466-828b-0cd13d4303ff | 1 | Microsoft Windows: 7 - 32bit |
5e5de275-a103-4f67-b55b-47532918fa59 | 1 | Microsoft Windows: 7 - 32bit |
3ff3ddae-e7fd-4969-818c-d5f1a2be336d | 1 | Microsoft Windows: 7 - 64bit |
6c453c9b-20f7-471a-956c-3198a868dc92
| 1 | Microsoft Windows: 8.1 - 64bit |
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
| 1 | Microsoft Windows: 10 |
Если ключ 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.
Важное обновление: начиная с версии Threat Emulation engine 4.1 возможно использовать унифицированный API (такой же, как и для облака TE) и на локальных устройствах Check Point.
Коллекции 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 систем.