Tento článok bude užitočný pre tých, ktorí sú oboznámení s technológiami Check Point na emuláciu súborov (Emulácia hrozieb) a proaktívne čistenie súborov (Extrakcia hrozieb) a chcú urobiť krok k automatizácii týchto úloh. Check Point má , ktorý funguje ako v cloude, tak aj na lokálnych zariadeniach, a funkčne sa odlišuje od kontroly súborov v prúde web/smtp/ftp/smb/nfs traffiku. Tento článok je čiastočne autorovou interpretáciou súboru článkov z oficiálnej dokumentácie, postavenou na vlastných skúsenostiach a na vlastných príkladoch. V článku nájdete aj autorove kolekcie Postman pre prácu s Threat Prevention API.
Hlavné skratky
Threat Prevention API pracuje so zlúčením troch hlavných komponentov, ktoré v API voláme prostredníctvom nasledujúcich textových hodnôt:
av — komponent Anti-Virus, zodpovedá za signatúrnu analýzu známych hrozieb.
te — komponent Threat Emulation, zodpovedá za kontrolu súborov v pieskovisku a vydanie verdiktu škodlivý (malicious)/čistý (benign) po emulácii.
extraction — komponent Threat Extraction, zodpovedný za rýchlu konverziu oficiálnych dokumentov do bezpečnej podoby (v ktorej je odstránený celý potenciálne škodlivý obsah), s cieľom ich rýchleho doručenia používateľom/systémom.
Struktúra API a hlavné obmedzenia
Threat Prevention API používa iba 4 požiadavky — upload, query, download a quota. V hlavičke všetkých štyroch požiadaviek je potrebné odoslať API kľúč, pričom sa používa parameter Authorization. Na prvý pohľad sa struktúra môže zdať oveľa jednoduchšia, ako v , ale počet polí v požiadavkách upload a query a štruktúra týchto požiadaviek sú dosť komplexné. Môžu sa funkčne porovnať s profilmi Threat Prevention v politike bezpečnosti brány/pieskoviska.
V súčasnosti bola vydaná jediná verzia Threat Prevention API — 1.0, v URL pre API volania je potrebné uviesť v1 v tej časti, kde je potrebné uviesť verziu. Na rozdiel od Management API je potrebné uviesť verziu API v URL adrese, inak požiadavka nebude vykonaná.
Komponent Anti-Virus pri volaní bez iných komponentov (te, extraction) v súčasnosti podporuje iba požiadavky query s md5 hash sumami. Threat Emulation a Threat Extraction podporujú aj sha1 a sha256 hash sumy.
Je veľmi dôležité nerobiť chyby v požiadavkách! Požiadavka môže byť vykonaná bez chyby, ale nie úplne. Trochu sa posunieme dopredu a preskúmame, čo sa môže stať pri chybách/tlačových chybách v požiadavkách.
Žiadosť s preklepom v slove reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}V odpovedi nebude chyba, ale informácie o správach vôbec nebudú
{
"response": [
{
"status": {
"code": 1001,
"label": "NÁJDENÉ",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "NÁJDENÉ",
"message": "Žiadosť bola úplne zodpovedaná."
}
}
}
]
}A to na žiadosť bez preklepu v kľúči reports
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Dostávame odpoveď, ktorá už obsahuje id pre sťahovanie správ
{
"response": [
{
"status": {
"code": 1001,
"label": "NÁJDENÉ",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "NÁJDENÉ",
"message": "Žiadosť bola úplne zodpovedaná."
}
}
}
]
}Ak je odoslaný nesprávny/neschválaný API kľúč, dostaneme v odpovedi chybu 403.
SandBlast API: v cloude a na lokálnych zariadeniach
API žiadosti možno odosielať na zariadenia Check Point, na ktorých je povolený komponent (blade) Threat Emulation. Ako adresu pre žiadosti je potrebné použiť ip/url zariadenia a port 18194 (napríklad — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию vypnuté a kľúč Authorization v hlavičkách žiadostí nie je potrebné odosielať vôbec.
API žiadosti do cloudu CheckPoint treba odosielať na adresu te.checkpoint.com (napríklad — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Na lokálnych zariadeniach zatiaľ nie je podpora pre Threat Extraction v štandardnom a mali by ste použiť (o ňom budeme hovoriť podrobnejšie na konci článku).
Lokálne zariadenia nepodporujú požiadavku quota.
Inak nie sú medzi požiadavkami na lokálne zariadenia a cloud žiadne rozdiely.
Volanie Upload API
Používaná metóda je: POST
Adresa pre volanie je: https://<service_address>/tecloud/api/v1/file/upload
Požiadavka sa skladá z dvoch častí (form-data): súbor určený na emuláciu/čistenie a telo požiadavky s textom.
Textová požiadavka nemôže byť prázdna, ale nemusí obsahovať žiadnu konfiguráciu. Aby bola požiadavka úspešná, je potrebné odoslať aspoň nasledujúci text v požiadavke:
Potrebné minimum pre požiadavku upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
Authorization: <api_key>
Telo
{
«request»: {
}
}
File
File
V takom prípade sa súbor na spracovanie dostane v súlade s parametrami predvolene: komponent — te, obrazy OS — Win XP a Win 7, bez generovania správy.
Komentáre k hlavným poliam v textovej požiadavke:
file_name a file_type môžete nechať prázdne alebo ich vôbec neposielať, pretože to nie je veľmi užitočná informácia pri nahrávaní súboru. V API odpovedi sa tieto polia vyplnia automaticky na základe názvu nahrávaného súboru a informácie v cache budete musieť aj tak hľadať podľa md5/sha1/sha256 hash súm.
Príklad požiadavky s prázdnymi file_name a file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — zoznam, v ktorom sa uvádza potrebná funkčnosť pri spracovaní v pieskovisku — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Ak tento parameter vôbec nepošlete, použije sa iba komponent podľa predvolených nastavení — te(Threat Emulation).
Aby ste aktivovali kontrolu v troch dostupných komponentoch, musíte tieto komponenty uviesť v API požiadavke.
Príklad požiadavky s kontrolou v av, te a extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Kľúče v sekcii te
images — zoznam, v ktorom musia byť uvedené slovníky s id a číslom revízie operačných systémov, na ktorých bude kontrola prebiehať. ID a čísla revízií sú rovnaké pre všetky lokálne zariadenia a cloud.
Zoznam operačných systémov a revízií
Dostupné OS Image ID
Revízia
Obrázok OS a aplikácie
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 a ActiveX 10.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
Ak je kľúč images úplne vynechaný, emulácia prebehne v obrazách odporúčaných Check Point (v súčasnosti sú to Win XP a Win 7). Tieto obrazy sú odporúčané s ohľadom na najlepší balans medzi výkonom a chytaním hrozieb.
reports — zoznam správ, ktoré požadujeme pre prípad, že sa súbor ukáže ako škodlivý. Dostupné sú nasledujúce možnosti:
summary — .tar.gz archív, ktorý obsahuje správu o emulácii týkajúcu sa všetkým požadovaných obrazov (ako html stránku, tak aj komponenty ako video z emulačného OS, výpis sieťovej prevádzky, správu v json a samotný vzor v archíve pod ochranou hesla). V odpovedi hľadáme kľúč — summary_report na následné stiahnutie správy.
pdf — dokument o emulácii v jednotlivom obraze, ktorý mnohí dostávajú cez Smart Console. V odpovedi hľadáme kľúč — pdf_report na následné stiahnutie správy.
xml — dokument o emulácii v jednotlivom obraz, ktorý je vhodný pre následné parsovanie parametrov v správe. V odpovedi hľadáme kľúč — xml_report na následné stiahnutie správy.
tar — .tar.gz archív, ktorý obsahuje správu o emulácii v jednotlivom požadovaných obrazov (ako html stránku, tak aj komponenty ako video z emulačného OS, výpis sieťovej prevádzky, správu v json a samotný vzor v archíve pod ochranou hesla). V odpovedi hľadáme kľúč — full_report na následné stiahnutie správy.
Čo je v správe summary
Kľúče full_report, pdf_report, xml_report sú v slovníku pre každý OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "Žiadosť bola úplne zodpovedaná."
}
}
}
]
}A tu je kľúč summary_report — existuje len jeden pre emuláciu celkovo
{
"response": [
{
"status": {
"code": 1001,
"label": "NÁJDENÉ",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "NÁJDENÉ",
"message": "Žiadosť bola úplne zodpovedaná."
}
}
}
]
}Môžete súčasne požiadať o správy tar a xml a pdf, môžete súčasne požiadať o správy summary a tar a xml. Nie je možné súčasne požiadať o správu summary a pdf.
Kľúče v sekcii extraction.
Na extrakciu hrozieb sa používajú iba dva kľúče:
method — pdf (konverzia do pdf, používa sa predvolene) alebo clean (čistenie aktívneho obsahu).
extracted_parts_codes — zoznam kódov na odstránenie aktívneho obsahu, platí iba pre metódu clean.
Kódy na odstránenie obsahu z súborov.
Kód
Description
1025
Prepojené objekty
1026
Makrá a kód
1034
Citlivé hypertextové odkazy
1137
PDF GoToR akcie
1139
PDF spúšťacie akcie
1141
PDF URI akcie
1142
PDF zvukové akcie
1143
PDF akcie filmu
1150
PDF JavaScript akcie
1151
PDF odoslanie formulára akcie
1018
Dotazy na databázu
1019
Zabudované objekty
1021
Rýchle údaje o uložení
1017
Vlastné vlastnosti
1036
Štatistické vlastnosti
1037
Vlastnosti súhrnu
Na stiahnutie vyčistenej kópie bude potrebné urobiť opäť požiadavku query (o ktorej bude reč neskôr) za niekoľko sekúnd, zadaním hash hodnoty súboru a komponentu extraction v texte požiadavky. Vyčistený súbor bude možné získať pomocou id z odpovede na požiadavku query — extracted_file_download_id. Ešte raz, trošku vopred, uvádzam príklady požiadavky a odpovede query na vyhľadanie id pre stiahnutie vyčisteného dokumentu.
Požiadavka query na vyhľadanie kľúča extracted_file_download_id.
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Odpoveď na požiadavku query (nájdite kľúč extracted_file_download_id).
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "Makrá a kód",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potenciálne škodlivý obsah extrahovaný",
"protection_type": "Konverzia do PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Aktívny obsah bol nájdený - XLS súbor bol konvertovaný na PDF",
"scrub_method": "Konvertovať do PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Makrá a kód"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Žiadosť bola úplne zodpovedaná."
}
}
}
]
}Základné informácie
V jednom API volaní je možné odoslať len jeden súbor na kontrolu.
Komponent av nevyžaduje ďalšiu sekciu s kľúčmi, stačí ho uviesť v slovníku features.
Volanie Query API
Používaná metóda je: POST
Adresa pre volanie je: https://<service_address>/tecloud/api/v1/file/query
Pred odoslaním súboru na nahratie (žiadosť o nahratie) je dobré vykonať kontrolu cache pieskoviska (žiadosti o dotaz) s cieľom optimalizovať zaťaženie na API serveri, pretože je možné, že na API serveri už existujú informácie a verdikt k nahrávanému súboru. Volanie sa skladá len z textovej časti. Povinná časť žiadosti — sha1/sha256/md5 hash suma súboru. Túto, mimochodom, možno získať v odpovedi na žiadosť o nahratie.
Nezbytné minimum pre požiadavku query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Telo
{
«request»: {
„sha256“: <sha256 hash sum>
}
}
Príklad odpovede na žiadosť o nahratie, kde sú viditeľné sha1/md5/sha256 hash sumy
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Súbor bol úspešne nahraný."
},
"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": "Súbor bol úspešne nahraný."
}
}
}
}Dotaz query by měl být ideálně stejný, jako byl (nebo bude) dotaz upload, nebo dokonce „už“ (obsahovat v dotazu query méně polí než v dotazu upload). V případě, že dotaz query obsahuje více polí, než byl v dotazu upload, nedostanete ve odpovědi všechny požadované informace.
Zde je příklad odpovědi na dotaz query, kde nebyly nalezeny všechny požadované údaje.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Žádost nelze v tuto chvíli plně zodpovědět."
},
"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": "Žádost byla plně zodpovězena."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Požadovaný soubor nebyl nalezen. Prosím, nahrajte ho."
}
}
}
]
}Všimněte si polí. code a label. Tyto pole se objevují třikrát ve slovnících status. Na začátku vidíme globální klíč „code“: 1006 a „label“: „PARTIALLY_FOUND“. Dále se tyto klíče objevují u každé jednotlivé komponenty, kterou jsme požádali — te a extraction. A pokud je pro te jasné, že údaje byly nalezeny, pak pro extraction informace chybí.
Takto vypadal dotaz query pro výše uvedený příklad.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Pokud odešlete dotaz query bez komponenty extraction.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Pak bude odpověď obsahovat kompletní informace („code“: 1001, „label“: „FOUND“).
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "Žiadosť bola úplne zodpovedaná."
}
}
}
]
}Ak v cache nie je žiadna informácia, v odpovedi bude „label“: „NOT_FOUND“
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Požadovaný súbor sa nenašiel. Nahrajte ho prosím."
},
"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": "Požadovaný súbor sa nenašiel. Nahrajte ho prosím."
}
}
}
]
}V jednom API volaní je možné zaslať viaceré hash sumy na kontrolu. V odpovedi budú vrátené údaje v tom istom poradí, v akom boli odoslané v požiadavke.
Príklad dopytu query s viacerými sha256 sumami
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Odpoveď na dopyt query s viacerými sha256 sumami
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Žiadosť bola úplne zodpovedaná."
},
"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": "Žiadosť bola úplne zodpovedaná."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nedalo sa nájsť požadovaný súbor. Prosím, nahrajte ho."
},
"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": "Nedalo sa nájsť požadovaný súbor. Prosím, nahrajte ho."
}
}
}
]
}Okamžitý prenos viacero hash sumy v požiadavke query pozitívne ovplyvní výkon API servera.
Volanie Download API
Používaná metóda je: POST (podľa dokumentácie), GET taktiež funguje (a môže sa zdať logickejšie)
Adresa pre volanie je: https://<service_address>/tecloud/api/v1/file/download?id=<id>
V hlavičke je potrebné poskytnúť API kľúč, telo požiadavky — prázdne, id pre sťahovanie je odovzdané v url adrese.
V odpovedi na požiadavku query, ak bola emulácia dokončená a pri sťahovaní súboru boli požadované správy, budú viditeľné id pre sťahovanie správ. Ak sa požaduje vyčistená kópia, je potrebné hľadať id pre sťahovanie vyčisteného dokumentu.
Celkovo môžu byť kľúče v odpovedi na požiadavku query, ktoré obsahujú hodnotu id pre sťahovanie:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Samozrejme, aby sa tieto kľúče objavili v odpovedi na požiadavku query, musia byť uvedené v požiadavke (pre správy) alebo nezabudnite vykonať požiadavku na funkciu extraction (pre vyčistené dokumenty)
Volanie Quota API
Používaná metóda je: POST
Adresa pre volanie je: https://<service_address>/tecloud/api/v1/file/quota
Pre kontrolu zostávajúcej kvóty v cloude sa používa požiadavka quota. Telo požiadavky je prázdne.
Príklad odpovede na požiadavku 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 pre Security Gateway
Tento API bol vyvinutý skôr ako Threat Prevention API a je určený iba pre lokálne zariadenia. V súčasnosti môže byť užitočný len v prípade, ak potrebujete Threat Extraction API. Pre Threat Emulation je lepšie používať klasické Threat Prevention API. Ak chcete povoliť TP API pre SG a konfiguráciu API kľúča je potrebné vykonať kroky z . Odporúčam venovať pozornosť kroku 6b a overiť dostupnosť stránky https:///UserCheck/TPAPI , pretože v prípade negatívneho výsledku ďalšia konfigurácia nemá zmysel. Na tento url budú odosielané všetky API požiadavky. Typ požiadavky (upload/query) sa reguluje v kľúči tela požiadavky — request_name. Rovnako sú povinnými kľúčmi — api_key (je potrebné si ho zapamätať počas konfigurácie) a protocol_version (aktualna verzia je zatiaľ 1.1). Oficiálnu dokumentáciu pre tento API nájdete na . Medzi relatívne výhody patrí možnosť posielať viacero súborov na emuláciu pri ich nahrávaní, pretože súbory sa odosielajú vo forme textového reťazca base64. Na kódovanie/dekódovanie súborov do/z base64 môžete použiť pre účely demonštrácie online konvertor v Postman, napríklad — . V praktických prípadoch pri písaní kódu je potrebné použiť vstavané metódy encode a decode.
Teraz sa podrobnejšie pozrime na funkcie te a extraction v tomto API.
Pre komponent te je predpokladaná slovník te_options v požiadavkách upload/query, pričom kľúče v tejto požiadavke úplne zodpovedajú kľúčom te v .
Príklad požiadavky pre emuláciu súboru vo Win10 s reportmi
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "",
"te_options": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": ["summary", "xml"]
}
}
]
}Pre komponent extraction je predpokladaná slovník scrub_options. V tomto dopyte sa uvádza metóda čistenia: konverzia do PDF, čistenie od aktívneho obsahu alebo výber režimu podľa profilu Prevencia hrozieb (uvádza sa názov profilu). Vlastnosťou odpovede na API dopyt s extrakciou pre súbor je to, že dostanete vyčistenú kópiu v odpovedi na tento dopyt vo forme zakódovaného reťazca base64 (nie je potrebné robiť dopyt query a hľadať id na načítanie dokumentu)
Príklad dopytu na čistenie súboru
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Odpoveď na dopyt
{
"response": [{
"protocol_version": "1.1",
"src_ip": "",
"scrub": {
"file_enc_data": "",
"input_real_extension": "js",
"message": "OK",
"orig_file_url": "",
"output_file_name": "hi.cleaned.pdf",
"protection_name": "Extrahovať potenciálne škodlivý obsah",
"protection_type": "Konverzia do PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT súbor bol konvertovaný do PDF",
"scrub_method": "Konverzia do PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Napriek tomu, že na získanie vyčistenej kópie je potrebné menej API dopytov, považujem túto možnosť za menej preferovanú a pohodlnú v porovnaní s dopytom form-data použitým v .
Zbierky Postman
Vytvoril som zbierky v Postman ako pre API Prevencia hrozieb, tak aj pre API Prevencia hrozieb pre bezpečnostnú bránu, kde sú uvedené najbežnejšie API dopyty. Aby sa IP/url API servera a kľúč automaticky dosadili do dopytov a hash suma sha256 po nahraní súboru bola tiež zapamätaná, v zbierkach sú vytvorené tri premenné (nájdete ich v nastaveniach zbierky Upraviť -> Premenné): te_api (vyžaduje sa vyplniť), api_key (vyžaduje sa vyplniť, s výnimkou prípadu použitia TP API s lokálnymi zariadeniami), sha256 (nechať prázdne, v TP API pre SG sa nepoužíva).
Príklady použitia
V komunite sú uvedené skripty napísané v Pythone, ktoré kontrolujú súbory z požadovanej adresáre ako cez , tak aj . Prostredníctvom interakcie s API Prevencia hrozieb sa vaše možnosti kontroly súborov výrazne rozširujú, pretože teraz môžete kontrolovať súbory okamžite na viacerých platformách (zaujímavé vyzerá kontrola v , a potom v pieskovisku Check Point), a súbory získavať nielen zo sieťovej prevádzky, ale aj ich vyťahovať z akýchkoľvek sieťových diskov a napríklad z CRM systémov.
Zdroj: habr.com
