Tento článok bude užitočný pre tých, ktorí sú oboznámení s technológiou Check Point emuláciou súboru (Emulácia hrozieb) a proaktívne čistenie súborov (Extrakcia hrozieb) a chce urobiť krok smerom k automatizácii týchto úloh. Check Point má
Základné skratky
Rozhranie Threat Prevention API pracuje s tromi hlavnými komponentmi, ktoré sa v rozhraní API volajú prostredníctvom nasledujúcich textových hodnôt:
av — Antivírusový komponent zodpovedný za analýzu signatúr známych hrozieb.
te - Komponent Threat Emulation, zodpovedný za kontrolu súborov v karanténe a za vykonanie škodlivého/nezhubného verdiktu po emulácii.
ťažba - Komponent Threat Extraction, zodpovedný za rýchlu konverziu kancelárskych dokumentov do bezpečnej formy (v ktorej je odstránený všetok potenciálne škodlivý obsah), aby ich bolo možné rýchlo doručiť používateľom/systémom.
Štruktúra API a hlavné obmedzenia
Threat Prevention API používa iba 4 požiadavky − upload, dotaz, download a kvóta. V hlavičke pre všetky štyri požiadavky musíte zadať kľúč API pomocou parametra povolenie. Na prvý pohľad sa môže zdať štruktúra oveľa jednoduchšia ako v
Momentálne bola vydaná jediná verzia Threat Prevention API – 1.0; URL pre volania API by mala obsahovať v1 v časti, kde je potrebné špecifikovať verziu. Na rozdiel od Management API je potrebné uviesť verziu API v URL, inak sa požiadavka nevykoná.
Komponent Anti-Virus, keď sa volá bez iných komponentov (te, extrakcia), v súčasnosti podporuje iba požiadavky dotazov so súčtom hash md5. Emulácia hrozieb a extrakcia hrozieb tiež podporujú súčty hash sha1 a sha256.
Je veľmi dôležité nerobiť chyby v dopytoch! Požiadavka môže byť vykonaná bez chyby, ale nie úplne. Pri pohľade trochu dopredu sa pozrime na to, čo sa môže stať, keď sa v dotazoch vyskytnú chyby/preklepy.
Žiadosť s preklepom so slovom reporty (reports)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}
V odpovedi nebude žiadna chyba, ale nebudú tam žiadne informácie o správach
{
"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."
}
}
}
]
}
Ale na požiadavku bez preklepu v kľúči prehľadov
{ "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 na sťahovanie prehľadov
{
"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."
}
}
}
]
}
Ak pošleme nesprávny/vypršaný API kľúč, ako odpoveď dostaneme chybu 403.
SandBlast API: v cloude a na lokálnych zariadeniach
Požiadavky API možno posielať zariadeniam Check Point, ktoré majú povolený komponent (blade) emulácie hrozieb. Ako adresu pre požiadavky musíte použiť ip/url zariadenia a port 18194 (napríklad https://10.10.57.19:18194/tecloud/api/v1/file/query). Mali by ste sa tiež uistiť, že bezpečnostná politika v zariadení umožňuje toto pripojenie. Predvolene autorizácia prostredníctvom kľúča API na miestnych zariadeniach vypnuté a Autorizačný kľúč v hlavičkách požiadaviek nemusí byť odoslaný vôbec.
Žiadosti API do cloudu CheckPoint by sa mali odosielať na te.checkpoint.com (napríklad - https://te.checkpoint.com/tecloud/api/v1/file/query). API kľúč je možné získať ako skúšobnú licenciu na 60 dní kontaktovaním partnerov Check Point alebo miestnej kancelárie spoločnosti.
Na lokálnych zariadeniach zatiaľ nie je štandardne podporovaná extrakcia hrozieb.
Miestne zariadenia nepodporujú požiadavku na kvótu.
V opačnom prípade neexistujú žiadne rozdiely medzi požiadavkami na lokálne zariadenia a do cloudu.
Nahrať volanie API
Použitá metóda − POST
Adresa volania - https:///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 nesmie obsahovať žiadnu konfiguráciu. Aby bola žiadosť úspešná, musíte v žiadosti zaslať aspoň tento text:
Minimálne potrebné pre žiadosť o nahranie
HTTP POST
https:///tecloud/api/v1/file/upload
Hlavičky:
povolenie:
Telo
{
"požiadavka": {
}
}
rezeň
rezeň
V tomto prípade bude súbor spracovaný v súlade s predvolenými parametrami: komponent - te, obrázky OS - Win XP a Win 7bez generovania prehľadu.
Komentáre k hlavným poliam v textovej žiadosti:
názov súboru и typ súboru Môžete ich nechať prázdne alebo ich neodoslať vôbec, pretože to nie je obzvlášť užitočná informácia pri nahrávaní súboru. V odpovedi API sa tieto polia vyplnia automaticky na základe názvu sťahovaného súboru a informácie vo vyrovnávacej pamäti sa budú musieť stále vyhľadávať pomocou množstiev hash md5/sha1/sha256.
Príklad žiadosti s prázdnym názvom_súboru a typom_súboru
{
"request": {
"file_name": "",
"file_type": "",
}
}
Vlastnosti — zoznam, ktorý označuje potrebné funkcie pri spracovaní v karanténe - av (Anti-Virus), te (Emulace hrozieb), extrakcia (Extrahcia hrozieb). Ak tento parameter nie je odovzdaný vôbec, potom sa použije iba predvolený komponent - te (Emulace hrozieb).
Ak chcete povoliť kontrolu troch dostupných komponentov, musíte tieto komponenty špecifikovať v požiadavke API.
Príklad požiadavky s prihlásením av, te a extrakciou
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}
Kľúče v sekcii te
obrazy — zoznam obsahujúci slovníky s ID a číslom revízie operačných systémov, v ktorých sa bude kontrola vykonávať. 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é ID obrázka operačného systému
Revízia
Obrazový operačný systém a aplikácia
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 - 32 bitov
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2 r152 (Zapojiť& ActiveX)
Java Runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 - 32 bitov
Office: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Zapojiť & ActiveX)
Java Runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 - 32 bitov
Office: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Zapojiť & ActiveX)
Java Runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 - 64 bitov
Office: 2013 (32bit)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Zapojiť & ActiveX)
Java Runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 - 64 bitov
Office: 2013 (64bit)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Zapojiť & 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 (Zapojiť & ActiveX)
Java Runtime: 1.7.0u9
Ak kľúč obrázkov nie je zadaný vôbec, emulácia sa uskutoční v obrázkoch odporúčaných spoločnosťou Check Point (v súčasnosti Win XP a Win 7). Tieto obrázky sa odporúčajú na základe úvah o najlepšom vyvážení výkonu a rýchlosti úlovku.
Správy — zoznam hlásení, ktoré požadujeme v prípade, že sa ukáže, že súbor je škodlivý. K dispozícii sú nasledujúce možnosti:
-
zhrnutie - archív .tar.gz obsahujúci správu o emulácii od každý požadované obrázky (stránka html aj komponenty, ako je video z operačného systému emulátora, výpis sieťovej prevádzky, správa v json a samotná vzorka v archíve chránenom heslom). Hľadáme kľúč v odpovedi - súhrnná správa na následné stiahnutie správy.
-
pdf - dokument o emulácii v jeden obraz, ktorý sú mnohí zvyknutí prijímať cez Smart Console. Hľadáme kľúč v odpovedi - pdf_report na následné stiahnutie správy.
-
xml - dokument o emulácii v jeden obrázok, vhodný pre následnú analýzu parametrov v správe. Hľadáme kľúč v odpovedi - xml_report na následné stiahnutie správy.
-
decht - archív .tar.gz obsahujúci správu o emulácii v jeden požadované obrázky (stránka html aj komponenty, ako je video z operačného systému emulátora, výpis sieťovej prevádzky, správa v json a samotná vzorka v archíve chránenom heslom). Hľadáme kľúč v odpovedi - úplná_správa na následné stiahnutie správy.
Čo obsahuje súhrnná správa
Kľúče full_report, pdf_report, xml_report sú v slovníku pre každý OS
{
"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."
}
}
}
]
}
Ale kľúč Summary_report - existuje jeden pre emuláciu vo všeobecnosti
{
"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."
}
}
}
]
}
Môžete požiadať súčasne o správy tar a xml a pdf, môžete požiadať o súhrn a tar a xml. Zároveň nebude možné požiadať o súhrnný výkaz a pdf.
Kľúče v extrakčnej časti
Na extrakciu hrozieb sa používajú iba dva kľúče:
metóda — pdf (previesť na pdf, používané predvolene) alebo čisté (vyčistenie aktívneho obsahu).
extrahované_kódy_dielov - zoznam kódov na odstránenie aktívneho obsahu, použiteľný len pre čistú metódu
Kódy na odstránenie obsahu zo súborov
kód
Popis
1025
Prepojené objekty
1026
Makrá a kód
1034
Citlivé hypertextové odkazy
1137
Akcie PDF GoToR
1139
Akcie spustenia PDF
1141
Akcie URI PDF
1142
Zvukové akcie PDF
1143
Akcie filmu vo formáte PDF
1150
Akcie PDF JavaScript
1151
Akcie na odoslanie formulára PDF
1018
Databázové dotazy
1019
Vložené objekty
1021
Rýchle ukladanie dát
1017
Vlastné vlastnosti
1036
Štatistické vlastnosti
1037
Súhrnné vlastnosti
Ak chcete stiahnuť vyčistenú kópiu, budete musieť po niekoľkých sekundách zadať požiadavku na dotaz (o ktorej sa bude hovoriť nižšie), pričom v texte požiadavky špecifikujete hodnotu hash súboru a extrakčný komponent. Vyčistený súbor si môžete vyzdvihnúť pomocou id z odpovede na dotaz – extract_file_download_id. Ešte raz, trochu dopredu, uvádzam príklady žiadosti a odpovede na dopyt na vyhľadanie ID na stiahnutie vymazaného dokumentu.
Dopyt na vyhľadanie kľúča extract_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}
Odpoveď na dotaz (hľadajte kľúč extract_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."
}
}
}
]
}
Prehľad
V jednom volaní API môžete poslať na overenie iba jeden súbor.
Komponent av nevyžaduje dodatočnú sekciu s kľúčmi, stačí ho špecifikovať v slovníku Vlastnosti.
Dopytové volanie API
Použitá metóda − POST
Adresa volania - https:///tecloud/api/v1/file/query
Pred odoslaním súboru na stiahnutie (žiadosť o nahranie) sa odporúča skontrolovať vyrovnávaciu pamäť karantény (požiadavka dopytu), aby sa optimalizovalo zaťaženie servera API, pretože server API už môže mať informácie a verdikt o stiahnutom súbore. Výzva pozostáva len z textovej časti. Požadovaná časť požiadavky je sha1/sha256/md5 hash množstvo súboru. Mimochodom, môžete ho získať v odpovedi na žiadosť o nahranie.
Minimálne požadované pre dopyt
HTTP POST
https:///tecloud/api/v1/file/query
Hlavičky:
povolenie:
Telo
{
"požiadavka": {
"sha256":
}
}
Príklad odpovede na požiadavku na nahrávanie, kde sú viditeľné hodnoty hash sha1/md5/sha256
{
"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."
}
}
}
}
Požiadavka dotazu, okrem množstva hash, by mala byť v ideálnom prípade rovnaká ako požiadavka na upload bola (alebo sa plánuje byť), alebo dokonca „už“ (obsahuje menej polí v dopyte ako v požiadavke na upload). V prípade, že požiadavka dopytu obsahuje viac polí, ako bolo v žiadosti o nahranie, v odpovedi nedostanete všetky požadované informácie.
Tu je príklad odpovede na dotaz, kde sa nenašli všetky požadované údaje
{
"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."
}
}
}
]
}
Venujte pozornosť poliam kód и štítok. Tieto polia sa v stavových slovníkoch objavia trikrát. Najprv vidíme globálny kľúč „code“: 1006 a „label“: „PARTIALLY_FOUND“. Ďalej sa tieto kľúče nachádzajú pre každý jednotlivý komponent, ktorý sme požadovali - te a extrakciu. A ak je pre vás jasné, že údaje boli nájdené, potom na extrakciu neexistujú žiadne informácie.
Takto vyzeral dopyt v príklade vyššie
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}
Ak odošlete požiadavku bez extrakčného komponentu
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}
Potom bude odpoveď obsahovať úplné informácie („kód“: 1001, „štítok“: „NÁJDENÉ“)
{
"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."
}
}
}
]
}
Ak vo vyrovnávacej pamäti nie sú žiadne informácie, odpoveď bude „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."
}
}
}
]
}
V jednom volaní API môžete poslať niekoľko hash čiastok naraz na overenie. Odpoveď vráti údaje v rovnakom poradí, v akom boli odoslané v požiadavke.
Príklad dotazu s niekoľkými sumami sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}
Odpoveď na dotaz s viacerými sumami 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."
}
}
}
]
}
Požiadanie o niekoľko hashových súm naraz v požiadavke dotazu bude mať tiež priaznivý vplyv na výkon servera API.
Stiahnuť volanie API
Použitá metóda − POST (podľa dokumentácie), GET tiež funguje (a môže sa zdať logickejšie)
Adresa volania - https:///tecloud/api/v1/file/download?id=
Hlavička vyžaduje odovzdanie API kľúča, telo požiadavky je prázdne, v URL adrese sa odovzdáva ID sťahovania.
V reakcii na požiadavku dotazu, ak je emulácia dokončená a pri sťahovaní súboru boli vyžiadané prehľady, bude viditeľné ID pre sťahovanie prehľadov. Ak sa požaduje vyčistená kópia, mali by ste vyhľadať ID na stiahnutie vyčisteného dokumentu.
Celkovo môžu kľúče v odpovedi na dotaz obsahujúci hodnotu id pre načítanie byť:
-
súhrnná správa
-
úplná_správa
-
pdf_report
-
xml_report
-
Extrahovaný_súbor_stiahnutie_id
Samozrejme, aby ste tieto kľúče dostali ako odpoveď na požiadavku dotazu, musia byť špecifikované v požiadavke (pre zostavy) alebo nezabudnite zadať požiadavku pomocou funkcie extrakcie (pre vyčistené dokumenty)
Volanie API kvóty
Použitá metóda − POST
Adresa volania - https:///tecloud/api/v1/file/quota
Ak chcete skontrolovať zostávajúcu kvótu v cloude, použite dotaz na kvótu. Telo požiadavky je prázdne.
Príklad odpovede na žiadosť o kvótu
{
"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
Toto API bolo vyvinuté pred Threat Prevention API a je určené len pre lokálne zariadenia. Zatiaľ to môže byť užitočné iba vtedy, ak potrebujete Threat Extraction API. Pre emuláciu hrozieb je lepšie použiť bežné rozhranie Threat Prevention API. Zapnúť TP API pre SG a nakonfigurujte kľúč API, z ktorého musíte postupovať podľa krokov
Teraz sa pozrime bližšie na funkcie te и ťažba v tomto API.
Pre komponent te poskytnutý slovník te_options v požiadavkách na upload/query a kľúče v tejto požiadavke sa úplne zhodujú s kľúčmi v te
Príklad žiadosti o emuláciu súboru vo Win10 s prehľadmi
{
"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"]
}
}
]
}
Pre komponent ťažba poskytnutý slovník možnosti čistenia. Táto požiadavka špecifikuje metódu čistenia: konvertovať do PDF, vymazať aktívny obsah alebo vybrať režim v súlade s profilom Prevencia hrozieb (je uvedený názov profilu). Skvelá vec na odpovedi na požiadavku extrakčného API pre súbor je, že v odpovedi na túto požiadavku dostanete vyčistenú kópiu ako zašifrovaný reťazec base64 (na stiahnutie súboru nemusíte zadávať požiadavku na dopyt a hľadať ID dokument)
Príklad žiadosti o vymazanie súboru
{
"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
}
}]
}
Odpovedzte na žiadosť
{
"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": ""
}
}]
}
Napriek skutočnosti, že na získanie vyčistenej kópie je potrebných menej žiadostí API, považujem túto možnosť za menej výhodnú a pohodlnú ako žiadosť o údaje formulára používaná v
Zbierky poštárov
V Postman som vytvoril kolekcie pre Threat Prevention API aj Threat Prevention API pre Security Gateway, ktoré predstavujú najbežnejšie požiadavky API. Aby sa server IP/url API a kľúč automaticky nahradili požiadavkami a aby sa po stiahnutí súboru zapamätalo množstvo hash sha256, v kolekciách boli vytvorené tri premenné (nájdete ich v nastaveniach kolekcie Upraviť -> Premenné): te_api (povinné), api_key (vyžaduje sa vyplniť, okrem prípadov, keď používate TP API s lokálnymi zariadeniami), sha256 (nechajte prázdne, nepoužíva sa v TP API pre SG).
Príklady použitia
V komunite
Zdroj: hab.com