Dieser Artikel ist nützlich für diejenigen, die mit Technologien vertraut sind Check Point zur Emulation von Dateien (Threat Emulation) und proaktiver Dateireinigung (Threat Extraction) und einen Schritt in Richtung Automatisierung dieser Aufgaben machen möchten. Check Point bietet , die sowohl in der Cloud als auch auf lokalen Geräten funktioniert, und funktional identisch mit der Überprüfung von Dateien im Web-/SMTP-/FTP-/SMB-/NFS-Datenverkehr. Dieser Artikel ist teilweise eine persönliche Auslegung einer Reihe von Artikeln aus der offiziellen Dokumentation, basiert jedoch auf meiner eigenen Betriebserfahrung und eigenen Beispielen. Außerdem finden Sie in diesem Artikel persönliche Postman-Sammlungen zur Verwendung mit der Threat Prevention API.
Wichtige Abkürzungen
Die Threat Prevention API arbeitet mit drei Hauptkomponenten, die im API durch die folgenden Textwerte aufgerufen werden:
av — das Anti-Virus-Komponente, verantwortlich für die signaturbasierte Analyse bekannter Bedrohungen.
te — die Komponente Threat Emulation, verantwortlich für die Dateiüberprüfung in einer Sandbox und die Abgabe eines Urteils über böswillig (malicious)/sauber (benign) nach der Emulation.
extraction — die Komponente Threat Extraction, zuständig für die schnelle Konvertierung von Büro-Dokumenten in ein sicheres Format (bei dem allen potenziell schädlichen Inhalt entfernt wird), um sie schnell an Benutzer/Systeme zu liefern.
Die Struktur der API und die wichtigsten Einschränkungen
Die Threat Prevention API verwendet insgesamt 4 Anfragen — upload, query, download und quota. In der Kopfzeile für alle vier Anfragen muss der API-Schlüssel über den Parameter Authorization. Auf den ersten Blick könnte die Struktur viel einfacher erscheinen als bei der , aber die Anzahl der Felder in den Anfragen upload und query sowie die Struktur dieser Anfragen sind ziemlich komplex. Sie können funktional mit den Profilen der Threat Prevention in der Sicherheitsrichtlinie der Gateway-/Sandbox verglichen werden.
Derzeit ist nur eine Version der Threat Prevention API veröffentlicht — 1.0, im URL für API-Aufrufe sollte angegeben werden v1 in dem Abschnitt, in dem 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, die md5-Hashwerte verwenden. Die Threat Emulation und Threat Extraction unterstützen auch sha1- und sha256-Hashwerte.
Es ist sehr wichtig, keine Fehler bei den Anfragen zu machen! Die Anfrage kann ohne Fehler, aber nicht vollständig ausgeführt werden. Ein wenig vorweggenommen betrachten wir, was bei Fehlern/Tippfehlern in Anfragen passieren kann.
Anfrage mit einem Tippfehler im Wort report (reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}Es gibt keine Fehler im Antworttext, aber es wird auch keine Information über die Berichte 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": "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": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Und hier 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": "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": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Wenn jedoch ein falscher/abgelaufener API-Schlüssel gesendet wird, erhalten wir einen Fehler 403 in der Antwort.
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 sollte die IP/URL des Geräts und der Port 18194 verwendet werden (zum Beispiel — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию deaktiviert und der Authorization-Schlüssel in den Anfrage-Headern kann vollständig weggelassen 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 verwendet werden (darüber werden wir am Ende des Artikels ausführlicher sprechen).
Lokale Geräte unterstützen die Anforderung quota nicht.
Abgesehen davon gibt es keine Unterschiede zwischen Anfragen an lokale Geräte und an die Cloud.
Der Aufruf des Upload-API
Die verwendete Methode ist — POST
Die Adresse für den Aufruf ist — https://<service_address>/tecloud/api/v1/file/upload
Die Anfrage besteht aus zwei Teilen (form-data): einer Datei, die zur Emulation/ Reinigung bestimmt ist, und dem Anfragekörper mit Text.
Die Textanfrage darf nicht leer sein, kann aber keine Konfiguration enthalten. Um die Anfrage erfolgreich zu machen, müssen mindestens der folgende Text in der Anfrage gesendet werden:
Das Mindestmaß für die Upload-Anfrage
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Header:
Authorization: <api_key>
Body
{
"request": {
}
}
Datei
Datei
In diesem Fall gelangt die Datei zur Verarbeitung gemäß den Standardparametern: Komponente — te, Betriebssystem-Images — Win XP und Win 7, ohne Erstellung eines Berichts.
Kommentare zu den wichtigsten Feldern in der Textanfrage:
file_name und file_type können leer gelassen oder gar nicht gesendet werden, da dies bei der Dateiübertragung nicht besonders nützliche Informationen sind. Im API-Antwort werden diese Felder automatisch basierend auf dem Namen der hochgeladenen Datei ausgefüllt, und die Informationen im Cache müssen trotzdem anhand von md5/sha1/sha256-Hashes gesucht werden.
Beispiel einer Anfrage mit leeren file_name und file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — eine Liste, in der die notwendige Funktionalität bei der Verarbeitung in der Sandbox angegeben wird — av (Antivirus), te (Threat Emulation), extraction (Threat Extraction). Wenn dieser Parameter gar nicht übergeben wird, wird nur die Standardkomponente — te (Threat Emulation) verwendet.
Um die Prüfung in den drei verfügbaren Komponenten zu aktivieren, müssen diese Komponenten in der API-Anfrage angegeben werden.
Beispiel einer Anfrage mit Prüfung in av, te und extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Die Schlüssel im Abschnitt te
images — eine Liste, in der Wörterbücher mit ID und Versionsnummern der Betriebssysteme, in denen die Prüfung durchgeführt wird, angegeben werden müssen. ID und Versionsnummern sind für alle lokalen Geräte und die Cloud gleich.
Liste der Betriebssysteme und Versionen
Verfügbare OS-Image-ID
Revision
Bild 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 — 32bit
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Plugin& ActiveX)
Java Runtime: 1.6.0u0
8d188031-1010-4466-828b-0cd13d4303ff
1
Microsoft Windows: 7 — 32bit
Office: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Plugin & ActiveX)
Java Runtime: 1.7.0u0
5e5de275-a103-4f67-b55b-47532918fa59
1
Microsoft Windows: 7 — 32bit
Office: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
3ff3ddae-e7fd-4969-818c-d5f1a2be336d
1
Microsoft Windows: 7 — 64bit
Office: 2013 (32bit)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
6c453c9b-20f7-471a-956c-3198a868dc92
1
Microsoft Windows: 8.1 — 64bit
Office: 2013 (64bit)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
10b4a9c6-e414-425c-ae8b-fe4dd7b25244
1
Microsoft Windows: 10
Office: Professional Plus 2016 en-us
Adobe Acrobat Reader: DC 2015 MUI
Flash Player: 20 (Plugin & ActiveX)
Java Runtime: 1.7.0u9
Wenn der Schlüssel images überhaupt nicht angegeben wird, erfolgt die Emulation anhand der von Check Point empfohlenen Images (aktuell sind dies Win XP und Win 7). Diese Images werden aufgrund des besten Verhältnisses von Leistung und Erkennungsrate empfohlen.
Berichte — eine Liste von Berichten, die wir anfordern, falls die Datei schädlich ist. Folgende Optionen stehen zur Verfügung:
summary — .tar.gz Archiv, das den Emulationsbericht für mit allem die angeforderten Images (sowohl als HTML-Seite als auch Komponenten wie ein Video aus dem Emulationsbetriebssystem, einen Dump des Netzwerkverkehrs, einen Bericht im JSON-Format sowie das Beispiel selbst in einem passwortgeschützten Archiv) enthält. Im Antwort suchen wir nach dem Schlüssel — summary_report zum anschließenden Herunterladen 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 zum anschließenden Herunterladen des Berichts.
xml — Dokument über die Emulation in einem Image, geeignet zum anschließenden Parsen der Parameter im Bericht. Im Antwort suchen wir nach dem Schlüssel — xml_report zum anschließenden Herunterladen des Berichts.
tar — .tar.gz Archiv, das den Emulationsbericht in einem die angeforderten Images (sowohl als HTML-Seite als auch Komponenten wie ein Video aus dem Emulationsbetriebssystem, einen Dump des Netzwerkverkehrs, einen Bericht im JSON-Format sowie das Beispiel selbst in einem passwortgeschützten Archiv) enthält. Im Antwort suchen wir nach dem Schlüssel — full_report zum anschließenden Herunterladen des Berichts.
Was im Bericht summary enthalten ist
Die Schlüssel full_report, pdf_report, xml_report sind im Wörterbuch für jedes Betriebssystem enthalten.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"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": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Der Schlüssel summary_report ist für die gesamte Emulation vorhanden.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "bösartig",
"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": "bösartig",
"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": "bösartig",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "FOUND",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
}
]
}Man kann gleichzeitig tar- und xml- sowie pdf-Berichte anfordern, zusammenfassende Berichte sowie tar- und xml-Berichte. Es ist nicht möglich, zusammenfassende Berichte und pdf gleichzeitig anzufordern.
Die Schlüssel im Abschnitt extraction
Für die Bedrohungsextraktion werden nur zwei Schlüssel verwendet:
method — pdf (Konvertierung in pdf, Standardmethode) oder clean (Bereinigung des aktiven Inhalts).
extracted_parts_codes — Liste der Codes zum Entfernen aktiven Inhalts, nur anwendbar für 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 Start Aktionen
1141
PDF URI Aktionen
1142
PDF Sound Aktionen
1143
PDF Film Aktionen
1150
PDF JavaScript Aktionen
1151
PDF Formularaktionen
1018
Datenbankabfragen
1019
Eingebettete Objekte
1021
Schnell gespeicherte Daten
1017
Benutzerdefinierte Eigenschaften
1036
Statistische Eigenschaften
1037
Zusammenfassende Eigenschaften
Um eine bereinigte Kopie herunterzuladen, ist auch eine Anfrage query erforderlich (darüber wird gleich gesprochen) nach wenigen Sekunden, indem die Hash-Summe der Datei und die Komponente extraction im Anfrage-Text angegeben werden. Die bereinigte Datei kann mit der id aus der Antwort auf die Anfrage query — extracted_file_download_id — abgerufen werden. Nochmals, um vorauszuspringen, gebe ich Beispiele für die Anfrage und die Antwort query zur Suche nach der id zum Herunterladen des bereinigten Dokuments an.
Anfrage query zur Suche nach dem Schlüssel extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Antwort auf die Anfrage 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ösartiger Inhalt extrahiert",
"protection_type": "Konvertierung in 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 av-Komponente benötigt keinen zusätzlichen Abschnitt mit Schlüsseln, es reicht, sie im Wörterbuch anzugeben. features.
API Abfrage aufrufen
Die verwendete Methode ist — POST
Die Adresse für den Aufruf ist — https://<service_address>/tecloud/api/v1/file/query
Bevor Sie eine Datei zum Hochladen (Upload-Anfrage) senden, ist es ratsam, den Cache der Sandbox (Query-Anfrage) zu überprüfen, um die Belastung des API-Servers zu optimieren, da möglicherweise bereits Informationen und ein Urteil zum hochzuladenden Datei auf dem API-Server vorhanden sind. Der Aufruf besteht nur aus dem Textteil. Ein notwendiger Teil der Anfrage ist der sha1/sha256/md5 Hash des Dateiinhalts. Dieser kann übrigens als Antwort auf die Upload-Anfrage erhalten werden.
Das erforderliche Minimum für die Query-Anfrage
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Header:
Authorization: <api_key>
Body
{
"request": {
"sha256": <sha256 hash sum>
}
}
Beispiel für eine Antwort auf die Upload-Anfrage, bei 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": "unbekannt"
},
"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 genau so sein wie die Anfrage upload (oder beabsichtigt ist), oder sogar "bereits" (weniger Felder in der Anfrage query als in der Anfrage upload enthalten). Falls die Anfrage query mehr Felder enthält als in der Anfrage upload, erhalten Sie in der Antwort nicht alle erforderlichen Informationen.
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 derzeit nicht vollständig beantwortet werden."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "schädlich",
"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": "schädlich",
"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 label. Diese Felder tauchen dreimal in den Status-Wörterbüchern auf. Zunächst sehen wir den globalen Schlüssel „code“: 1006 und „label“: „PARTIALLY_FOUND“. Danach erscheinen diese Schlüssel für jede einzelne Komponente, die wir angefordert haben - te und extraction. Und während für te klar ist, dass Daten gefunden wurden, fehlen für extraction die Informationen.
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"
]
}
}
]
}Dann wird auch in der Antwort vollständige Information vorhanden sein ("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 es überhaupt keine Informationen im Cache gibt, wird in der Antwort "label": "NOT_FOUND" stehen.
{
"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": "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."
}
}
}
]
}In einem API-Aufruf können mehrere Hash-Summen zur Überprüfung gesendet werden. Die Daten werden in derselben Reihenfolge zurückgegeben, in der sie in der Anfrage gesendet wurden.
Beispiel einer Anfrage query mit mehreren sha256-Summen
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Antwort auf die Anfrage query mit mehreren sha256-Summen
{
"response": [
{
"status": {
"code": 1001,
"label": "GEFUNDEN",
"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": "GEFUNDEN",
"message": "Die Anfrage wurde vollständig beantwortet."
}
}
},
{
"status": {
"code": 1004,
"label": "NICHT_GEFUNDEN",
"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": "NICHT_GEFUNDEN",
"message": "Die angeforderte Datei konnte nicht gefunden werden. Bitte laden Sie sie hoch."
}
}
}
]
}Die Anfrage mehrerer Hash-Werte im Query wird sich ebenfalls positiv auf die Leistung des API-Servers auswirken.
Aufruf der Download-API
Die verwendete Methode ist — POST (entsprechend der Dokumentation), GET funktioniert ebenfalls (und könnte logischer erscheinen)
Die Adresse für den Aufruf ist — https://<service_address>/tecloud/api/v1/file/download?id=<id>
Im Header muss der API-Schlüssel übermittelt werden, der Anfrageinhalt 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 Hochladen der Datei Berichte angefordert wurden, werden die IDs für den Download der Berichte sichtbar sein. Wenn eine bereinigte Kopie angefordert wird, muss die ID für den Download des bereinigten Dokuments gesucht werden.
Zusammenfassend können die Schlüssel in der Antwort auf die Query-Anfrage, die den Wert der ID für den Download enthalten, 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 enthalten sind, müssen sie in der Anfrage angegeben werden (für Berichte) oder man sollte nicht vergessen, einen Antrag auf die Funktion Extraktion zu stellen (für bereinigte Dokumente).
Aufruf der Quota-API
Die verwendete Methode ist — POST
Die Adresse für den Aufruf ist — https://<service_address>/tecloud/api/v1/file/quota
Zur Überprüfung des verbleibenden Kontingents in der Cloud wird die Anfrage quota verwendet. Der Anfrageinhalt 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 für Security Gateway
Diese API wurde vor der Threat Prevention API entwickelt und ist nur für lokale Geräte gedacht. Derzeit ist sie nur nützlich, wenn Sie die Threat Extraction API benötigen. Für die Threat Emulation sollten Sie die reguläre Threat Prevention API verwenden. Um zu aktivieren TP API für SG und den API-Schlüssel zu konfigurieren, müssen die Schritte aus befolgt werden. Ich empfehle, auf Schritt 6b zu achten und die Verfügbarkeit der Seite https:///UserCheck/TPAPI zu überprüfen, da eine negative Rückmeldung die weitere Konfiguration sinnlos macht. An diese URL werden alle API-Aufrufe gesendet. Der Aufruftyp (upload/query) wird durch den Schlüssel im Anfragebody geregelt — request_name. Die erforderlichen Schlüssel sind außerdem — api_key (muss während der Konfiguration notiert werden) und protocol_version (derzeit ist die aktuelle Version 1.1). Die offizielle Dokumentation für diese API finden Sie in . Zu den relativen Vorteilen gehört die Möglichkeit, mehrere Dateien gleichzeitig zur Emulation bei ihrer Übertragung zu senden, da die Dateien als Base64-Textzeichenfolge gesendet werden. Um Dateien in Base64 zu kodieren/dekodieren, können Sie zu Demonstrationszwecken in Postman einen Online-Konverter verwenden, zum Beispiel — . In der praktischen Anwendung sollten beim Kodieren die integrierten Methoden encode und decode verwendet werden.
Nun lassen Sie uns näher auf die Funktionen te und extraction in dieser API eingehen.
Für die Komponente te ist ein Wörterbuch te_options in den Anfragen upload/query vorgesehen, und die Schlüssel in dieser Anfrage stimmen vollständig mit den Schlüsseln te in .
Beispielanfrage zur Emulation einer Datei in 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 ist ein Wörterbuch scrub_options. In dieser Anfrage wird die Reinigungsmethode angegeben: Konvertierung in PDF, Bereinigung von aktivem Inhalt oder Auswahl des Modus gemäß dem Profil Threat Prevention (der Name des Profils wird angegeben). Ein charakteristisches Merkmal der Antwort auf die API-Anfrage mit Extraction für die Datei ist, dass Sie eine gereinigte Kopie als Antwort auf diese Anfrage in Form einer verschlüsselten base64-Zeichenfolge erhalten (Sie müssen keine Anfrage für die Abfrage stellen und die ID zur Dokumentenladung suchen).
Beispiel einer Anfrage zur Bereinigung einer Datei
{
"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 bösartige Inhalte extrahieren",
"protection_type": "Konvertierung in PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "TXT-Datei wurde in PDF konvertiert",
"scrub_method": "Konvertierung in PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Obwohl für den Erhalt einer gereinigten Kopie weniger API-Anfragen erforderlich sind, halte ich diese Variante für weniger direkt und praktisch als die form-data Anfrage, die in .
Postman-Kollektionen
Ich habe Kollektionen in Postman sowohl für die Threat Prevention API als auch für die Threat Prevention API für Security Gateway erstellt, in denen die gängigsten API-Anfragen dargestellt sind. Damit IP/URL des API-Servers und der Schlüssel automatisch in die Anfragen eingesetzt werden und die SHA256-Hashsumme nach dem Hochladen der Datei gespeichert bleibt, wurden innerhalb der Kollektionen drei Variablen erstellt (diese finden Sie in den Einstellungen der Sammlung unter Bearbeiten -> Variablen): 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, wird in der TP API für SG nicht verwendet).
Beispiele zur Verwendung
In der Gemeinschaft sind Skripte dargestellt, die in Python geschrieben wurden 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 Dateiprüfung erheblich, da Sie nun Dateien sofort auf mehreren Plattformen überprüfen können (interessant erscheint die Prüfung auf , und dann in der Sandbox Check Point), und Dateien nicht nur aus dem Netzwerkverkehr erhalten, sondern sie auch von beliebigen Netzlaufwerken sowie beispielsweise aus CRM-Systemen abrufen.
Quelle: habr.com
