Cet article sera utile à ceux qui connaissent la technologie Check Point par émulation de fichier (Émulation de menace) et un nettoyage proactif des fichiers (Extraction des menaces) et souhaite faire un pas vers l'automatisation de ces tâches. Check Point a , qui s'exécute à la fois dans le cloud et sur des appareils locaux, et fonctionnellement, cela est identique à la vérification des fichiers dans les flux de trafic web/smtp/ftp/smb/nfs. Cet article est en partie l’interprétation de l’auteur d’un ensemble d’articles de la documentation officielle, mais basé sur ma propre expérience opérationnelle et mes propres exemples. Dans l'article, vous trouverez également les collections Postman de l'auteur pour travailler avec l'API Threat Prevention.
Abréviations de base
L'API Threat Prevention fonctionne avec trois composants principaux, qui sont appelés dans l'API via les valeurs de texte suivantes :
av — Composant antivirus, responsable de l'analyse des signatures des menaces connues.
te - Composant d'émulation des menaces, chargé de vérifier les fichiers dans le bac à sable et de rendre un verdict malveillant/inoffensif après l'émulation.
extraction - Composant Threat Extraction, chargé de convertir rapidement les documents bureautiques sous une forme sécurisée (dans laquelle tout contenu potentiellement malveillant est supprimé), afin de les livrer rapidement aux utilisateurs/systèmes.
Structure de l'API et principales limitations
L'API de prévention des menaces n'utilise que 4 requêtes - téléchargement, requête, téléchargement et quota. Dans l'en-tête des quatre requêtes, vous devez transmettre la clé API à l'aide du paramètre Autorisation. À première vue, la structure peut paraître beaucoup plus simple que dans , mais le nombre de champs dans les requêtes de téléchargement et de requête ainsi que la structure de ces requêtes sont assez complexes. Ceux-ci peuvent être comparés fonctionnellement aux profils de prévention contre les menaces dans une politique de sécurité de passerelle/bac à sable.
Pour le moment, la seule version de l'API Threat Prevention a été publiée - 1.0 ; l'URL des appels d'API doit inclure v1 dans la partie où vous devez spécifier la version. Contrairement à l’API de Gestion, il est nécessaire d’indiquer la version de l’API dans l’URL, sans quoi la requête ne sera pas exécutée.
Le composant antivirus, lorsqu'il est appelé sans d'autres composants (te, extraction), ne prend actuellement en charge que les requêtes de requête avec des sommes de hachage md5. L'émulation des menaces et l'extraction des menaces prennent également en charge les sommes de hachage sha1 et sha256.
Il est très important de ne pas faire d’erreurs dans les requêtes ! La requête peut être exécutée sans erreur, mais pas complètement. En regardant un peu vers l'avenir, regardons ce qui peut arriver lorsqu'il y a des erreurs/fautes de frappe dans les requêtes.
Demande avec une faute de frappe avec le mot rapports(rapportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Il n'y aura aucune erreur dans la réponse, mais il n'y aura aucune information sur les rapports
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Mais pour une demande sans faute de frappe dans la touche rapports
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Nous recevons une réponse qui contient déjà l'identifiant pour télécharger les rapports
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
"pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
"xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Si nous envoyons une clé API incorrecte/expirée, nous recevrons une erreur 403 en réponse.
API SandBlast : dans le cloud et sur les appareils locaux
Les requêtes API peuvent être envoyées aux appareils Check Point sur lesquels le composant Threat Emulation (lame) est activé. Comme adresse pour les demandes, vous devez utiliser l'adresse IP/url de l'appareil et le port 18194 (par exemple, https://10.10.57.19:18194/tecloud/api/v1/file/query). Vous devez également vous assurer que la politique de sécurité de l'appareil autorise cette connexion. Autorisation via clé API sur les appareils locaux par défaut à l'arrêt et la clé d'autorisation dans les en-têtes de demande peut ne pas être envoyée du tout.
Les requêtes API vers le cloud CheckPoint doivent être envoyées à te.checkpoint.com (par exemple - https://te.checkpoint.com/tecloud/api/v1/file/query). La clé API peut être obtenue sous forme de licence d’essai pendant 60 jours en contactant les partenaires Check Point ou le bureau local de l’entreprise.
Sur les appareils locaux, Threat Extraction n’est pas encore pris en charge en standard. et doit être utilisé (nous en reparlerons plus en détail à la fin de l'article).
Les appareils locaux ne prennent pas en charge la demande de quota.
Sinon, il n'y a aucune différence entre les requêtes vers les appareils locaux et vers le cloud.
Télécharger un appel d'API
Méthode utilisée - POSTEZ
Adresse d'appel - https:///tecloud/api/v1/file/upload
La requête se compose de deux parties (formulaire-données) : un fichier destiné à l'émulation/nettoyage et un corps de requête avec du texte.
La demande de texte ne peut pas être vide, mais elle ne peut contenir aucune configuration. Pour que la demande aboutisse, vous devez envoyer au moins le texte suivant dans la demande :
Minimum requis pour une demande de téléchargement
POST HTTP
https:///tecloud/api/v1/file/upload
En-têtes:
Autorisation:
Transformation
{
"demande": {
}
}
Déposez votre dernière attestation
Déposez votre dernière attestation
Dans ce cas, le fichier sera traité selon les paramètres par défaut : composant - te, images du système d'exploitation - Gagnez XP et gagnez 7, sans générer de rapport.
Commentaires sur les principaux champs de la demande de texte :
file_name и Type de fichier Vous pouvez les laisser vides ou ne pas les envoyer du tout, car ce ne sont pas des informations particulièrement utiles lors du téléchargement d'un fichier. Dans la réponse de l'API, ces champs seront remplis automatiquement en fonction du nom du fichier téléchargé, et les informations dans le cache devront toujours être recherchées à l'aide des quantités de hachage md5/sha1/sha256.
Exemple de requête avec file_name et file_type vides
{
"request": {
"file_name": "",
"file_type": "",
}
}Caractéristiques — une liste qui indique 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 transmis du tout, alors seul le composant par défaut sera utilisé - te (Threat Emulation).
Pour activer l'archivage des trois composants disponibles, vous devez spécifier ces composants dans la requête API.
Exemple de requête avec archivage av, te et extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Clés dans la section te
satellite — une liste contenant les dictionnaires avec l'identifiant et le numéro de révision des systèmes d'exploitation dans lesquels la vérification sera effectuée. Les ID et les numéros de révision sont les mêmes pour tous les appareils locaux et dans le cloud.
Liste des systèmes d'exploitation et révisions
ID d'image du système d'exploitation disponible
Révision
Système d'exploitation et application d'image
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP-32 bits SP3
Bureaux: 2003, 2007
Adobe Acrobat Reader: 9.0
flash Player 9r115 et ActiveX 10.0
Exécution Java : 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 - 32 bits
Bureaux: 2003, 2007
Adobe Acrobat Reader: 9.0
Lecteur Flash: 10.2r152 (Brancher& ActiveX)
Exécution Java : 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 - 32 bits
Bureaux: 2010
Adobe Acrobat Reader: 9.4
Lecteur Flash: 11.0.1.152 (Brancher & ActiveX)
Exécution Java : 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 - 32 bits
Bureaux: 2013
Adobe Acrobat Reader: 11.0
Lecteur Flash: 15 (Brancher & ActiveX)
Exécution Java : 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 - 64 bits
Bureaux: 2013 (32 bits)
Adobe Acrobat Reader: 11.0.01
Lecteur Flash: 13 (Brancher & ActiveX)
Exécution Java : 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 - 64 bits
Bureaux: 2013 (64 bits)
Adobe Acrobat Reader: 11.0.10
Lecteur Flash: 18.0.0.160 (Brancher & ActiveX)
Exécution Java : 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Bureaux: Professionnel Plus 2016 fr-ca
Adobe Acrobat Reader: DC 2015 MUI
Lecteur Flash: 20 (Brancher & ActiveX)
Exécution Java : 1.7.0u9
Si la clé des images n'est pas spécifiée du tout, alors l'émulation aura lieu dans les images recommandées par Check Point (actuellement Win XP et Win 7). Ces images sont recommandées en fonction du meilleur équilibre entre performances et taux de capture.
rapports — une liste de rapports que nous demandons au cas où le fichier s'avérerait malveillant. Les options suivantes sont disponibles :
-
résumé - Archive .tar.gz contenant un rapport sur l'émulation par tous images demandées (à la fois une page HTML et des composants tels qu'une vidéo du système d'exploitation de l'émulateur, un vidage du trafic réseau, un rapport en json et l'échantillon lui-même dans une archive protégée par mot de passe). Nous cherchons la clé dans la réponse - rapport sommaire pour le téléchargement ultérieur du rapport.
-
pdf - document sur l'émulation dans un image, que beaucoup sont habitués à recevoir via la Smart Console. Nous cherchons la clé dans la réponse - rapport_pdf pour le téléchargement ultérieur du rapport.
-
xml - document sur l'émulation dans un image, pratique pour l’analyse ultérieure des paramètres dans le rapport. Nous cherchons la clé dans la réponse - rapport_xml pour le téléchargement ultérieur du rapport.
-
goudron - Archive .tar.gz contenant un rapport sur l'émulation dans un images demandées (à la fois une page HTML et des composants tels qu'une vidéo du système d'exploitation de l'émulateur, un vidage du trafic réseau, un rapport en json et l'échantillon lui-même dans une archive protégée par mot de passe). Nous cherchons la clé dans la réponse - rapport complet pour le téléchargement ultérieur du rapport.
Que contient le rapport récapitulatif
Les clés full_report, pdf_report, xml_report sont dans le dictionnaire de chaque OS
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicious",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "found",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Mais la clé summary_report - il y en a une pour l'émulation en général
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "malicious",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "found",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}Vous pouvez demander des rapports tar, xml et pdf en même temps, vous pouvez demander un résumé et des rapports tar et xml. Il ne sera pas possible de demander un rapport de synthèse et un pdf en même temps.
Clés dans la section extraction
Pour l’extraction des menaces, seules deux clés sont utilisées :
méthode — pdf (conversion en pdf, utilisé par défaut) ou clean (nettoyage du contenu actif).
extrait_parts_codes - liste des codes de suppression du contenu actif, applicable uniquement pour la méthode clean
Codes pour supprimer le contenu des fichiers
Code
Description
1025
Objets liés
1026
Macros et code
1034
Liens hypertextes sensibles
1137
Actions PDF GoToR
1139
Actions de lancement du PDF
1141
Actions d'URI PDF
1142
Actions sonores PDF
1143
Actions sur les films PDF
1150
Actions JavaScript PDF
1151
Actions du formulaire de soumission PDF
1018
Les requêtes de bases de données
1019
Objets incorporés
1021
Sauvegarde rapide des données
1017
Propriétés personnalisées
1036
Propriétés statistiques
1037
Propriétés récapitulatives
Pour télécharger une copie nettoyée, vous devrez également faire une demande de requête (qui sera discutée ci-dessous) après quelques secondes, en spécifiant la quantité de hachage du fichier et le composant d'extraction dans le texte de la demande. Vous pouvez récupérer le fichier nettoyé en utilisant l'identifiant de la réponse à la requête - extrait_file_download_id. Encore une fois, en regardant un peu vers l'avenir, je donne des exemples de requête et de réponse à une requête pour rechercher un identifiant pour télécharger un document effacé.
Requête de requête pour rechercher la clé extrait_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Réponse à la requête (recherchez la clé extrait_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"extraction"
],
"extraction": {
"method": "pdf",
"extract_result": "CP_EXTRACT_RESULT_SUCCESS",
"extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"time": "0.013",
"extract_content": "Macros and Code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potential malicious content extracted",
"protection_type": "Conversion to PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Active content was found - XLS file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Macros and Code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}vue d'ensemble
Dans un appel API, vous ne pouvez envoyer 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 le préciser dans le dictionnaire Caractéristiques.
Appel d'API de requête
Méthode utilisée - POSTEZ
Adresse d'appel - https:///tecloud/api/v1/file/query
Avant d'envoyer un fichier en téléchargement (demande d'upload), il est conseillé de vérifier le cache sandbox (demande de requête) afin d'optimiser la charge sur le serveur API, puisque le serveur API peut déjà disposer d'informations et d'un verdict sur le fichier téléchargé. L'appel se compose uniquement d'une partie de texte. La partie requise de la demande est la quantité de hachage sha1/sha256/md5 du fichier. À propos, vous pouvez l'obtenir dans la réponse à la demande de téléchargement.
Minimum requis pour la requête
POST HTTP
https:///tecloud/api/v1/file/query
En-têtes:
Autorisation:
Transformation
{
"demande": {
"sha256":
}
}
Un exemple de réponse à une demande de téléchargement, où les montants de hachage sha1/md5/sha256 sont visibles
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "The file was uploaded successfully."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "The file was uploaded successfully."
}
}
}
}La demande de requête, en plus du montant de hachage, devrait idéalement être la même que la demande de téléchargement était (ou est prévue de l'être), ou même « déjà » (contenir moins de champs dans la demande de requête que dans la demande de téléchargement). Dans le cas où la demande de requête contient plus de champs que la demande de téléchargement, vous ne recevrez pas toutes les informations requises dans la réponse.
Voici un exemple de réponse à une requête où toutes les données requises n'ont pas été trouvées
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "The request cannot be fully answered at this time."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}Faites attention aux champs code и étiquette. Ces champs apparaissent trois fois dans les dictionnaires d'état. Nous voyons d'abord la clé globale « code » : 1006 et « label » : « PARTIALLY_FOUND ». Ensuite, ces clés sont trouvées pour chaque composant individuel que nous avons demandé - te et extraction. Et s'il est clair que les données ont été trouvées, alors pour l'extraction, il n'y a aucune information.
Voici à quoi ressemblait la requête 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 de requête sans le composant d'extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Ensuite, la réponse contiendra des informations complètes (« code » : 1001, « étiquette » : « TROUVÉ »)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"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": "The request has been fully answered."
}
}
}
]
}S'il n'y a aucune information dans le cache, alors la réponse sera « label » : « NOT_FOUND »
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"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": "Could not find the requested file. Please upload it."
}
}
}
]
}Dans un seul appel API, vous pouvez envoyer plusieurs montants de hachage à la fois pour vérification. La réponse renverra les données dans le même ordre que celui dans lequel elles ont été envoyées dans la demande.
Exemple de requête de requête avec plusieurs montants sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Réponse à une requête avec plusieurs montants sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}Demander plusieurs sommes de hachage à la fois dans une requête de requête aura également un effet bénéfique sur les performances du serveur API.
Télécharger l'appel API
Méthode utilisée - POSTEZ (selon documentation), ÉCONOMISEZ fonctionne aussi (et peut paraître plus logique)
Adresse d'appel - https:///tecloud/api/v1/file/download?id=
L'en-tête nécessite que la clé API soit transmise, le corps de la requête est vide, l'identifiant de téléchargement est transmis dans l'adresse URL.
En réponse à une demande de requête, si l'émulation est terminée et que des rapports ont été demandés lors du téléchargement du fichier, l'identifiant de téléchargement des rapports sera visible. Si une copie nettoyée est demandée, vous devez rechercher l'identifiant pour télécharger le document nettoyé.
Au total, les clés de la réponse à la requête contenant la valeur id pour le chargement peuvent être :
-
rapport sommaire
-
rapport complet
-
rapport_pdf
-
rapport_xml
-
extrait_file_download_id
Bien entendu, afin de recevoir ces clés en réponse à la requête d'interrogation, il faut les préciser dans la requête (pour les rapports) ou penser à faire une requête via la fonction d'extraction (pour les documents nettoyés)
Appel d'API de quota
Méthode utilisée - POSTEZ
Adresse d'appel - https:///tecloud/api/v1/file/quota
Pour vérifier le quota restant dans le cloud, utilisez la requête de quota. Le corps de la requête est vide.
Exemple de réponse à une demande de 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"
}
]
}API de prévention des menaces pour Security Gateway
Cette API a été développée avant l'API Threat Prevention et est destinée uniquement aux appareils locaux. Pour l’instant, cela ne peut être utile que si vous avez besoin de l’API Threat Extraction. Pour l’émulation des menaces, il est préférable d’utiliser l’API standard de prévention des menaces. Pour allumer API TP pour SG et configurez la clé API dont vous avez besoin pour suivre les étapes de . Je recommande de prêter attention à l'étape 6b et de vérifier l'accessibilité de la page https://<IPAddressofSecurityGateway>/UserCheck/TPAPI car en cas de résultat négatif, une configuration ultérieure n'a pas de sens. Tous les appels API seront envoyés à cette URL. Le type d'appel (téléchargement/requête) est réglementé dans la clé du corps de l'appel - nom_demande. Les clés requises sont également - clé API (vous devez vous en souvenir pendant le processus de configuration) et version_protocole (actuellement, la version actuelle est la 1.1). Vous pouvez trouver la documentation officielle de cette API sur . Les avantages relatifs incluent la possibilité d'envoyer plusieurs fichiers à la fois pour l'émulation lors de leur chargement, puisque les fichiers sont envoyés sous forme de chaîne de texte base64. Pour encoder/décoder des fichiers vers/depuis base64, vous pouvez utiliser un convertisseur en ligne dans Postman à des fins de démonstration, par exemple : . Pour des raisons pratiques, vous devez utiliser les méthodes d'encodage et de décodage intégrées lors de l'écriture du code.
Examinons maintenant de plus près les fonctions te и extraction dans cette API.
Pour composant te dictionnaire fourni te_options dans les requêtes de téléchargement/requête, et les clés de cette requête coïncident complètement avec les clés te dans .
Exemple de demande d'émulation de fichier dans Win10 avec rapports
{
"request": [{
"protocol_version": "1.1",
"api_key": "<api_key>",
"request_name": "UploadFile",
"file_enc_data": "<base64_encoded_file>",
"file_orig_name": "<filename>",
"te_options": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": ["summary", "xml"]
}
}
]
}Pour composant extraction dictionnaire fourni options_gommage. Cette demande précise la méthode de nettoyage : convertir en PDF, effacer le contenu actif ou sélectionner un mode conformément au profil Threat Prevention (le nom du profil est indiqué). L'avantage de répondre à une demande d'API d'extraction pour un fichier est que vous obtenez une copie nettoyée dans la réponse à cette demande sous forme de chaîne cryptée en base64 (vous n'avez pas besoin de faire une demande de requête et de rechercher l'identifiant pour télécharger le fichier). document)
Exemple de demande d'effacement d'un fichier
{
"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
}
}]
}Répondre à une demande
{
"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": "Extract potentially malicious content",
"protection_type": "Conversion to PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT file was converted to PDF",
"scrub_method": "Convert to PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Malgré le fait que moins de requêtes API sont nécessaires pour obtenir une copie effacée, je trouve cette option moins préférable et moins pratique que la requête de données de formulaire utilisée dans .
Collections de facteurs
J'ai créé des collections dans Postman pour l'API Threat Prevention et l'API Threat Prevention pour Security Gateway, qui représentent les requêtes API les plus courantes. Afin que l'API et la clé ip/url du serveur soient automatiquement remplacées dans les requêtes, et que le montant de hachage sha256 soit 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 Édition -> Variables) : te_api (obligatoire), api_key (à renseigner obligatoirement, sauf lors de l'utilisation de l'API TP avec des appareils locaux), sha256 (laisser vide, non utilisé dans TP API pour SG).
Exemples d'utilisation
Dans la communauté des scripts écrits en Python sont présentés qui vérifient les fichiers du répertoire souhaité via Et . Grâce à l'interaction avec l'API Threat Prevention, votre capacité à analyser les fichiers est considérablement étendue, puisque vous pouvez désormais analyser des fichiers sur plusieurs plates-formes à la fois (archivage , puis dans le bac à sable Check Point), et recevez des fichiers non seulement du trafic réseau, mais également de n'importe quel lecteur réseau et, par exemple, des systèmes CRM.
Source: habr.com