Взаимодействие с Check Point SandBlast чрез API

Тази статия ще бъде полезна за тези, които са запознати с технологиите Check Point чрез файлова емулация (Емулация на заплахи) и проактивно почистване на файлове (Извличане на заплахи) и иска да направи крачка към автоматизирането на тези задачи. Check Point има API за предотвратяване на заплахи, който работи както в облака, така и на локални устройства, и функционално е идентичен с проверката на файлове в уеб/smtp/ftp/smb/nfs трафик потоци. Тази статия е частично интерпретация на автора на набор от статии от официалната документация, но въз основа на моя собствен оперативен опит и мои собствени примери. Също така в статията ще намерите колекциите на автора Postman за работа с API за предотвратяване на заплахи.

Основни съкращения

API за предотвратяване на заплахи работи с три основни компонента, които се извикват в API чрез следните текстови стойности:

av — Антивирусен компонент, отговорен за сигнатурен анализ на известни заплахи.

te - Компонент за емулация на заплахи, отговорен за проверка на файлове в пясъчната среда и издаване на злонамерена/доброкачествена присъда след емулация.

екстракция - Компонент за извличане на заплахи, отговорен за бързото конвертиране на офис документи в безопасна форма (в която се премахва цялото потенциално злонамерено съдържание), за да бъдат бързо доставени до потребителите/системите.

API структура и основни ограничения

API за предотвратяване на заплахи използва само 4 заявки − качване, заявка, изтегляне и квота. В заглавката за четирите заявки трябва да предадете API ключа, като използвате параметъра Упълномощаване. На пръв поглед структурата може да изглежда много по-проста, отколкото в API за управление, но броят на полетата в заявките за качване и заявки и структурата на тези заявки са доста сложни. Те могат да бъдат функционално сравнени с профили за предотвратяване на заплахи в политика за сигурност на шлюз/изолирана среда.

В момента е пусната единствената версия на API за предотвратяване на заплахи - 1.0; URL адресът за извиквания на API трябва да включва v1 в частта, където трябва да посочите версията. За разлика от API за управление, е необходимо да посочите версията на API в URL адреса, в противен случай заявката няма да бъде изпълнена.

Компонентът Anti-Virus, когато се извика без други компоненти (te, извличане), в момента поддържа само заявки за заявки с md5 хеш суми. Threat Emulation и Threat Extraction също поддържат sha1 и sha256 хеш суми.

Много е важно да не правите грешки в заявките! Заявката може да бъде изпълнена без грешка, но не напълно. Гледайки малко напред, нека да видим какво може да се случи, когато има грешки/печатни грешки в заявките.

Заявка с правописна грешка с думата reports(reports)

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                reportss: ["tar", "pdf", "xml"]
            }
		}
	] 
}

Няма да има грешка в отговора, но изобщо няма да има информация за докладите

{
  "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."
        }
      }
    }
  ]
}

Но за заявка без печатна грешка в ключа за отчети

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                reports: ["tar", "pdf", "xml"]
            }
		}
	] 
}

Получаваме отговор, който вече съдържа идентификатор за изтегляне на отчети

{
  "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."
        }
      }
    }
  ]
}

Ако изпратим неправилен/изтекъл API ключ, в отговор ще получим грешка 403.

SandBlast API: в облака и на локални устройства

Заявките за API могат да се изпращат до устройства на Check Point, които имат активиран компонент за емулация на заплахи (блейд). Като адрес за заявки трябва да използвате ip/url на устройството и порт 18194 (например https://10.10.57.19:18194/tecloud/api/v1/file/query). Трябва също така да се уверите, че политиката за сигурност на устройството позволява тази връзка. Упълномощаване чрез API ключ на локални устройства по подразбиране изключено и ключът за оторизация в заглавките на заявката може изобщо да не бъде изпратен.

Трябва да се изпращат API заявки към облака на CheckPoint te.checkpoint.com (например - https://te.checkpoint.com/tecloud/api/v1/file/query). API ключът може да бъде получен като пробен лиценз за 60 дни, като се свържете с партньорите на Check Point или местния офис на компанията.

На локални устройства Threat Extraction все още не се поддържа като стандарт. API за предотвратяване на заплахи и трябва да се използва API за предотвратяване на заплахи за шлюз за сигурност (ще говорим за това по-подробно в края на статията).

Локалните устройства не поддържат заявката за квота.

В противен случай няма разлики между заявките към локалните устройства и към облака.

Извикване на API за качване

Използван метод − ПУСНИ

Адрес за обаждане - https:///tecloud/api/v1/file/upload

Заявката се състои от две части (form-data): файл, предназначен за емулация/почистване и тяло на заявката с текст.

Текстовата заявка не може да бъде празна, но може да не съдържа никаква конфигурация. За да бъде заявката успешна, трябва да изпратите поне следния текст в заявката:

Необходим минимум за заявка за качване

HTTP POST

https:///tecloud/api/v1/file/upload

Заглавия:

разрешението за употреба:

Body

{

"заявка": {

}

}

досие

досие

В този случай файлът ще бъде обработен в съответствие с параметрите по подразбиране: компонент - te, изображения на ОС - Win XP и Win 7, без генериране на отчет.

Коментари по основните полета в текстовата заявка:

име на файл и тип файл Можете да ги оставите празни или изобщо да не ги изпращате, тъй като това не е особено полезна информация при качване на файл. В отговора на API тези полета ще бъдат попълнени автоматично въз основа на името на изтегления файл и информацията в кеша все пак ще трябва да се търси с помощта на md5/sha1/sha256 хеш суми.

Примерна заявка с празни file_name и file_type

{

"request": {

"file_name": "",

"file_type": "",

}

}

Характеристика — списък, който показва необходимата функционалност при обработка в пясъчника - av (Anti-Virus), te (Threat Emulation), извличане (Threat Extraction). Ако този параметър изобщо не бъде подаден, тогава ще се използва само компонентът по подразбиране - te (Емулация на заплахи).

За да активирате проверката в трите налични компонента, трябва да посочите тези компоненти в заявката за API.

Пример за заявка с проверка в av, te и извличане

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["av", "te", "extraction"]  
		}
	] 
}

Ключове в секцията te

изображения — списък, съдържащ речници с идентификатор и номер на версия на операционните системи, в които ще се извършва проверката. Идентификаторите и номерата на ревизиите са еднакви за всички локални устройства и облака.

Списък на операционни системи и ревизии

ID на изображението на наличната операционна система

Ревизия

Image OS и приложение

e50e99f3-5963-4573-af9e-e3f4750b55e2

1

Microsoft Windows: XP - 32-битов SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 и ActiveX 10.0
Java Runtime: 1.6.0u22

7e6fe36e-889e-4c25-8704-56378f0830df

1

Microsoft Windows: 7 - 32 бита
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player: 10.2r152 (Plug-in& ActiveX)
Java Runtime: 1.6.0u0

8d188031-1010-4466-828b-0cd13d4303ff

1

Microsoft Windows: 7 - 32 бита
Office: 2010
Adobe Acrobat Reader: 9.4
Flash Player: 11.0.1.152 (Plug-in & ActiveX)
Java Runtime: 1.7.0u0

5e5de275-a103-4f67-b55b-47532918fa59

1

Microsoft Windows: 7 - 32 бита
Office: 2013
Adobe Acrobat Reader: 11.0
Flash Player: 15 (Plug-in & ActiveX)
Java Runtime: 1.7.0u9

3ff3ddae-e7fd-4969-818c-d5f1a2be336d

1

Microsoft Windows: 7 - 64 бита
Office: 2013 (32 бита)
Adobe Acrobat Reader: 11.0.01
Flash Player: 13 (Plug-in & ActiveX)
Java Runtime: 1.7.0u9

6c453c9b-20f7-471a-956c-3198a868dc92 

 

1 

Microsoft Windows: 8.1 - 64 бита
Office: 2013 (64 бита)
Adobe Acrobat Reader: 11.0.10
Flash Player: 18.0.0.160 (Plug-in & 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 (Plug-in & ActiveX)
Java Runtime: 1.7.0u9

Ако ключът за изображения изобщо не е посочен, емулацията ще се извърши в изображения, препоръчани от Check Point (в момента Win XP и Win 7). Тези изображения се препоръчват въз основа на съображения за най-добър баланс между производителност и скорост на улов.

доклади — списък с доклади, които изискваме, в случай че файлът се окаже злонамерен. Налични са следните опции:

1. обобщение - .tar.gz архив, съдържащ отчет за емулация от всички поискани изображения (както html страница, така и компоненти като видео от операционната система на емулатора, дъмп на мрежовия трафик, отчет в json и самата проба в защитен с парола архив). Търсим ключа в отговора - обобщен_отчет за последващо изтегляне на отчета.

2. PDF - документ за емулация в един изображение, което мнозина са свикнали да получават чрез Smart Console. Търсим ключа в отговора - pdf_отчет за последващо изтегляне на отчета.

3. XML - документ за емулация в един изображение, удобно за последващ анализ на параметрите в отчета. Търсим ключа в отговора - xml_report за последващо изтегляне на отчета.

4. катран - .tar.gz архив, съдържащ отчет за емулация в един поискани изображения (както html страница, така и компоненти като видео от операционната система на емулатора, дъмп на мрежовия трафик, отчет в json и самата проба в защитен с парола архив). Търсим ключа в отговора - пълен_отчет за последващо изтегляне на отчета.

Какво има вътре в обобщения отчет

Ключовете full_report, pdf_report, xml_report са в речника за всяка ОС

{
  "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."
        }
      }
    }
  ]
}

Но ключът summary_report - има го за емулация като цяло

{
  "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."
        }
      }
    }
  ]
}

Можете да поискате tar и xml и pdf отчети едновременно, можете да поискате резюме и tar и xml. Няма да е възможно да поискате обобщен отчет и pdf едновременно.

Ключове в секцията за извличане

За извличане на заплахи се използват само два ключа:

метод — pdf (конвертиране в pdf, използва се по подразбиране) или чист (почистване на активно съдържание).

извлечени_кодове_на_части - списък с кодове за премахване на активно съдържание, приложим само за чистия метод

Кодове за премахване на съдържание от файлове

код

Описание

1025

Свързани обекти

1026

Макроси и код

1034

Чувствителни хипервръзки

1137

PDF GoToR действия

1139

Действия за стартиране на PDF

1141

PDF URI действия

1142

PDF звукови действия

1143

Действия с PDF филми

1150

PDF JavaScript действия

1151

Действия с формуляр за изпращане на PDF

1018

Заявки към база данни

1019

Вградени обекти

1021

Бързо запазване на данни

1017

Персонализирани свойства

1036

Статистически свойства

1037

Обобщени свойства

За да изтеглите почистено копие, ще трябва също така да направите заявка за заявка (която ще бъде обсъдена по-долу) след няколко секунди, като посочите сумата на хеша на файла и компонента за извличане в текста на заявката. Можете да вземете изчистения файл, като използвате идентификатора от отговора на заявката - extracted_file_download_id. Още веднъж, гледайки малко напред, давам примери за заявка и отговор на заявка за търсене на идентификатор за изтегляне на изчистен документ.

Заявка за търсене на извлечения_file_download_id ключ

{ "request":  [  

		{	
			"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
			"features": ["extraction"] , 
			"extraction": {
		        "method": "pdf"
            }
		}
	] 
}

Отговор на заявка (потърсете ключ 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."
                }
            }
        }
    ]
}

Преглед

В едно извикване на API можете да изпратите само един файл за проверка.

Компонентът av не изисква допълнителен раздел с ключове, достатъчно е да го посочите в речника Характеристика.

Извикване на API за заявка

Използван метод − ПУСНИ

Адрес за обаждане - https:///tecloud/api/v1/file/query

Преди да изпратите файл за изтегляне (заявка за качване), препоръчително е да проверите кеша на пясъчника (заявка за заявка), за да оптимизирате натоварването на API сървъра, тъй като API сървърът може вече да има информация и присъда за изтегления файл. Обаждането се състои само от текстова част. Задължителната част от заявката е sha1/sha256/md5 хеш сума на файла. Между другото, можете да го получите в отговор на заявката за качване.

Необходим минимум за заявка

HTTP POST

https:///tecloud/api/v1/file/query

Заглавия:

разрешението за употреба:

Body

{

"заявка": {

"sha256":

}

}

Пример за отговор на заявка за качване, където се виждат хеш суми sha1/md5/sha256

{
  "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."
      }
    }
  }
}

Заявката за заявка, в допълнение към сумата на хеша, в идеалния случай трябва да бъде същата като заявката за качване (или се планира да бъде) или дори „вече“ (да съдържа по-малко полета в заявката за заявка, отколкото в заявката за качване). В случай, че заявката за заявка съдържа повече полета, отколкото в заявката за качване, няма да получите цялата необходима информация в отговора.

Ето пример за отговор на заявка, при която не са намерени всички необходими данни

{
  "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."
        }
      }
    }
  ]
}

Обърнете внимание на полетата код и етикет. Тези полета се появяват три пъти в речниците на състоянието. Първо виждаме глобалния ключ „code“: 1006 и „label“: „PARTIALLY_FOUND“. След това тези ключове се намират за всеки отделен компонент, който поискахме - te и извличане. И ако за теб е ясно, че данните са открити, то за извличане информация няма.

Ето как изглеждаше заявката за горния пример

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te", "extraction"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                "reports": [
                    "xml", "pdf"
                ]
            }
		}
	] 
}

Ако изпратите заявка за заявка без компонента за извличане

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                "reports": [
                    "xml", "pdf"
                ]
            }
		}
	] 
}

Тогава отговорът ще съдържа пълна информация („код“: 1001, „етикет“: „НАМЕРЕНО“)

{
  "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."
        }
      }
    }
  ]
}

Ако изобщо няма информация в кеша, тогава отговорът ще бъде „етикет“: „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."
        }
      }
    }
  ]
}

В едно извикване на API можете да изпратите няколко хеш суми наведнъж за проверка. Отговорът ще върне данни в същия ред, в който са били изпратени в заявката.

Примерна заявка за заявка с няколко sha256 суми

{ "request":  [  

		{	
			"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
        },
        		{	
			"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
        }
	] 
}

Отговор на заявка с множество sha256 суми

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
      "file_type": "dll",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    },
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Could not find the requested file. Please upload it."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "unknown"
            },
            "status": "not_found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

Заявяването на няколко хеш суми наведнъж в заявка за заявка също ще има благоприятен ефект върху производителността на API сървъра.

Изтеглете API повикване

Използван метод − ПУСНИ (по документация), GET също работи (и може да изглежда по-логично)

Адрес за обаждане - https:///tecloud/api/v1/file/download?id=

Заглавката изисква подаването на API ключ, тялото на заявката е празно, идентификаторът за изтегляне се предава в URL адреса.

В отговор на заявка за заявка, ако емулацията е завършена и отчетите са били поискани при изтегляне на файла, идентификаторът за изтегляне на отчети ще бъде видим. Ако се поиска почистено копие, трябва да потърсите идентификатора, за да изтеглите почистения документ.

Общо ключовете в отговора на заявката, съдържаща id стойността за зареждане, могат да бъдат:

• обобщен_отчет

• пълен_отчет

• pdf_отчет

• xml_report

• извлечен_файл_изтегляне_id

Разбира се, за да получите тези ключове в отговор на заявката за заявка, те трябва да бъдат посочени в заявката (за отчети) или не забравяйте да направите заявка с помощта на функцията за извличане (за почистени документи)

Извикване на API за квота

Използван метод − ПУСНИ

Адрес за обаждане - https:///tecloud/api/v1/file/квота

За да проверите оставащата квота в облака, използвайте заявката за квота. Основният текст на заявката е празен.

Примерен отговор на заявка за квота

{
  "response": [
    {
      "remain_quota_hour": 1250,
      "remain_quota_month": 10000000,
      "assigned_quota_hour": 1250,
      "assigned_quota_month": 10000000,
      "hourly_quota_next_reset": "1599141600",
      "monthly_quota_next_reset": "1601510400",
      "quota_id": "TEST",
      "cloud_monthly_quota_period_start": "1421712300",
      "cloud_monthly_quota_usage_for_this_gw": 0,
      "cloud_hourly_quota_usage_for_this_gw": 0,
      "cloud_monthly_quota_usage_for_quota_id": 0,
      "cloud_hourly_quota_usage_for_quota_id": 0,
      "monthly_exceeded_quota": 0,
      "hourly_exceeded_quota": 0,
      "cloud_quota_max_allow_to_exceed_percentage": 1000,
      "pod_time_gmt": "1599138715",
      "quota_expiration": "0",
      "action": "ALLOW"
    }
  ]
}

API за предотвратяване на заплахи за шлюз за сигурност

Този API е разработен преди API за предотвратяване на заплахи и е предназначен само за локални устройства. Засега може да бъде полезно само ако имате нужда от API за извличане на заплахи. За Threat Emulation е по-добре да използвате обикновения API за предотвратяване на заплахи. За включване TP API за SG и конфигурирайте API ключа, от който трябва да следвате стъпките sk113599. Препоръчвам да обърнете внимание на стъпка 6b и да проверите достъпността на страницата https://<IPAddressofSecurityGateway>/UserCheck/TPAPI защото в случай на отрицателен резултат по-нататъшната конфигурация няма смисъл. Всички извиквания на API ще бъдат изпратени до този URL адрес. Типът повикване (качване/запитване) се регулира в основния ключ − име_заявка. Необходими са и ключове - api_key (трябва да го запомните по време на процеса на конфигуриране) и протокол_версия (текущата версия е 1.1). Можете да намерите официалната документация за този API на sk137032. Относителните предимства включват възможността за изпращане на няколко файла наведнъж за емулация при зареждането им, тъй като файловете се изпращат като текстов низ base64. За да кодирате/декодирате файлове към/от base64, можете да използвате онлайн конвертор в Postman за демонстрационни цели, например - https://base64.guru. За практически цели трябва да използвате вградените методи за кодиране и декодиране, когато пишете код.

Сега нека разгледаме по-отблизо функциите te и екстракция в този API.

За компонент te предоставен речник te_options в заявки за качване/заявка и ключовете в тази заявка напълно съвпадат с te ключовете в API за предотвратяване на заплахи.

Примерна заявка за емулация на файл в Win10 с отчети

{
"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"]
    }
    }
    ]
}

За компонент екстракция предоставен речник scrub_options. Тази заявка указва метода за почистване: конвертиране в PDF, изчистване на активно съдържание или избор на режим в съответствие с профила за предотвратяване на заплахи (името на профила е посочено). Страхотното при отговарянето на заявка за API за извличане на файл е, че получавате почистено копие в отговора на тази заявка като base64 шифрован низ (не е необходимо да правите заявка за заявка и да търсите идентификатора, за да изтеглите документ)

Пример за заявка за изчистване на файл

    {
	"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
		}
	}]
}

Отговор на заявка

{
	"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": ""
		}
	}]
} 

Въпреки факта, че са необходими по-малко API заявки за получаване на изчистено копие, намирам тази опция за по-малко предпочитана и удобна от заявката за формуляр-данни, използвана в API за предотвратяване на заплахи.

Колекции на пощальона

Създадох колекции в Postman както за API за предотвратяване на заплахи, така и за API за предотвратяване на заплахи за шлюза за сигурност, които представляват най-често срещаните заявки за API. За да може сървърният ip/url API и ключът да бъдат автоматично замествани в заявки и сумата на sha256 хеш да бъде запомнена след изтеглянето на файла, в колекциите са създадени три променливи (можете да ги намерите, като отидете в настройките на колекцията Редактиране -> Променливи): te_api (задължително), api_key (задължително за попълване, освен когато използвате TP API с локални устройства), sha256 (оставете празно, не се използва в TP API за SG).

Изтеглете колекцията Postman за API за предотвратяване на заплахи

Изтеглете колекцията Postman за API за предотвратяване на заплахи за Security Gateway

Примери за използване

В общността Проверете приятели представени са скриптове, написани на Python, които проверяват файлове от желаната директория чрез TP APIИ TP API за SG. Чрез взаимодействие с API за предотвратяване на заплахи, способността ви да сканирате файлове е значително разширена, тъй като сега можете да сканирате файлове в няколко платформи едновременно (регистриране в VirusTotal API, а след това в пясъчника на Check Point) и получават файлове не само от мрежовия трафик, но и ги вземат от всякакви мрежови устройства и, например, CRM системи.

Източник: www.habr.com