Questo articolo sarà utile a coloro che hanno familiarità con le tecnologie Check Point per l'emulazione dei file (Emulazione delle minacce) e la pulizia proattiva dei file (Estrazione delle minacce) e desiderano compiere un passo verso l'automazione di queste attività. Check Point offre , che funziona sia nel cloud che su dispositivi locali, e funzionalmente è identico al controllo dei file nei flussi di traffico web/smtp/ftp/smb/nfs. Questo articolo è in parte un'interpretazione originale di una serie di articoli dalla documentazione ufficiale, ma basata sulla mia esperienza operativa e su esempi personali. Troverete anche collezioni di Postman per lavorare con Threat Prevention API.
Principali abbreviazioni
Threat Prevention API lavora con tre componenti principali, che nell'API sono chiamati attraverso i seguenti valori testuali:
av — componente Anti-Virus, responsabile dell'analisi delle firme delle minacce conosciute.
te — componente Threat Emulation, responsabile del controllo dei file nella sandbox, e dell'emissione di un verdetto malevolo (malicious)/pulito (benign) dopo l'emulazione.
extraction — componente Threat Extraction, responsabile della rapida conversione dei documenti di Microsoft Office in un formato sicuro (da cui viene rimosso tutto il contenuto potenzialmente dannoso), al fine di una rapida consegna agli utenti/sistemi.
Struttura dell'API e principali limitazioni
Threat Prevention API utilizza solo 4 richieste — upload, query, download e quota. Nell'intestazione per tutte e quattro le richieste, è necessario fornire la chiave API, utilizzando il parametro Authorization. A prima vista, la struttura potrebbe sembrare molto più semplice rispetto a , ma il numero di campi nelle richieste upload e query e la struttura di queste richieste sono sufficientemente complesse. Possono essere confrontate funzionalmente con i profili di Threat Prevention nella politica di sicurezza del gateway/sandbox.
Attualmente, è stata rilasciata un'unica versione di Threat Prevention API — 1.0, nell'URL per le chiamate API è necessario specificare v1 nella parte in cui è richiesta l'indicazione della versione. A differenza di Management API, è obbligatorio specificare la versione API nell'URL, altrimenti la richiesta non verrà eseguita.
Il componente Anti-Virus, quando chiamato senza altri componenti (te, extraction) al momento supporta solo richieste query con hash md5. Threat Emulation e Threat Extraction supportano anche hash sha1 e sha256.
È molto importante non commettere errori nelle richieste! Una richiesta può essere eseguita senza errori, ma non completamente. Anticipando ciò, esamineremo cosa può accadere in caso di errori/o errori di battitura nelle richieste.
Richiesta con errore di battitura nella parola reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Nella risposta non ci saranno errori, ma non ci sarà alcuna informazione sui report.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente soddisfatta."
},
"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": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}Ecco una richiesta senza errori di battitura nella chiave reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Riceviamo una risposta che già contiene gli id per il download dei report.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente soddisfatta."
},
"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": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}Se invece si invia una chiave API errata/trascorsa, riceveremo un errore 403.
SandBlast API: nel cloud e sui dispositivi locali.
Le richieste API possono essere inviate ai dispositivi Check Point con il componente (blade) Threat Emulation attivato. Come indirizzo per le richieste è necessario utilizzare l'ip/url del dispositivo e la porta 18194 (ad esempio — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию disattivata e la chiave Authorization negli header delle richieste può non essere inviata affatto.
Le richieste API nel cloud CheckPoint devono essere inviate all'indirizzo te.checkpoint.com (ad esempio — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Sui dispositivi locali, Threat Extraction non è ancora supportato come standard e deve essere utilizzato (ne parleremo più dettagliatamente alla fine dell'articolo).
I dispositivi locali non supportano la richiesta quota.
Per il resto non ci sono differenze tra le richieste ai dispositivi locali e al cloud.
Chiamata Upload API
Il metodo utilizzato è – POST
Indirizzo per la chiamata – https://<service_address>/tecloud/api/v1/file/upload
La richiesta è composta da due parti (form-data): un file destinato all'emulazione/pulizia e il corpo della richiesta con il testo.
La richiesta testuale non può essere vuota, ma può non contenere alcuna configurazione. Affinché la richiesta sia efficace, è necessario inviare almeno il seguente testo nella richiesta:
Il minimo richiesto per la richiesta di upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Intestazioni:
Autorizzazione: <api_key>
Body
{
"request": {
}
}
File
File
In tal caso, il file verrà elaborato secondo i parametri predefiniti: componente – te, immagini OS – Win XP e Win 7, senza generare alcun rapporto.
Commenti sui campi principali nella richiesta testuale:
file_name e file_type possono essere lasciati vuoti o non inviati affatto, poiché non sono informazioni particolarmente utili durante il caricamento del file. Nella risposta dell'API, questi campi verranno compilati automaticamente in base al nome del file caricato, e le informazioni nella cache dovranno comunque essere cercate tramite le somme hash md5/sha1/sha256.
Esempio di richiesta con file_name e file_type vuoti
{
"request": {
"file_name": "",
"file_type": "",
}
}features — un elenco in cui viene specificata la funzionalità necessaria durante l'elaborazione in sandbox – av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Se questo parametro non viene fornito, verrà utilizzato solo il componente predefinito – te (Threat Emulation).
Per abilitare il controllo nei tre componenti disponibili, è necessario specificare questi componenti nella richiesta API.
Esempio di richiesta con controllo in av, te e extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Chiavi nella sezione te
images — un elenco in cui devono essere specificati i dizionari con id e numero di revisione dei sistemi operativi in cui sarà eseguito il controllo. Gli ID e i numeri di revisione sono identici per tutti i dispositivi locali e cloud.
Elenco dei sistemi operativi e delle revisioni
ID immagine OS disponibile
Revisione
Immagine OS e Applicazione
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 e 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
Se la chiave images non viene specificata affatto, l'emulazione avverrà utilizzando le immagini consigliate da Check Point (attualmente sono Win XP e Win 7). Queste immagini sono raccomandate per il miglior equilibrio tra prestazioni e catch rate.
report — elenco di report che richiediamo nel caso in cui il file risulti dannoso. Sono disponibili le seguenti opzioni:
summary — archivio .tar.gz contenente il report di emulazione per di tutto le immagini richieste (sia come pagina html che come componenti come video dall'OS dell'emulatore, dump del traffico di rete, report in json e il campione stesso in un archivio protetto da password). Nella risposta cerchiamo la chiave — summary_report per il successivo download del report.
pdf — documento di emulazione in un'unica immagine, che molti sono abituati a ricevere tramite Smart Console. Nella risposta cerchiamo la chiave — pdf_report per il successivo download del report.
xml — documento di emulazione in un'unica immagine, utile per il successivo parsing dei parametri nel report. Nella risposta cerchiamo la chiave — xml_report per il successivo download del report.
tar — archivio .tar.gz contenente il report di emulazione in un'unica le immagini richieste (sia come pagina html che come componenti come video dall'OS dell'emulatore, dump del traffico di rete, report in json e il campione stesso in un archivio protetto da password). Nella risposta cerchiamo la chiave — full_report per il successivo download del report.
Cosa c'è dentro il report summary
Le chiavi full_report, pdf_report, xml_report sono disponibili nel dizionario per ogni OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente soddisfatta."
},
"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": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}La chiave summary_report è unica per l'emulazione nel suo complesso
{
"response": [
{
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "maligno",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "maligno",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "trovato",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "maligno",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
}
}
}
]
}È possibile richiedere simultaneamente report tar, xml e pdf; si può richiedere anche summary insieme a tar e xml. Non è possibile richiedere simultaneamente il report summary e il pdf.
Le chiavi nella sezione estrazione
Per l'estrazione delle minacce vengono utilizzate solo due chiavi:
method — pdf (conversione in pdf, utilizzata per impostazione predefinita) o clean (pulizia del contenuto attivo).
codici parti estratte — elenco di codici per rimuovere contenuto attivo, applicabile solo al metodo clean
Codici per rimuovere contenuto dai file
Codice
Descrizione
1025
Oggetti collegati
1026
Macro e codice
1034
Hyperlink sensibili
1137
Azioni PDF GoToR
1139
Azioni di avvio PDF
1141
Azioni PDF URI
1142
Azioni sonore PDF
1143
Azioni video PDF
1150
Azioni JavaScript PDF
1151
Azioni di invio modulo PDF
1018
Query di database
1019
Oggetti incorporati
1021
Dati di salvataggio rapido
1017
Proprietà personalizzate
1036
Proprietà statistiche
1037
Proprietà di riepilogo
Per scaricare una copia pulita sarà necessario fare anche una richiesta query (di cui parleremo più avanti) dopo qualche secondo, indicando l'hash del file e il componente extraction nel testo della richiesta. Il file pulito potrà essere prelevato con l'id della risposta alla richiesta query — extracted_file_download_id. Ancora una volta, per anticipare, fornisco esempi di richiesta e risposta per cercare l'id per il download del documento pulito.
Richiesta query per cercare la chiave extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["estrazione"] ,
"extraction": {
"method": "pdf"
}
}
]
}Risposta alla richiesta query (trova la chiave extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente soddisfatta."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"estrazione"
],
"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": "Macro e Codice",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Contenuto potenzialmente dannoso estratto",
"protection_type": "Conversione in PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Contenuto attivo trovato - file XLS convertito in PDF",
"scrub_method": "Convertire in PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macro e Codice"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}Panoramica
È possibile inviare un solo file per verifica in una singola chiamata API.
Il componente av non richiede una sezione aggiuntiva con le chiavi, è sufficiente indicarlo nel dizionario. features.
Chiamata all'API Query
Il metodo utilizzato è – POST
Indirizzo per la chiamata – https://<service_address>/tecloud/api/v1/file/query
Prima di inviare un file per il caricamento (richiesta upload), è consigliabile effettuare un controllo della cache sandbox (richiesta query) per ottimizzare il carico sul server API, poiché potrebbe già esserci informazione e un verdetto sul file che si sta caricando. La chiamata consiste solo nella parte testuale. La parte obbligatoria della richiesta è il hash sha1/sha256/md5 del file. Questo, tra l'altro, può essere ottenuto nella risposta alla richiesta di upload.
Minimo necessario per la richiesta query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Intestazioni:
Autorizzazione: <api_key>
Body
{
"request": {
"sha256": <sha256 hash sum>
}
}
Esempio di risposta alla richiesta di upload, in cui sono visibili i hash sha1/md5/sha256
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Il file è stato caricato con successo."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "sconosciuto"
},
"status": "non_trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Il file è stato caricato con successo."
}
}
}
}La richiesta query, oltre all'hash, dovrebbe idealmente essere la stessa di quella della richiesta upload (o di quella che si prevede di fare), o addirittura "già" (contenere nella richiesta query meno campi rispetto alla richiesta upload). Nel caso in cui la richiesta query contenga più campi di quelli presenti nella richiesta upload, non riceverete tutte le informazioni richieste nella risposta.
Ecco un esempio di risposta alla richiesta query, in cui non sono stati trovati tutti i dati richiesti.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "La richiesta non può essere completamente soddisfatta in questo momento."
},
"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": "La richiesta è stata completamente soddisfatta."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Impossibile trovare il file richiesto. Si prega di caricarlo."
}
}
}
]
}Si prega di prestare attenzione ai campi. code e label. Questi campi si trovano tre volte nei dizionari di stato. Inizialmente vediamo la chiave globale "code": 1006 e "label": "PARTIALLY_FOUND". Successivamente, queste chiavi appaiono per ogni singolo componente che abbiamo richiesto — te e extraction. E se per te è chiaro che i dati sono stati trovati, per extraction le informazioni sono assenti.
Ecco com'era la richiesta query per l'esempio sopra.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Se inviate la richiesta query senza il componente extraction.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Anche nella risposta ci sarà informazioni complete ("code": 1001, "label": "FOUND").
{
"response": [
{
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "maligno",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "maligno",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
}
}
}
]
}Se non ci sono informazioni nella cache, nella risposta ci sarà "label": "NON_TROVATO"
{
"response": [
{
"status": {
"code": 1004,
"label": "NON_TROVATO",
"message": "Impossibile trovare il file richiesto. Si prega di caricarlo."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "sconosciuto"
},
"status": "non_trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NON_TROVATO",
"message": "Impossibile trovare il file richiesto. Si prega di caricarlo."
}
}
}
]
}In una chiamata API è possibile inviare più hash contemporaneamente per il controllo. I dati nella risposta verranno restituiti nello stesso ordine in cui sono stati inviati nella richiesta.
Esempio di richiesta query con più hash sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Risposta alla richiesta query con più hash sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "maligno"
},
"status": "trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "maligno",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
}
}
},
{
"status": {
"code": 1004,
"label": "NON_TROVATO",
"message": "Impossibile trovare il file richiesto. Si prega di caricarlo."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "sconosciuto"
},
"status": "non_trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NON_TROVATO",
"message": "Impossibile trovare il file richiesto. Si prega di caricarlo."
}
}
}
]
}Richiedere più hash in un'unica query avrà sicuramente un effetto positivo sulle prestazioni del server API.
Chiamata all'API Download
Il metodo utilizzato è – POST (secondo la documentazione), e username/password: admin/admin. funziona anche (e può sembrare più logico)
Indirizzo per la chiamata – https://<service_address>/tecloud/api/v1/file/download?id=<id>
Nel header è necessario fornire la chiave API, il corpo della richiesta deve essere vuoto e l'id per il download deve essere fornito nell'URL.
In risposta alla richiesta di query, se l'emulazione è stata completata e sono stati richiesti rapporti durante il caricamento del file, saranno visibili gli id per il download dei rapporti. Se si richiede una copia ripulita, è necessario cercare l'id per il download del documento ripulito.
In sintesi, le chiavi nella risposta alla query che contengono un valore id per il download possono essere:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Naturalmente, affinché nella risposta alla query vengano restituiti questi chiavi, devono essere specificati nella richiesta (per i rapporti) o non dimenticare di fare la richiesta per la funzione di estrazione (per i documenti ripuliti)
Chiamata all'API Quota
Il metodo utilizzato è – POST
Indirizzo per la chiamata – https://<service_address>/tecloud/api/v1/file/quota
Per controllare il credito rimanente nel cloud si usa la richiesta quota. Il corpo della richiesta è vuoto.
Esempio di risposta alla richiesta 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
Questa API è stata sviluppata prima della Threat Prevention API ed è destinata esclusivamente ai dispositivi locali. Al momento, può essere utile solo se hai bisogno della Threat Extraction API. Per la Threat Emulation è meglio utilizzare la normale Threat Prevention API. Per attivare TP API per SG e configurare la chiave API è necessario eseguire i passi di . Ti consiglio di prestare attenzione al passaggio 6b e controllare la disponibilità della pagina https:///UserCheck/TPAPI perché in caso di esito negativo la configurazione successiva non ha senso. A questo URL verranno inviati tutti i richiami API. Il tipo di chiamata (upload/query) è regolato nella chiave del corpo della chiamata — request_name. Sono obbligatorie anche le chiavi — api_key (è necessario memorizzarlo durante la configurazione) e protocol_version (al momento l'ultima versione è 1.1). Puoi trovare la documentazione ufficiale per questa API in . Tra i vantaggi relativi c'è la possibilità di inviare più file contemporaneamente per l'emulazione durante il caricamento, poiché i file vengono inviati come stringhe testuali base64. Per codificare/decodificare file da/a base64 è possibile utilizzare, a scopo dimostrativo, un convertitore online in Postman, ad esempio — . In pratica, durante la scrittura del codice, è consigliabile utilizzare i metodi integrati encode e decode.
Adesso concentriamoci sulle funzioni te e extraction in questa API.
Per il componente te è previsto un dizionario te_options nelle richieste upload/query, mentre le chiavi in questa richiesta corrispondono completamente alle chiavi te in .
Esempio di richiesta per emulare un file in Win10 con report
{
"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"]
}
}
]
}Per il componente extraction è previsto un dizionario scrub_options. In questa richiesta viene specificato il metodo di pulizia: conversione in PDF, rimozione di contenuti attivi oppure scegliere una modalità in base al profilo di Threat Prevention (indicare il nome del profilo). Una caratteristica distintiva della risposta alla richiesta API con extraction per il file è che si riceve una copia pulita in risposta a questa richiesta sotto forma di stringa cifrata base64 (non è necessario eseguire una richiesta query e cercare un id per caricare il documento)
Esempio di richiesta per la pulizia del file
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Risposta alla richiesta
{
"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": "Estrai contenuti potenzialmente dannosi",
"protection_type": "Conversione in PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "Il file TXT è stato convertito in PDF",
"scrub_method": "Convertire in PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Nonostante siano necessari meno richieste API per ottenere una copia pulita, considero questa opzione meno preferibile e comoda rispetto alla richiesta form-data utilizzata in .
Collezioni Postman
Ho creato collezioni in Postman sia per l'API di Threat Prevention che per l'API di Threat Prevention per Security Gateway, dove sono presentate le richieste API più comuni. Affinché l'IP/url del server API e la chiave siano inseriti automaticamente nelle richieste, e che il valore hash sha256 venga memorizzato dopo il caricamento del file, all'interno delle collezioni sono state create tre variabili (si possono trovare nelle impostazioni della collezione Modifica -> Variabili): te_api (richiesta compilazione), api_key (richiesta compilazione, tranne nel caso di utilizzo dell'API TP con dispositivi locali), sha256 (lasciare vuoto, non utilizzato nell'API TP for SG).
Esempi di utilizzo
Nella comunità sono disponibili script scritti in Python che controllano i file dalla directory desiderata sia tramite , sia . Attraverso l'interazione con l'API di Threat Prevention, le tue capacità di controllo dei file si ampliano notevolmente, poiché ora puoi controllare i file su più piattaforme contemporaneamente (è interessante il controllo su , e poi nella sandbox di Check Point), e i file possono essere ottenuti non solo dal traffico di rete, ma anche prelevati da qualsiasi disco di rete e, ad esempio, dai sistemi CRM.
Fonte: habr.com
