Dieser Artikel ist nützlich für diejenigen, die mit Technologien vertraut sind Check Point zur Dateiemulation (Threat Emulation) und der proaktiven Datei-Entfernung (Threat Extraction) und die einen Schritt in Richtung Automatisierung dieser Aufgaben machen möchten. Check Point bietet die , die sowohl in der Cloud als auch auf lokalen Geräten funktioniert, und funktionell identisch zur Überprüfung von Dateien in Web-/SMTP-/FTP-/SMB-/NFS-Datenströmen ist. Dieser Artikel ist teilweise eine persönliche Auslegung einer Reihe von Artikeln aus der offiziellen Dokumentation, basiert jedoch auf eigenen Erfahrungen und Beispielen. Außerdem finden Sie in dem Artikel persönliche Postman-Sammlungen für die Arbeit mit der Threat Prevention API.
Wichtige Abkürzungen
Die Threat Prevention API arbeitet mit drei Hauptkomponenten, die über die folgenden Textwerte im API aufgerufen werden:
av — die Anti-Virus-Komponente, verantwortlich für die signaturbasierte Analyse bekannter Bedrohungen.
tum — die Threat Emulation-Komponente, verantwortlich für die Überprüfung von Dateien in einer Sandbox und die Abgabe eines Urteils über bösartig (malicious) / sauber (benign) nach der Emulation.
extraction — die Komponente Threat Extraction, die für die schnelle Umwandlung von Bürodokumenten in eine sichere Form zuständig ist (in der allen potenziell schädlichen Inhalt entfernt wird), um eine zügige Bereitstellung für Benutzer/Systeme zu ermöglichen.
API-Struktur und grundlegende Einschränkungen
Die Threat Prevention API verwendet insgesamt 4 Anfragen — upload, query, download und quota. Im Header aller vier Anfragen muss der API-Schlüssel über das Parameter Authorizationübertragen werden. Auf den ersten Blick mag die Struktur viel einfacher erscheinen als die , aber die Anzahl der Felder in den Anfragen upload und query sowie die Struktur dieser Anfragen sind recht komplex. Sie können funktional mit den Profilen der Threat Prevention in der Sicherheitsrichtlinie des Gateways/Sandbox verglichen werden.
Derzeit ist die einzige Version der Threat Prevention API — 1.0 verfügbar, die im URL für API-Aufrufe angegeben werden muss v1 in dem Abschnitt, wo die Version angegeben werden muss. Im Gegensatz zur 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 derzeit bei Aufrufen ohne andere Komponenten (te, extraction) nur Anfragen query mit md5-Hashwerten. Threat Emulation und Threat Extraction unterstützen außerdem sha1- und sha256-Hashwerte.
Es ist sehr wichtig, keine Fehler bei Anfragen zu machen! Die Anfrage kann zwar fehlerfrei ausgeführt werden, jedoch nicht vollständig. Lassen Sie uns vorab betrachten, was bei Fehlern oder Tippfehlern in den Anfragen passieren kann.
Anfrage mit einem Tippfehler im Wort reports (reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Es wird keine Fehlermeldung im Antwort geben, jedoch werden keine Informationen zu den Berichten vorhanden sein.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "bösartig"
},
"status": "gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "bösartig",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Und jetzt die Anfrage ohne Tippfehler im Schlüssel reports
{ "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 die IDs zum Herunterladen der Berichte enthält.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "schädlich",
"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": "schädlich",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Wenn Sie jedoch einen falschen oder abgelaufenen API-Schlüssel senden, erhalten Sie eine Fehlerantwort 403.
SandBlast API: in der Cloud und auf lokalen Geräten
API-Anfragen können an Check Point-Geräte gesendet werden, auf denen die Komponente (Blade) Threat Emulation aktiviert ist. Als Adresse für die Anfragen sollten Sie die IP/URL des Geräts und den Port 18194 verwenden (zum Beispiel — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию deaktiviert und der Authorization-Key muss in den Anfrage-Headern nicht gesendet werden.
API-Anfragen an die CheckPoint-Cloud müssen an die Adresse te.checkpoint.com (zum Beispiel — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Auf lokalen Geräten wird Threat Extraction derzeit nicht standardmäßig unterstützt und es sollte (darüber sprechen wir am Ende des Artikels genauer).
Lokale Geräte unterstützen keine Quota-Anfragen.
Abgesehen davon gibt es keine Unterschiede zwischen den Anfragen an lokale Geräte und an die Cloud.
API-Aufruf Upload
Die verwendete Methode ist — POST
Adresse für den Aufruf — https://<service_address>/tecloud/api/v1/file/upload
Die Anfrage besteht aus zwei Teilen (form-data): einer Datei, die für die Emulation/Reinigung bestimmt ist, und einem Anfragebody mit Text.
Der Textanfrage darf nicht leer sein, kann jedoch keine Konfiguration enthalten. Damit die Anfrage erfolgreich ist, muss mindestens der folgende Text in der Anfrage gesendet werden:
Das notwendige Minimum für die Upload-Anfrage
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
Authorization: <api_key>
Body
{
«request»: {
}
}
Datei
Datei
In diesem Fall wird die Datei gemäß den Voreinstellungen verarbeitet: Komponente — tum, Betriebssystem-Images — Win XP und Win 7, ohne Generierung eines Berichts.
Kommentare zu den wichtigsten Feldern in der Textanfrage:
file_name und file_type können leer gelassen oder ganz weggelassen werden, da diese Informationen beim Hochladen der Datei nicht besonders nützlich sind. In der API-Antwort werden diese Felder automatisch auf Grundlage des Namens der hochgeladenen Datei ausgefüllt, und die Informationen im Cache müssen dennoch anhand von md5/sha1/sha256-Hashes gesucht werden.
Beispielanfrage mit leeren file_name und file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — eine Liste, die die erforderlichen Funktionen bei der Verarbeitung in der Sandbox angibt — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Wenn dieser Parameter nicht übergeben wird, wird nur die Standardkomponente — te (Threat Emulation) verwendet.
Um die Überprüfung in den drei verfügbaren Komponenten zu aktivieren, müssen diese Komponenten in der API-Anfrage angegeben werden.
Beispielanfrage mit Überprüfung in av, te und extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Schlüssel im Abschnitt te
images — eine Liste, in der die Wörterbücher mit ID und Versionsnummer der Betriebssysteme aufgeführt sein müssen, in denen die Überprüfung durchgeführt wird. ID und Versionsnummern sind für alle lokalen Geräte und die Cloud identisch.
Liste der Betriebssysteme und Versionen
Verfügbarer OS-Image-ID
Version
Image OS und Anwendung
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32-Bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 und ActiveX 10.0
Java Runtime: 1.6.0u22
7e6fe36e-889e-4c25-8704-56378f0830df
1
Microsoft Windows: 7 — 32-Bit
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-Bit
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-Bit
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-Bit
Office: 2013 (32-Bit)
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-Bit
Office: 2013 (64-Bit)
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
Wenn der Schlüssel images nicht angegeben wird, erfolgt die Emulation mit den von Check Point empfohlenen Images (derzeit Win XP und Win 7). Diese Images werden aufgrund des besten Gleichgewichts zwischen Leistung und Erkennungsrate empfohlen.
Berichte — eine Liste von Berichten, die wir anfordern, falls die Datei schädlich sein sollte. Folgende Optionen sind verfügbar:
Zusammenfassung — .tar.gz Archiv, das den Emulationsbericht enthält über alle angeforderten Images (sowohl als HTML-Seite als auch Komponenten wie ein Video aus dem Emulator-System, Netzwerkverkehrsdump, Bericht im JSON-Format sowie das Muster in einem passwortgeschützten Archiv). Im Antwort suchen wir nach dem Schlüssel — summary_report für den anschließenden Download des Berichts.
pdf — Dokument über die Emulation in einem Image, das viele gewohnt sind über die Smart Console zu erhalten. Im Antwort suchen wir nach dem Schlüssel — pdf_report für den anschließenden Download des Berichts.
xml — Dokument über die Emulation in einem Image, geeignet für die anschließende Analyse der Parameter im Bericht. Im Antwort suchen wir nach dem Schlüssel — xml_report für den anschließenden Download des Berichts.
, — .tar.gz Archiv, das den Bericht über die Emulation in sich enthält. einem angeforderten Images (sowohl als HTML-Seite als auch Komponenten wie ein Video aus dem Emulator-System, Netzwerkverkehrsdump, Bericht im JSON-Format sowie das Muster in einem passwortgeschützten Archiv). Im Antwort suchen wir nach dem Schlüssel — full_report für den anschließenden Download des Berichts.
Was im Summary-Bericht enthalten ist
Die Schlüssel full_report, pdf_report, xml_report sind im Wörterbuch für jedes Betriebssystem vorhanden.
{
"response": [
{
"status": {
"code": 1001,
"label": "GEFUNDEN",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
"file_type": "html",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "schädlich",
"full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
"pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
"xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
},
"status": "gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "schädlich",
"full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
"pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
"xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
},
"status": "gefunden",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "schädlich",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "GEFUNDEN",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Der Schlüssel summary_report ist jetzt einer zur Emulation insgesamt.
{
"response": [
{
"status": {
"code": 1001,
"label": "GEBEN",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "schädlich",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "schädlich",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "gefunden",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "schädlich",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "GEBEN",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Sie können die Berichte im tar-, xml- und pdf-Format gleichzeitig anfordern, sowie sowohl summary- als auch tar- und xml-Berichte. Eine gleichzeitige Anfrage nach einem summary-Bericht und pdf ist nicht möglich.
Die Schlüssel im Abschnitt extraction
Für die Bedrohungsextraktion werden nur zwei Schlüssel verwendet:
Methode — pdf (Konvertierung in pdf, standardmäßig verwendet) oder clean (Bereinigung der aktiven Inhalte).
extracted_parts_codes — Liste der Codes zum Entfernen aktiver Inhalte, anwendbar nur auf die Methode 'clean'
Codes zum Entfernen von Inhalten aus Dateien
Code
Beschreibung
1025
Verknüpfte Objekte
1026
Makros und Code
1034
Empfindliche Hyperlinks
1137
PDF GoToR-Aktionen
1139
PDF Startaktionen
1141
PDF URI-Aktionen
1142
PDF Audio-Aktionen
1143
PDF Film-Aktionen
1150
PDF JavaScript-Aktionen
1151
PDF Formularabsendungen
1018
Datenbankabfragen
1019
Eingebettete Objekte
1021
Schneller Speichern-Daten
1017
Benutzerdefinierte Eigenschaften
1036
Statistische Eigenschaften
1037
Zusammenfassungs-Eigenschaften
Um eine bereinigte Kopie herunterzuladen, muss außerdem eine Abfrage (query) gestellt werden, auf die später eingegangen wird. Dabei ist die Hashsumme der Datei und die Komponente 'extraction' im Text der Anfrage anzugeben. Die bereinigte Datei kann mithilfe der ID aus der Antwort auf die Abfrage — extracted_file_download_id — abgerufen werden. Noch einmal, um vorzugreifen, finden Sie hier Beispiele für die Anfrage und die Antwort, um die ID zum Herunterladen des bereinigten Dokuments zu suchen.
Abfrage (query) zur Suche nach dem Schlüssel extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Antwort auf die Abfrage (query) (finden Sie den Schlüssel extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"Extraktion"
],
"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": "Makros und Code",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potentiell bösartige Inhalte extrahiert",
"protection_type": "Konvertierung zu PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Aktiver Inhalt gefunden - XLS-Datei wurde in PDF konvertiert",
"scrub_method": "In PDF konvertieren",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Makros und Code"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Allgemeine Informationen
In einem API-Aufruf kann nur eine Datei zur Überprüfung gesendet werden.
Die Komponente av benötigt keinen zusätzlichen Abschnitt mit Schlüsseln; es genügt, sie im Wörterbuch anzugeben. features.
Abfrage der Query-API
Die verwendete Methode ist — POST
Adresse für den Aufruf — https://<service_address>/tecloud/api/v1/file/query
Bevor Sie eine Datei zum Hochladen senden (Upload-Anfrage), ist es sinnvoll, eine Überprüfung des Sandbox-Caches (Query-Anfrage) durchzuführen, um die Last auf dem API-Server zu optimieren, da möglicherweise bereits Informationen und ein Urteil über die hochzuladende Datei auf dem API-Server vorhanden sind. Der Aufruf besteht nur aus dem Textteil. Ein obligatorischer Teil der Anfrage ist der Datei sha1/sha256/md5-Hash. Dieser kann übrigens auch in der Antwort auf die Upload-Anfrage erhalten werden.
Minimalanforderung für die Query-Anfrage
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Body
{
«request»: {
„sha256“: <sha256 hash sum>
}
}
Beispielantwort auf die Upload-Anfrage, in der die sha1/md5/sha256-Hashwerte sichtbar sind.
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Die Datei wurde erfolgreich hochgeladen."
},
"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": "Die Datei wurde erfolgreich hochgeladen."
}
}
}
}Die Anfrage 'query' sollte idealerweise die gleiche Anzahl an Feldern wie die Anfrage 'upload' haben oder sogar weniger enthalten. Wenn die Anfrage 'query' mehr Felder enthält als die Anfrage 'upload', erhalten Sie möglicherweise nicht alle erforderlichen Informationen in der Antwort.
Hier ist ein Beispiel für eine Antwort auf die Anfrage 'query', bei der nicht alle erforderlichen Daten gefunden wurden.
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Die Anfrage kann zurzeit nicht vollständig beantwortet werden."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "bösartig",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "bösartig",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Die angeforderte Datei konnte nicht gefunden werden. Bitte laden Sie sie hoch."
}
}
}
]
}Bitte beachten Sie die Felder code und Bezeichnung. Diese Felder erscheinen dreimal in den Statuswörterbüchern. Zunächst sehen wir den globalen Schlüssel „code“: 1006 und „label“: „PARTIALLY_FOUND“. Anschließend tauchen diese Schlüssel bei jedem einzelnen angeforderten Komponenten auf — te und extraction. Während für te klar ist, dass die Daten gefunden wurden, fehlt die Information für extraction.
So sah die Anfrage query 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 die Anfrage query ohne die Komponente extraction gesendet wird
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}wird die Antwort vollständige Informationen enthalten („code“: 1001, „label“: „FOUND“)
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "bösartig",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "bösartig",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Wenn im Cache keine Informationen vorhanden sind, wird in der Antwort "label": "NOT_FOUND" angezeigt.
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Die angeforderte Datei konnte nicht gefunden werden. Bitte laden Sie sie hoch."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unbekannt"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Die angeforderte Datei konnte nicht gefunden werden. Bitte laden Sie sie hoch."
}
}
}
]
}In einem API-Aufruf können mehrere Hash-Werte gleichzeitig zur Überprüfung gesendet werden. Die Antwort enthält die Daten in derselben Reihenfolge, wie sie im Anfrage gesendet wurden.
Beispiel einer Anfrage mit mehreren sha256 Hash-Werten
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Antwort auf die Anfrage mit mehreren sha256 Hash-Werten
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "bösartig"
},
"status": "gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "bösartig",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
},
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Die angeforderte Datei konnte nicht gefunden werden. Bitte laden Sie sie hoch."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unbekannt"
},
"status": "nicht gefunden",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Die angeforderte Datei konnte nicht gefunden werden. Bitte laden Sie sie hoch."
}
}
}
]
}Die Abfrage mehrerer Hashsummen in der Anfrage kann sich positiv auf die API-Serverleistung auswirken.
Aufruf der Download-API
Die verwendete Methode ist — POST (laut Dokumentation), GET funktioniert ebenfalls (und könnte logischer erscheinen)
Adresse für den Aufruf — https://<service_address>/tecloud/api/v1/file/download?id=<id>
Im Header muss der API-Schlüssel übermittelt werden, der Request-Body ist leer, die ID für den Download wird in der URL übergeben.
Als Antwort auf die Query-Anfrage, falls die Emulation abgeschlossen ist und beim Dateiupload Berichte angefordert wurden, werden die IDs für den Download der Berichte sichtbar. Falls eine bereinigte Kopie angefordert wird, sollte nach der ID für den Download des bereinigten Dokuments gesucht werden.
Zusammengefasst können die Schlüssel in der Antwort auf die Query-Anfrage, die den Wert der ID für den Download enthalten, folgende sein:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Um sicherzustellen, dass diese Schlüssel in der Antwort auf die Query-Anfrage erhalten werden, müssen sie in der Anfrage angegeben werden (für Berichte) oder man darf nicht vergessen, einen Request für die Extraktionsfunktion zu stellen (für bereinigte Dokumente).
Aufruf der Quota API
Die verwendete Methode ist — POST
Adresse für den Aufruf — https://<service_address>/tecloud/api/v1/file/quota
Zur Überprüfung des verbleibenden Kontingents in der Cloud wird die Anfrage quota verwendet. Der Request-Body ist leer.
Beispielantwort auf die Anfrage 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
Diese API wurde vor der Threat Prevention API entwickelt und ist nur für lokale Geräte gedacht. Derzeit kann sie nur nützlich sein, wenn Sie die Threat Extraction API benötigen. Für die Threat Emulation ist es besser, die herkömmliche Threat Prevention API zu nutzen. Um zu aktivieren TP API für SG und den API-Schlüssel zu konfigurieren, sind die Schritte auszuführen . Ich empfehle, Schritt 6b zu beachten und die Verfügbarkeit der Seite zu überprüfen https:///UserCheck/TPAPI , da die weitere Konfiguration im Falle eines negativen Ergebnisses keinen Sinn macht. Alle API-Aufrufe werden an diese URL gesendet. Die Art des Aufrufs (upload/query) wird im Body-Key geregelt — request_name. Auch die folgenden Schlüssel sind erforderlich: — api_key (diesen während der Konfiguration notieren) und protocol_version (derzeit ist die aktuelle Version 1.1). Die offizielle Dokumentation für dieses API finden Sie in . Zu den relativen Vorteilen gehört die Möglichkeit, mehrere Dateien gleichzeitig für die Emulation hochzuladen, da die Dateien als base64-Textzeichenfolge gesendet werden. Um Dateien in base64 zu codieren/dekodieren, kann für Demonstrationszwecke der Online-Konverter in Postman verwendet werden, zum Beispiel — . In der Praxis sollten die integrierten Methoden encode und decode verwendet werden.
Jetzt schauen wir uns die Funktionen tum und extraction in diesem API näher an.
Für die Komponente tum gibt es ein Wörterbuch te_options in den Anfragen upload/query, und die Schlüssel in dieser Anfrage stimmen vollständig mit den Schlüsseln te in .
Ein Beispiel für eine Anfrage zur Emulation einer Datei unter Win10 mit Berichten
{
"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"]
}
}
]
}Für die Komponente extraction gibt es ein Wörterbuch scrub_options. In dieser Anfrage wird die Reinigungsmethode angegeben: Konvertierung in PDF, Entfernung aktiver Inhalte oder die Auswahl des Modus gemäß dem Profil Threat Prevention (Profilname angeben). Ein besonderes Merkmal der API-Antwort bei einem Extraktionsantrag für eine Datei ist, dass Sie eine bereinigte Kopie in Form eines verschlüsselten base64-Strings als Antwort auf diese Anfrage erhalten (es ist nicht notwendig, eine Abfrage anzufordern und die ID für den Dokumenten-Download zu suchen).
Beispielanfrage zur Dateireinigung
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Antwort auf die Anfrage
{
"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": "Potenziell schädliche Inhalte extrahieren",
"protection_type": "Konvertierung in PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT-Datei wurde in PDF umgewandelt",
"scrub_method": "In PDF konvertieren",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Obwohl weniger API-Anfragen erforderlich sind, um eine bereinigte Kopie zu erhalten, halte ich diese Option für weniger bevorzugt und komfortabel als die form-data-Anfrage, die in .
Postman-Kollektionen
Ich habe in Postman Kollektionen sowohl für die Threat Prevention API als auch für die Threat Prevention API für die Sicherheits-Gateway erstellt, in denen die gängigsten API-Anfragen dargestellt sind. Damit die IP/URL des API-Servers und der Schlüssel automatisch in die Anfragen eingefügt werden und der SHA256-Hash nach dem Hochladen der Datei ebenfalls gespeichert wird, wurden innerhalb der Kollektionen drei Variablen erstellt (diese finden Sie in den Einstellungen der Kollektion unter Edit -> Variables): te_api (muss ausgefüllt werden), api_key (muss ausgefüllt werden, außer bei Verwendung der TP API mit lokalen Geräten), sha256 (leer lassen, bei TP API für SG nicht verwendet).
Beispielverwendungen
In der Community werden Skripte vorgestellt, die in Python geschrieben sind und Dateien aus dem gewünschten Verzeichnis sowohl über , als auch . Durch die Interaktion mit der Threat Prevention API erweitern sich Ihre Möglichkeiten zur Überprüfung von Dateien erheblich, da Sie jetzt Dateien gleichzeitig auf mehreren Plattformen überprüfen können (interessant ist die Überprüfung über , und dann in der Check Point Sandbox), wobei Dateien nicht nur aus dem Netzwerkverkehr abgerufen werden, sondern auch von beliebigen Netzwerk-Laufwerken und beispielsweise CRM-Systemen.
Quelle: habr.com
