Questo articolo sarà utile a chi è familiare con le tecnologie Check Point di emulazione dei file (Emulazione delle Minacce) e pulizia proattiva dei file (Estrazione delle Minacce) e desidera fare un passo verso l'automazione di queste attività. Check Point offre , che funziona sia nel cloud che su dispositivi locali, e funzionalmente è equivalente al controllo dei file nei flussi di traffico web/smtp/ftp/smb/nfs. Questo articolo è in parte un'interpretazione personale di una serie di articoli dalla documentazione ufficiale, ma è basato sulla mia esperienza 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 vengono richiamati attraverso i seguenti valori testuali:
av — componente Anti-Virus, responsabile dell'analisi delle firme delle minacce conosciute.
ta — componente Threat Emulation, responsabile del controllo dei file in sandbox e della determinazione se siano malevoli (malicious) o puliti (benign) dopo l'emulazione.
extraction — componente di Threat Extraction, che si occupa della rapida conversione di documenti di Office in un formato sicuro (che rimuove tutto il contenuto potenzialmente dannoso), per garantire una rapida consegna agli utenti/sistemi.
Struttura API e principali limitazioni
Threat Prevention API utilizza solo 4 richieste — upload, query, download e quota. Nell'intestazione di tutte e quattro le richieste deve essere fornita 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 piuttosto 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 indicare v1 nella sezione dove è richiesta l'indicazione della versione. A differenza di Management API, indicare la versione API nell'URL è obbligatorio, altrimenti la richiesta non verrà eseguita.
Il componente Anti-Virus, quando viene chiamato senza altri componenti (te, extraction), supporta attualmente 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 un po', vediamo cosa può accadere in caso di errori/spronunci in una richiesta.
Richiesta con errore nella parola reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Non ci sarà alcun errore nella risposta, ma non ci sarà alcuna informazione sui rapporti.
{
"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 la richiesta senza errore 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 contenente già gli id per il download dei rapporti.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente evasa."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malware",
"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": "malware",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente evasa."
}
}
}
]
}Se viene inviato una chiave API errata o scaduta, riceveremo un errore 403 in risposta.
SandBlast API: nel cloud e su dispositivi locali.
È possibile inviare richieste API ai dispositivi Check Point in cui è attivato il componente (blade) Threat Emulation. Per le richieste, utilizzare l'indirizzo 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 non deve essere inviata nelle intestazioni delle richieste.
Le richieste API al cloud Check Point 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 nella configurazione standard e si deve utilizzare (di cui parleremo più in dettaglio 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 quelle al cloud.
Chiamata all'Upload API
Il metodo utilizzato è POST
L'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.
Il testo della richiesta non può essere vuoto, ma può non contenere alcuna configurazione. Affinché la richiesta abbia successo, è necessario inviare almeno il seguente testo nella richiesta:
Minimo necessario per la richiesta di upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Intestazioni:
Authorization: <api_key>
Corpo
{
«request»: {
}
}
File
File
In questo caso, il file verrà elaborato secondo i parametri predefiniti: componente — ta, immagini OS — Win XP e Win 7, senza generazione di report.
Commenti sui principali campi 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 hash md5/sha1/sha256.
Esempio di richiesta con file_name e file_type vuoti
{
"request": {
"file_name": "",
"file_type": "",
}
}features — un elenco che indica le funzionalità necessarie durante l'elaborazione in sandbox — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Se questo parametro non viene passato, verrà utilizzato solo il componente predefinito — te (Threat Emulation).
Per attivare il controllo nei tre componenti disponibili, è necessario specificare questi componenti nella richiesta API.
Esempio di richiesta con verifica 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 l'id e la versione dei sistemi operativi su cui verrà eseguita la verifica. L'id e i numeri di versione sono identici per tutti i dispositivi locali e per il cloud.
Elenco dei sistemi operativi e delle versioni
ID immagine OS disponibile
Versione
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 è specificata, l'emulazione avverrà con le immagini raccomandate da Check Point (attualmente si tratta di Win XP e Win 7). Queste immagini sono raccomandate per garantire il miglior equilibrio tra prestazioni e catch rate.
report — un 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 di tutto richiesti image (come pagina HTML, così come componenti come video da un sistema operativo emulato, dump del traffico di rete, report in json, così come il campione stesso in un archivio protetto da password). Nella risposta cerchiamo la chiave — summary_report per il successivo caricamento del report.
pdf — documento di emulazione in uno image, che molti sono abituati a ricevere tramite Smart Console. Nella risposta cerchiamo la chiave — pdf_report per il successivo caricamento del report.
xml — documento di emulazione in uno image, comodo per l'analisi successiva dei parametri nel report. Nella risposta cerchiamo la chiave — xml_report per il successivo caricamento del report.
tar — archivio .tar.gz, contenente il report di emulazione in uno richiesti image (come pagina HTML, così come componenti come video da un sistema operativo emulato, dump del traffico di rete, report in json, così come il campione stesso in un archivio protetto da password). Nella risposta cerchiamo la chiave — full_report per il successivo caricamento del report.
Cosa c'è dentro il report summary
Le chiavi full_report, pdf_report, xml_report sono 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": "malevolo",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malevolo",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "trovato",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malevolo",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}Ecco la chiave summary_report — ce n'è una per l'emulazione in generale
{
"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": "malevolo",
"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": "malevolo",
"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": "malevolo",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente elaborata."
}
}
}
]
}È possibile richiedere contemporaneamente report in tar, xml e pdf; è possibile avere un report riassuntivo insieme a tar e xml. Non è possibile richiedere un report riassuntivo e pdf contemporaneamente.
Chiavi nella sezione extraction
Per l'estrazione delle minacce vengono utilizzate solo due chiavi:
method — pdf (conversione in pdf, utilizzata di default) o clean (pulizia del contenuto attivo).
extracted_parts_codes — elenco dei codici per la rimozione di contenuti attivi, applicabile solo al metodo clean
Codici per la rimozione di contenuti dai file
Code
Descrizione
1025
Oggetti collegati
1026
Macro e codice
1034
Collegamenti ipertestuali sensibili
1137
Azioni PDF GoToR
1139
Azioni PDF Launch
1141
Azioni PDF URI
1142
Azioni sonore PDF
1143
Azioni film 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 effettuare anche una richiesta query (di cui parleremo più avanti) dopo pochi secondi, specificando l'hash del file e il componente extraction nel testo della richiesta. Potrai recuperare il file pulito utilizzando l'id della risposta alla richiesta query — extracted_file_download_id. Anteponendo, fornisco esempi di richiesta e risposta query per trovare l'id per scaricare il documento pulito.
Richiesta query per cercare la chiave extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Risposta alla richiesta query (trova la chiave extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"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 - il file XLS è stato convertito in PDF",
"scrub_method": "Converti in PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macro e Codice"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}Panoramica
In una chiamata API è possibile inviare solo un file per la verifica.
Il componente av non richiede una sezione aggiuntiva con chiavi, è sufficiente indicarlo nel dizionario features.
Chiamata all'API Query
Il metodo utilizzato è POST
L'indirizzo per la chiamata è https://<service_address>/tecloud/api/v1/file/query
Prima di inviare un file per il caricamento (richiesta upload), è consigliabile eseguire un controllo della cache della sandbox (richiesta query) per ottimizzare il carico sul server API, poiché potrebbe già esserci informazioni e un verdetto sul file da caricare. La chiamata consiste solo nella parte testuale. La parte obbligatoria della richiesta è il codice hash sha1/sha256/md5 del file. Questo può essere ottenuto nella risposta alla richiesta upload.
Il minimo necessario per la richiesta query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Intestazioni:
Authorization: <api_key>
Corpo
{
«request»: {
«sha256»: <sha256 hash sum>
}
}
Esempio di risposta alla richiesta upload, dove sono visibili i codici 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": "unknown"
},
"status": "not_found",
"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 al valore hash, dovrebbe idealmente essere la stessa richiesta upload (o quella che si intende fare) o addirittura ‘già’ (contenere meno campi nella richiesta query rispetto alla richiesta upload). Nel caso in cui la richiesta query contenga più campi rispetto alla richiesta upload, non riceverete tutte le informazioni richieste.
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."
}
}
}
]
}Attenzione ai campi code e etichetta. Questi campi appaiono tre volte nei dizionari di stato. Inizialmente vediamo la chiave globale "code": 1006 e "label": "PARTIALLY_FOUND". Successivamente, queste chiavi si ripetono per ciascun componente specifico che abbiamo richiesto: te e extraction. Se per te è chiaro che i dati sono stati trovati, per extraction l'informazione è assente.
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 invii 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 completa ("code": 1001, "label": "FOUND")
{
"response": [
{
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente soddisfatta."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malevolo",
"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": "malevolo",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente soddisfatta."
}
}
}
]
}Se non ci sono informazioni nella cache, la risposta avrà «label»: «NON_TROVATO»
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Impossibile trovare il file richiesto. Si prega di caricarlo."
},
"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": "Impossibile trovare il file richiesto. Si prega di caricarlo."
}
}
}
]
}In una chiamata API è possibile inviare più hash per la verifica. I dati restituiti saranno nella stessa sequenza 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 soddisfatta."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malevolo"
},
"status": "trovato",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malevolo",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "TROVATO",
"message": "La richiesta è stata completamente soddisfatta."
}
}
},
{
"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 contemporaneamente più hash nel query avrà un effetto positivo sulle prestazioni del server API.
Chiamata all'API di Download
Il metodo utilizzato è POST (secondo la documentazione), GET funziona anche (e potrebbe sembrare più logico)
L'indirizzo per la chiamata è https://<service_address>/tecloud/api/v1/file/download?id=<id>
Nell'intestazione è necessario fornire la chiave API, il corpo della richiesta è vuoto, e l'id per il download è passato nell'indirizzo URL.
In risposta alla richiesta query, se l'emulazione è completata e sono stati richiesti rapporti durante il download del file, saranno visibili gli id per il download dei rapporti. Se si richiede una copia depurata, bisogna cercare l'id per il download del documento depurato.
In sintesi, le chiavi nella risposta alla richiesta query che contengono il valore id per il download possono essere:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Certamente, affinché in risposta alla richiesta query vengano ricevute queste chiavi, devono essere specificate nella richiesta (per i rapporti) o non dimenticare di effettuare la richiesta mediante la funzione extraction (per i documenti depurati)
Chiamata all'API Quota
Il metodo utilizzato è POST
L'indirizzo per la chiamata è https://<service_address>/tecloud/api/v1/file/quota
Per controllare la quota rimanente nel cloud si utilizza 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 dell'API per la prevenzione delle minacce ed è destinata solo ai dispositivi locali. Attualmente, può essere utile solo se è necessaria l'API per l'estrazione delle minacce. Per l'emulazione delle minacce, è meglio utilizzare l'API per la prevenzione delle minacce. Per attivare TP API per SG e configurare la chiave API è necessario seguire le istruzioni da . Ti consiglio di prestare attenzione al passo 6b e controllare la disponibilità della pagina https:///UserCheck/TPAPI poiché in caso di esito negativo la configurazione successiva non ha senso. Tutti i richiami API verranno inviati a questo URL. Il tipo di chiamata (upload/query) è regolato nella chiave del corpo della chiamata — request_name. Inoltre, le chiavi obbligatorie sono — api_key (da ricordare durante la configurazione) e protocol_version (al momento l'ultima versione è la 1.1). La documentazione ufficiale per questo API può essere trovata in . Tra i vantaggi relativi c'è la possibilità di inviare più file per l'emulazione durante il caricamento, poiché i file vengono inviati come stringhe di testo base64. Per codificare/decodificare i file in/da base64 si può utilizzare un convertitore online, ad esempio in Postman — . Nella pratica, durante la scrittura del codice, si dovrebbero usare i metodi integrati encode e decode.
Ora approfondiamo le funzioni ta e extraction di questo API.
Per il componente ta è previsto un dizionario te_options nelle richieste upload/query, e le chiavi in questa richiesta coincidono completamente con le 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 questo comando è specificato il metodo di pulizia: conversione in PDF, rimozione di contenuto attivo oppure scegliere la modalità in base al profilo Threat Prevention (specificare il nome del profilo). Un aspetto distintivo della risposta alla richiesta API con extraction per il file è che si riceve una copia pulita in risposta a questa richiesta sotto forma di una stringa base64 codificata (non è necessario effettuare una richiesta query e cercare l'id per caricare il documento)
Esempio di richiesta per la pulizia del file
{
"request": [{
"protocol_version": "1.1",
"api_key": "<API_KEY>",
"request_name": "UploadFile",
"file_enc_data": "<base64_encoded_file>",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Risposta alla richiesta
{
"response": [{
"protocol_version": "1.1",
"src_ip": "<IP_ADDRESS>",
"scrub": {
"file_enc_data": "<base64_encoded_converted_to_PDF_file>",
"input_real_extension": "js",
"message": "OK",
"orig_file_url": "",
"output_file_name": "hi.cleaned.pdf",
"protection_name": "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": "Converti in PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Anche se per ottenere una copia pulita sono richieste meno richieste API, ritengo che questa opzione sia meno preferibile e conveniente 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 dell'API del server e la chiave vengano inseriti automaticamente nelle richieste, e il riepilogo hash sha256 venga memorizzato dopo il caricamento del file, sono state create tre variabili all'interno delle collezioni (è possibile trovarle 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 per SG).
Esempi di utilizzo
Nella comunità sono presenti script scritti in Python che controllano i file della directory desiderata sia tramite , sia . Interagendo con l'API di Threat Prevention, le tue capacità di verifica dei file si espandono notevolmente, poiché ora puoi controllare file contemporaneamente su diverse piattaforme (interessante è la verifica in , e poi nella sandbox Check Point), e i file possono essere acquisiti non solo dal traffico di rete, ma anche da qualsiasi unità di rete e, ad esempio, dai sistemi CRM.
Fonte: habr.com
