Ten artykuł będzie przydatny dla osób znających technologie Check Point emulacji plików (Emulacja zagrożeń) oraz proaktywnego czyszczenia plików (Ekstrakcja zagrożeń) i pragnących uczynić krok w kierunku automatyzacji tych zadań. Check Point oferuje , które działa zarówno w chmurze, jak i na lokalnych urządzeniach. Jego funkcjonalność jest identyczna jak w przypadku analizy plików w ruchu web/smtp/ftp/smb/nfs. Artykuł ten jest częściowo autorską interpretacją zestawu artykułów z oficjalnej dokumentacji, opartą na swoim doświadczeniu z eksploatacji oraz na własnych przykładach. W artykule znajdziesz również autorskie kolekcje Postman do pracy z Threat Prevention API.
Podstawowe skróty
Threat Prevention API działa z trzema głównymi komponentami, które w API są wywoływane przez następujące tekstowe wartości:
av — komponent Anti-Virus, odpowiedzialny za analizę sygnatur znanych zagrożeń.
te — komponent Threat Emulation, odpowiedzialny za analizę plików w piaskownicy oraz wydawanie werdyktu złośliwy (malicious)/czysty (benign) po emulacji.
extraction — komponent Threat Extraction, odpowiedzialny za szybkie konwertowanie dokumentów biurowych na bezpieczny format (w którym usuwana jest cała potencjalnie złośliwa treść), w celu szybkiej dostawy do użytkowników/systemów.
Struktura API i główne ograniczenia
Threat Prevention API używa zaledwie 4 zapytań — upload, query, download oraz quota. W nagłówku dla wszystkich czterech zapytań należy przesłać klucz API, używając parametru Authorization. Na pierwszy rzut oka struktura może wydawać się znacznie prostsza niż w , ale liczba pól w zapytaniach upload i query oraz struktura tych zapytań są dość złożone. Można je funkcjonalnie porównać z profilami Threat Prevention w polityce bezpieczeństwa bramy/piaskownicy.
Obecnie dostępna jest tylko jedna wersja Threat Prevention API — 1.0, w URL do wywołań API należy wskazać v1 w tej części, gdzie wymagana jest wskazanie wersji. W przeciwieństwie do Management API, wskazanie wersji API w adresie URL jest obowiązkowe, inaczej zapytanie nie zostanie wykonane.
Komponent Anti-Virus przy wywołaniu bez innych komponentów (te, extraction) obecnie wspiera tylko zapytania query z sumami kontrolnymi md5. Threat Emulation i Threat Extraction wspierają również sumy kontrolne sha1 i sha256.
Bardzo ważne jest unikanie błędów w zapytaniach! Żądanie może być wykonane bez błędu, ale nie w pełni. Z przodu omówimy, co może się zdarzyć w przypadku błędów/pomyłek w żądaniach.
Żądanie z błędem w słowie reports(reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}W odpowiedzi nie będzie błędu, ale nie będzie żadnych informacji o raportach.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zaadresowane."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "złośliwy"
},
"status": "znaleziony",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "złośliwy",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zaadresowane."
}
}
}
]
}A oto żądanie bez błędu w kluczu reports.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}Otrzymujemy odpowiedź, w której już znajdują się identyfikatory do pobrania raportów.
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zaadresowane."
},
"sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
"file_type": "pdf",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "złośliwy",
"full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
"pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
"xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
},
"status": "znaleziony",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "złośliwy",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zaadresowane."
}
}
}
]
}Jeśli jednak wyślemy niewłaściwy/zatrzymany klucz API, to w odpowiedzi otrzymamy błąd 403.
SandBlast API: w chmurze i na lokalnych urządzeniach.
Żądania API można wysyłać do urządzeń Check Point, na których włączony jest komponent (blade) Threat Emulation. Jako adres do żądań należy używać ip/url urządzenia oraz portu 18194 (na przykład — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию wyłączona i klucz Authorization w nagłówkach zapytań można całkowicie pominąć.
Zapytania API do chmury CheckPoint należy wysyłać na adres te.checkpoint.com (na przykład — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Na lokalnych urządzeniach Threat Extraction na razie nie jest obsługiwane w standardowym i należy używać (o tym omówimy szczegółowo pod koniec artykułu).
Lokalne urządzenia nie obsługują zapytania quota.
Poza tym nie ma różnic między zapytaniami do lokalnych urządzeń a do chmury.
Wywołanie Upload API
Używana metoda to — POST
Adres do wywołania to — https://<service_address>/tecloud/api/v1/file/upload
Zapytanie składa się z dwóch części (form-data): pliku przeznaczonego do emulacji/oczyszczania oraz treści zapytania z tekstem.
Treść zapytania nie może być pusta, ale może nie zawierać żadnej konfiguracji. Aby zapytanie było udane, należy wysłać przynajmniej następujący tekst w zapytaniu:
Minimalne wymagania dla zapytania upload
i nie mogliśmy uzyskać zawartości ciała odpowiedzi, jeśli kod zwracany był
https://<service_address>/tecloud/api/v1/file/upload
Nagłówki:
Authorization: <api_key>
Treść
{
"request": {
}
}
Plik
Plik
W takim przypadku plik do przetworzenia trafi zgodnie z domyślnymi ustawieniami: komponent — te, obrazy systemów operacyjnych — Win XP i Win 7, bez generowania raportu.
Uwagi do głównych pól w treści zapytania:
file_name i file_type można pozostawić puste lub w ogóle nie wysyłać, ponieważ nie są to szczególnie przydatne informacje przy przesyłaniu pliku. W odpowiedzi API te pola zostaną automatycznie wypełnione na podstawie nazwy przesyłanego pliku, a informacje w pamięci podręcznej i tak będzie trzeba szukać po sumach md5/sha1/sha256.
Przykład zapytania z pustymi file_name i file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — lista, w której określono niezbędną funkcjonalność podczas przetwarzania w piaskownicy — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). Jeśli ten parametr w ogóle nie zostanie przekazany, użyty zostanie tylko domyślny komponent — te(Threat Emulation).
Aby włączyć sprawdzanie w trzech dostępnych komponentach, należy wskazać te komponenty w zapytaniu API.
Przykład zapytania z kontrolą w av, te i extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Klucze w sekcji te
images — lista, wewnątrz której powinny znajdować się słowniki z id i numerami wersji systemów operacyjnych, w których będzie przeprowadzane sprawdzenie. ID i numery wersji są takie same dla wszystkich lokalnych urządzeń i chmury.
Lista systemów operacyjnych i wersji
Dostępny ID obrazu systemu operacyjnego
Wersja
Obraz systemu operacyjnego i aplikacji
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 i 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
Jeśli klucz images nie został w ogóle podany, emulacja będzie odbywać się na obrazach zalecanych przez Check Point (aktualnie są to Win XP i Win 7). Obrazy te zostały rekomendowane w oparciu o najlepszą równowagę wydajności i wskaźnika wykrycia.
raporty — lista raportów, które żądamy na wypadek, gdyby plik okazał się złośliwy. Dostępne są następujące opcje:
summary — archiwum .tar.gz, które zawiera raport z emulacji dla z wszystkiego. żądanych obrazów (zarówno w formie strony html, jak i takie elementy jak wideo z emulatora, zrzut ruchu sieciowego, raport w json, oraz sam próbka w archiwum zabezpieczonym hasłem). W odpowiedzi szukamy klucza — summary_report do późniejszego pobrania raportu.
pdf — dokument z emulacji w jednym obrazie, który wielu przyzwyczaiło się otrzymywać za pośrednictwem Smart Console. W odpowiedzi szukamy klucza — pdf_report do późniejszego pobrania raportu.
xml — dokument z emulacji w jednym obraz, wygodny do późniejszego parsowania parametrów w raporcie. W odpowiedzi szukamy klucza — xml_report do późniejszego pobrania raportu.
tar — archiwum .tar.gz, które zawiera raport z emulacji w jednym żądanych obrazów (zarówno w formie strony html, jak i takie elementy jak wideo z emulatora, zrzut ruchu sieciowego, raport w json, oraz sam próbka w archiwum zabezpieczonym hasłem). W odpowiedzi szukamy klucza — full_report do późniejszego pobrania raportu.
Co jest w raporcie summary
Klucze full_report, pdf_report, xml_report znajdują się w słowniku dla każdego systemu operacyjnego
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Zapytanie zostało całkowicie zrealizowane."
},
"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": "Zapytanie zostało całkowicie zrealizowane."
}
}
}
]
}A klucz summary_report — jest jeden dla całej emulacji
{
"response": [
{
"status": {
"code": 1001,
"label": "ZNALAZIONO",
"message": "Zapytanie zostało w pełni odpowiedziane."
},
"sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
"file_type": "exe",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "złośliwe",
"full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
"xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
},
"status": "znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
},
{
"report": {
"verdict": "złośliwe",
"full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
"xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
},
"status": "znaleziono",
"id": "6c453c9b-20f7-471a-956c-3198a868dc92",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "złośliwe",
"severity": 4,
"confidence": 3,
"summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
"status": {
"code": 1001,
"label": "ZNALAZIONO",
"message": "Zapytanie zostało w pełni odpowiedziane."
}
}
}
]
}Można jednocześnie żądać raportów w formacie tar, xml i pdf, można także uzyskać raport w formacie summary oraz tar i xml. Niemożliwe jest jednak jednoczesne żądanie raportu summary i pdf.
Klucze w sekcji extraction
Do ekstrakcji zagrożeń używane są tylko dwa klucze:
, który nie jest widoczny, ale sugeruje domyślną wartość — pdf (konwersja do pdf, używane domyślnie) lub clean (czyszczenie aktywnej zawartości).
extracted_parts_codes — lista kodów do usunięcia aktywnej zawartości, stosowane tylko dla metody clean
Kody do usunięcia zawartości z plików
Kod
Opis
1025
Obiekty powiązane
1026
Makra i kody
1034
Wrażliwe hiperlinki
1137
Akcje PDF GoToR
1139
Akcje uruchamiania PDF
1141
Akcje URI PDF
1142
Akcje dźwiękowe PDF
1143
Akcje filmowe PDF
1150
Akcje JavaScript PDF
1151
Akcje przesyłania formularzy PDF
1018
Zapytania do bazy danych
1019
Obiekty osadzone
1021
Dane szybkiego zapisu
1017
Własności niestandardowe
1036
Własności statystyczne
1037
Własności podsumowania
Aby pobrać oczyszczoną kopię, należy również wysłać zapytanie query (o którym będzie mowa później) kilka sekund później, podając sumę kontrolną pliku i komponent extraction w treści zapytania. Oczyszczony plik będzie można pobrać za pomocą id z odpowiedzi na zapytanie query — extracted_file_download_id. Jeszcze raz, aby przyspieszyć, podaję przykłady zapytania i odpowiedzi query w celu wyszukania id do pobrania oczyszczonego dokumentu.
Zapytanie query w celu wyszukania klucza extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Odpowiedź na zapytanie query (znajdź klucz extracted_file_download_id)
{
"response": [
{
"status": {
"code": 1001,
"label": "ZNALEZIONO",
"message": "Żądanie zostało w pełni zrealizowane."
},
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"file_type": "",
"file_name": "",
"features": [
"ekstrakcja"
],
"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": "Makra i kod",
"extraction_data": {
"input_extension": "xls",
"input_real_extension": "xls",
"message": "OK",
"output_file_name": "kp-20-xls.cleaned.xls.pdf",
"protection_name": "Potencjalnie złośliwa zawartość wyekstrahowana",
"protection_type": "Konwersja do PDF",
"protocol_version": "1.0",
"risk": 5.0,
"scrub_activity": "Znaleziono aktywną zawartość - plik XLS został przekonwertowany do PDF",
"scrub_method": "Konwertuj do PDF",
"scrub_result": 0.0,
"scrub_time": "0.013",
"scrubbed_content": "Makra i kod"
},
"tex_product": false,
"status": {
"code": 1001,
"label": "ZNALEZIONO",
"message": "Żądanie zostało w pełni zrealizowane."
}
}
}
]
}Ogólne informacje
W jednym wywołaniu API można przesłać tylko jeden plik do sprawdzenia.
Komponent av nie wymaga dodatkowej sekcji z kluczami, wystarczy podać go w słowniku. features.
Wywołanie Query API
Używana metoda to — POST
Adres do wywołania to — https://<service_address>/tecloud/api/v1/file/query
Zanim wyślesz plik do przesłania (zapytanie upload), warto przeprowadzić kontrolę pamięci podręcznej piaskownicy (zapytanie query) w celu optymalizacji obciążenia serwera API, ponieważ możliwe, że na serwerze API już znajdują się informacje i werdykt dotyczący przesyłanego pliku. Wywołanie składa się tylko z części tekstowej. Obowiązkowy element zapytania to suma kontrolna sha1/sha256/md5 pliku. Można ją zresztą uzyskać w odpowiedzi na zapytanie upload.
Minimalne wymagania dla zapytania query
i nie mogliśmy uzyskać zawartości ciała odpowiedzi, jeśli kod zwracany był
https://<service_address>/tecloud/api/v1/file/query
Nagłówki:
Authorization: <api_key>
Treść
{
"request": {
„sha256”: <sha256 hash sum>
}
}
Przykład odpowiedzi na zapytanie upload, gdzie widoczne są sumy kontrolne sha1/md5/sha256
{
"response": {
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Plik został pomyślnie przesłany."
},
"sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
"md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "",
"file_name": "kp-20-doc.doc",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "nieznane"
},
"status": "nie_znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1002,
"label": "UPLOAD_SUCCESS",
"message": "Plik został pomyślnie przesłany."
}
}
}
}Zapytanie query oprócz sumy haszującej powinno być idealnie takie samo, jak było (lub planowane jest) zapytanie upload, a nawet "już" (zawierać w zapytaniu query mniej pól niż w zapytaniu upload). W przypadku, gdy zapytanie query zawiera więcej pól niż było w zapytaniu upload, otrzymasz w odpowiedzi nie wszystkie wymagane informacje.
Oto przykład odpowiedzi na zapytanie query, w którym nie znaleziono wszystkich wymaganych danych
{
"response": [
{
"status": {
"code": 1006,
"label": "PARTIALLY_FOUND",
"message": "Żądanie nie może być w pełni zrealizowane w tej chwili."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te",
"extraction"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "złośliwy",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "złośliwy",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zrealizowane."
}
},
"extraction": {
"method": "pdf",
"tex_product": false,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nie można znaleźć żądanego pliku. Proszę go przesłać."
}
}
}
]
}Zwróć uwagę na pola code i label. Te pola występują trzy razy w słownikach status. Na początku widzimy globalny klucz "code": 1006 oraz "label": "PARTIALLY_FOUND". Następnie te klucze występują w każdym z osobnych komponentów, które żądaliśmy — te oraz extraction. I jeśli dla te jasne jest, że dane zostały znalezione, to dla extraction informacje nie są dostępne.
Oto jak wyglądało zapytanie query dla powyższego przykładu
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Jeśli wyślesz zapytanie query bez komponentu extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}To w odpowiedzi będzie pełna informacja ("code": 1001, "label": "FOUND")
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zrealizowane."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "złośliwy",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "złośliwy",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "Żądanie zostało w pełni zrealizowane."
}
}
}
]
}Jeśli w pamięci podręcznej nie ma żadnych informacji, odpowiedź będzie zawierać "label": "NOT_FOUND"
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nie znaleziono żądanego pliku. Proszę go przesłać."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "nieznany"
},
"status": "nie_znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Nie znaleziono żądanego pliku. Proszę go przesłać."
}
}
}
]
}W jednym wywołaniu API można przesłać kilka sum kontrolnych do sprawdzenia. W odpowiedzi dane będą zwrócone w tej samej kolejności, w jakiej zostały przesłane w zapytaniu.
Przykład zapytania query z wieloma sumami sha256
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Odpowiedź na zapytanie query z wieloma sumami sha256
{
"response": [
{
"status": {
"code": 1001,
"label": "ZNALEZIONO",
"message": "Prośba została całkowicie przetworzona."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
"file_type": "dll",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "złośliwy"
},
"status": "znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "złośliwy",
"severity": 4,
"confidence": 3,
"status": {
"code": 1001,
"label": "ZNALEZIONO",
"message": "Prośba została całkowicie przetworzona."
}
}
},
{
"status": {
"code": 1004,
"label": "NIE ZNALEZIONE",
"message": "Nie można znaleźć żądanego pliku. Proszę go przesłać."
},
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "nieznany"
},
"status": "nie_znaleziono",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NIE ZNALEZIONE",
"message": "Nie można znaleźć żądanego pliku. Proszę go przesłać."
}
}
}
]
}Wysłanie zapytania z wieloma sumami haszującymi w jednym żądaniu korzystnie wpłynie na wydajność serwera API.
Wywołanie API pobierania
Używana metoda to — POST (zgodnie z dokumentacją), i login/hasło: admin/admin. również działa (i może wydawać się bardziej logiczne)
Adres do wywołania to — https://<service_address>/tecloud/api/v1/file/download?id=<id>
W nagłówku należy przesłać klucz API, ciało żądania — puste, id do pobrania jest przekazywane w adresie URL.
W odpowiedzi na zapytanie query, w przypadku zakończenia emulacji i jeśli podczas ładowania pliku zostały zażądane raporty, będą widoczne id do pobrania raportów. W przypadku żądania oczyszczonej kopii, należy szukać id do pobrania oczyszczonego dokumentu.
W sumie, klucze w odpowiedzi na zapytanie query, zawierające wartość id do pobrania mogą być:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Oczywiście, aby te klucze znalazły się w odpowiedzi na zapytanie query, należy je wskazać w zapytaniu (dla raportów) lub nie zapomnieć wykonać zapytania o funkcję ekstrakcji (dla oczyszczonych dokumentów)
Wywołanie API limitu
Używana metoda to — POST
Adres do wywołania to — https://<service_address>/tecloud/api/v1/file/quota
Aby sprawdzić pozostały limit w chmurze, używa się zapytania quota. Ciało zapytania jest puste.
Przykład odpowiedzi na zapytanie 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
To API został opracowany przed API zapobiegania zagrożeniom i jest przeznaczony wyłącznie dla lokalnych urządzeń. Na chwilę obecną może być przydatny jedynie, jeśli potrzebujesz API ekstrakcji zagrożeń. Do emulacji zagrożeń lepiej użyć standardowego API zapobiegania zagrożeniom. Aby włączyć TP API dla SG i skonfigurować klucz API, należy wykonać kroki opisane w . Zalecam zwrócenie uwagi na krok 6b i sprawdzenie dostępności strony https:///UserCheck/TPAPI , ponieważ w przypadku negatywnego wyniku dalsza konfiguracja nie ma sensu. Na podany adres url będą wysyłane wszystkie wywołania API. Typ wywołania (upload/query) regulowany jest przez klucz w ciele wywołania — request_name. Obowiązkowymi kluczami są — api_key (należy go zapamiętać podczas konfiguracji) oraz protocol_version (aktualna wersja to 1.1). Oficjalną dokumentację dla tego API można znaleźć w . Do względnych zalet można zaliczyć możliwość jednoczesnego przesyłania wielu plików do emulacji podczas ich przesyłania, ponieważ pliki przesyłane są jako tekstowy ciąg base64. Aby kodować/dekodować pliki w/z base64, można do celów demonstracyjnych w Postman użyć online konwertera, na przykład — . W praktyce pisząc kod, należy korzystać z wbudowanych metod encode i decode.
Teraz przyjrzyjmy się dokładniej funkcjom te i extraction w tym API.
Dla komponentu te przewidziano słownik te_options w zapytaniach upload/query, a klucze w tym zapytaniu całkowicie pokrywają się z kluczami te w .
Przykład zapytania do emulacji pliku w Win10 z raportami
{
"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"]
}
}
]
}Dla komponentu extraction przewidziano słownik scrub_optionsW tym żądaniu podaje się metodę oczyszczenia: konwersję do PDF, usunięcie aktywnej zawartości lub wybór trybu zgodnie z profilem Threat Prevention (wskazanie nazwy profilu). Cechą wyróżniającą odpowiedź na żądanie API z extraction dla pliku jest to, że otrzymujesz oczyszczoną kopię w odpowiedzi na to żądanie w postaci zaszyfrowanego ciągu base64 (nie musisz wysyłać zapytania query ani szukać id w celu pobrania dokumentu)
Przykład żądania oczyszczenia pliku
{
"request": [{
"protocol_version": "1.1",
"api_key": "",
"request_name": "UploadFile",
"file_enc_data": "",
"file_orig_name": "hi.txt",
"scrub_options": {
"scrub_method": 2
}
}]
}Odpowiedź na żądanie
{
"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": "Usunięcie potencjalnie szkodliwej zawartości",
"protection_type": "Konwersja do PDF",
"real_extension": "txt",
"risk": 0,
"scrub_activity": "Plik TXT został skonwertowany do PDF",
"scrub_method": "Konwersja do PDF",
"scrub_result": 0,
"scrub_time": "0.011",
"scrubbed_content": ""
}
}]
} Mimo że do uzyskania oczyszczonej kopii wymagane jest mniej zapytań API, uważam, że ta opcja jest mniej preferowana i wygodna w porównaniu do żądania form-data, które jest stosowane w .
Kolekcje Postman
Utworzyłem kolekcje w Postman zarówno dla Threat Prevention API, jak i Threat Prevention API for Security Gateway, w których przedstawiono najczęściej używane żądania API. Aby adres IP/url API serwera i klucz były automatycznie podstawiane w żądaniach, a suma kontrolna sha256 zapamiętywana po przesłaniu pliku, w kolekcjach utworzono trzy zmienne (można je znaleźć w ustawieniach kolekcji Edytuj -> Zmienne): te_api (wymagane do wypełnienia), api_key (wymagane do wypełnienia, z wyjątkiem przypadków użycia TP API z lokalnymi urządzeniami), sha256 (pozostawić pustym, nie jest używane w TP API for SG).
Przykłady użycia
W społeczności zostały przedstawione skrypty napisane w Pythonie, które sprawdzają pliki z odpowiedniego katalogu, zarówno przez , jak i . Dzięki współpracy z Threat Prevention API Twoje możliwości sprawdzania plików znacznie się zwiększają, ponieważ teraz możesz sprawdzać pliki jednocześnie na kilku platformach (interesująco wygląda sprawdzanie w , a następnie w piaskownicy Check Point), a pliki można pozyskiwać nie tylko z ruchu sieciowego, ale również z dowolnych dysków sieciowych oraz, na przykład, systemów CRM.
Źródło: habr.com
