This article will be useful for those familiar with technologies Check Point for file emulation (Threat Emulation) and proactive file cleaning (Threat Extraction) and wish to take a step towards automating these tasks. Check Point offers , which works both in the cloud and on local devices, and functionally it is identical to file checks in web/smtp/ftp/smb/nfs traffic streams. This article is partly an author's interpretation of a set of articles from the official documentation, but built on personal experience and examples. You will also find author's Postman collections for working with the Threat Prevention API in this article.
Key abbreviations
Threat Prevention API works with three main components, which are called in the API through the following textual values:
av — Anti-Virus component, responsible for signature analysis of known threats.
te — Threat Emulation component, responsible for checking files in the sandbox and issuing a verdict of malicious or benign after emulation.
extraction — Threat Extraction component, responsible for quickly converting office documents into a safe form (from which all potentially harmful content is removed), for their rapid delivery to users/systems.
API Structure and Key Limitations
Threat Prevention API uses only 4 requests — upload, query, download, and quota. In the header for all four requests, you need to provide the API key using the Authorization. At first glance, the structure may seem much simpler than in , but the number of fields in the upload and query requests and the structure of these requests are quite complex. They can be functionally compared to Threat Prevention profiles in the gateway/sandbox security policy.
Currently, there is a single version of the Threat Prevention API released — 1.0, and in the URL for API calls, you should specify v1 where the version needs to be indicated. Unlike the Management API, specifying the API version in the URL address is mandatory, otherwise the request will not be executed.
The Anti-Virus component, when called without other components (te, extraction), currently only supports query requests with md5 hash sums. Threat Emulation and Threat Extraction also support sha1 and sha256 hash sums.
It is very important not to make mistakes in the requests! The request may be executed without error, but not fully. To give a heads up, let's consider what can happen with errors/typos in requests.
Request with a typo in the word reports (reportss)
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reportss: ["tar", "pdf", "xml"]
}
}
]
}The response will not contain an error, but there will be no information about reports at all
{
"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."
}
}
}
]
}Here is the request without a typo in the key reports
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
reports: ["tar", "pdf", "xml"]
}
}
]
}We receive a response that already contains IDs for downloading reports
{
"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."
}
}
}
]
}If a wrong/expired API key is sent, we will receive error 403 in response.
SandBlast API: in the cloud and on local devices
API requests can be sent to Check Point devices where the Threat Emulation component (blade) is enabled. The address for requests should use the device's ip/url and port 18194 (for example — https://10.10.57.19:18194/tecloud/api/v1/file/query). Также следует убедиться в том, что политикой безопасности на устройстве разрешено такое подключение. Авторизация через API ключ на локальных устройствах по умолчанию disabled and the Authorization key in the request headers can be omitted altogether.
API requests to the CheckPoint cloud should be sent to the address te.checkpoint.com (for example — https://te.checkpoint.com/tecloud/api/v1/file/query). API ключ можно получить в виде триальной лицензии на 60 дней, обратившись к партнерам Check Point или в локальный офис компании.
Threat Extraction is not yet supported on local devices in the standard and should use (which we will discuss in more detail at the end of the article).
Local devices do not support the quota request.
Other than that, there are no differences between requests to local devices and to the cloud.
Calling the Upload API
The method used is — POST
The call address is — https://<service_address>/tecloud/api/v1/file/upload
The request consists of two parts (form-data): a file intended for emulation/cleaning and the body of the request with the text.
The text request cannot be empty, but it may not contain any configuration. To ensure the request is successful, you need to send at least the following text in the request:
The minimum required for the upload request
HTTP POST
https://<service_address>/tecloud/api/v1/file/upload
Headers:
Authorization: <api_key>
Body
{
"request": {
}
}
File
File
In this case, the file for processing will be submitted according to the default parameters: component — te, OS images — Win XP and Win 7, without generating a report.
Comments on the main fields in the text request:
file_name and file_type can be left empty or not sent at all, as this is not particularly useful information when uploading a file. In the API response, these fields will be automatically filled based on the name of the uploaded file, and the information in the cache will still have to be searched for by the md5/sha1/sha256 hash sums.
Example of a request with empty file_name and file_type
{
"request": {
"file_name": "",
"file_type": "",
}
}features — a list specifying the necessary functionality during processing in the sandbox — av (Anti-Virus), te (Threat Emulation), extraction (Threat Extraction). If this parameter is not provided at all, only the default component — te (Threat Emulation) will be activated.
To enable verification in the three available components, these components must be specified in the API request.
Example of a request with checks in av, te, and extraction
{ "request": [
{
"sha256": {{sha256}},
"features": ["av", "te", "extraction"]
}
]
}Keys in the te section
images — a list where dictionaries with the id and revision number of the operating systems in which the check will be performed must be specified. The IDs and revision numbers are the same for all local devices and the cloud.
List of operating systems and revisions
Available OS Image ID
Revision
Image OS and Application
e50e99f3-5963-4573-af9e-e3f4750b55e2
1
Microsoft Windows: XP — 32bit SP3
Office: 2003, 2007
Adobe Acrobat Reader: 9.0
Flash Player 9r115 and 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
If the key images is not specified, then the emulation will take place in the images recommended by Check Point (currently Windows XP and Windows 7). These images are recommended to achieve the best balance of performance and catch rate.
reports — a list of reports that we request in case the file turns out to be malicious. The following options are available:
summary — .tar.gz archive containing the emulation report for with everything requested images (both as an HTML page and components such as video from the emulator OS, network traffic dump, report in JSON, and the sample itself in a password-protected archive). In the response, look for the key — summary_report for subsequent download of the report.
pdf — emulation document in one image, which many are accustomed to receiving via Smart Console. In the response, look for the key — pdf_report for subsequent download of the report.
xml — emulation document in one image suitable for extracting parameters from the report. In the response, look for the key — xml_report for subsequent download of the report.
tar — .tar.gz archive containing the emulation report in one requested images (both as an HTML page and components such as video from the emulator OS, network traffic dump, report in JSON, and the sample itself in a password-protected archive). In the response, look for the key — full_report for subsequent download of the report.
What's inside the summary report
Keys full_report, pdf_report, xml_report exist in the dictionary for each OS
{
"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."
}
}
}
]
}And here the key summary_report — is one for the entire emulation
{
"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."
}
}
}
]
}You can request both tar and xml reports, as well as pdf; you can request both summary and tar or xml together. However, you cannot request a summary report and pdf simultaneously.
Keys in the extraction section
Only two keys are used for threat extraction:
method — pdf (conversion to pdf, used by default) or clean (removal of active content).
extracted_parts_codes — a list of codes for removing active content, applicable only for the clean method
Codes for removing content from files
Code
Description
1025
Linked Objects
1026
Macros and Code
1034
Sensitive Hyperlinks
1137
PDF GoToR Actions
1139
PDF Launch Actions
1141
PDF URI Actions
1142
PDF Sound Actions
1143
PDF Movie Actions
1150
PDF JavaScript Actions
1151
PDF Submit Form Actions
1018
Database Queries
1019
Embedded Objects
1021
Fast Save Data
1017
Custom Properties
1036
Statistic Properties
1037
Summary Properties
To download a cleaned copy, you will also need to make a query request (which will be discussed later) after a few seconds, specifying the file hash and the extraction component in the query text. You can retrieve the cleaned file using the id from the query response — extracted_file_download_id. Again, looking ahead, I provide examples of the request and response for the query to find the id to download the cleaned document.
Query request to find the key extracted_file_download_id
{ "request": [
{
"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
"features": ["extraction"] ,
"extraction": {
"method": "pdf"
}
}
]
}Response to the query request (find the key 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."
}
}
}
]
}General information
Only one file can be sent for verification in a single API call.
The av component does not require an additional section with keys; it is sufficient to specify it in the dictionary. features.
Query API Call
The method used is — POST
The call address is — https://<service_address>/tecloud/api/v1/file/query
Before uploading a file (upload request), it is advisable to perform a sandbox cache check (query request) to optimize the load on the API server, as there might already be information and a verdict about the uploaded file on the API server. The call consists only of the text part. The mandatory part of the request is the sha1/sha256/md5 hash of the file. This can be obtained in the response to the upload request.
The minimum required for a query request
HTTP POST
https://<service_address>/tecloud/api/v1/file/query
Headers:
Authorization: <api_key>
Body
{
"request": {
"sha256": <sha256 hash sum>
}
}
Example response to the upload request, showing the sha1/md5/sha256 hash sums
{
"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."
}
}
}
}The query aside from the hash sum ideally should be the same as the upload request (or planned to be), or even "already" (containing fewer fields in the query than in the upload request). If the query contains more fields than in the upload request, you will not receive all the required information in response.
Here is an example of a response to a query where not all required data was found.
{
"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."
}
}
}
]
}Please note the fields. code and label. These fields appear three times in the status dictionaries. Initially, we see the global key "code": 1006 and "label": "PARTIALLY_FOUND". Then these keys appear for each individual component we requested — te and extraction. And while it's clear for te that data was found, the information for extraction is absent.
Here is what the query looked like for the example above.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te", "extraction"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}If you send the query without the extraction component.
{ "request": [
{
"sha256": {{sha256}},
"features": ["te"] ,
"te": {
"images": [
{
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"reports": [
"xml", "pdf"
]
}
}
]
}Then the response will contain complete information ("code": 1001, "label": "FOUND").
{
"response": [
{
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
"file_type": "doc",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 10,
"images": [
{
"report": {
"verdict": "malicious",
"pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
"xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
},
"status": "found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"combined_verdict": "malicious",
"severity": 4,
"confidence": 1,
"status": {
"code": 1001,
"label": "FOUND",
"message": "The request has been fully answered."
}
}
}
]
}If there is no information in the cache at all, the response will include "label": "NOT_FOUND".
{
"response": [
{
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
},
"sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
"file_type": "",
"file_name": "",
"features": [
"te"
],
"te": {
"trust": 0,
"images": [
{
"report": {
"verdict": "unknown"
},
"status": "not_found",
"id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
"revision": 1
}
],
"score": -2147483648,
"status": {
"code": 1004,
"label": "NOT_FOUND",
"message": "Could not find the requested file. Please upload it."
}
}
}
]
}In a single API call, multiple hash sums can be sent for verification. The response will return data in the exact same order as they were sent in the request.
Example of a query request with multiple sha256 sums.
{ "request": [
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
},
{
"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
}
]
}Response to a query request with multiple sha256 sums.
{
"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."
}
}
}
]
}Requesting multiple hash sums in the query will also positively impact the API server's performance.
Download API call
The method used is — POST (according to the documentation), GET also works (and may seem more logical)
The call address is — https://<service_address>/tecloud/api/v1/file/download?id=<id>
The API key must be passed in the header, the request body should be empty, and the id for download is provided in the URL.
In response to the query request, if the emulation is completed and reports were requested during file upload, the download report ids will be visible. If a cleaned copy is requested, look for the id to download the cleaned document.
Thus, the keys in the response to the query request containing the id value for download may be:
summary_report
full_report
pdf_report
xml_report
extracted_file_download_id
Of course, to receive these keys in response to the query request, they need to be specified in the request (for reports) or do not forget to make a request using the extraction function (for cleaned documents).
Quota API call
The method used is — POST
The call address is — https://<service_address>/tecloud/api/v1/file/quota
To check the remaining quota in the cloud, a quota request is used. The request body is empty.
Example response to the quota request
{
"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
This API was developed earlier than the Threat Prevention API and is intended solely for local devices. It may currently only be useful if you need the Threat Extraction API. For Threat Emulation, it is better to use the standard Threat Prevention API. To enable TP API for SG and configure the API key, follow the actions outlined in . I recommend paying attention to step 6b and checking the availability of the page https:///UserCheck/TPAPI because if the result is negative, further configuration is pointless. All API calls will be sent to this URL. The type of call (upload/query) is controlled by the key in the body of the call — request_name. Other mandatory keys include — api_key (you need to remember this during configuration) and protocol_version (currently, the relevant version is 1.1). You can find the official documentation for this API at . The relative advantages include the ability to send multiple files for emulation upon upload, as files are sent as a base64 encoded text string. To encode/decode files to/from base64, you can use an online converter in Postman for demonstration purposes, for example — . In practical coding, you should utilize the built-in encode and decode methods.
Now, let’s take a closer look at the functions te and extraction of this API.
For the component te a dictionary is provided te_options in the upload/query requests, and the keys in this request completely match the keys te in .
An example request for emulating a file in Win10 with reports
{
"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"]
}
}
]
}For the component extraction a dictionary is provided scrub_optionsThis request specifies the cleaning method: conversion to PDF, removal of active content, or selecting a mode according to the Threat Prevention profile (the profile name is specified). A distinctive feature of the response to an API request with extraction for a file is that you receive a cleaned copy in response to this request as a base64 encoded string (you don't need to make a query and search for the ID to download the document)
Example of a file cleaning request
{"request": [{"protocol_version": "1.1", "api_key": "", "request_name": "UploadFile", "file_enc_data": "", "file_orig_name": "hi.txt", "scrub_options": {"scrub_method": 2}}]}Response to the request
{"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": "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": ""}}]} Although obtaining a cleaned copy requires fewer API requests, I consider this option less preferable and convenient than the form-data request used in .
Postman Collections
I have created collections in Postman for both the Threat Prevention API and the Threat Prevention API for Security Gateway, where the most common API requests are presented. To ensure that the IP/url of the API server and the key are automatically included in requests, and that the sha256 hash after uploading the file is also remembered, three variables have been created within the collections (you can find them by going to collection settings Edit -> Variables): te_api (required to fill in), api_key (required to fill in, except when using the TP API with local devices), sha256 (leave empty, not used in TP API for SG).
Examples of usage
In the community scripts written in Python are presented, which check files from the necessary directory both through and . By interacting with the Threat Prevention API, your file-checking capabilities are significantly expanded, as you can now check files across multiple platforms (notably interesting is the check in , and then in the Check Point sandbox), and files can be obtained not only from network traffic but also from any network drives and, for example, CRM systems.
Source: habr.com
