Эта статья будет полезна тем, кто знаком с технологиями
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 Player9r115
andActiveX10.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
для загрузки могут быть:
Безусловно, чтобы в ответе на запрос 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.
30.06.2020 14:13:12 |
Автор: 
Категории: 