Ky artikull do të jetë i dobishëm për ata që janë të njohur me teknologjitë Check Point për emulimin e skedarëve (Threat Emulation) dhe pastrimin proaktiv të skedarëve (Threat Extraction) dhe duan të hedhin një hap drejt automatizimit të këtyre detyrave. Check Point ka , i cili funksionon si në cloud, ashtu edhe në pajisjet lokale, dhe nga ana funksionale është identik me kontrollin e skedarëve në rrjedhat e trafikut web/smtp/ftp/smb/nfs. Ky artikull është pjesërisht një interpretim autorial i një serie artikujsh nga dokumentacioni zyrtar, por i ndërtuar mbi përvojën time praktike të përdorimit dhe mbi shembujt e mi. Gjithashtu, në artikull do të gjeni koleksione autoriale Postman për punë me Threat Prevention API.
Shkurtesat kryesore
Threat Prevention API punon me tre komponentë kryesorë, të cilët në API thirren përmes vlerave të mëposhtme tekstuale:
av — komponenti Anti-Virus, përgjegjës për analizën me nënshkrime të kërcënimeve të njohura.
te — komponenti Threat Emulation, përgjegjës për kontrollin e skedarëve në sandbox dhe për dhënien e verdiktit keqdashës (malicious)/i pastër (benign) pas emulimit.
extraction — komponenti Threat Extraction, përgjegjës për konvertimin e shpejtë të dokumenteve të zyrës në një formë të sigurt (ku hiqet i gjithë përmbajtja potencialisht e dëmshme), me qëllim dorëzimin e shpejtë te përdoruesit/sistemet.
Struktura e API dhe kufizimet kryesore
Threat Prevention API përdor vetëm 4 kërkesa — upload, query, download dhe quota. Në header për të katër kërkesat duhet të dërgohet çelësi API duke përdorur parametrin Authorization. Në pamje të parë, struktura mund të duket shumë më e thjeshtë se te , por numri i fushave në kërkesat upload dhe query, si dhe struktura e këtyre kërkesave, janë mjaft komplekse. Nga ana funksionale, ato mund të krahasohen me profilet Threat Prevention në politikën e sigurisë së gateway/sandbox.
Aktualisht, është lëshuar vetëm një version i Threat Prevention API — 1.0; në URL për thirrjet API duhet të specifikoni v1 në pjesën ku kërkohet versioni. Ndryshe nga Management API, specifikimi i versionit të API në adresën URL është i detyrueshëm, përndryshe kërkesa nuk do të ekzekutohet.
Komponenti Anti-Virus, kur thirret pa komponentë të tjerë (te, extraction), aktualisht mbështet vetëm kërkesa query me hash md5. Threat Emulation dhe Threat Extraction mbështesin gjithashtu hash sha1 dhe sha256.
Është shumë e rëndësishme të mos bëni gabime në kërkesa! Kërkesa mund të përpunohet pa gabim, por jo plotësisht. Duke e paraprirë pak, le të shohim çfarë mund të ndodhë kur në kërkesa ka gabime shtypi/gabime drejtshkrimore.
Kërkesë me gabim shtypi në fjalën reports (reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Në përgjigje nuk do të ketë gabim, por nuk do të ketë fare informacion për raportet.
{
"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."
}
}
}
]
}Ndërsa për një kërkesë pa gabim shtypi në çelësin reports
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Marrim një përgjigje që tashmë përmban ID-të për shkarkimin e raporteve.
{
"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."
}
}
}
]
}Nëse dërgoni një çelës API të pasaktë ose të skaduar, në përgjigje do të merrni gabimin 403.
SandBlast API: në cloud dhe në pajisje lokale
Kërkesat API mund të dërgohen te pajisjet Check Point ku është aktivizuar komponenti (blade) Threat Emulation. Si adresë për kërkesat duhet të përdorni IP/URL-në e pajisjes dhe portën 18194 (për shembull — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию e çaktivizuar dhe çelësi Authorization në header-at e kërkesave mund të mos dërgohet fare.
Kërkesat API drejt cloud-it CheckPoint duhet të dërgohen në adresën te.checkpoint.com (për shembull — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Në pajisjet lokale, Threat Extraction ende nuk mbështetet në mënyrën standarde dhe duhet përdorur (për të do të flasim më hollësisht në fund të artikullit).
Pajisjet lokale nuk mbështesin kërkesat quota.
Për pjesën tjetër, nuk ka dallime midis kërkesave për pajisjet lokale dhe atyre për cloud-in.
Thirrja e Upload API
Metoda e përdorur — POST
Adresa për thirrje — https://<service_address>/tecloud/api/v1/file/upload
Kërkesa përbëhet nga dy pjesë (form-data): skedari i destinuar për emulim/pastrim dhe trupi i kërkesës me tekst.
Kërkesa tekstuale nuk mund të jetë bosh, por mund të mos përmbajë asnjë konfigurim. Që kërkesa të jetë e suksesshme, duhet të dërgohet të paktën teksti i mëposhtëm në kërkesë:
Minimumi i nevojshëm për kërkesën upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
Authorization: <api_key>
Body
{
«request»: {
}
}
Skedari
Skedari
Në këtë rast, skedari do të dërgohet për përpunim sipas parametrave të parazgjedhur: komponenti — te, imazhet e OS — Win XP dhe Win 7, pa gjenerim raporti.
Komente për fushat kryesore në kërkesën tekstuale:
file_name dhe file_type mund të lihen bosh ose të mos dërgohen fare, pasi ky nuk është informacion veçanërisht i dobishëm gjatë ngarkimit të skedarit. Në përgjigjen e API, këto fusha do të plotësohen automatikisht bazuar në emrin e skedarit të ngarkuar, ndërsa informacioni në cache gjithsesi do të duhet të kërkohet sipas shumave hash md5/sha1/sha256.
Shembull kërkese me file_name dhe file_type bosh
{
"request": {
"file_name": "",
"file_type": "",
}
}features — listë në të cilën përcaktohet funksionaliteti i nevojshëm gjatë përpunimit në sandbox — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Nëse ky parametër nuk dërgohet fare, do të përdoret vetëm komponenti i parazgjedhur — te (Threat Emulation).
Për të aktivizuar kontrollin në të tre komponentët e disponueshëm, duhet t’i specifikoni këta komponentë në kërkesën API.
Shembull kërkese me kontroll në av, te dhe extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Çelësat në seksionin te
images — listë brenda së cilës duhet të specifikohen fjalorë me id dhe numrin e revision të sistemeve operative, në të cilat do të kryhet kontrolli. ID-të dhe numrat e revision janë të njëjtë për të gjitha pajisjet lokale dhe cloud-in.
Lista e sistemeve operative dhe revisioneve
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 dhe 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
Nëse çelësi images nuk specifikohet fare, emulimi do të kryhet në imazhet e rekomanduara nga Check Point (aktualisht këto janë Win XP dhe Win 7). Këto imazhe rekomandohen duke u bazuar në balancën më të mirë midis performancës dhe catch rate.
raportet — lista e raporteve që kërkojmë në rast se skedari rezulton të jetë keqdashës. Janë të disponueshme opsionet e mëposhtme:
përmbledhje — arkiv .tar.gz që përmban raportin e emulimit për me gjithçka image-at e kërkuara (si faqe html, ashtu edhe komponentë të tillë si video nga OS i emulatorit, dump i trafikut të rrjetit, raport në json, si edhe vetë kampioni në arkiv të mbrojtur me fjalëkalim). Në përgjigje kërkojmë çelësin — summary_report për shkarkimin e mëtejshëm të raportit.
pdf — dokument emulimi në një image, të cilin shumë janë mësuar ta marrin përmes Smart Console. Në përgjigje kërkojmë çelësin — pdf_report për shkarkimin e mëtejshëm të raportit.
xml — dokument emulimi në një image, i përshtatshëm për parsimin e mëtejshëm të parametrave në raport. Në përgjigje kërkojmë çelësin — xml_report për shkarkimin e mëtejshëm të raportit.
tar — arkiv .tar.gz që përmban raportin e emulimit në një image-at e kërkuara (si faqe html, ashtu edhe komponentë të tillë si video nga OS i emulatorit, dump i trafikut të rrjetit, raport në json, si edhe vetë kampioni në arkiv të mbrojtur me fjalëkalim). Në përgjigje kërkojmë çelësin — full_report për shkarkimin e mëtejshëm të raportit.
Çfarë ka brenda raportit summary
Çelësat full_report, pdf_report, xml_report gjenden në fjalor për çdo 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."
}
}
}
]
}Ndërsa çelësi summary_report është një i vetëm për emulimin në tërësi
{
"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."
}
}
}
]
}Mund të kërkoni njëkohësisht raportet tar, xml dhe pdf, si edhe summary, tar dhe xml. Nuk është e mundur të kërkohet njëkohësisht raporti summary dhe pdf.
Çelësat në seksionin extraction
Për threat extraction përdoren vetëm dy çelësa:
method — pdf (konvertim në pdf, përdoret si parazgjedhje) ose clean (pastrim i përmbajtjes aktive).
extracted_parts_codes — lista e kodeve për heqjen e përmbajtjes aktive, vlen vetëm për metodën clean
Kodet për heqjen e përmbajtjes nga skedarët
Code
Përshkrimi
1025
Objekte të lidhura
1026
Makro dhe kod
1034
Hiperlidhje të ndjeshme
1137
Veprimet PDF GoToR
1139
Veprimet PDF Launch
1141
Veprimet PDF URI
1142
Veprimet PDF Sound
1143
Veprimet PDF Movie
1150
Veprimet PDF JavaScript
1151
Veprimet PDF Submit Form
1018
Pyetje ndaj bazës së të dhënave
1019
Objekte të integruara
1021
Të dhëna Fast Save
1017
Veti të personalizuara
1036
Veti statistikore
1037
Veti përmbledhëse
Për të shkarkuar një kopje të pastruar, do t'ju duhet të bëni edhe një kërkesë query (për të do të flitet më poshtë) pas disa sekondash, duke specifikuar hash-in e skedarit dhe komponentin extraction në trupin e kërkesës. Skedarin e pastruar do të mund ta merrni duke përdorur id nga përgjigjja e kërkesës query — extracted_file_download_id. Edhe një herë, duke paraprirë pak, po jap shembuj të kërkesës dhe përgjigjes query për të gjetur id-në për shkarkimin e dokumentit të pastruar.
Kërkesa query për të gjetur çelësin extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Përgjigjja ndaj kërkesës query (gjeni çelësin extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extraction"
],
"extraction": {
"method": "pdf",
"extract_result": "CP_EXTRACT_RESULT_SUCCESS",
"extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"time": "0.013",
"extract_content": "Macros and Code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potential malicious content extracted",
"protection_type": "Conversion to PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Active content was found - XLS file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros and Code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Të dhëna të përgjithshme
Në një thirrje API mund të dërgohet vetëm një skedar për kontroll.
Komponenti av nuk kërkon seksion shtesë me çelësa, mjafton të specifikohet në fjalor features.
Thirrja e Query API
Metoda e përdorur — POST
Adresa për thirrje — https://<service_address>/tecloud/api/v1/file/query
Përpara se të dërgoni skedarin për ngarkim (kërkesa upload), rekomandohet të kryeni kontrollin e cache-it të sandbox-it (kërkesa query) për të optimizuar ngarkesën në serverin API, pasi është e mundur që serveri API të ketë tashmë informacionin dhe verdiktin për skedarin që po ngarkohet. Thirrja përbëhet vetëm nga pjesa tekstuale. Pjesa e detyrueshme e kërkesës është shuma hash sha1/sha256/md5 e skedarit. Ajo, meqë ra fjala, mund të merret në përgjigjen e kërkesës upload.
Minimumi i nevojshëm për kërkesën query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Body
{
«request»: {
«sha256»: <sha256 hash sum>
}
}
Shembull i përgjigjes ndaj kërkesës upload, ku shihen shumat 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."
}
}
}
}Kërkesa query, përveç shumës hash, idealisht duhet të jetë e njëjtë me kërkesën upload që është dërguar (ose planifikohet të dërgohet), ose madje më e ngushtë (të përmbajë në query më pak fusha sesa në kërkesën upload). Nëse kërkesa query përmban më shumë fusha sesa kishte kërkesa upload, në përgjigje nuk do të merrni të gjithë informacionin e kërkuar.
Ja një shembull i përgjigjes ndaj kërkesës query, ku nuk u gjetën të gjitha të dhënat e kërkuara
{
"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."
}
}
}
]
}Kushtojini vëmendje fushave code dhe label. Këto fusha shfaqen tri herë në fjalorët status. Fillimisht shohim çelësin global «code»: 1006 dhe «label»: «PARTIALLY_FOUND». Më pas këta çelësa shfaqen për secilin komponent të veçantë që kemi kërkuar — te dhe extraction. Dhe nëse për te është e qartë që të dhënat janë gjetur, për extraction informacioni mungon.
Kështu dukej kërkesa query për shembullin e mësipërm
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Nëse dërgoni një kërkesë query pa komponentin extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Atëherë edhe në përgjigje do të ketë informacion të plotë («code»: 1001, «label»: «FOUND»)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Kërkesa është përpunuar plotësisht."
},
"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": "Kërkesa është përpunuar plotësisht."
}
}
}
]
}Nëse në cache nuk ka fare informacion, atëherë në përgjigje do të jetë «label»: «NOT_FOUND»
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Skedari i kërkuar nuk u gjet. Ju lutemi, ngarkojeni atë."
},
"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": "Skedari i kërkuar nuk u gjet. Ju lutemi, ngarkojeni atë."
}
}
}
]
}Në një thirrje API mund të dërgoni menjëherë disa hash sha256 për verifikim. Në përgjigje, të dhënat do të kthehen në të njëjtin rend siç janë dërguar në kërkesë.
Shembull i kërkesës query me disa hash sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Përgjigjja ndaj kërkesës query me disa hash sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Kërkesa është përpunuar plotësisht."
},
"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": "Kërkesa është përpunuar plotësisht."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Skedari i kërkuar nuk u gjet. Ju lutemi, ngarkojeni."
},
"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": "Skedari i kërkuar nuk u gjet. Ju lutemi, ngarkojeni."
}
}
}
]
}Dërgimi i disa hash-eve njëkohësisht në query ndikon pozitivisht edhe në performancën e serverit API.
Thirrja e Download API
Metoda e përdorur — POST (sipas dokumentacionit), GET gjithashtu funksionon (dhe mund të duket më logjike)
Adresa për thirrje — https://<service_address>/tecloud/api/v1/file/download?id=<id>
Në header duhet të dërgohet çelësi API, trupi i kërkesës është bosh, ndërsa id për shkarkim përcillet në adresën URL.
Në përgjigje të kërkesës query, nëse emulimi ka përfunduar dhe gjatë ngarkimit të skedarit janë kërkuar raporte, do të shfaqen id-të për shkarkimin e raporteve. Nëse kërkohet një kopje e pastruar, atëherë duhet të kërkohet id-ja për shkarkimin e dokumentit të pastruar.
Pra, çelësat në përgjigjen e kërkesës query që mund të përmbajnë vlerën e id-së për shkarkim janë:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Natyrisht, që këta çelësa të shfaqen në përgjigjen e kërkesës query, ato duhet të specifikohen në kërkesë (për raportet) ose nuk duhet harruar të bëhet një kërkesë me funksionin extraction (për dokumentet e pastruara)
Thirrja e Quota API
Metoda e përdorur — POST
Adresa për thirrje — https://<service_address>/tecloud/api/v1/file/quota
Për të kontrolluar kuotën e mbetur në cloud përdoret kërkesa quota. Trupi i kërkesës është bosh.
Shembull i përgjigjes për kërkesën 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
Ky API u zhvillua përpara Threat Prevention API dhe është i destinuar vetëm për pajisje lokale. Aktualisht, ai mund të jetë i dobishëm vetëm nëse ju nevojitet Threat Extraction API. Për Threat Emulation rekomandohet të përdorni Threat Prevention API standard. Për të aktivizuar TP API for SG dhe për të konfiguruar çelësin API, duhet të ndiqni hapat nga . Ju rekomandoj t’i kushtoni vëmendje hapit 6b dhe të kontrolloni disponueshmërinë e faqes https:///UserCheck/TPAPI sepse nëse rezultati është negativ, konfigurimi i mëtejshëm nuk ka kuptim. Të gjitha thirrjet API do të dërgohen në këtë URL. Lloji i thirrjes (upload/query) përcaktohet nga çelësi në trupin e kërkesës — request_name. Çelësa të detyrueshëm janë gjithashtu — api_key (duhet ta ruani mend gjatë procesit të konfigurimit) dhe protocol_version (aktualisht versioni i vlefshëm është 1.1). Dokumentacionin zyrtar për këtë API mund ta gjeni te . Ndër avantazhet relative mund të përmendet mundësia për të dërguar menjëherë disa skedarë për emulim gjatë ngarkimit të tyre, pasi skedarët dërgohen si varg teksti base64. Për të koduar/dekoduar skedarët në/nga base64, për qëllime demonstrimi në Postman mund të përdorni një konvertues online, për shembull — . Në praktikë, gjatë shkrimit të kodit, duhet të përdorni metodat e integruara encode dhe decode.
Tani le të ndalemi më në detaje te funksionet te dhe extraction në këtë API.
Për komponentin te parashikohet fjalori te_options në kërkesat upload/query, ndërsa çelësat në këtë kërkesë përputhen plotësisht me çelësat te në .
Shembull kërkese për emulimin e një skedari në Win10 me raporte
{
"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"]
}
}
]
}Për komponentin extraction parashikohet fjalori scrub_options. Në këtë kërkesë përcaktohet metoda e pastrimit: konvertimi në PDF, pastrimi nga përmbajtja aktive ose zgjedhja e mënyrës sipas profilit të Threat Prevention (jepet emri i profilit). Veçoria dalluese e përgjigjes ndaj kërkesës API me extraction për skedarin është se ju merrni një kopje të pastruar në përgjigje të kësaj kërkese në formën e një vargu të koduar base64 (nuk keni nevojë të bëni një kërkesë query dhe të kërkoni id-në për shkarkimin e dokumentit)
Shembull i kërkesës për pastrimin e skedarit
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Përgjigjja ndaj kërkesës
{
"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": ""
}
}]
} Megjithëse për të marrë një kopje të pastruar nevojiten më pak kërkesa API, unë e konsideroj këtë variant më pak të preferueshëm dhe më pak të përshtatshëm sesa kërkesa form-data e përdorur në .
Koleksionet Postman
Kam krijuar koleksione në Postman si për Threat Prevention API, ashtu edhe për Threat Prevention API for Security Gateway, ku janë paraqitur kërkesat API më të zakonshme. Që IP/URL e serverit API dhe çelësi të vendosen automatikisht në kërkesa, ndërsa hash-i sha256 pas ngarkimit të skedarit të ruhet gjithashtu, brenda koleksioneve janë krijuar tre variabla (mund t'i gjeni duke hapur te cilësimet e koleksionit Edit -> Variables): te_api (duhet plotësuar), api_key (duhet plotësuar, përveç rastit të përdorimit të TP API me pajisje lokale), sha256 (lëreni bosh, në TP API for SG nuk përdoret).
Shembuj përdorimi
Në komunitet janë publikuar skripte të shkruara në Python, të cilat kontrollojnë skedarët nga direktoria e nevojshme si përmes , ashtu edhe . Përmes ndërveprimit me Threat Prevention API, mundësitë tuaja për kontrollin e skedarëve zgjerohen ndjeshëm, pasi tani mund të kontrolloni skedarë menjëherë në disa platforma (interesante duket kontrolli në , dhe më pas në sandbox-in e Check Point), ndërsa skedarët mund të merren jo vetëm nga trafiku i rrjetit, por edhe nga çdo disk rrjeti dhe, për shembull, nga sistemet CRM.
Burimi: habr.com
