Cet article sera utile à ceux qui sont familiers avec les technologies Check Point d'émulation de fichiers (Émulation des menaces) et à la suppression proactive des fichiers (Extraction des menaces) et souhaitent faire un pas vers l'automatisation de ces tâches. Check Point a , qui fonctionne à la fois dans le cloud et sur des dispositifs locaux, et fonctionnellement il est identique à la vérification des fichiers dans les flux de trafic web/smtp/ftp/smb/nfs.Cet article est en partie une interprétation personnelle d'un ensemble d'articles tirés de la documentation officielle, mais basé sur mon expérience d'exploitation et sur mes propres exemples. Vous trouverez également dans cet article des collections Postman pour travailler avec l'API de prévention des menaces.
Principales abréviations
Threat Prevention API fonctionne avec trois composants principaux, qui sont appelés dans l'API par les valeurs textuelles suivantes :
av — composant Anti-Virus, responsable de l'analyse par signature des menaces connues.
te — composant Émulation des menaces, responsable de la vérification des fichiers dans un bac à sable, et de rendre un verdict malveillant (malicious)/propre (benign) après émulation.
extraction — composant Extraction des menaces, responsable de la conversion rapide de documents bureautiques en une forme sécurisée (dans laquelle tout contenu potentiellement nuisible est supprimé), afin de permettre une livraison rapide aux utilisateurs/systèmes.
Structure de l'API et principales limitations
Threat Prevention API utilise seulement 4 requêtes — upload, query, download et quota. Dans l'en-tête de ces quatre requêtes, il faut transmettre la clé API en utilisant le paramètre Authorization. À première vue, la structure peut sembler beaucoup plus simple que dans le , mais le nombre de champs dans les requêtes upload et query et la structure de ces requêtes sont suffisamment complexes. Elles peuvent être fonctionnellement comparées aux profils de prévention des menaces dans la politique de sécurité du passage/bac à sable.
À ce jour, une seule version de l'API de prévention des menaces a été publiée — 1.0, dans l'URL pour les appels API il faut indiquer v1 à l'endroit où la version doit être spécifiée. Contrairement à l'API de gestion, indiquer la version de l'API dans l'URL est obligatoire, sinon la requête ne sera pas exécutée.
Le composant Anti-Virus lors de l'appel sans d'autres composants (te, extraction) ne supporte actuellement que les requêtes query avec des sommes de hachage md5. L'Émulation des menaces et l'Extraction des menaces supportent également les sommes de hachage sha1 et sha256.
Il est très important de ne pas faire d'erreurs dans les requêtes ! La demande peut être exécutée sans erreur, mais pas complètement. En avançant légèrement, examinons ce qui peut se passer en cas d'erreurs/typos dans les requêtes.
Demande avec une faute de frappe dans le mot rapports (reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Il n'y aura pas d'erreur dans la réponse, mais aucune information sur les rapports ne sera fournie.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La demande a été entièrement traitée."
},
"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 demande a été entièrement traitée."
}
}
}
]
}Voici une demande sans faute de frappe dans la clé rapports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Nous réceptionnons une réponse qui contient déjà des ID pour le téléchargement des rapports.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La demande a été entièrement traitée."
},
"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 demande a été entièrement traitée."
}
}
}
]
}Si vous envoyez une clé API incorrecte ou périmée, vous obtiendrez une erreur 403 en réponse.
SandBlast API : dans le cloud et sur les appareils locaux.
Les demandes API peuvent être envoyées aux appareils Check Point sur lesquels le composant (blade) Threat Emulation est activé. Pour les demandes, utilisez l'ip/url de l'appareil et le port 18194 (par exemple — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию désactivée et la clé Authorization dans les en-têtes des requêtes peut ne pas être envoyée du tout.
Les requêtes API vers le cloud CheckPoint doivent être envoyées à l'adresse te.checkpoint.com (par exemple — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Sur les dispositifs locaux, Threat Extraction n'est pas encore pris en charge dans la version standard et il convient d'utiliser (nous en parlerons plus en détail à la fin de l'article).
Les dispositifs locaux ne prennent pas en charge la requête quota.
À part cela, il n'y a pas de différences entre les requêtes aux dispositifs locaux et à ceux du cloud.
L'appel Upload API
La méthode utilisée est — POST
L'adresse pour l'appel est — https://<service_address>/tecloud/api/v1/file/upload
La requête se compose de deux parties (form-data) : un fichier destiné à l'émulation/nettoyage et le corps de la requête avec le texte.
Le texte de la requête ne peut pas être vide, mais il peut ne pas contenir de configuration. Pour que la requête soit réussie, il faut envoyer au moins le texte suivant dans la requête :
Minimum requis pour la requête upload
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
En-têtes :
Authorization : <api_key>
Corps
{
"request": {
}
}
Fichier
Fichier
Dans ce cas, le fichier à traiter sera soumis selon les paramètres par défaut : composant — te, images des systèmes d'exploitation — Win XP et Win 7, sans génération de rapport.
Commentaires sur les principaux champs dans la requête textuelle :
file_name et file_type peuvent être laissés vides ou non envoyés, car ce n'est pas une information particulièrement utile lors du téléchargement du fichier. Dans la réponse API, ces champs seront remplis automatiquement en fonction du nom du fichier téléchargé, et l'information dans le cache devra quand même être recherchée par les sommes de hash md5/sha1/sha256.
Exemple de requête avec file_name et file_type vides
{
"request": {
"file_name": "",
"file_type": "",
}
}features — liste dans laquelle sont spécifiées les fonctionnalités nécessaires lors du traitement dans le bac à sable — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Si ce paramètre n'est pas du tout transmis, seul le composant par défaut — te (Threat Emulation) sera utilisé.
Pour activer la vérification dans les trois composants disponibles, il faut spécifier ces composants dans la requête API.
Exemple de requête avec vérification dans av, te et extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Clés dans la section te
images — liste dans laquelle doivent être spécifiés des dictionnaires avec l'id et le numéro de révision des systèmes d'exploitation, dans lesquels la vérification sera effectuée. L'ID et les numéros de révision sont identiques pour tous les dispositifs locaux et le cloud.
Liste des systèmes d'exploitation et révisions
Available OS Image ID
Révision
Image OS et Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 et ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 — 32 bits
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 — 32 bits
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 — 32 bits
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 — 64 bits
Office: 2013 (32 bits)
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 — 64 bits
Office: 2013 (64 bits)
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
Si la clé images n'est pas spécifiée, l'émulation se fera avec des images recommandées par Check Point (actuellement, il s'agit de Win XP et Win 7). Ces images sont recommandées pour un meilleur équilibre entre performance et taux de détection.
rapports — une liste de rapports que nous demandons au cas où le fichier serait malveillant. Les options suivantes sont disponibles :
résumé — archive .tar.gz contenant un rapport d'émulation pour de tout les images demandées (y compris une page html, ainsi que des composants comme une vidéo du système d'exploitation de l'émulateur, un dump du trafic réseau, un rapport en json, ainsi que l'échantillon lui-même dans une archive protégée par mot de passe). Dans la réponse, cherchons la clé — summary_report pour le téléchargement ultérieur du rapport.
pdf — document d'émulation dans un image, que beaucoup sont habitués à recevoir via Smart Console. Dans la réponse, cherchons la clé — pdf_report pour le téléchargement ultérieur du rapport.
xml — document d'émulation dans un image, pratique pour un parsing ultérieur des paramètres dans le rapport. Dans la réponse, cherchons la clé — xml_report pour le téléchargement ultérieur du rapport.
tar — archive .tar.gz contenant le rapport d'émulation dans un les images demandées (y compris une page html, ainsi que des composants comme une vidéo du système d'exploitation de l'émulateur, un dump du trafic réseau, un rapport en json, ainsi que l'échantillon lui-même dans une archive protégée par mot de passe). Dans la réponse, cherchons la clé — full_report pour le téléchargement ultérieur du rapport.
Que contient le rapport résumé
Les clés full_report, pdf_report, xml_report sont présentes dans le dictionnaire pour chaque OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La demande a été entièrement traitée."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malveillant",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "trouvé",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malveillant",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "trouvé",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malveillant",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La demande a été entièrement traitée."
}
}
}
]
}La clé summary_report — est unique pour l'ensemble de l'émulation
{
"response": [
{
"status": {
"code": 1001,
"label": "TROUVÉ",
"message": "La demande a été entièrement satisfaite."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malveillant",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "trouvé",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malveillant",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "trouvé",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malveillant",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "TROUVÉ",
"message": "La demande a été entièrement satisfaite."
}
}
}
]
}Il est possible de demander simultanément des rapports au format tar, xml et pdf, ainsi que des résumés au format tar et xml. Il n'est pas possible de demander un rapport résumé et un pdf en même temps.
Clés dans la section extraction
Deux clés sont utilisées pour l'extraction des menaces :
méthode — pdf (conversion en pdf, utilisée par défaut) ou clean (nettoyage du contenu actif).
codes_des_parties_extraites — liste des codes pour supprimer le contenu actif, applicable uniquement pour la méthode clean
Codes pour supprimer du contenu des fichiers
Code
Description
1025
Objets Liés
1026
Macros et Code
1034
Hyperliens Sensibles
1137
Actions PDF GoToR
1139
Actions de Lancement PDF
1141
Actions URI PDF
1142
Actions Sonores PDF
1143
Actions de Film PDF
1150
Actions JavaScript PDF
1151
Actions de Soumission de Formulaire PDF
1018
Requêtes de Base de Données
1019
Objets Incorporés
1021
Données de Sauvegarde Rapide
1017
Propriétés Personnalisées
1036
Propriétés de Statistiques
1037
Propriétés de Résumé
Pour télécharger une copie nettoyée, il sera également nécessaire de faire une requête query (ce dont nous parlerons bientôt) dans quelques secondes, en indiquant le hash du fichier et le composant extraction dans le texte de la demande. Le fichier nettoyé pourra être récupéré à l'aide de l'id de la réponse à la requête query — extracted_file_download_id. Encore une fois, en avançant un peu, je vais fournir des exemples de demande et de réponse de query pour rechercher l'id pour télécharger le document nettoyé.
Requête query pour rechercher la clé extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Réponse à la requête query (trouvez la clé extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "TROUVÉ",
"message": "La demande a été entièrement traitée."
},
"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 et code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Contenu potentiellement malveillant extrait",
"protection_type": "Conversion en PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Du contenu actif a été trouvé - le fichier XLS a été converti en PDF",
"scrub_method": "Convertir en PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros et code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "TROUVÉ",
"message": "La demande a été entièrement traitée."
}
}
}
]
}Informations générales
Lors d'un appel API, vous ne pouvez soumettre qu'un seul fichier pour vérification.
Le composant av ne nécessite pas de section supplémentaire avec des clés, il suffit de l'indiquer dans le dictionnaire. features.
Appel de l'API Query
La méthode utilisée est — POST
L'adresse pour l'appel est — https://<service_address>/tecloud/api/v1/file/query
Avant d'envoyer un fichier pour téléchargement (demande upload), il est conseillé d'effectuer une vérification du cache sandbox (demande query) afin d'optimiser la charge sur le serveur API, car il se peut que le serveur API ait déjà des informations et un verdict sur le fichier à télécharger. L'appel se compose uniquement de la partie texte. La partie obligatoire de la demande est la somme de hachage sha1/sha256/md5 du fichier. Elle peut d'ailleurs être obtenue dans la réponse à la demande upload.
Le minimum requis pour la demande query
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
En-têtes :
Authorization : <api_key>
Corps
{
"request": {
"sha256": <sha256 hash sum>
}
}
Exemple de réponse à la demande upload, où apparaissent les sommes de hachage sha1/md5/sha256
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Le fichier a été téléchargé avec succès."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "inconnu"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Le fichier a été téléchargé avec succès."
}
}
}
}La requête query, en dehors de la somme de contrôle hash, doit idéalement être la même que celle de la requête upload (ou prévue pour être), ou même « déjà » (contient moins de champs dans la requête query que dans la requête upload). Si la requête query contient plus de champs que dans la requête upload, vous ne recevrez pas toutes les informations requises en réponse.
Voici un exemple de réponse à la requête query, où toutes les données requises n'ont pas été trouvées.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "La requête ne peut pas être entièrement répondue à ce 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": "La requête a été entièrement répondue."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Impossible de trouver le fichier demandé. Veuillez le télécharger."
}
}
}
]
}Veuillez prêter attention aux champs. code et label. Ces champs apparaissent trois fois dans les dictionnaires status. Nous voyons d'abord la clé globale « code » : 1006 et « label » : « PARTIALLY_FOUND ». Ensuite, ces clés apparaissent pour chaque composant séparé que nous avons demandé — te et extraction. Alors que pour te, il est clair que les données ont été trouvées, pour extraction, les informations sont absentes.
Voici à quoi ressemblait la requête query pour l'exemple ci-dessus.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Si vous envoyez une requête query sans le composant extraction,
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}vous obtiendrez également une réponse complète (« code » : 1001, « label » : « FOUND »).
{
"response": [
{
"status": {
"code": 1001,
"label": "TROUVÉ",
"message": "La demande a été entièrement traitée."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malveillant",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "trouvé",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malveillant",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "TROUVÉ",
"message": "La demande a été entièrement traitée."
}
}
}
]
}Si aucune information n'est présente dans le cache, la réponse sera «label»: «NON_TROUVÉ»
{
"response": [
{
"status": {
"code": 1004,
"label": "NON_TROUVÉ",
"message": "Impossible de trouver le fichier demandé. Veuillez le télécharger."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "inconnu"
},
"status": "non_trouvé",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NON_TROUVÉ",
"message": "Impossible de trouver le fichier demandé. Veuillez le télécharger."
}
}
}
]
}Dans un appel API, plusieurs sommes de hachage peuvent être envoyées pour vérification. Les données de réponse seront renvoyées dans le même ordre que celles envoyées dans la demande.
Exemple de demande de requête avec plusieurs sommes sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Réponse à la demande de requête avec plusieurs sommes sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "La demande a été entièrement traitée."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malveillant"
},
"status": "trouvé",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malveillant",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "La demande a été entièrement traitée."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Impossible de trouver le fichier demandé. Veuillez le télécharger."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "inconnu"
},
"status": "non_trouvé",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Impossible de trouver le fichier demandé. Veuillez le télécharger."
}
}
}
]
}La demande de plusieurs sommes de hachage dans la requête query aura également un impact positif sur la performance de l'API du serveur.
Appel de l'API de téléchargement
La méthode utilisée est — POST (selon la documentation), GET fonctionne également (et peut sembler plus logique)
L'adresse pour l'appel est — https://<service_address>/tecloud/api/v1/file/download?id=<id>
Une clé API doit être transmise dans l'en-tête, le corps de la requête doit être vide, l'id pour le téléchargement est passé dans l'URL.
En réponse à une requête query, si l'émulation est terminée et que des rapports ont été demandés lors du téléchargement du fichier, les id pour le téléchargement des rapports seront visibles. Si une copie nettoyée est demandée, il faudra rechercher l'id pour télécharger le document nettoyé.
Ainsi, les clés dans la réponse à la requête query contenant la valeur id pour le téléchargement peuvent être :
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Bien sûr, pour que ces clés soient obtenues dans la réponse à la requête query, elles doivent être spécifiées dans la requête (pour les rapports) ou ne pas oublier de faire une demande pour la fonction d'extraction (pour les documents nettoyés)
Appel de l'API Quota
La méthode utilisée est — POST
L'adresse pour l'appel est — https://<service_address>/tecloud/api/v1/file/quota
Pour vérifier le quota restant dans le cloud, la requête quota est utilisée. Le corps de la requête est vide.
Exemple de réponse à la requête 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
Cette API a été développée avant l'API de prévention des menaces et est destinée uniquement aux appareils locaux. Pour le moment, elle peut être utile uniquement si vous avez besoin de l'API d'extraction des menaces. Pour l'émulation des menaces, il est préférable d'utiliser l'API de prévention des menaces normale. Pour activer API TP pour SG et configurer la clé API, il est nécessaire d'exécuter les étapes de . Je recommande de prêter attention à l'étape 6b et de vérifier l'accessibilité de la page https:///UserCheck/TPAPI car en cas de résultat négatif, la configuration ultérieure n'a pas de sens. Tous les appels API seront envoyés à cette URL. Le type d'appel (upload/query) est régulé par la clé dans le corps de l'appel — request_name. Les clés obligatoires sont également — api_key (à mémoriser lors de la configuration) et protocol_version (la version actuelle est 1.1). Vous pouvez trouver la documentation officielle pour cette API dans . Parmi les avantages relatifs, on peut citer la possibilité d'envoyer plusieurs fichiers pour émulation lors de leur téléchargement, car les fichiers sont envoyés sous forme de chaîne de texte base64. Pour encoder/décoder des fichiers en/de base64, vous pouvez utiliser un convertisseur en ligne pour démonstration dans Postman, par exemple — . Dans un cadre pratique, lors de l'écriture de code, il est recommandé d'utiliser les méthodes intégrées encode et decode.
Maintenant, approfondissons les fonctions te et extraction de cette API.
Pour le composant te un dictionnaire est prévu te_options dans les requêtes upload/query, et les clés de cette requête correspondent exactement aux clés te dans .
Exemple de requête pour émuler un fichier sous Win10 avec rapports
{
"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"]
}
}
]
}Pour le composant extraction un dictionnaire est prévu scrub_optionsDans cette requête, la méthode de nettoyage est spécifiée : conversion en PDF, nettoyage des contenus actifs ou sélection du mode en fonction du profil de prévention des menaces (le nom du profil est spécifié). La particularité de la réponse à la requête API avec extraction pour le fichier est que vous recevez une copie nettoyée en réponse à cette requête sous la forme d'une chaîne chiffrée en base64 (vous n'avez pas besoin d'effectuer une requête pour chercher l'ID afin de télécharger le document).
Exemple de requête pour nettoyer un fichier
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Réponse à la requête
{
"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": "Extraire les contenus potentiellement malveillants",
"protection_type": "Conversion en PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "Le fichier TXT a été converti en PDF",
"scrub_method": "Convertir en PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Bien que la réception d'une copie nettoyée nécessite moins de requêtes API, je trouve cette option moins préférable et pratique que la requête form-data utilisée dans .
Collections Postman
J'ai créé des collections dans Postman à la fois pour l'API de prévention des menaces et pour l'API de prévention des menaces pour Security Gateway, où sont présentées les requêtes API les plus courantes. Pour que l'IP/URL du serveur API et la clé soient automatiquement insérés dans les requêtes, et que le hash sha256 soit également mémorisé après le téléchargement du fichier, trois variables ont été créées à l'intérieur des collections (vous pouvez les trouver en allant dans les paramètres de la collection Éditer -> Variables) : te_api (doit être rempli), api_key (doit être rempli, sauf en cas d'utilisation de l'API TP avec des appareils locaux), sha256 (laisser vide, non utilisé dans l'API TP for SG).
Exemples d'utilisation
Dans la communauté sont présentés des scripts écrits en Python qui vérifient des fichiers dans le répertoire souhaité à la fois via , et via . Grâce à l'interaction avec l'API de prévention des menaces, vos capacités de vérification des fichiers s'élargissent considérablement, car vous pouvez désormais vérifier les fichiers sur plusieurs plateformes (la vérification dans , puis dans le bac à sable Check Point), et les fichiers peuvent être récupérés non seulement à partir du trafic réseau, mais aussi depuis n'importe quel disque réseau et, par exemple, des systèmes CRM.
Source : habr.com
