> Source: [sk137032](https://support.checkpoint.com/results/sk/sk137032) # sk137032 - Threat Prevention API for Security Gateway | Property | Value | |----------|-------| | Solution ID | sk137032 | | Date Created | 2018-09-27 | | Last Modified | 2026-02-12 | | Technical Level | General | | Products | Security Gateway | | Versions | R82, R81.20, R81.10 (EOS), R81 (EOS) | | OS | Gaia | ## Solution **Table of Contents:** * Overview * Configuration * Access the API * Global Request Headers * JSON Request and Response Structure * QueryFile Request * UploadFile Request * Upload Request Format * Upload Response Format * Scrub Result Codes * Scrubbed Parts Codes * Increase maximum supported file size Overview {#Overview} -------------------- This guide is for Threat Prevention API with Security Gateway. For Threat Prevention API for Cloud, refer to [Threat Prevention API 1.0](https://sc1.checkpoint.com/documents/TPAPI/CP_1.0_ThreatPreventionAPI_APIRefGuide/html_frameset.htm). Configuration {#Configuration} ------------------------------ It is assumed that Threat Extraction API is enabled on the Security Gateway. For more information, refer to these sections in [sk113599](https://supportcenter.checkpoint.com/supportcenter/portal?eventSubmit_doGoviewsolutiondetails=&solutionid=sk113599): * Configuring Threat Emulation and Threat Extraction * Enabling the Threat Prevention API Access the API {#Access the API} -------------------------------- POST request to the following URL: *https://\/UserCheck/TPAPI* Global Request Headers {#Global Request Headers} ------------------------------------------------ You *must* include these fields in each request: * **api_key** : A valid API key from the Security Gateway, located at /opt/CPUserCheckPortal/phpincs/conf/TPAPI.ini * **protocol_version** : Current protocol version. ("1.1") * **request_name** : "QueryFile", "UploadFile" JSON Request and Response Structure {#JSON Request and Response Structure} -------------------------------------------------------------------------- The request body can be a single JSON object or contain an array of objects, called a request object. A JSON request has this structure: ``` { "request": [{ "protocol_version": "1.1", "request_name": "", "api_key": "" }] } ``` The response body has one object, or an array of response objects. A response has this structure: ``` { "response": [{ "protocol_version": "1.1", "src_ip": "" }] } ``` Request Object structure: * A request object has JSON fields that are applicable to the request, with metadata about the request. * The body of the request can also have a detailed section, with data for each feature that can be used. * If not given, the Threat Prevention service uses the best default values. Response Object structure: * The response object has general and feature-specific fields and properties. * [Response status codes](https://sc1.checkpoint.com/documents/TPAPI/CP_1.0_ThreatPreventionAPI_APIRefGuide/html_frameset.htm) (go to **Introduction** \> **Response Status Codes**) QueryFile Request {#QueryFile Request} -------------------------------------- Use the Query API to have a client application look for: * The status of a file, uploaded for analysis. * The analysis report of a specific file on the Check Point Threat Prevention service databases. This section is only applicable to Threat Emulation (when *te_options* field is sent in *UploadFile*request). For more details regarding Threat Emulation options refer to [Threat Prevention API 1.0.](https://sc1.checkpoint.com/documents/TPAPI/CP_1.0_ThreatPreventionAPI_APIRefGuide/html_frameset.htm) ### Example **Query request** ``` { "request": [{ "protocol_version": "1.1", "api_key": "", "request_name": "QueryFile", "sha1": "c22b5f9178342609428d6f51b2c5af4c0bde6a42", "features": ["te"], "te": {} }] } ``` **Query response** ``` { "response": [{ "protocol_version": "1.1", "src_ip": "", "te": { "features": ["te"], "file_type": "pdf", "md5": "49f68a5c8493ec2c0bf489821c21fc3b", "sha1": "c22b5f9178342609428d6f51b2c5af4c0bde6a42", "sha256": "8f434346648f6b96df89dda901c5176b10a6d839", "status": { "code": 1001, "label": "FOUND", "message": "We have found your request" }, "te": { "combined_verdict": "Benign", "confidence": 0, "images": [{ "id": "5e5de275-a103-4f67-b55b-47532918fa59", "report": { "additional_emulation_data": { "dropped_data": "", "dropped_files_info": "", "embedded_data": "", "embedded_files_info": "", "source_url_risk": "", "verdict_decider": "" }, "verdict": "Benign" }, "revision": 1, "status": "found" }, { "id": "e50e99f3-5963-4573-af9e-e3f4750b55e2", "report": { "additional_emulation_data": { "dropped_data": "", "dropped_files_info": "", "embedded_data": "", "embedded_files_info": "", "source_url_risk": "", "verdict_decider": "" }, "verdict": "Benign" }, "revision": 1, "status": "found" }], "score": -2147483648, "severity": 0, "status": { "code": 1001, "label": "FOUND", "message": "We have found your request" } } } }] } ``` UploadFile Request {#UploadFile Request} ---------------------------------------- * Use the Upload API to send a client application request for Check Point Threat Prevention modules to scan and analyze. * For enhanced security, HTTPS is used during upload and download (in Threat Extraction) of the file to the service. * Unless *save_original_file_on_server=True* is specified in *scrub_options* (see below), the file is deleted from the server when the scan is completed. * The Maximum supported File Size is 15MB. The API does not enforce it, and does not send proper errors if the file size exceeded. Make sure to enforce the file size on the client application. To increase the maximum supported file size above 15MB, refer to "Increase maximum supported file size" section below. * **Important Limitation: Multiple Features** In te_options, when using the \`features\` parameter with multiple feature values (e.g., \`\["te", "av"\]\`), only one feature will be executed per request due to Security Gateway architecture. Workaround: To scan a file with multiple features: 1. Submit separate UploadFile requests, one for each feature 2. Execute requests sequentially (one after the other) 3. \*\*Recommended order:\*\* Anti-Virus (AV) first, then Threat Emulation (TE) - AV provides faster, initial verdict - TE provides comprehensive, deeper analysis 4. Use QueryFile requests to retrieve results for each feature independently Upload Request Format {#Upload Request Format} ---------------------------------------------- * **file_enc_data** : Base64 encoded file * **file_orig_name** : File name You *must* specify at least one of the fields below: * **scrub_options**: used for Threat Extraction * **te_options** : used for Threat Emulation ### scrub_options #### **Required fields:** * **scrub_method** : * 0 : According to profile * 1 : Extract * 2 : Convert to PDF * **profile_name** : Name of the Threat Prevention profile to be used * this field is mandatory if scrub_method=0 #### Optional fields: * **save_original_file_on_server** : \[True\|False\] * Saves the original file. The user accesss it in UserCheck portal * **scrubbed_parts_codes** : * Parts to be extracted * Applicable when *extract*method is used * **sender** : Original URL of the file ### Upload Response Format {#Upload Response Format} * **scrub_result** : Result code. See *Scrub result codes* section * **scrubbed_content** : Parts that were extracted from the document. * **scrub_time** : Time (in seconds) it took to scrub the file. * **output_file_name**: Name of the resulted file. * **message** : Description of *scrub_result* code. See *Scrub result codes* section * **scrub_method**: Method used to scrub the file * **orig_file_url** : * UserCheck URL to get the original file. * Relevant when *save_original_file_on_server=True* * **real_extension** : Suffix of the sent file * **input_real_extension** : Resolve file type * **scrub_activity** : Free text regarding the extraction activity * **risk** : Calculated risk of the file * **protection_name** : "Extract potentially malicious content" * **protection_type** : The protection method that was use * "Conversion to PDF" : scrub_method=2 * "Content Removal" : scrub_method=1 Example 1 : Threat Extraction - Convert to PDF ---------------------------------------------- **Upload request** ``` { "request": [{ "protocol_version": "1.1", "api_key": "", "request_name": "UploadFile", "file_enc_data": "", "file_orig_name": "hi.txt", "scrub_options": { "scrub_method": 2 } }] } ``` **Upload response** ``` { "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": "" } }] } ``` Example 2 : Threat Extraction - According to profile ---------------------------------------------------- **Upload request** ``` { "request": [{ "protocol_version": "1.1", "api_key": "", "request_name": "UploadFile", "subject": "http://www.bitsavers.org/pdf/3Com/3C400_May82.pdf", "file_orig_name": "3C400_May82.pdf", "file_enc_data": "", "scrub_options": { "scrub_method": 0, "scrubbed_parts_codes": [1034, 1026, 1019, 1025, 1018, 1139, 1142, 1143, 1141, 1150, 1151, 1137, 1021], "save_original_file_on_server": false, "profile_name": "Recommended_Profile" }, "te_options": { "file_name": "3C400_May82.pdf", "file_type": "pdf", "url": "http://www.bitsavers.org/pdf/3Com/3C400_May82.pdf", "is_base64": true, "features": ["te"], "te": { "rule_id": 1 } } }] } ``` **Upload response** ``` { "response": [{ "protocol_version": "1.1", "src_ip": "", "scrub": { "file_enc_data": "", "input_real_extension": "pdf", "message": "Skipped", "orig_file_url": "", "output_file_name": "", "protection_name": "Extract potentially malicious content", "protection_type": "Content Removal", "real_extension": "pdf", "risk": 0, "scrub_activity": "The file doesn't include cleanable parts", "scrub_method": "Clean Document", "scrub_result": 4, "scrub_time": "0.483", "scrubbed_content": "" }, "te": { "features": ["te"], "file_name": "3C400_May82.pdf", "file_type": "pdf", "md5": "58bc8adb1caf374db12e0849489324c1", "sha1": "5a5b144395de4881c538fcfdd5621aa5b0d7d1b3", "sha256": "c8d2562cf43786a8b8fef952434c1538c985c0e4952729d0479c5a11b51072f7", "status": { "code": 1002, "label": "UPLOAD_SUCCESS", "message": "The file was uploaded successfully" }, "te": { "images": [{ "id": "5e5de275-a103-4f67-b55b-47532918fa59", "report": { "verdict": "unknown" }, "revision": 1, "status": "not_found" }, { "id": "e50e99f3-5963-4573-af9e-e3f4750b55e2", "report": { "verdict": "unknown" }, "revision": 1, "status": "not_found" }], "status": { "code": 1002, "label": "UPLOAD_SUCCESS", "message": "The file was uploaded successfully" } } } }] } ``` For more details regarding *te_options* in the request and the *te* field in the response, refer to [Threat Prevention API 1.0.](https://sc1.checkpoint.com/documents/TPAPI/CP_1.0_ThreatPreventionAPI_APIRefGuide/html_frameset.htm) Scrub Result Codes ------------------ | scrub_result | message | Explanation | |--------------|---------------------------------|---------------------------------------------------------------------| | 0 | OK | File was successfully scrubbed | | 1 | Failed | Failed to scrub file | | 2 | Timeout | Scrubbing operation timed-out | | 3 | Unsupported | Sent file is not supported by Threat Extraction | | 4 | Skipped | There are no cleanable parts. Applicable when the method is extract | | 5 | Error | | | 6 | Disk limit reached | | | 7 | Password protected | File is encrypted, and so cannot be opened and extracted | | 8 | Protected by DocSec | File is encrypted, and so cannot be opened and extracted | | 9 | Out of memory | | | 15 | Unknown | File is encrypted and cannot be extracted, but can be analyzed | | 17 | Larger than next hop size limit | DPI has been reduced to decrease the file's size |







Scrubbed Parts Codes {#Scrubbed Parts Codes} -------------------------------------------- Array of parts to remove. |------|----------------------------|---------------------------------------------------------| | Code | Display name | Description | | 500 | Embedded Images | Images embedded in documents | | 1017 | Custom Properties | Custom document properties | | 1018 | Database Queries | Queries to remote databases | | 1019 | Embedded Objects | Files and objects embedded in documents | | 1021 | Fast Save Data | Stored data for fast document saving | | 1025 | Linked Objects | Links to files that are reviewed by another application | | 1026 | Macros And Code | Microsoft Office macros and PDF JavaScript code | | 1034 | Sensitive Hyperlinks | Links to network/local file paths | | 1036 | Statistic Properties | Statistic document properties | | 1037 | Summary Properties | Summary document properties | | 1137 | PDF Go To Remote Actions | Open other PDF files | | 1139 | PDF Launch Actions | PDF Launch Actions | | 1141 | PDF URI Actions | Open Uniform Resource Identifier (URI) resources | | 1142 | PDF Sound Actions | Play sound objects | | 1143 | PDF Movie Actions | Play movie files | | 1150 | PDF JavaScript Actions | Execute JavaScript code | | 1151 | PDF Submit Form Actions | Submit data to remote locations | | 1178 | PDF 3D Artwork Annotations | Embedded 3D Artwork | Increase maximum supported file size {#Increase Max File Size} -------------------------------------------------------------- It is recommended to use the default maximum supported file size of 15MB. If you decide to increase it, then make sure the Security Gateway RAM has a minimum of 16GB. Handling heavy traffic, especially on oversized files, might have an effect on performance and other API-unrelated issues. To increase the maximum supported file size to at least 100MB, do these steps on the Security Gateway: 1. In configuration file ***/opt/CPUserCheckPortal/conf/httpd.conf*** replace ***LimitRequestBody \<..\>*** with ***LimitRequestBody 0*** 2. In configuration file ***/opt/CPUserCheckPortal/conf/php.ini*** replace ***memory_limit = \<..\>*** with ***memory_limit = 2G*** 3. In script file ***/opt/CPUserCheckPortal/htdocs/UserCheck/TPAPI*** replace ***ini_set('memory_limit','180M');*** with ***ini_set('memory_limit','900M');*** 4. Run the command: ***\[Expert@HostName:0\]# mpclient restart UserCheck*** --- # Agent Instructions This content is from the Check Point Support Center (https://support.checkpoint.com), the official knowledge base for Check Point cybersecurity products. ## Navigating This Knowledge Base - **Complete index**: [llms.txt](https://support.checkpoint.com/llms.txt) - **All SK articles**: [SecureKnowledge Sitemap](https://support.checkpoint.com/sitemaps/secureknowledge-sitemap-index.xml) - **SK article URL pattern**: `https://support.checkpoint.com/results/sk/{skId}` - **Markdown responses**: AI bot User-Agents automatically receive `text/markdown` content