Tento článek bude užitečný pro ty, kteří znají technologie Check Point pro emulaci souborů (Threat Emulation) a proaktivní čištění souborů (Threat Extraction) a chtějí se posunout směrem k automatizaci těchto úloh. Check Point má , které funguje jak v cloudu, tak na lokálních zařízeních, a funkčně je identické kontrole souborů v tocích web/smtp/ftp/smb/nfs provozu. Tento článek je částečně autorovu interpretací souboru článků z oficiální dokumentace, ale je postaven na jeho zkušenostech a vlastních příkladech. Také v článku najdete autorské sbírky Postman pro práci s Threat Prevention API.
Hlavní zkratky
Threat Prevention API pracuje se třemi hlavními komponenty, které se v API volají pomocí následujících textových hodnot:
av — komponent Anti-Virus, odpovídá za signaturní analýzu známých hrozeb.
te — komponent Threat Emulation, odpovídá za kontrolu souborů v pískovišti a vydání verdiktu škodlivý (malicious)/čistý (benign) po emulaci.
extraction — komponent Threat Extraction, který odpovídá za rychlou konverzi kancelářských dokumentů do bezpečné podoby (ve které je odstraněn veškerý potenciálně škodlivý obsah), za účelem jejich rychlého doručení uživatelům/systemům.
Struktura API a hlavní omezení
Threat Prevention API používá celkem 4 požadavky — upload, query, download a quota. V hlavičce pro všechny čtyři požadavky je třeba předat API klíč pomocí parametru Authorization. Na první pohled se struktura může zdát mnohem jednodušší než v , ale počet polí v požadavcích upload a query a struktura těchto požadavků jsou dost komplexní. Lze je funkčně porovnat s profily Threat Prevention v politice zabezpečení brány/pískoviště.
V současnosti byla vydána jediná verze Threat Prevention API — 1.0, v URL pro API volání je třeba uvést v1 v té části, kde je požadováno uvést verzi. Na rozdíl od Management API je povinné uvádět verzi API v URL adrese, jinak se požadavek neprovedení.
Komponent Anti-Virus při volání bez jiných komponent (te, extraction) v současnosti podporuje pouze požadavky query s md5 hash sumami. Threat Emulation a Threat Extraction také podporují sha1 a sha256 hash sumy.
Je velmi důležité neudělat chyby v požadavcích! Dotaz může být proveden bez chyby, ale ne úplně. Pojďme se nyní zamyslet, co se může stát při chybách nebo překlepech v dotazech.
Dotaz s překlepem ve slově reports (reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}V odpovědi nebude chyba, ale informace o zprávách vůbec nebude.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Dotaz byl plně zodpovězen."
},
"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": "Dotaz byl plně zodpovězen."
}
}
}
]
}A tímto dotazem bez překlepu ve klíči reports
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Obdržíme odpověď, která již obsahuje ID pro stažení zpráv.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Dotaz byl plně zodpovězen."
},
"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": "Dotaz byl plně zodpovězen."
}
}
}
]
}Pokud však odešlete nesprávný/neplatný API klíč, obdržíte v odpovědi chybu 403.
SandBlast API: v cloudu i na místních zařízeních.
API dotazy lze posílat na zařízení Check Point, na kterých je zapnutý komponent (blade) Threat Emulation. Jako adresu pro dotazy je třeba použít ip/url zařízení a port 18194 (například — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию vypnuto A klíč Authorization v záhlaví požadavků není nutné posílat vůbec.
API požadavky do cloudu CheckPoint je třeba posílat na adresu te.checkpoint.com (například — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Na místních zařízeních zatím není standardně podporován Threat Extraction a je nutné použít (o kterém si povíme podrobněji na konci článku).
Místní zařízení nepodporují požadavek quota.
Jinak není mezi požadavky na místní zařízení a cloud žádný rozdíl.
Vyvolání Upload API
Používaná metoda je POST
Adresa pro vyvolání je https://<service_address>/tecloud/api/v1/file/upload
Požadavek se skládá ze dvou částí (form-data): soubor určený pro emulaci/údržbu a těla požadavku s textem.
Textový požadavek nemůže být prázdný, ale nemusí obsahovat žádnou konfiguraci. Aby byl požadavek úspěšný, je třeba poslat alespoň následující text v požadavku:
Nejmenší potřebné minimum pro požadavek upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Hlavice:
Authorization: <api_key>
Tělo
{
"request": {
}
}
Soubor
Soubor
V takovém případě se soubor k zpracování dostane podle výchozích parametrů: komponent — te, obrazy OS — Win XP a Win 7, bez generování zprávy.
Komentáře k hlavním polím v textovém požadavku:
file_name a file_type lze nechat prázdná nebo je vůbec nesendat, protože to není příliš užitečná informace při nahrávání souboru. V odpovědi API se tato pole automaticky vyplní na základě názvu nahrávaného souboru, a informace v cache stejně bude muset být hledána podle md5/sha1/sha256 hashů.
Příklad požadavku s prázdnými file_name a file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — seznam, ve kterém se udává požadovaná funkcionalita při zpracování v pískovišti — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Pokud tento parametr vůbec nepředáte, bude aktivován pouze výchozí komponent — te (Threat Emulation).
Aby bylo možné aktivovat kontrolu ve třech dostupných komponentech, je třeba tyto komponenty uvést v API požadavku.
Příklad požadavku s kontrolou v av, te a extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Klíče v sekci te
images — seznam, uvnitř kterého by měly být uvedeny slovníky s id a číslem revize operačních systémů, ve kterých bude probíhat kontrola. ID a čísla revizí jsou stejná pro všechna místní zařízení a cloud.
Seznam operačních systémů a revizí
Dostupný OS Image ID
Revize
Obraz OS a aplikací
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
Pokud klíč images není uveden, emulace proběhne na doporučených obrazech Check Point (v tuto chvíli jsou to Win XP a Win 7). Tyto obrazy jsou doporučeny na základě nejlepšího vyvážení výkonu a úspěšné detekce.
reports — seznam zpráv, které požadujeme v případě, že by soubor byl škodlivý. K dispozici jsou tyto možnosti:
summary — .tar.gz archiv obsahující zprávu o emulaci pro všem požadované image (jak html stránku, tak komponenty jako video z emulované OS, dump síťového provozu, zprávu v json, stejně jako samotný vzorek v archivu chráněném heslem). V odpovědi hledáme klíč — summary_report pro následné stažení zprávy.
pdf — dokument o emulaci v jeden image, který mnozí zvyknou získávat přes Smart Console. V odpovědi hledáme klíč — pdf_report pro následné stažení zprávy.
xml — dokument o emulaci v jeden image, vhodný pro následné zpracování parametrů ve zprávě. V odpovědi hledáme klíč — xml_report pro následné stažení zprávy.
tar — .tar.gz archiv obsahující zprávu o emulaci v jeden požadované image (jak html stránku, tak komponenty jako video z emulované OS, dump síťového provozu, zprávu v json, stejně jako samotný vzorek v archivu chráněném heslem). V odpovědi hledáme klíč — full_report pro následné stažení zprávy.
Co je uvnitř zprávy summary
Klíče full_report, pdf_report, xml_report jsou ve slovníku pro každý OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Požadavek byl plně zodpovězen."
},
"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": "Požadavek byl plně zodpovězen."
}
}
}
]
}A klíč summary_report — je jeden pro celou emulaci
{
"response": [
{
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zpracována."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malware",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "nalezen",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malware",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "nalezen",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malware",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zpracována."
}
}
}
]
}Můžete požádat o zprávy ve formátu tar, xml a pdf současně, můžete mít shrnutí a tar a xml. Není však možné současně požádat o shrnutí zprávy a pdf.
Klíče v sekci extraction
Pro hrozby extraction se používají pouze dva klíče:
method — pdf (konverze do pdf, používá se jako výchozí) nebo clean (čištění aktivního obsahu).
extracted_parts_codes — seznam kódů pro odstranění aktivního obsahu, použitelné pouze pro metodu clean
Kódy pro odstranění obsahu z souborů
Kód
Popis
1025
Propojené objekty
1026
Makra a kód
1034
Citlivé hyperlinky
1137
PDF GoToR akce
1139
PDF spuštění akcí
1141
PDF URI akce
1142
PDF zvukové akce
1143
PDF filmové akce
1150
PDF JavaScript akce
1151
PDF odeslat formulář akce
1018
Dotazy do databáze
1019
Vložené objekty
1021
Rychlé ukládání dat
1017
Vlastní vlastnosti
1036
Statistické vlastnosti
1037
Shrnutí vlastnosti
Pro stažení očištěné kopie bude potřeba provést ještě dotaz query (o kterém budeme mluvit dále) během několika sekund, uvedením hash součtu souboru a komponenty extraction v textu dotazu. Očištěný soubor si můžete vyzvednout pomocí id z odpovědi na dotaz query — extracted_file_download_id. Ještě jednou, abych to přehnal, uvádím příklady požadavku a odpovědi query pro hledání id na stažení očištěného dokumentu.
Dotaz query pro hledání klíče extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Odpověď na dotaz query (najděte klíč extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zodpovězena."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extrakce"
],
"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": "Makra 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álně škodlivý obsah byl extrahován",
"protection_type": "Konverze do PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Byl nalezen aktivní obsah - XLS soubor byl převeden na PDF",
"scrub_method": "Převést na PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Makra a kód"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zodpovězena."
}
}
}
]
}Obecné informace
V jednom API volání lze odeslat pouze jeden soubor k ověření.
Komponent av nevyžaduje další sekci s klíči, stačí jej uvést ve slovníku. features.
Volání Query API
Používaná metoda je POST
Adresa pro vyvolání je https://<service_address>/tecloud/api/v1/file/query
Před odesláním souboru k nahrání (žádost upload) je vhodné provést kontrolu cache pískoviště (žádost query) za účelem optimalizace zátěže na API server, protože na API serveru může již být informace a verdikt o nahrávaném souboru. Volání se skládá pouze z textové části. Povinnou součástí žádosti je sha1/sha256/md5 hash součet souboru. Ten lze mimochodem získat jako odpověď na žádost upload.
Nutné minimum pro žádost query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Hlavice:
Authorization: <api_key>
Tělo
{
"request": {
„sha256“: <sha256 hash sum>
}
}
Příklad odpovědi na žádost upload, kde jsou viditelné sha1/md5/sha256 hash součty.
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Soubor byl úspěšně nahrán."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "neznámý"
},
"status": "nenalezen",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Soubor byl úspěšně nahrán."
}
}
}
}Dotaz query by měl ideálně odpovídat dotazu upload (nebo být plánován tak), nebo by měl 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 dotaz upload, neobdržíte všechny požadované informace.
Zde je příklad odpovědi na dotaz query, kde nebyla nalezena všechna požadovaná data
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Žádost nemůže být v tuto chvíli plně zodpovězena."
},
"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 jej."
}
}
}
]
}Vezměte prosím na vědomí pole code a label. Tato pole se vyskytují třikrát ve slovnících status. Nejprve 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žadovali — te a extraction. A pokud je pro te jasné, že data byla nalezena, 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"
]
}
}
]
}Tak v odpovědi bude kompletní informace („code“: 1001, „label“: „FOUND“)
{
"response": [
{
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zodpovězena."
},
"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": "nalezen",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zodpovězena."
}
}
}
]
}Pokud v mezipaměti vůbec žádné informace nejsou, odpověď bude obsahovat "label": "NOT_FOUND".
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nepodařilo se najít požadovaný soubor. Prosím, nahrajte ho."
},
"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": "Nepodařilo se najít požadovaný soubor. Prosím, nahrajte ho."
}
}
}
]
}V jednom API volání můžete najednou odeslat více hashů k ověření. Odpověď vrátí data ve stejném pořadí, v jakém byla odeslána v žádosti.
Příklad dotazu query s více sha256 hashi
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Odpověď na dotaz query s více sha256 hashi
{
"response": [
{
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zodpovězena."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "škodlivý"
},
"status": "nalezen",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "škodlivý",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "NALEZEN",
"message": "Žádost byla plně zodpovězena."
}
}
},
{
"status": {
"code": 1004,
"label": "NENALEZEN",
"message": "Požadovaný soubor nebyl nalezen. Prosím, nahrajte ho."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "neznámý"
},
"status": "nenalezen",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NENALEZEN",
"message": "Požadovaný soubor nebyl nalezen. Prosím, nahrajte ho."
}
}
}
]
}Zasílání několika hash hodnot v dotazu také pozitivně ovlivní výkon API serveru.
Volání Download API
Používaná metoda je POST (podle dokumentace), GET také funguje (a může se zdát logičtější)
Adresa pro vyvolání je https://<service_address>/tecloud/api/v1/file/download?id=<id>
Do hlavičky je třeba zaslat API klíč, tělo požadavku - prázdné, id pro stažení se předává v URL adrese.
V odpovědi na dotaz query, pokud je emulace dokončena a byly vyžádány zprávy během nahrávání souboru, budou viditelné id pro stahování zpráv. Pokud je požadována čistá kopie, je třeba hledat id pro stažení vyčištěného dokumentu.
Celkem, klíče v odpovědi na dotaz query, obsahující hodnotu id pro stahování, mohou být:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Samozřejmě, aby tyto klíče byly v odpovědi na dotaz query, je nutné je uvést v požadavku (pro zprávy) nebo nezapomenout provést požadavek na funkci extraction (pro vyčištěné dokumenty).
Volání Quota API
Používaná metoda je POST
Adresa pro vyvolání je https://<service_address>/tecloud/api/v1/file/quota
Pro kontrolu zbývající kvóty v cloudu se používá dotaz quota. Tělo požadavku je prázdné.
Příklad odpovědi na dotaz 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
Toto API bylo vyvinuto dříve, než Threat Prevention API, a je určeno pouze pro lokální zařízení. V tuto chvíli může být užitečné pouze v případě, že potřebujete Threat Extraction API. Pro Threat Emulation je lepší použít standardní Threat Prevention API. Chcete-li jej aktivovat, TP API pro SG a pro konfiguraci API klíče je třeba provést kroky z . Doporučuji věnovat pozornost kroku 6b a zkontrolovat dostupnost stránky https:///UserCheck/TPAPI , protože v případě negativního výsledku nemá další konfigurace význam. Na tuto URL budou odesílány všechny API volání. Typ volání (upload/query) je řízen klíčem v těle volání — request_name. Mezi povinné klíče patří — api_key to je třeba si zapamatovat během konfigurace, a protocol_version (aktuální verze je 1.1). Oficiální dokumentaci pro toto API můžete najít v . K relativním výhodám patří možnost odesílat více souborů na emulaci při jejich nahrávání, protože soubory jsou odesílány jako textová řetězec base64. Pro kódování/dekódování souborů do/z base64 můžete použít online konvertor v Postmanu, například — . V praxi při psaní kódu byste měli použít vestavěné metody encode a decode.
Nyní se podrobněji zaměřme na funkce te a extraction v tomto API.
Pro komponentu te je předpokládán slovník te_options v dotazech upload/query, a klíče v tomto dotazu se zcela shodují s klíči te v .
Příklad dotazu pro emulaci souboru ve Win10 s reporty
{
"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"]
}
}
]
}Pro komponentu extraction je předpokládán slovník scrub_options. V tomto požadavku je uvedena metoda čištění: převod do PDF, odstranění aktivního obsahu nebo zvolit režim podle profilu Threat Prevention (uvádí se jméno profilu). Významným rysem odpovědi na API požadavek s extraction pro soubor je, že obdržíte vyčištěnou kopii v odpovědi na tento požadavek ve formě šifrovaného řetězce base64 (není nutné provádět dotaz query a hledat id pro načtení dokumentu)
Příklad požadavku na čištění souboru
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Odpověď na požadavek
{
"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": "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": ""
}
}]
} I když je k získání vyčištěné kopie zapotřebí méně API požadavků, považuji tuto možnost za méně výhodnou a pohodlnou než požadavek form-data, který se používá v .
Kolekce Postman
Vytvořil jsem kolekce v Postman pro jak Threat Prevention API, tak pro Threat Prevention API for Security Gateway, kde jsou uvedeny nejběžnější API požadavky. Aby se ip/url API serveru a klíč automaticky vkládaly do požadavků, a hash suma sha256 po nahrání souboru byla také uložená, byly uvnitř kolekcí vytvořeny tři proměnné (lze je nalézt v nastaveních kolekce Edit -> Variables): te_api (je třeba vyplnit), api_key (je třeba vyplnit, kromě případu použití TP API s lokálními zařízeními), sha256 (nechat prázdné, v TP API for SG se nepoužívá).
Příklady použití
Ve společenství jsou uvedeny skripty napsané v Pythonu, které kontrolují soubory z požadovaného adresáře jak přes , tak i . Prostřednictvím interakce s Threat Prevention API se vaše možnosti kontrolování souborů významně rozšiřují, protože nyní můžete kontrolovat soubory najednou na několika platformách (zajímavé vypadá kontrola v , a poté v pískovišti Check Point), a soubory získávat nejen z síťového provozu, ale i stahovat je z libovolných síťových disků a například z CRM systémů.
Zdroj: habr.com
