[Информационная безопасность, Системное администрирование, Антивирусная защита, IT-инфраструктура] Взаимодействие с Check Point SandBlast через API

Ответить на тему

Автор

Сообщение

news_bot ^®

Стаж: 6 лет 9 месяцев
Сообщений: 27286

news_bot ^® написал(а)
11-Сен-2020 14:34

Цитировать

Эта статья будет полезна тем, кто знаком с технологиями 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): файла предназначенный для эмуляции/очистки и тела запроса с текстом.Текстовый запрос не может быть пустым, но при этом может не содержать никакой конфигурации. Для того, чтобы запрос был успешным, нужно отправить минимум следующий текст в запросе:Необходимый минимум для запроса uploadHTTP POSThttps://<service_address>/tecloud/api/v1/file/uploadHeaders:Authorization: <api_key>Body{ "request": { } }
FileFileВ таком случае файл на обработку попадет в соответствии с параметрами по умолчанию: компонент - 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"]
}
]
}

Ключи в разделе teimages - список, внутри которого должны быть указаны словари с id и номером ревизии операционных систем, в которых будет выполняться проверка. ID и номера ревизий одинаковые для всех локальных устройств и облака.Список операционных систем и ревизийAvailable OS Image IDRevisionImage OS and Applicatione50e99f3-5963-4573-af9e-e3f4750b55e21Microsoft Windows: XP - 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 and ActiveX 10.0
Java Runtime: 1.6.0u227e6fe36e-889e-4c25-8704-56378f0830df1Microsoft Windows: 7 - 32bit
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Plugin& ActiveX)
Java Runtime: 1.6.0u08d188031-1010-4466-828b-0cd13d4303ff1Microsoft Windows: 7 - 32bit
Office: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Plugin & ActiveX)
Java Runtime: 1.7.0u05e5de275-a103-4f67-b55b-47532918fa591Microsoft Windows: 7 - 32bit
Office: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Plugin & ActiveX)
Java Runtime: 1.7.0u93ff3ddae-e7fd-4969-818c-d5f1a2be336d1Microsoft Windows: 7 - 64bit
Office: 2013 (32bit)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Plugin & ActiveX)
Java Runtime: 1.7.0u96c453c9b-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.0u910b4a9c6-e414-425c-ae8b-fe4dd7b25244  1Microsoft 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Коды для удаления содержимого из файловCodeDescription1025Linked Objects1026Macros and Code1034Sensitive Hyperlinks1137PDF GoToR Actions1139PDF Launch Actions1141PDF URI Actions1142PDF Sound Actions1143PDF Movie Actions1150PDF JavaScript Actions1151PDF Submit Form Actions1018Database Queries1019Embedded Objects1021Fast Save Data1017Custom Properties1036Statistic Properties1037Summary 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.Необходимый минимум для запроса queryHTTP POSThttps://<service_address>/tecloud/api/v1/file/queryHeaders: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.
===========
Источник:
habr.com
===========
Похожие новости:

Теги для поиска: #_informatsionnaja_bezopasnost (Информационная безопасность), #_sistemnoe_administrirovanie (Системное администрирование), #_antivirusnaja_zaschita (Антивирусная защита), #_itinfrastruktura (IT-инфраструктура), #_checkpoint, #_api, #_restful_api, #_sandblast, #_informatsionnaja_bezopasnost (
Информационная безопасность
), #_sistemnoe_administrirovanie (
Системное администрирование
), #_antivirusnaja_zaschita (
Антивирусная защита
), #_itinfrastruktura (
IT-инфраструктура
)

Профиль ЛС

Ответить на тему

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 22-Ноя 23:41
Часовой пояс: UTC + 5