Acest articol va fi util celor care sunt familiarizați cu tehnologiile Check Point de emulare a fișierelor (Emularea Amenințărilor) și de curățare proactivă a fișierelor (Threat Extraction) și doresc să facă un pas spre automatizarea acestor sarcini. Check Point are , care funcționează atât în cloud, cât și pe dispozitive locale, și funcțional este identic cu verificarea fișierelor în fluxurile de trafic web/smtp/ftp/smb/nfs. Acest articol este parțial o interpretare autorală a unui set de articole din documentația oficială, dar bazată pe experiența proprie de exploatare și pe exemplele proprii. De asemenea, în articol veți găsi colecții autorale Postman pentru a lucra cu Threat Prevention API.
Abrevieri principale
Threat Prevention API funcționează cu trei componente principale, care în API sunt apelate prin următoarele valori textuale:
av — componenta Anti-Virus, responsabilă pentru analiza semnăturilor amenințărilor cunoscute.
te — componenta Threat Emulation, responsabilă pentru verificarea fișierelor într-un sandbox, și formularea unui verdict de malware (malicious)/curat (benign) după emulare.
extraction — componenta Threat Extraction, responsabilă pentru conversia rapidă a documentelor de birou într-o formă sigură (din care este eliminat tot conținutul potențial dăunător), în scopul livrării rapide către utilizatori/sisteme.
Structura API și principalele limitări
Threat Prevention API utilizează doar 4 cereri — upload, query, download și quota. În antetul pentru toate cele patru cereri trebuie să transmiteți cheia API, folosind parametrul Authorization. La prima vedere, structura poate părea mult mai simplă decât în , dar numărul de câmpuri în cererile upload și query și structura acestor cereri sunt destul de complexe. Acestea pot fi comparate funcțional cu profilurile Threat Prevention în politica de securitate a gateway-ului/sandbox-ului.
În prezent, a fost lansată o singură versiune a Threat Prevention API — 1.0, în URL pentru apelurile API ar trebui să specificați v1 în partea în care trebuie să specificați versiunea. Spre deosebire de Management API, specificarea versiunii API în adresa URL este obligatorie, altfel cererea nu va fi executată.
Componenta Anti-Virus, atunci când este apelată fără alte componente (te, extraction), în prezent suportă doar cererile query cu sume hash md5. Threat Emulation și Threat Extraction suportă de asemenea sume hash sha1 și sha256.
Este foarte important să nu faceți erori în cereri! Solicitarea poate fi executată fără erori, dar incomplet. Să anticipăm ce se poate întâmpla atunci când apar erori/greșeli de tipar în solicitări.
Solicitarea cu o greșeală de tipar în cuvântul reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}În răspuns nu va fi nicio eroare, dar, în același timp, informațiile despre rapoarte nu vor fi disponibile deloc.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Solicitarea a fost complet răspunsă."
},
"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": "Solicitarea a fost complet răspunsă."
}
}
}
]
}Iată o solicitare fără greșeală în cheie reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Primiți un răspuns în care deja sunt incluse id-urile pentru descărcarea rapoartelor.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Solicitarea a fost complet răspunsă."
},
"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": "Solicitarea a fost complet răspunsă."
}
}
}
]
}Dacă trimiteți o cheie API greșită/expirată, veți primi eroarea 403 în răspuns.
SandBlast API: în cloud și pe dispozitive locale.
Solicitările API pot fi trimise către dispozitivele Check Point, pe care este activat componenta (blade) Threat Emulation. Ca adresă pentru solicitări, trebuie utilizat ip/url-ul dispozitivului și portul 18194 (de exemplu — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию oprită și cheia Authorization în antetele cererilor poate să nu fie trimisă deloc.
Cererea API către cloud-ul CheckPoint trebuie trimisă la adresa te.checkpoint.com (de exemplu — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Pe dispozitivele locale, Threat Extraction nu este încă suportat în mod standard și trebuie utilizat (despre care vom discuta mai în detaliu la sfârșitul articolului).
Dispozitivele locale nu suportă cererea quota.
În rest, nu există diferențe între cererile pentru dispozitivele locale și cele pentru cloud.
Apelul Upload API
Metoda utilizată este — POST
Adresa pentru apel — https://<service_address>/tecloud/api/v1/file/upload
Cererea constă din două părți (form-data): un fișier destinat emulării/curățării și corpul cererii cu textul.
Cererea text nu poate fi goală, dar poate să nu conțină nicio configurație. Pentru ca cererea să fie reușită, trebuie trimisă cel puțin următorul text în cerere:
Minimul necesar pentru cererea upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Antete:
Authorization: <api_key>
Corpul
{
„request”: {
}
}
File
File
În acest caz, fișierul pentru procesare va ajunge conform parametrilor standard: componenta — te, imaginile OS — Win XP și Win 7, fără generarea unui raport.
Comentarii privind câmpurile principale din cererea text:
file_name și file_type pot fi lăsate goale sau pot să nu fie trimise deloc, deoarece acestea nu sunt informații foarte utile la încărcarea unui fișier. În răspunsul API, aceste câmpuri vor fi completate automat pe baza numelui fișierului încărcat, iar informațiile din cache vor trebui căutate în continuare după suma md5/sha1/sha256 hash.
Exemplu de cerere cu file_name și file_type goale
{
"request": {
"file_name": "",
"file_type": "",
}
}features — listă în care se specifică funcționalitatea necesară la procesare în sandbox — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Dacă acest parametru nu este transmis deloc, atunci va fi utilizată doar componenta standard — te(Threat Emulation).
Pentru a activa verificarea în cele trei componente disponibile, trebuie indicate aceste componente în cererea API.
Exemplu de cerere cu verificare în av, te și extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Cheile din secțiunea te
images — listă, în interiorul căreia trebuie indicate dicționare cu id și numărul versiunii sistemelor de operare în care va fi efectuată verificarea. ID-urile și numerele versiunii sunt aceleași pentru toate dispozitivele locale și cloud.
Lista sistemelor de operare și versiunilor
ID imagine OS disponibil
Revizie
Imagine OS și aplicație
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 și 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
Dacă cheia images nu este specificată, emularea se va desfășura în imaginile recomandate de Check Point (în prezent acestea sunt Win XP și Win 7). Aceste imagini sunt recomandate pe baza unui echilibru optim între performanță și rata de detecție.
rapoarte — lista rapoartelor pe care le solicităm în cazul în care fișierul se dovedește a fi dăunător. Următoarele opțiuni sunt disponibile:
rezumat — arhivă .tar.gz care conține raportul de emulare pentru toate imaginile solicitate (atât ca pagină html, cât și componente precum videoclipuri din OS-ul emulatorului, dump-ul traficului de rețea, raport în json și sample-ul într-o arhivă protejată cu parolă). În răspuns căutăm cheia — summary_report pentru descărcarea ulterioară a raportului.
pdf — document de emulare într-o imagine, pe care mulți sunt obișnuiți să-l primească prin Smart Console. În răspuns căutăm cheia — pdf_report imagine, convenabilă pentru parsarea ulterioară a parametrilor din raport. În răspuns căutăm cheia — pentru descărcarea ulterioară a raportului.
xml — document de emulare într-o imagine, pe care mulți sunt obișnuiți să-l primească prin Smart Console. În răspuns căutăm cheia — xml_report — arhivă .tar.gz care conține raportul de emulare în pentru descărcarea ulterioară a raportului.
tar full_report imagine, pe care mulți sunt obișnuiți să-l primească prin Smart Console. În răspuns căutăm cheia — imaginile solicitate (atât ca pagină html, cât și componente precum videoclipuri din OS-ul emulatorului, dump-ul traficului de rețea, raport în json și sample-ul într-o arhivă protejată cu parolă). În răspuns căutăm cheia — Ce conține raportul de rezumat pentru descărcarea ulterioară a raportului.
Cheile full_report, pdf_report, xml_report sunt în dicționar pentru fiecare OS
{ "response": [ { "status": { "code": 1001, "label": "FOUND", "message": "Cererea a fost complet răspunsă." }, "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": "Cererea a fost complet răspunsă." } } } ] }
Iar cheia summary_report — este una pentru emularea de ansambluIată că cheia summary_report există pentru întreaga emulare
{
"response": [
{
"status": {
"code": 1001,
"label": "GĂSIT",
"message": "Cererea a fost complet răspunsă."
},
"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": "GĂSIT",
"message": "Cererea a fost complet răspunsă."
}
}
}
]
}Se pot solicita simultan rapoartele tar și xml și pdf, se poate obține și un raport summary cùng tar și xml. Nu se poate solicita simultan un raport summary și pdf.
Cheile din secțiunea extraction
Pentru extragerea amenințărilor se folosesc doar două chei:
metodă — pdf (conversie în pdf, folosită implicit) sau clean (curățarea conținutului activ).
extracted_parts_codes — lista codurilor pentru eliminarea conținutului activ, aplicabilă doar pentru metoda clean
Coduri pentru eliminarea conținutului din fișiere
Cod
Description
1025
Obiecte legate
1026
Macros și cod
1034
Hyperlink-uri sensibile
1137
Acțiuni PDF GoToR
1139
Acțiuni Launch PDF
1141
Acțiuni URI PDF
1142
Acțiuni de sunet PDF
1143
Acțiuni video PDF
1150
Acțiuni JavaScript PDF
1151
Acțiuni de trimitere formular PDF
1018
Interogări de bază de date
1019
Obiecte încorporate
1021
Date de salvare rapidă
1017
Proprietăți personalizate
1036
Proprietăți statistice
1037
Proprietăți sumare
Pentru a descărca o copie curățată, va fi necesar să faceți o interogare query (despre care se va discuta mai târziu) după câteva secunde, specificând hash-ul fișierului și componenta extraction în textul interogării. Fișierul curățat poate fi recuperat folosind id-ul din răspunsul la interogarea query — extracted_file_download_id. Încă o dată, anticipând, ofer exemple de interogare și răspuns pentru căutarea id-ului pentru descărcarea documentului curățat.
Interogare query pentru căutarea cheii extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Răspunsul la interogarea query (găsiți cheia extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Cererea a fost răspunsă complet."
},
"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 și Cod",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Conținut potențial rău extras",
"protection_type": "Conversie în PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Conținut activ a fost găsit - fișierul XLS a fost convertit în PDF",
"scrub_method": "Conversie în PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros și Cod"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Cererea a fost răspunsă complet."
}
}
}
]
}Informații generale
Într-o apelare API, se poate trimite un singur fișier pentru verificare.
Componența av nu necesită o secțiune suplimentară cu chei, este suficient să o specifici în dicționar. features.
Apelarea Query API.
Metoda utilizată este — POST
Adresa pentru apel — https://<service_address>/tecloud/api/v1/file/query
Înainte de a trimite un fișier pentru încărcare (cererea upload), este recomandabil să efectuezi verificarea cache-ului sandbox (cererea query) pentru a optimiza încărcarea pe serverul API, deoarece informații și un verdict despre fișierul încărcat pot fi deja disponibile pe serverul API. Apelul constă doar în partea text. Parte obligatorie a cererii - suma hash sha1/sha256/md5 a fișierului. Aceasta poate fi obținută în răspunsul la cererea upload.
Minimum necesar pentru cererea query.
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Antete:
Authorization: <api_key>
Corpul
{
„request”: {
„sha256”: <sha256 hash sum>
}
}
Exemplu de răspuns la cererea upload, unde sunt vizibile sumele hash sha1/md5/sha256.
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Fișierul a fost încărcat cu succes."
},
"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": "Fișierul a fost încărcat cu succes."
}
}
}
}Cererea query, pe lângă suma hash, ar trebui ideal să fie la fel ca a fost (sau se preconizează a fi) cererea upload, sau chiar "deja" (să conțină în cererea query mai puține câmpuri decât în cererea upload). În cazul în care cererea query conține mai multe câmpuri decât a fost în cererea upload, veți primi un răspuns care nu conține toate informațiile necesare.
Iată un exemplu de răspuns la cererea query, unde nu au fost găsite toate datele necesare.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Cererea nu poate fi răspunsă complet în acest moment."
},
"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": "Cererea a fost răspunsă complet."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nu s-a putut găsi fișierul solicitat. Vă rugăm să-l încărcați."
}
}
}
]
}Vă rugăm să acordați atenție câmpurilor. code și label. Aceste câmpuri apar de trei ori în dicționarele status. La început vedem cheia globală „code”: 1006 și „label”: „PARTIALLY_FOUND”. Apoi, aceste chei apar pentru fiecare componentă specifică pe care am solicitat-o — te și extraction. Și dacă pentru te este clar că datele au fost găsite, pentru extraction informația lipsește.
Așa a arătat cererea query pentru exemplul de mai sus.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Dacă trimiteți cererea query fără componenta extraction.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Atunci și în răspuns va fi informația completă („code”: 1001, „label”: „FOUND”)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Cererea a fost complet răspunsă."
},
"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": "Cererea a fost complet răspunsă."
}
}
}
]
}Dacă nu există deloc informații în cache, atunci în răspuns va fi „label”: „NOT_FOUND”
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nu am putut găsi fișierul solicitat. Te rugăm să-l încarci."
},
"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": "Nu am putut găsi fișierul solicitat. Te rugăm să-l încarci."
}
}
}
]
}Într-o apelare API, poți trimite mai multe hash-uri pentru verificare. Răspunsul va returna datele în aceeași ordine în care au fost trimise în cerere.
Exemplu de cerere query cu mai multe hash-uri sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Răspunsul la cererea query cu mai multe hash-uri sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "GĂSIT",
"message": "Cererea a fost complet răspunsă."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicios"
},
"status": "găsit",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicios",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "GĂSIT",
"message": "Cererea a fost complet răspunsă."
}
}
},
{
"status": {
"code": 1004,
"label": "NE_GĂSIT",
"message": "Nu s-a putut găsi fișierul solicitat. Vă rugăm să-l încărcați."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "necunoscut"
},
"status": "ne_găsit",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NE_GĂSIT",
"message": "Nu s-a putut găsi fișierul solicitat. Vă rugăm să-l încărcați."
}
}
}
]
}Solicitarea mai multor hash-uri într-o singură întrebare va influența favorabil performanța serverului API.
Apelare API pentru descărcare
Metoda utilizată este — POST (conform documentației), metoda GET. de asemenea, funcționează (și poate părea mai logic)
Adresa pentru apel — https://<service_address>/tecloud/api/v1/file/download?id=<id>
În antet trebuie să se transmită cheia API, corpul cererii — gol, id-ul pentru descărcare se transmite în adresa URL.
Ca răspuns la cererea de întrebare, în cazul în care emularea a fost finalizată și la descărcarea fișierului au fost solicitate rapoarte, vor fi vizibile id-uri pentru descărcarea rapoartelor. În cazul în care se solicită o copie curățată, trebuie căutată id-ul pentru descărcarea documentului curățat.
Prin urmare, cheile din răspunsul cererii, care conțin valoarea id-ului pentru descărcare, pot fi:
summary_report
Ce conține raportul de rezumat
imagine, convenabilă pentru parsarea ulterioară a parametrilor din raport. În răspuns căutăm cheia —
— arhivă .tar.gz care conține raportul de emulare în
extracted_file_download_id
Desigur, pentru ca în răspunsul cererii să fie obținute aceste chei, trebuie specificate în cerere (pentru rapoarte) sau nu uitați să faceți o solicitare pentru funcția de extragere (pentru documente curățate)
Apelare API pentru cotă
Metoda utilizată este — POST
Adresa pentru apel — https://<service_address>/tecloud/api/v1/file/quota
Pentru a verifica cota disponibilă în cloud se folosește cererea quota. Corpul cererii este gol.
Exemplu de răspuns la cererea 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
Aceast API a fost dezvoltat înaintea Threat Prevention API și este destinat doar dispozitivelor locale. În prezent, poate fi util doar dacă aveți nevoie de Threat Extraction API. Pentru Threat Emulation, este mai bine să folosiți API-ul obișnuit Threat Prevention. Pentru a activa TP API pentru SG și a configura cheia API, trebuie să urmați pașii din . Recomand să acordați atenție pasului 6b și să verificați disponibilitatea paginii https:///UserCheck/TPAPI deoarece în cazul unui rezultat negativ, continuarea configurației nu are sens. La această adresă URL vor fi trimise toate apelurile API. Tipul apelului (upload/query) este reglementat în cheia corpului apelului — request_name. De asemenea, cheile obligatorii sunt — api_key (trebuie memorat în timpul configurării) și protocol_version (în prezent, versiunea actuală este 1.1). Documentația oficială pentru acest API o puteți găsi în . Printre avantajele relative se numără posibilitatea de a trimite mai multe fișiere pentru emulare simultan la încărcare, deoarece fișierele sunt trimise sub formă de șir de text base64. Pentru a codifica/deocodifica fișiere în/din base64, puteți folosi pentru scopuri demonstrative un convertor online în Postman, de exemplu — . În scopuri practice, când scrieți cod, ar trebui să folosiți metodele încorporate encode și decode.
Acum să ne oprim mai în detaliu asupra funcțiilor te și extraction din acest API.
Pentru componenta te se preconizează un dicționar te_options în cererile upload/query, iar cheile din această cerere coincid complet cu cheile te din .
Exemplu de cerere pentru emularea unui fișier în Win10 cu rapoarte
{
"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"]
}
}
]
}Pentru componenta extraction se preconizează un dicționar scrub_options. În această solicitare se specifică metoda de curățare: conversie în PDF, curățare de conținut activ sau alegerea modului conform profilului Threat Prevention (se indică numele profilului). Caracteristica distinctivă a răspunsului la solicitarea API pentru fișier este că obțineți o copie curățată în răspunsul la această solicitare sub formă de șir criptat base64 (nu trebuie să faceți o solicitare query și să căutați id-ul pentru a descărca documentul)
Exemplu de solicitare pentru curățarea unui fișier
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Răspuns la solicitare
{
"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": "Conversie în PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "Fișierul TXT a fost convertit în PDF",
"scrub_method": "Convertire în PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Deși pentru obținerea unei copii curățate sunt necesare mai puține solicitări API, consider această variantă mai puțin preferabilă și convenabilă în comparație cu solicitarea form-data, utilizată în .
Colecții Postman
Am creat colecții în Postman atât pentru Threat Prevention API, cât și pentru Threat Prevention API for Security Gateway, unde sunt prezentate cele mai frecvente solicitări API. Pentru ca ip/url-ul serverului API și cheia să fie incluse în solicitări automat, iar suma hash sha256 după încărcarea fișierului să fie, de asemenea, memorată, în interiorul colecțiilor au fost create trei variabile (le puteți găsi accesând setările colecției Edit -> Variables): te_api (trebuie completat), api_key (trebuie completat, cu excepția cazului în care se folosește TP API cu dispozitive locale), sha256 (lăsați gol, nu este utilizat în TP API for SG).
Exemple de utilizare
În comunitate sunt prezentate scripturi scrise în Python, care verifică fișiere din directorul dorit atât prin , sau . Prin interacțiunea cu Threat Prevention API, capacitățile dvs. de a verifica fișiere sunt semnificativ extinse, deoarece acum puteți verifica fișiere simultan pe mai multe platforme (interesantă este verificarea în , și apoi în sandboxul Check Point), iar fișierele sunt obținute nu doar din traficul de rețea, ci și din orice discuri de rețea și, de exemplu, din sistemele CRM.
Sursa: habr.com
