Ta članek bo koristen tistim, ki poznajo tehnologije Check Point za emulacijo datotek (Emulacija groženj) in proaktivno čiščenje datotek (Threat Extraction) in želijo narediti korak proti avtomatizaciji teh nalog. Check Point ima , ki deluje tako v oblaku kot na lokalnih napravah, in funkcionalno je enak preverjanju datotek v prometu web/smtp/ftp/smb/nfs. Ta članek je delno avtorska interpretacija niza člankov iz uradne dokumentacije, vendar temelji na lastnih izkušnjah in lastnih primerih. Prav tako v članku najdete avtorska zbiranja Postman za delo z Threat Prevention API.
Glavne okrajšave
Threat Prevention API deluje s tremi glavnimi komponentami, ki se v API-ju kličeta skozi naslednje besedilne vrednosti:
av — komponenta Anti-Virus, odgovorna za analizo znanih groženj.
te — komponenta Threat Emulation, odgovorna za preverjanje datotek v peskovniku in izdajo sodbe zlonamerna (malicious)/čista (benign) po emulaciji.
extraction — komponenta Threat Extraction, ki odgovarja za hitro konverzijo uradnih dokumentov v varno obliko (iz katere se odstrani vsa potencialno škodljiva vsebina), za hitro dostavo uporabnikom/sistemom.
Struktura API in glavne omejitve
Threat Prevention API uporablja le 4 poizvedbe — upload, query, download in quota. V glavi vseh štirih poizvedb je treba poslati API ključ, z uporabo parametra Authorization. Na prvi pogled se struktura lahko zdi precej preprosta, kot v , vendar je število polj v poizvedbah upload in query ter struktura teh poizvedb precej kompleksna. Te lahko funkcionalno primerjamo s profili Threat Prevention v politiki varnosti prehodov/peskovnika.
Trenutno je izšla edina različica Threat Prevention API — 1.0, v URL-ju za API klice je treba navesti v1 v delu, kjer je treba navesti različico. Za razliko od Management API je obvezno navesti različico API v URL-ju, sicer poizvedba ne bo izvedena.
Komponenta Anti-Virus ob klicu brez drugih komponent (te, extraction) trenutno podpira le poizvedbe query z md5 hash vsotami. Threat Emulation in Threat Extraction podpira tudi sha1 in sha256 hash vsote.
Zelo pomembno je, da ne naredite napak v poizvedbah! Poizvedba je lahko izvedena brez napak, vendar ne povsem. Malce prehitro bomo pregledali, kaj se lahko zgodi ob napakah/tipkarskih napakah v poizvedbah.
Zahteva z napako v besedi reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}V odgovoru ne bo napake, a informacije o poročilih ne bodo na voljo.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahteva je bila povsem odgovorjena."
},
"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": "Zahteva je bila povsem odgovorjena."
}
}
}
]
}To pa je zahteva brez napake v ključu reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Prejeli smo odgovor, ki že vsebuje id za prenos poročil.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahteva je bila povsem odgovorjena."
},
"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": "Zahteva je bila povsem odgovorjena."
}
}
}
]
}Če pa pošljete napačen/zastarel API ključ, bomo v odgovoru prejeli napako 403.
SandBlast API: v oblaku in na lokalnih napravah.
API zahteve lahko pošiljamo napravam Check Point, na katerih je vklopljen komponent (blade) Threat Emulation. Kot naslov za zahteve je treba uporabiti ip/url naprave in vrata 18194 (na primer — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию izklopljen in ključa Authorization v glavi zahtev ni potrebno pošiljati.
API zahteve v oblak CheckPoint je treba pošiljati na naslov te.checkpoint.com (na primer — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Na lokalnih napravah Threat Extraction še ni podprt po standardu in ga je treba uporabljati (o tem bomo podrobneje govorili na koncu članka).
Lokalne naprave ne podpirajo poizvedbe quota.
Drugače ni razlik med poizvedbami na lokalnih napravah in oblakom.
Klic Upload API
Uporabljen postopek je — POST
Naslov za klic je — https://<service_address>/tecloud/api/v1/file/upload
Poizvedba je sestavljena iz dveh delov (form-data): datoteke namenjene emulaciji/čiščenju in telesa poizvedbe s tekstom.
Tekstovna poizvedba ne more biti prazna, lahko pa ne vsebuje nobene konfiguracije. Da bi bila poizvedba uspešna, je potrebno poslati vsaj naslednji tekst v poizvedbi:
Potrebni minimum za poizvedbo upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
Authorization: <api_key>
Telo
{
«request»: {
}
}
Datoteka
Datoteka
V tem primeru bo datoteka za obdelavo prispela v skladu s privzetimi parametri: komponenta — te, slike OS — Win XP in Win 7, brez generiranja poročila.
Komentarji k osnovnim poljem v tekstovni poizvedbi:
file_name in file_type lahko ostanejo prazna ali se ne pošiljata sploh, saj to ni posebej koristna informacija pri nalaganju datoteke. V API odgovoru se bodo ta polja avtomatsko izpolnila na podlagi imena nalagane datoteke, informacije v predpomnilniku pa bo vseeno treba iskati po md5/sha1/sha256 hash-ih.
Primer poizvedbe s praznima file_name in file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — seznam, v katerem je naveden potreben funkcionalnost pri obdelavi v peščeni škatli — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Če ta parameter ne bo poslan, bo vključen le privzet komponent — te (Threat Emulation).
Za vključitev preverjanja v treh razpoložljivih komponentah je treba te komponente navesti v API poizvedbi.
Primer poizvedbe s preverjanjem v av, te in extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Ključi v razdelku te
images — seznam, v katerem morajo biti navedeni slovarji z id in številko revizije operacijskih sistemov, v katerih bo izvedena preveritev. ID in številke revizij so enake za vse lokalne naprave in oblak.
Seznam operacijskih sistemov in revizij
Available OS Image ID
Revision
Image OS and Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 in 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
Če ključ images ni naveden, se bo emulacija izvajala z uporabo slik, ki jih priporoča Check Point (trenutno so to Windows XP in Windows 7). Te slike so priporočene zaradi najboljšega ravnovesja med zmogljivostjo in stopnjo prestrezanja.
poročila — seznam poročil, ki jih zahtevamo v primeru, da se izkaže, da je datoteka zlonamerna. Na voljo so naslednje možnosti:
povzetek — .tar.gz arhiv, ki vsebuje poročilo o emulaciji po z vsem zahtevanih slikah (kot html stran, ter komponente, kot so videoposnetek iz emulirane OS, dump omrežnega prometa, poročilo v json, ter sam vzorec v zaščitenem arhivu). V odgovoru iščemo ključ — summary_report za nadaljnje prenos poročila.
pdf — dokument o emulaciji v enotni sliki, ki jo mnogi poznajo iz Smart Console. V odgovoru iščemo ključ — pdf_report za nadaljnje prenos poročila.
xml — dokument o emulaciji v enotni slika, primerna za nadaljnje razčlenjevanje parametrov v poročilu. V odgovoru iščemo ključ — xml_report za nadaljnje prenos poročila.
tar — .tar.gz arhiv, ki vsebuje poročilo o emulaciji v enotni zahtevanih slikah (kot html stran, ter komponente, kot so videoposnetek iz emulirane OS, dump omrežnega prometa, poročilo v json, ter sam vzorec v zaščitenem arhivu). V odgovoru iščemo ključ — full_report za nadaljnje prenos poročila.
Kaj je notri v poročilu povzetek
Ključi full_report, pdf_report, xml_report so v slovarju za vsak OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahteva je bila popolnoma odgovorjena."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "zlonamerno",
"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": "zlonamerno",
"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": "zlonamerno",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahteva je bila popolnoma odgovorjena."
}
}
}
]
}Ključ summary_report je edini za celotno emulacijo.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahtev je u potpunosti obrađen."
},
"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": "Zahtev je u potpunosti obrađen."
}
}
}
]
}Možete istovremeno zatražiti tar, xml i pdf izveštaje, kao i summary, tar i xml. Nije moguće istovremeno zatražiti summary izveštaj i pdf.
Ključevi u odeljku extraction
Za vađenje pretnji koristi se samo dva ključa:
method — pdf (konverzija u pdf, koristi se po defaultu) ili clean (bršenje aktivnog sadržaja).
extracted_parts_codes — lista kodova za brisanje aktivnog sadržaja, primenjuje se samo za metodu clean
Kodovi za brisanje sadržaja iz datoteka
Koda
Opis
1025
Linked Objects
1026
Macros and Code
1034
Sensitive Hyperlinks
1137
PDF GoToR Actions
1139
PDF Launch Actions
1141
PDF URI Actions
1142
PDF Sound Actions
1143
PDF Movie Actions
1150
PDF JavaScript Actions
1151
PDF Submit Form Actions
1018
Database Queries
1019
Embedded Objects
1021
Fast Save Data
1017
Custom Properties
1036
Statistic Properties
1037
Summary Properties
Za preuzimanje očišćene kopije potrebno je još poslati zahtev query (o njemu će biti reči kasnije) kroz nekoliko sekundi, navodeći hash sumu datoteke i komponentu extraction u tekstu zahteva. Očišćenu datoteku možete preuzeti pomoću id-a iz odgovora na zahtev query — extracted_file_download_id. Ponovo, da se malo unapred pozabavimo, navodim primere zahteva i odgovora query za pronalaženje id-a za preuzimanje očišćenog dokumenta.
Zahtev query za pronalaženje ključa extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Odgovor na zahtev query (pronađite ključ extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahteva je bila popolnoma obdelana."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"ekstrakcija"
],
"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": "Makri in Koda",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potencialno zlo vsebino je bilo mogoče izvleči",
"protection_type": "Pretvorba v PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Aktivna vsebina je bila najdena - XLS datoteka je bila pretvorjena v PDF",
"scrub_method": "Pretvori v PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Makri in Koda"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zahteva je bila popolnoma obdelana."
}
}
}
]
}Splošne informacije
V enem API klicu lahko pošljete samo eno datoteko za preverjanje.
Komponenta av ne potrebuje dodatnega razdelka s ključi, dovolj je navesti v slovarju. features.
Klic Query API.
Uporabljen postopek je — POST
Naslov za klic je — https://<service_address>/tecloud/api/v1/file/query
Preden pošljete datoteko za nalaganje (zahteva upload), je priporočljivo preveriti predpomnilnik peskovnika (zahteva query) za optimizacijo obremenitve strežnika API, saj je mogoče, da so že na strežniku API na voljo informacije in odločitev glede naložene datoteke. Klic vsebuje samo besedilni del. Obvezni del zahteve je sha1/sha256/md5 hash vsote datoteke. To lahko dobite v odgovoru na zahtevo upload.
Potrebno minimum za zahtevo query.
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Telo
{
«request»: {
«sha256»: <sha256 hash sum>
}
}
Primer odgovora na zahtevo upload, kjer so vidne sha1/md5/sha256 hash vsote.
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Datoteka je bila uspešno naložena."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "neznano"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Datoteka je bila uspešno naložena."
}
}
}
}Zahteva query mora biti idealno enaka zahtevi upload ali vsaj enako zasnovana, torej naj vsebuje manj polj kot zahteva upload. Če zahteva query vsebuje več polj, kot jih je imela zahteva upload, ne boste prejeli vseh potrebnih informacij.
Tukaj je primer odgovora na zahtevo query, kjer niso bili najdeni vsi zahtevani podatki.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Zahteva trenutno ne more biti v celoti obdelana."
},
"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": "Zahteva je bila v celoti obdelana."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Želene datoteke ni bilo mogoče najti. Prosimo, naložite jo."
}
}
}
]
}Prosimo, bodite pozorni na polja. code in label. Ta polja se pojavijo trikrat v slovarjih status. Najprej vidimo globalni ključ "code": 1006 in "label": "PARTIALLY_FOUND". Nato se ti ključi pojavljajo pri vsakem posameznem komponentu, ki smo ga zahtevali — te in extraction. In če je pri te jasno, da so podatki najdeni, pa za extraction informacije manjkajo.
Tako je izgledala zahteva query za zgoraj navedeni primer.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Če pošljete zahtevo query brez komponente extraction.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Potem bo v odgovoru na voljo polna informacija ("code": 1001, "label": "FOUND").
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Заявка была полностью обработана."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "вредоносный",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "найден",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "вредоносный",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Заявка была полностью обработана."
}
}
}
]
}Если в кэше нет никакой информации, то в ответе будет «label»: «NOT_FOUND»
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Не удалось найти запрашиваемый файл. Пожалуйста, загрузите его."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "неизвестно"
},
"status": "не найден",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Не удалось найти запрашиваемый файл. Пожалуйста, загрузите его."
}
}
}
]
}В одном API-вызове можно отправить сразу несколько хэш-сумм на проверку. В ответе будут возвращены данные в том же порядке, в каком они были отправлены в запросе.
Пример запроса query с несколькими sha256-суммами
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Ответ на запрос query с несколькими sha256-суммами
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Запрос полностью обработан."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "вредоносный"
},
"status": "найден",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "вредоносный",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Запрос полностью обработан."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Не удалось найти запрашиваемый файл. Пожалуйста, загрузите его."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "неизвестно"
},
"status": "не найден",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Не удалось найти запрашиваемый файл. Пожалуйста, загрузите его."
}
}
}
]
}Запрос нескольких хеш-сумм в одном запросе также положительно скажется на производительности API сервера.
Вызов API загрузки
Uporabljen postopek je — POST (согласно документации), GET тоже работает (и может показаться более логичным)
Naslov za klic je — https://<service_address>/tecloud/api/v1/file/download?id=<id>
В заголовке необходимо передать API-ключ, тело запроса — пустое, id для загрузки передается в URL.
В ответ на запрос query, если эмуляция завершена и при загрузке файла были запрошены отчеты, будут видны id для загрузки отчетов. Если запрашивается очищенная копия, следует искать id для загрузки очищенного документа.
Таким образом, ключами в ответе на запрос query, содержащими значение id для загрузки, могут быть:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Для получения этих ключей в ответе на запрос query их необходимо указать в запросе (для отчетов) или не забыть сделать запрос по функции extraction (для очищенных документов)
Вызов API квоты
Uporabljen postopek je — POST
Naslov za klic je — https://<service_address>/tecloud/api/v1/file/quota
Для проверки оставшейся квоты в облаке используется запрос quota. Тело запроса пустое.
Пример ответа на запрос quota
{
"response": [
{
"remain_quota_hour": 1250,
"remain_quota_month": 10000000,
"assigned_quota_hour": 1250,
"assigned_quota_month": 10000000,
"hourly_quota_next_reset": "1599141600",
"monthly_quota_next_reset": "1601510400",
"quota_id": "TEST",
"cloud_monthly_quota_period_start": "1421712300",
"cloud_monthly_quota_usage_for_this_gw": 0,
"cloud_hourly_quota_usage_for_this_gw": 0,
"cloud_monthly_quota_usage_for_quota_id": 0,
"cloud_hourly_quota_usage_for_quota_id": 0,
"monthly_exceeded_quota": 0,
"hourly_exceeded_quota": 0,
"cloud_quota_max_allow_to_exceed_percentage": 1000,
"pod_time_gmt": "1599138715",
"quota_expiration": "0",
"action": "ALLOW"
}
]
}Threat Prevention API for Security Gateway
Ta API je bil razvit pred Threat Prevention API in je zasnovan samo za lokalne naprave. Trenutno je lahko koristen le, če potrebujete Threat Extraction API. Za Threat Emulation je bolje uporabiti običajni Threat Prevention API. Da bi omogočili TP API za SG in konfigurirali API ključ, je potrebno upoštevati korake iz . Priporočam, da posebno pozornost namenite koraku 6b in preverite dostopnost strani https:///UserCheck/TPAPI , saj v primeru negativnega rezultata nadaljnja konfiguracija nima smisla. Na ta URL bodo poslana vsa API klicanja. Vrsta klica (upload/query) se ureja v ključu telesa klica — request_name. Z obveznimi čelnimi ključi so tudi — api_key (izredno ga je treba shraniti med konfiguracijo) in protocol_version (trenutno je veljavna različica 1.1). Uradno dokumentacijo za ta API lahko najdete v . K relativnim prednostim sodi možnost pošiljanja več datotek hkrati za emulacijo, saj se datoteke pošiljajo v obliki besedilne vrstice base64. Za kodiranje/dekodiranje datotek v/iz base64 lahko uporabite spletni pretvornik v Postmanu, na primer — . V praktične namene pri pisanju kode je priporočljivo uporabiti vgrajene metode encode in decode.
Zdaj se ustavimo podrobneje pri funkcijah te in extraction v tem API-ju.
Za komponento te je predviden slovar te_options v klicanju upload/query, ključi pa v tem klicu popolnoma sovpadajo s ključi te v .
Primer klica za emulacijo datoteke v Win10 z poročili
{
"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"]
}
}
]
}Za komponento extraction je predviden slovar scrub_optionsV tem zahtevku je navedena metoda čiščenja: pretvorba v PDF, odstranjevanje aktivne vsebine ali pa izberite način v skladu s profilom za preprečevanje groženj (navedite ime profila). Posebnost odgovora na API zahtevek za ekstrakcijo datoteke je, da dobite očiščen izvod v odgovoru na to zahtevo v obliki šifriranega niza base64 (ni potrebno pošiljati poizvedbe in iskati id za nalaganje dokumenta).
Primer zahteve za čiščenje datoteke
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Odgovor na zahtevek
{
"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": "Izvleči potencialno zlonamerno vsebino",
"protection_type": "Pretvorba v PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT datoteka je bila pretvorjena v PDF",
"scrub_method": "Pretvorba v PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Čeprav je za pridobitev očiščenega izvoda potrebno manj API zahtevkov, menim, da je ta možnost manj zaželena in udobna v primerjavi z zahtevo form-data, ki se uporablja v .
Postman zbirke
Ustvaril sem zbirke v Postman za Threat Prevention API ter Threat Prevention API za Security Gateway, kjer so predstavljene najpogostejše API zahteve. Da se IP/URL API strežnika in ključ avtomatsko vstavljata v zahtevke, prav tako pa se shranjuje hash vrednost sha256 po nalaganju datoteke, so znotraj zbirk ustvarjene tri spremenljivke (te lahko najdete v nastavitvah zbirke Uredi -> Spremenljivke): te_api (potrebno izpolniti), api_key (potrebno izpolniti, razen v primeru uporabe TP API z lokalnimi napravami), sha256 (pustiti prazno, v TP API za SG ni uporabljeno).
Примери за употреба
V skupnosti so predstavljeni skripti, napisani v Pythonu, ki preverjajo datoteke iz želenega direktorija tako preko , kot tudi . S sodelovanjem z Threat Prevention API se vaše možnosti za preverjanje datotek znatno širijo, saj lahko zdaj preverjate datoteke kar na več platformah (zanimivo je preverjanje v , in Check Point sandbox), Files can be obtained not only from network traffic but also retrieved from any network drives and, for example, CRM systems.
Izvor: habr.com
