Support Center > Search Results > SecureKnowledge Details
Threat Prevention API for Security Gateway Technical Level
Solution

Table of Contents:

  • Overview
  • Configuration
  • Access the API
  • Global Request Headers
  • JSON Request and Response Structure
  • QueryFile Request
  • Scrub Result Codes
  • Scrubbed Parts Codes

Overview

This guide is for Threat Prevention API with Security Gateway.

For Threat Prevention API for Cloud, refer to Threat Prevention API 1.0.

Configuration

It is assumed that Threat Extraction API is enabled on the Security Gateway.

For more information, refer to the following sections in sk113599:

  • Configuring Threat Emulation and Threat Extraction
  • Enabling the Threat Prevention API

Access the API

POST request to the following URL:

https://<GW_IP>/UserCheck/TPAPI

Global Request Headers

These fields must be included 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

The request body can be a single JSON object, or it can contain an array of objects, called a request object.

A JSON request has the following structure:

{
	"request": [{
		"protocol_version": "1.1",
		"request_name": "<request name>",
		"api_key": "<API key from the GW>"
	}]
}

 

The response body has one object, or an array of response objects. A response has the following structure:

{
	"response": [{
		"protocol_version": "1.1",
		"src_ip": "<GW IP>"
	}]
}    

Request Object structure:

  • A request object has JSON fields that are relevant 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:

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.

Note that this section is only relevant for 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.

Example

Query request

{
	"request": [{
		"protocol_version": "1.1",
		"api_key": "<API_KEY>",
		"request_name": "QueryFile",
		"sha1": "c22b5f9178342609428d6f51b2c5af4c0bde6a42",
		"features": ["te"],
		"te": {}
	}]
}

Query response

{
	"response": [{
		"protocol_version": "1.1",
		"src_ip": "<IP_ADDRESS>",
		"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

  • Use the Upload API to have a client application request sent 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 once the scan is completed. 

Upload Request Format

  • file_enc_data : Base64 encoded file
  • file_orig_name : File name

at least one of the below fields must be specified:

  • 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 in case scrub_method=0

Optional fields:

  • save_original_file_on_server : [True|False]
    • Will save the original file. User would be able to access it in UserCheck portal
  • scrubbed_parts_codes
    • Parts to be extracted
    • Relevant when extract method is used
  • sender : Original URL of the file

 

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": "<API_KEY>",
		"request_name": "UploadFile",
		"file_enc_data": "<base64_encoded_file>",
		"file_orig_name": "hi.txt",
		"scrub_options": {
			"scrub_method": 2
		}
	}]
}

 

Upload response

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

Example 2 : Threat Extraction - According to profile

Upload request

{
	"request": [{
		"protocol_version": "1.1",
		"api_key": "<API_KEY>",
		"request_name": "UploadFile",		
		"subject": "http://www.bitsavers.org/pdf/3Com/3C400_May82.pdf",
		"file_orig_name": "3C400_May82.pdf",
		"file_enc_data": "<base64_encoded_file>",
		"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": "<IP_ADDRESS>",
		"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 as well as te field in the response, please refer to Threat Prevention API 1.0.

 

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. Relevant when 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

Array of parts to remove.

Code Display name Description
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

Give us Feedback
Please rate this document
[1=Worst,5=Best]
Comment