Эта статья будет полезна тем, кто знаком с технологиями өткөрүү пунктун файл эмуляциясы боюнча (Threat Emulation) жана проактивдүү файлдарды тазалоо (Коркунучту чыгаруу) и желает сделать шаг в сторону автоматизации данных задач. У Check Point есть , булутта да, жергиликтүү түзмөктөрдө да иштейт жана функционально он идентичен проверке файлов в потоках web/smtp/ftp/smb/nfs трафика. Бул макала жарым-жартылай автордун расмий документтердеги макалалардын жыйындысын чечмелеп берген, бирок менин жеке тажрыйбама жана өз мисалдарыма негизделген. Ошондой эле макалада сиз Threat Prevention API менен иштөө үчүн автордун Почтачы жыйнактарын таба аласыз.
Негизги аббревиатуралар
Threat Prevention API работает с тремя основными компонентами, которые в API вызываются через следующие текстовые значения:
av — компонент Anti-Virus, отвечает за сигнатурный анализ известных угроз.
te — компонент Threat Emulation, отвечает за проверку файлов в песочнице, и вынесение вердикта зловредный (malicious)/чистый(benign) после эмуляции.
казып алуу — компонент Threat Extraction, отвечающий за быструю конвертацию офисных документов в безопасный вид (в котором удаляется весь потенциально вредоносный контент), в целях их быстрой доставки пользователям/системам.
API түзүмү жана негизги чектөөлөр
Threat Prevention API 4 гана өтүнүчтү колдонот - жүктөө, суроо, жүктөө жана квота. В заголовке для всех четырех запросов нужно передать API ключ, используя параметр укук берүү. На первый взгляд, структура может показаться гораздо проще, чем в , бирок жүктөө жана суроо сурамдарындагы талаалардын саны жана бул суроо-талаптардын структурасы кыйла татаал. Аларды шлюз/кумдук коопсуздук саясатындагы Коркунучтун алдын алуу профилдери менен функционалдык жактан салыштырса болот.
На данный момент, выпущена единственная версия 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 (отчеттор) деген сөз менен ката менен суроо
{ "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"]
}
}
]
}Мы получаем ответ, в котором уже содержатся 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 в заголовках запросов можно не отправлять вовсе.
CheckPoint булутуна API сурамдары жөнөтүлүшү керек te.checkpoint.com (мисалы - https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
На локальных устройствах Threat Extraction пока не поддерживается в стандартном жана колдонулушу керек (бул тууралуу макаланын аягында кененирээк сөз кылабыз).
Жергиликтүү түзмөктөр квота сурамын колдоого албайт.
В остальном отличий между запросами к локальным устройствам и к облаку нет.
API чалуу жүктөө
Колдонулган ыкма - POST
Чалуу дареги - https:///tecloud/api/v1/file/upload
Запрос состоит из двух частей (form-data): файла предназначенный для эмуляции/очистки и тела запроса с текстом.
Текстовый запрос не может быть пустым, но при этом может не содержать никакой конфигурации. Для того, чтобы запрос был успешным, нужно отправить минимум следующий текст в запросе:
Жүктөп берүү өтүнүчү үчүн минималдуу талап кылынат
HTTP POST
https:///tecloud/api/v1/file/upload
Баш аты:
уруксат берүү:
дене
{
"суроо": {
}
}
File
File
В таком случае файл на обработку попадет в соответствии с параметрами по умолчанию: компонент — te, OS сүрөттөрү - Win XP жана Win 7, отчетту түзбөстөн.
Комментарии по основным полям в текстовом запросе:
Шилтемелер аты и файл түрү Сиз аларды бош калтырсаңыз же такыр жөнөтпөй койсоңуз болот, анткени бул файлды жүктөөдө өзгөчө пайдалуу маалымат эмес. API жоопунда бул талаалар жүктөлүп алынган файлдын аталышына жараша автоматтык түрдө толтурулат жана кэштеги маалымат дагы эле md5/sha1/sha256 хэш суммалары аркылуу изделиши керек болот.
Бош файлдын_аты жана файлдын_тиби менен сурамдын мисалы
{
"request": {
"file_name": "",
"file_type": "",
}
}Өзгөчөлүктөрү — список, в котором указывается необходимый функционал при обработке в песочнице — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Если данный параметр не передать вовсе, то будет задействован только компонент по умолчанию — te(Threat Emulation).
Чтобы включить проверку в трех доступных компонентах, нужно указать эти компоненты в API запросе.
Ав, те жана экстракцияны текшерүү менен сурамдын мисалы
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Те бөлүмүндөгү ачкычтар
сүрөттөр — список, внутри которого должны быть указаны словари с id и номером ревизии операционных систем, в которых будет выполняться проверка. ID и номера ревизий одинаковые для всех локальных устройств и облака.
Операциялык системалардын жана оңдоолордун тизмеси
Жеткиликтүү OS Image ID
кайрадан кароо
Image OS жана колдонмо
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP - 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 жана ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 - 32бит
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Плагин& ActiveX)
Java Runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 - 32бит
Office: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Плагин & ActiveX)
Java Runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 - 32бит
Office: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Плагин & ActiveX)
Java Runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 - 64бит
Office: 2013 (32бит)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Плагин & ActiveX)
Java Runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 - 64бит
Office: 2013 (64бит)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Плагин & 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 (Плагин & ActiveX)
Java Runtime: 1.7.0u9
Если ключ images не указать вовсе, то эмуляция будет проходить в образах, рекомендованных Check Point (на данный момент это Win XP и Win 7). Данные образы рекомендованы исходя из соображений наилучшего баланса производительности и catch rate.
отчеттор — список отчетов, которые мы запрашиваем на случай, если файл окажется вредоносным. Доступны следующие варианты:
-
на - .tar.gz архивинде эмуляция жөнүндө отчет камтылган бардык суралган сүрөттөр (html баракчасы жана эмулятордун OS видеосу, тармактык трафиктин таштандысы, json тилиндеги отчет жана сырсөз менен корголгон архивдеги үлгүнүн өзү сыяктуу компоненттер). Биз жооптун ачкычын издеп жатабыз - корутунду_отчет отчетту кийинки жүктөө үчүн.
-
PDF - эмуляция жөнүндө документ бир image, который многие привыкли получать через Smart Console. В ответе ищем ключ — pdf_отчет отчетту кийинки жүктөө үчүн.
-
XML - эмуляция жөнүндө документ бир image, удобный для последующего парсинга параметров в отчете. В ответе ищем ключ — xml_report отчетту кийинки жүктөө үчүн.
-
кара май - .tar.gz архивинде эмуляция боюнча отчет камтылган бир суралган сүрөттөр (html баракчасы жана эмулятордун OS видеосу, тармактык трафиктин таштандысы, json тилиндеги отчет жана сырсөз менен корголгон архивдеги үлгүнүн өзү сыяктуу компоненттер). Биз жооптун ачкычын издеп жатабыз - толук_отчет отчетту кийинки жүктөө үчүн.
Кыскача отчеттун ичинде эмне бар
Ключи 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 не получится.
Чыгаруу бөлүмүндөгү ачкычтар
Коркунучту жоюу үчүн эки гана ачкыч колдонулат:
ыкма — pdf(конвертация в pdf, используется по умолчанию) или clean(очистка активного содержимого).
алынган_бөлүктөрдүн_коддору — список кодов для удаления активного содержимого, применимо только для метода clean
Файлдардан мазмунду алып салуу үчүн коддор
коду
баяндоо
1025
Байланышкан объекттер
1026
Макрос жана код
1034
Сезимтал гипершилтемелер
1137
PDF GoToR аракеттери
1139
PDF ишке киргизүү аракеттери
1141
PDF URI аракеттери
1142
PDF үн аракеттери
1143
PDF Movie Actions
1150
PDF JavaScript аракеттери
1151
PDF формасын тапшыруу аракеттери
1018
базасы Queries
1019
Киргизилген объекттер
1021
Маалыматтарды тез сактоо
1017
Ыңгайлаштырылган касиеттер
1036
Statistic Properties
1037
Жыйынтык касиеттери
Тазаланган көчүрмөнү жүктөп алуу үчүн, ошондой эле бир нече секунддан кийин файлдын хэш көлөмүн жана суроонун текстиндеги экстракция компонентин көрсөтүү менен суроо-талапты (төмөндө талкууланат) жасашыңыз керек болот. Тазаланган файлды суроого жооптун идентификатору менен ала аласыз - extracted_file_download_id. Дагы бир жолу, бир аз алдыга карап, мен тазаланган документти жүктөп алуу үчүн ID издөө үчүн суроо-жооптун мисалдарын келтирем.
Extracted_file_download_id ачкычын издөө өтүнүчү
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Суроого жооп (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 не требует дополнительного раздела с ключами, достаточно указать его в словаре Өзгөчөлүктөрү.
Сурам API чалуу
Колдонулган ыкма - POST
Чалуу дареги - https:///tecloud/api/v1/file/query
Файлды жүктөө үчүн (жүктөө өтүнүчү) жөнөтүүдөн мурун, API сервериндеги жүктөөнү оптималдаштыруу үчүн құмсалгыч кэшин (суроо талабы) текшерүү сунушталат, анткени API серверинде жүктөлүп алынган файл боюнча маалымат жана өкүм мурунтан эле болушу мүмкүн. Чалуу тексттик бөлүктөн гана турат. Сурамдын талап кылынган бөлүгү файлдын sha1/sha256/md5 хэш суммасы. Айтмакчы, сиз аны жүктөө суроосуна жооп ала аласыз.
Суроо үчүн минималдуу талап кылынат
HTTP POST
https:///tecloud/api/v1/file/query
Баш аты:
уруксат берүү:
дене
{
"суроо": {
"sha256":
}
}
Пример ответа на запрос 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, где были найдены не все требуемые данные
{
"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."
}
}
}
]
}Талааларга көңүл буруңуз коду и этикетка. Бул талаалар статус сөздүктөрүндө үч жолу кездешет. Адегенде биз глобалдык ачкычты көрөбүз "код": 1006 жана "белги": "PARTIALLY_FOUND". Андан кийин, бул ачкычтар биз сураган ар бир жеке компонент үчүн табылат - те жана казып алуу. Эгер маалымат табылганы анык болсо, анда алуу үчүн эч кандай маалымат жок.
Жогорудагы мисал үчүн суроо ушундай көрүндү
{ "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"
]
}
}
]
}То и в ответе будет полная информация («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 вызове можно отправить сразу несколько хэш сумм на проверку. В ответе будут возвращены данные в том же самом порядке, как они были отправлены в запросе.
Бир нече sha256 суммалары менен сурам сурамынын мисалы
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Бир нече 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 сервера.
API чалууларын жүктөп алыңыз
Колдонулган ыкма - POST (документтерге ылайык), ТААНЫШ ошондой эле иштейт (жана логикалуураак сезилиши мүмкүн)
Чалуу дареги - https:///tecloud/api/v1/file/download?id=
В заголовке требуется передать API ключ, тело запроса — пустое, id для загрузки передается в url адресе.
В ответ на query запрос, в случае если эмуляция завершена и при загрузке файла были запрошены отчеты, будут видны id для загрузки отчетов. В случае, если запрашивается очищенная копия, то следует искать id для загрузки очищенного документа.
Итого, ключами в ответе на запрос query, содержащими значение id для загрузки могут быть:
-
корутунду_отчет
-
толук_отчет
-
pdf_отчет
-
xml_report
-
алынган_файл_жүктөө_идентификатору
Безусловно, чтобы в ответе на запрос query были получена эти ключи, их нужно указать в запросе (для отчетов) или не забыть сделать запрос по функции extraction (для очищенных документов)
Квота API чалуу
Колдонулган ыкма - POST
Чалуу дареги - https:///tecloud/api/v1/file/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"
}
]
}Коопсуздук шлюзи үчүн коркунучтарды алдын алуу API
Бул API Threat Prevention API'ден мурун иштелип чыккан жана жергиликтүү түзмөктөр үчүн гана арналган. Азырынча ал сизге Threat Extraction API керек болгондо гана пайдалуу болушу мүмкүн. Threat Emulation үчүн кадимки Threat Prevention API колдонуу жакшы. Күйгүзүү SG үчүн TP API и сконфигурировать API ключ требуется выполнить действия из . Рекомендую обратить внимание на шаг 6b и проверить доступность страницы https://<IPAddressofSecurityGateway>/UserCheck/TPAPI потому как в случае отрицательного результата дальнейшая конфигурация не имеет смысла. На данный url будут отправляться все API вызовы. Тип вызова (upload/query) регулируется в ключе тела вызова — суроо_аты. Ошондой эле керектүү ачкычтар бар - api_key (нужно запомнить его в процессе конфигурации) и протокол_версиясы (на данный момент актуальная версия 1.1). Официальную документацию для данного API вы можете найти в . Салыштырмалуу артыкчылыктарга бир эле учурда бир нече файлдарды жүктөөдө эмуляция үчүн жөнөтүү мүмкүнчүлүгү кирет, анткени файлдар base64 тексттик сап катары жөнөтүлөт. Файлдарды base64тен коддоо/декоддоо үчүн сиз Почтачыдагы онлайн конвертерди демонстрациялоо максатында колдонсоңуз болот, мисалы - . В практических целях при написании кода следует использовать встроенные методы encode и decode.
Эми функцияларды кененирээк карап чыгалы te и казып алуу бул APIде.
Компонент үчүн te сөздүк берилген te_options в запросах upload/query, а ключи в данном запросе полностью совпадают с ключами te в .
Пример запроса для эмуляции файла в 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"]
}
}
]
}Компонент үчүн казып алуу сөздүк берилген scrub_options. Бул сурам тазалоо ыкмасын аныктайт: PDF форматына айландыруу, активдүү мазмунду тазалоо же Коркунучтун алдын алуу профилине ылайык режимди тандоо (профилдин аталышы көрсөтүлгөн). Файлды чыгаруу үчүн API сурамына жооп берүүнүн эң сонун жагы - бул суроо-талапка жооп катары тазаланган көчүрмөнү base64 шифрленген сап катары аласыз (сизге суроо-талапты жасап, жүктөп алуу үчүн 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 Prevention API for Security Gateway үчүн коллекцияларды түздүм, алар эң кеңири таралган API сурамдарын чагылдырат. IP/url серверинин API жана ачкычы автоматтык түрдө суроо-талаптарга алмаштырылышы жана sha256 хэш суммасы файлды жүктөп алгандан кийин эсте калышы үчүн коллекциялардын ичинде үч өзгөрмө түзүлдү (сиз аларды коллекциянын жөндөөлөрүнө өтүү аркылуу таба аласыз. Түзөтүү -> Өзгөрмөлөр): te_api (милдеттүү), api_key(требуется заполнить, кроме случая использования TP API с локальными устройствами), sha256 (бош калтырыңыз, SG үчүн TP API колдонулбайт).
Колдонуунун мисалдары
Коомчулукта представлены скрипты, написанные на Python, которые проверяют файлы из нужной директории как через жана . Через взаимодействие с Threat Prevention API ваши возможности по проверке файлов значительно расширяются, так как теперь вы можете проверять файлы сразу в нескольких платформах (интересным выглядит проверка в , а затем в песочнице Check Point), а файлы получать не только из сетевого трафика, но и забирать их из любых сетевых дисков и, например, CRM систем.
Source: www.habr.com