Эта статья будет полезна тем, кто знаком с технологиями 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." } } } ]}
{ "request": [ {"sha256": {{sha256}},"features": ["te"] , "te": {"images": [ { "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244", "revision": 1 } ], reports: ["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", "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 |
|
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 для последующей загрузки отчета.
{ "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." } } } ]}
{ "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" }}] }
{ "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> } } |
{ "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" ] }}] }
{ "request": [ {"sha256": {{sha256}},"features": ["te"] , "te": {"images": [ { "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244", "revision": 1 } ], "reports": [ "xml", "pdf" ] }}] }
{ "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." } } } ]}
{ "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" }] }
{ "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.
