Dieser Artikel wird für diejenigen nützlich sein, die sich mit Technologie auskennen Check Point durch Dateiemulation (Bedrohungsemulation) und proaktive Dateibereinigung (Bedrohungsextraktion) und möchte einen Schritt in Richtung Automatisierung dieser Aufgaben gehen. Check Point hat
Grundlegende Abkürzungen
Die Threat Prevention API arbeitet mit drei Hauptkomponenten, die in der API über die folgenden Textwerte aufgerufen werden:
av – Antiviren-Komponente, verantwortlich für die Signaturanalyse bekannter Bedrohungen.
te – Bedrohungsemulationskomponente, die für die Überprüfung von Dateien in der Sandbox verantwortlich ist und nach der Emulation ein bösartiges/gutartiges Urteil fällt.
Extraktion - Threat Extraction-Komponente, verantwortlich für die schnelle Konvertierung von Office-Dokumenten in eine sichere Form (in der alle potenziell schädlichen Inhalte entfernt werden), um sie schnell an Benutzer/Systeme zu übermitteln.
API-Struktur und Haupteinschränkungen
Die Threat Prevention API verwendet nur 4 Anfragen − Hochladen, Abfragen, Herunterladen und Kontingent. Im Header aller vier Anfragen müssen Sie den API-Schlüssel mithilfe des Parameters übergeben Genehmigung. Auf den ersten Blick scheint die Struktur viel einfacher zu sein als in
Derzeit ist die einzige Version der Threat Prevention API veröffentlicht – 1.0; die URL für API-Aufrufe sollte Folgendes enthalten: v1 in dem Teil, in dem Sie die Version angeben müssen. Anders als bei der Management API ist es notwendig, die API-Version in der URL anzugeben, andernfalls wird die Anfrage nicht ausgeführt.
Die Anti-Virus-Komponente unterstützt, wenn sie ohne andere Komponenten (te, extraction) aufgerufen wird, derzeit nur Abfrageanfragen mit MD5-Hashsummen. Threat Emulation und Threat Extraction unterstützen auch die Hash-Summen sha1 und sha256.
Es ist sehr wichtig, bei Abfragen keine Fehler zu machen! Die Anfrage kann fehlerfrei ausgeführt werden, jedoch nicht vollständig. Lassen Sie uns mit Blick auf die Zukunft einen Blick darauf werfen, was passieren kann, wenn in Abfragen Fehler/Tippfehler auftreten.
Anfrage mit einem Tippfehler beim Wort „reports“
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}
In der Antwort wird kein Fehler angezeigt, aber es werden überhaupt keine Informationen zu den Berichten angezeigt
{
"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."
}
}
}
]
}
Aber für eine Anfrage ohne einen Tippfehler im Berichtsschlüssel
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}
Wir erhalten eine Antwort, die bereits eine ID zum Herunterladen von Berichten enthält
{
"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."
}
}
}
]
}
Wenn wir einen falschen/abgelaufenen API-Schlüssel senden, erhalten wir als Antwort einen 403-Fehler.
SandBlast API: in der Cloud und auf lokalen Geräten
API-Anfragen können an Check Point-Geräte gesendet werden, auf denen die Threat Emulation-Komponente (Blade) aktiviert ist. Als Adresse für Anfragen müssen Sie die IP/URL des Geräts und den Port 18194 verwenden (z. B. https://10.10.57.19:18194/tecloud/api/v1/file/query). Sie sollten außerdem sicherstellen, dass die Sicherheitsrichtlinie auf dem Gerät diese Verbindung zulässt. Autorisierung standardmäßig über API-Schlüssel auf lokalen Geräten aus und der Autorisierungsschlüssel in Anforderungsheadern wird möglicherweise überhaupt nicht gesendet.
API-Anfragen an die CheckPoint-Cloud sollten an gesendet werden te.checkpoint.com (zum Beispiel - https://te.checkpoint.com/tecloud/api/v1/file/query). Der API-Schlüssel kann als Testlizenz für 60 Tage erworben werden, indem Sie sich an Check Point-Partner oder die örtliche Niederlassung des Unternehmens wenden.
Auf lokalen Geräten wird Threat Extraction noch nicht standardmäßig unterstützt.
Lokale Geräte unterstützen die Kontingentanfrage nicht.
Ansonsten gibt es keine Unterschiede zwischen Anfragen an lokale Geräte und an die Cloud.
API-Aufruf hochladen
Verwendete Methode − jetzt lesen
Rufadresse - https:///tecloud/api/v1/file/upload
Die Anfrage besteht aus zwei Teilen (Formulardaten): einer Datei zur Emulation/Bereinigung und einem Anfragetext mit Text.
Die Textanfrage darf nicht leer sein, darf aber keine Konfiguration enthalten. Damit die Anfrage erfolgreich ist, müssen Sie in der Anfrage mindestens den folgenden Text senden:
Für eine Upload-Anfrage erforderliches Minimum
HTTP-POST
https:///tecloud/api/v1/file/upload
Kopfzeilen:
Zulassung:
Body
{
"Anfrage": {
}
}
Reichen Sie das
Reichen Sie das
In diesem Fall wird die Datei gemäß den Standardparametern verarbeitet: Komponente - te, Betriebssystem-Images - Win XP und Win 7, ohne einen Bericht zu erstellen.
Anmerkungen zu den Hauptfeldern der Textanfrage:
file_name и Dateityp Sie können sie leer lassen oder gar nicht senden, da dies beim Hochladen einer Datei keine besonders nützlichen Informationen sind. In der API-Antwort werden diese Felder automatisch basierend auf dem Namen der heruntergeladenen Datei ausgefüllt und die Informationen im Cache müssen weiterhin mithilfe der Hash-Beträge md5/sha1/sha256 durchsucht werden.
Beispielanfrage mit leerem Dateinamen und Dateityp
{
"request": {
"file_name": "",
"file_type": "",
}
}
Funktionen — eine Liste, die die erforderliche Funktionalität bei der Verarbeitung in der Sandbox angibt – av (Anti-Virus), te (Threat Emulation), Extraktion (Threat Extraction). Wenn dieser Parameter überhaupt nicht übergeben wird, wird nur die Standardkomponente verwendet – te (Threat Emulation).
Um das Einchecken der drei verfügbaren Komponenten zu ermöglichen, müssen Sie diese Komponenten in der API-Anfrage angeben.
Beispiel einer Anfrage mit Einchecken von AV, TE und Extraktion
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}
Schlüssel im TE-Abschnitt
Bilder — eine Liste mit Wörterbüchern mit ID und Revisionsnummer der Betriebssysteme, in denen die Prüfung durchgeführt wird. IDs und Revisionsnummern sind für alle lokalen Geräte und die Cloud gleich.
Liste der Betriebssysteme und Revisionen
Verfügbare Betriebssystem-Image-ID
Änderungsstand
Image-Betriebssystem und Anwendung
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP - 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 und ActiveX 10.0
Java Laufzeit: 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 Laufzeit: 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 Laufzeit: 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 Laufzeit: 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 Laufzeit: 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 Laufzeit: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Office: Professional Plus 2016 de-us
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (Plugin & ActiveX)
Java Laufzeit: 1.7.0u9
Wenn der Bildschlüssel überhaupt nicht angegeben ist, erfolgt die Emulation in von Check Point empfohlenen Bildern (derzeit Win XP und Win 7). Diese Bilder werden unter Berücksichtigung der besten Balance zwischen Leistung und Fangquote empfohlen.
Berichte – eine Liste von Berichten, die wir anfordern, falls sich herausstellt, dass die Datei bösartig ist. Folgende Optionen stehen zur Verfügung:
-
Zusammenfassung - .tar.gz-Archiv mit einem Bericht über die Emulation von alle angeforderte Bilder (sowohl eine HTML-Seite als auch Komponenten wie ein Video vom Emulator-Betriebssystem, ein Netzwerk-Traffic-Dump, ein Bericht in JSON und das Beispiel selbst in einem passwortgeschützten Archiv). Wir suchen den Schlüssel in der Antwort - Kurzbericht zum späteren Herunterladen des Berichts.
-
pdf - Dokument zur Emulation in ein Bild, das viele gewohnt sind, über die Smart Console zu empfangen. Wir suchen den Schlüssel in der Antwort - pdf_report zum späteren Herunterladen des Berichts.
-
xml - Dokument zur Emulation in ein Bild, praktisch für die spätere Analyse der Parameter im Bericht. Wir suchen den Schlüssel in der Antwort - xml_report zum späteren Herunterladen des Berichts.
-
Teer - .tar.gz-Archiv mit einem Bericht über die Emulation in ein angeforderte Bilder (sowohl eine HTML-Seite als auch Komponenten wie ein Video vom Emulator-Betriebssystem, ein Netzwerk-Traffic-Dump, ein Bericht in JSON und das Beispiel selbst in einem passwortgeschützten Archiv). Wir suchen den Schlüssel in der Antwort - Kompletter Bericht zum späteren Herunterladen des Berichts.
Was steht im zusammenfassenden Bericht?
Die Schlüssel full_report, pdf_report, xml_report befinden sich im Wörterbuch für jedes Betriebssystem
{
"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."
}
}
}
]
}
Aber der summary_report-Schlüssel – es gibt einen für die Emulation im Allgemeinen
{
"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."
}
}
}
]
}
Sie können TAR- und XML- und PDF-Berichte gleichzeitig anfordern, Sie können eine Zusammenfassung sowie TAR- und XML-Berichte anfordern. Es ist nicht möglich, gleichzeitig einen zusammenfassenden Bericht und ein PDF anzufordern.
Schlüssel im Extraktionsbereich
Zur Bedrohungsextraktion werden nur zwei Schlüssel verwendet:
Methode — pdf (in PDF konvertieren, standardmäßig verwendet) oder clean (aktiven Inhalt bereinigen).
extrahierte_Teile_Codes - Liste der Codes zum Entfernen aktiver Inhalte, gilt nur für die Clean-Methode
Codes zum Entfernen von Inhalten aus Dateien
Code
Beschreibung
1025
Verknüpfte Objekte
1026
Makros und Code
1034
Sensible Hyperlinks
1137
PDF-GoToR-Aktionen
1139
PDF-Startaktionen
1141
PDF-URI-Aktionen
1142
PDF-Soundaktionen
1143
PDF-Filmaktionen
1150
PDF-JavaScript-Aktionen
1151
Aktionen zum Senden von PDF-Formularen
1018
Datenbankabfragen
1019
Embedded Objects
1021
Daten schnell speichern
1017
Benutzerdefinierte Eigenschaften
1036
Statistikeigenschaften
1037
Zusammenfassungseigenschaften
Um eine bereinigte Kopie herunterzuladen, müssen Sie außerdem nach einigen Sekunden eine Abfrageanfrage stellen (die weiter unten besprochen wird) und dabei die Hash-Menge der Datei und die Extraktionskomponente im Anfragetext angeben. Sie können die bereinigte Datei mithilfe der ID aus der Antwort auf die Abfrage abrufen – extract_file_download_id. Mit Blick auf die Zukunft gebe ich noch einmal Beispiele für eine Anfrage und eine Antwort auf eine Anfrage, um nach einer ID zum Herunterladen eines freigegebenen Dokuments zu suchen.
Abfrageanforderung zur Suche nach dem Schlüssel „extracted_file_download_id“.
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}
Antwort auf die Anfrage (suchen Sie nach dem Schlüssel „extracted_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."
}
}
}
]
}
Übersicht
In einem API-Aufruf können Sie nur eine Datei zur Überprüfung senden.
Die AV-Komponente erfordert keinen zusätzlichen Abschnitt mit Schlüsseln, es reicht aus, sie im Wörterbuch anzugeben Funktionen.
API-Aufruf abfragen
Verwendete Methode − jetzt lesen
Rufadresse - https:///tecloud/api/v1/file/query
Bevor Sie eine Datei zum Herunterladen senden (Upload-Anfrage), empfiehlt es sich, den Sandbox-Cache (Abfrageanforderung) zu überprüfen, um die Auslastung des API-Servers zu optimieren, da der API-Server möglicherweise bereits über Informationen und ein Urteil über die heruntergeladene Datei verfügt. Der Aufruf besteht nur aus einem Textteil. Der erforderliche Teil der Anfrage ist die Hash-Menge sha1/sha256/md5 der Datei. Sie können es übrigens in der Antwort auf die Upload-Anfrage erhalten.
Für die Abfrage erforderliches Minimum
HTTP-POST
https:///tecloud/api/v1/file/query
Kopfzeilen:
Zulassung:
Body
{
"Anfrage": {
„sha256“:
}
}
Ein Beispiel für eine Antwort auf eine Upload-Anfrage, bei der die Hash-Beträge sha1/md5/sha256 sichtbar sind
{
"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."
}
}
}
}
Die Abfrageanforderung sollte neben der Hash-Menge idealerweise mit der Upload-Anfrage übereinstimmen (oder geplant sein) oder sogar „schon“ sein (weniger Felder in der Abfrageanforderung enthalten als in der Upload-Anfrage). Falls die Abfrageanforderung mehr Felder enthält als die Upload-Anfrage, erhalten Sie in der Antwort nicht alle erforderlichen Informationen.
Hier ist ein Beispiel für eine Antwort auf eine Anfrage, bei der nicht alle erforderlichen Daten gefunden wurden
{
"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."
}
}
}
]
}
Achten Sie auf die Felder Code и Etikette. Diese Felder erscheinen dreimal in Statuswörterbüchern. Zuerst sehen wir den globalen Schlüssel „code“: 1006 und „label“: „PARTIALLY_FOUND“. Als nächstes werden diese Schlüssel für jede einzelne Komponente gefunden, die wir angefordert haben – Te und Extraktion. Und wenn klar ist, dass die Daten gefunden wurden, dann liegen für die Extraktion keine Informationen vor.
So sah die Abfrage für das obige Beispiel aus
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}
Wenn Sie eine Abfrageanfrage ohne die Extraktionskomponente senden
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}
Dann enthält die Antwort vollständige Informationen („Code“: 1001, „Label“: „FOUND“)
{
"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."
}
}
}
]
}
Wenn überhaupt keine Informationen im Cache vorhanden sind, lautet die Antwort „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."
}
}
}
]
}
In einem API-Aufruf können Sie mehrere Hash-Beträge gleichzeitig zur Überprüfung senden. Die Antwort gibt die Daten in derselben Reihenfolge zurück, in der sie in der Anfrage gesendet wurden.
Beispiel einer Abfrageanfrage mit mehreren sha256-Beträgen
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}
Antwort auf eine Anfrage mit mehreren sha256-Beträgen
{
"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."
}
}
}
]
}
Auch das gleichzeitige Anfordern mehrerer Hashsummen in einer Abfrageanforderung wirkt sich positiv auf die Leistung des API-Servers aus.
API-Aufruf herunterladen
Verwendete Methode − jetzt lesen (laut Dokumentation), BESTELLE funktioniert auch (und erscheint vielleicht logischer)
Rufadresse - https:///tecloud/api/v1/file/download?id=
Der Header erfordert die Übergabe des API-Schlüssels, der Hauptteil der Anfrage ist leer, die Download-ID wird in der URL-Adresse übergeben.
Als Antwort auf eine Abfrageanforderung wird die ID zum Herunterladen von Berichten angezeigt, wenn die Emulation abgeschlossen ist und beim Herunterladen der Datei Berichte angefordert wurden. Wenn eine bereinigte Kopie angefordert wird, sollten Sie nach der ID suchen, um das bereinigte Dokument herunterzuladen.
Insgesamt können die Schlüssel in der Antwort auf die Abfrage, die den ID-Wert zum Laden enthält, sein:
-
Kurzbericht
-
Kompletter Bericht
-
pdf_report
-
xml_report
-
extrahierte_datei_download_id
Um diese Schlüssel als Antwort auf die Abfrageanfrage zu erhalten, müssen diese natürlich in der Anfrage angegeben werden (für Berichte) oder daran gedacht werden, eine Anfrage über die Extraktionsfunktion zu stellen (für bereinigte Dokumente).
Kontingent-API-Aufruf
Verwendete Methode − jetzt lesen
Rufadresse - https:///tecloud/api/v1/file/quota
Um das verbleibende Kontingent in der Cloud zu überprüfen, verwenden Sie die Kontingentabfrage. Der Anfragetext ist leer.
Beispielantwort auf eine Kontingentanfrage
{
"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"
}
]
}
Bedrohungspräventions-API für Security Gateway
Diese API wurde vor der Threat Prevention API entwickelt und ist nur für lokale Geräte gedacht. Im Moment kann es nur dann nützlich sein, wenn Sie die Threat Extraction API benötigen. Für die Bedrohungsemulation ist es besser, die reguläre Threat Prevention API zu verwenden. Zum Einschalten TP-API für SG und konfigurieren Sie den API-Schlüssel, den Sie benötigen, um den Schritten folgen zu können
Schauen wir uns nun die Funktionen genauer an te и Extraktion in dieser API.
Für Komponente te Wörterbuch zur Verfügung gestellt te_options in Upload-/Abfrageanfragen, und die Schlüssel in dieser Anfrage stimmen vollständig mit den Te-Schlüsseln in überein
Beispielanforderung zur Dateiemulation in Win10 mit Berichten
{
"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"]
}
}
]
}
Für Komponente Extraktion Wörterbuch zur Verfügung gestellt Scrub_options. Diese Anfrage gibt die Reinigungsmethode an: in PDF konvertieren, aktive Inhalte löschen oder einen Modus gemäß dem Threat Prevention-Profil auswählen (der Profilname wird angezeigt). Das Tolle an der Antwort auf eine Extraktions-API-Anfrage für eine Datei ist, dass Sie in der Antwort auf diese Anfrage eine bereinigte Kopie als Base64-verschlüsselte Zeichenfolge erhalten (Sie müssen keine Abfrageanfrage stellen und die ID nachschlagen, um die Datei herunterzuladen dokumentieren)
Beispiel für eine Anfrage zum Löschen einer Datei
{
"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
}
}]
}
Auf eine Anfrage antworten
{
"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": ""
}
}]
}
Trotz der Tatsache, dass weniger API-Anfragen erforderlich sind, um eine freigegebene Kopie zu erhalten, finde ich diese Option weniger vorzuziehen und bequemer als die Formulardatenanforderung, die in verwendet wird
Postman-Sammlungen
Ich habe in Postman Sammlungen sowohl für die Threat Prevention API als auch für die Threat Prevention API für Security Gateway erstellt, die die häufigsten API-Anfragen darstellen. Damit die Server-IP/URL-API und der Schlüssel automatisch in Anfragen eingesetzt werden und die sha256-Hash-Menge nach dem Herunterladen der Datei gespeichert wird, wurden in den Sammlungen drei Variablen erstellt (Sie finden sie in den Sammlungseinstellungen). Bearbeiten -> Variablen): te_api (erforderlich), api_key (muss ausgefüllt werden, außer bei Verwendung der TP-API mit lokalen Geräten), sha256 (leer lassen, wird nicht in der TP-API für SG verwendet).
Примеры использования
In der Gemeinschaft
Source: habr.com