Review Single-piece Content

Introduces how to call the interface to review a single piece of content in the WebService application channel.

Request method

POST
URL

Interface URL

/skg/v1/dlp/channel/webserviceapp/<WebService Application ID>/<Request Mode>

Request Parameters

The following table introduces the parameters in the interface URL.
Parameter Name Parameter Location Required Description
<WebService Application ID> URL Parameter Yes The ID of the WebService application. Log in to Unified Content Secure Server (UCSS), and go to the page DLP Management > Policy Elements > WebService Application. Look for the corresponding WebService ID in the ID column of the page list.

Note: The WebService ID needs to be bound to the Data Loss Prevention (DLP) policy to take effect.

The specific binding steps are as follows:
  1. On the page UCSS > DLP Management > Policy Elements > WebService Application, click the Add button to add a WebService application, just fill in the name. After adding, an ID will be generated automatically.
  2. On the page DLP Management > Policies, choose to edit or create a new policy.
  3. Click the Source/Destination tab below, click Add Match, and in the drop-down menu, click Destination.
  4. On the Add Destination Match page, in the Condition row, select Add Destination. At the end of the options, check WebService Application, click the add button, and add the just-created WebService.
  5. Click OK to save the match settings. Click OK again to save the policy.
<Request Mode> URL Parameter Yes Specify the request mode as synchronous or asynchronous. The specific parameter values include:
  • sync
  • async

The following table introduces the parameters in the request header.

Metadata Parameters

Definition of metadata parameters

Parameter Name Type Applicable Status Description
user String (Required) Synchronous and Asynchronous The username that generates the event - supports domain users, in the format domain\username.
customAttribute String (Optional) Synchronous and Asynchronous Supports user-defined parameter names.
filename String (Optional) Synchronous and Asynchronous The file name - can be used for policy matching based on the file name.
Note: If you are using product version 3.3, then filename is a required option.
encoding String (Optional) Synchronous and Asynchronous File encoding
queryID String (Required) Synchronous and Asynchronous The event query ID associated with this request, must be unique. If the request does not generate an event, the event details cannot be queried.
Note: The value of queryid corresponds to the traffic UUID in the third-party cloud service.
redaction Dict (Optional) Synchronous and Asynchronous Related to redaction functionality. Whether to enable redaction. For specific redaction settings, please refer to the sendBack parameter. 
 "redaction": {
        "enable": true # Redaction request takes effect when enable is true
  }
sendBack Dict (Optional) Synchronous and Asynchronous Related to redaction functionality. Handling of redacted content.
Note: To use the redaction feature, set the value of the redaction parameter to true.

This field requires an input of a required type attribute, indicating the way the file is returned. The Type attribute supports the following options:

response: Return the redacted content to the current path

httpUpload: Send the redacted content to the specified URL

s3: Upload the redacted content to Amazon S3 storage space

Note: This step also applies to storage in Swift, COS, OSS, etc. For specific related configuration parameters, please refer to the chapter objectinfo Parameters for Reviewing Cloud Service Stored Content in Asynchronous Mode.
  • response: Return the redacted content to the current path. The following is a code example: 
      "sendBack": {
    "type": "response" # Return the redacted content to the current path
  },
  • httpUpload: Send the redacted content to the specified URL. The following is a code example: 
     "sendBack": {
    "type": "httpUpload",
    "url": "http://172.11.11.6/callback " # Send the redacted content to this url
  },
  • S3: Upload the redacted content to cloud storage. The following is a code example applicable to S3: 
     "sendBack": {
        "type": "s3",
        "s3Bucket": "test",
        "s3Region": "", # Upload the redacted file to this location. The value here is the region name when using s3.
# If running on EC2 and using AWS IAM role, the following three items can be omitted, then the following three accessKey, secretKey, endpointUrl can be omitted
        "accessKey": "aws_accessKey",
        "secretKey": "aws_secretKey",
        "endpointUrl": ""
  },
md5 String (Optional) Synchronous and Asynchronous The MD5 value of the file, used for recording and cache acceleration. Supports sending MD5 together with the document for inspection, as well as sending only MD5 for inspection. 
"md5":"09e066b382d4225de3c0594aa89b5fi"
operation int (Optional) Synchronous and Asynchronous Operation ID. Defined when creating the WebService application, and the operation name corresponding to the operation ID will be displayed in the Webservice Operation field of the API traffic log. There are four defaults, and users can also define their own:
  • 1 - Read
  • 2 - Write
  • 3 - Add
  • 4 - Delete
antivirus Bool (Optional) Synchronous and Asynchronous Whether to perform virus scanning, default is False.
md5 String (Optional) Synchronous and Asynchronous The MD5 value of the file, only used for recording.
callback_url String (Optional) Asynchronous Only for asynchronous mode, the listening address for callback
uploadtype String (Required) Asynchronous Only for asynchronous. Supports AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, Swift, as well as local files and download URLs.
  • swift
  • oss
  • cos
  • s3
  • file
  • http
objectInfo Dict (Optional) Asynchronous Only for asynchronous mode and when using object storage. Asynchronous mode supports reviewing objects stored in Amazon S3, Swfit, Alibaba Cloud OSS, Tencent Cloud COS, and other cloud services. For specific setting parameters, refer to the chapter: objectinfo Parameters for Reviewing Cloud Service Stored Content in Asynchronous Mode

Return Parameters

Including the following：

Name Description
result Indicates whether the request was successful. 0 for success, 1 for failure.
actionCode When the request is successful, the user can choose to perform a default action on the content that meets the request conditions. Default actions include 1 - Allow data transfer and 2 - Block data transfer.
errorCode The error code returned when the request fails.
message The error message returned when the request fails.

Python Request Example - WebService Channel (Synchronous Mode)

The following example shows how to use Python code to call the interface to perform content security review of files in the WebService channel in synchronous mode.

Note: In the following Python code example, the imported header files ucwi_config and ucwi_auth need to be created beforehand. For detailed reference examples, see Header File Examples.
Note: In the following Python code example, app_id is the WebService application ID. To obtain this ID, refer to Obtaining WebService Application ID.
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import os
import uuid

requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

app_id = "caafb22a-9f6d-4a06-a0e4-b12c170afdf5"
api = "/skg/v1/dlp/channel/webserviceapp/{}/sync".format(app_id)
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"

metadata = {
    "user": "ucwitestuser",
}

headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path)
files = {
    "request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()

if response.status_code != 200:
    print("Bad request, response code:", response.status_code)
    print(response.text)
else:
    result = response.json()
    # print(json.dumps(result, indent=4).decode('raw_unicode_escape'))
    if result["responseCode"] != 200:
        print("Bad request, response code:", result["responseCode"])
        print(result["message"])
    else:
        hint = "# 1: Allow; 2: Block; 3: Confirm; 4: Delete Attachment; 5: Email Encryption; 6: Email Quarantine; 7: Terminal System Encryption; 8: Email Content Encryption; 9: Terminal Personal Key Encryption"
        print("action:{}    {}".format(result["actionCode"], hint))
        if len(result["incident_info"]) == 0:
            print("not matched.")
        else:
            print("matched policy:")
            for policy in result["incident_info"]["matchedPolicies"]:
                print(json.dumps(policy, indent=2).encode('utf-8').decode('raw_unicode_escape'))

Python Request Example - WebService Channel (Asynchronous Mode)

The following example shows how to use Python code to call the interface to upload files in the WebService channel in asynchronous mode for content security review.

Note: In the following Python code example, the imported header files ucwi_config and ucwi_auth need to be created beforehand. For detailed reference examples, see Header File Examples.
Note: In the following Python code example, app_id is the WebService application ID. To obtain this ID, refer to Obtaining WebService Application ID.
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import os
import uuid

requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

# Get the WebServiceapp id from UCSS
app_id = "caafb22a-9f6d-4a06-a0e4-b12c170afdf5"
api = "/skg/v1/dlp/channel/webserviceapp/{}/async".format(app_id)
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"

metadata = {
    # The user who sent the data, used for policy matching during inspection and final event display
    "user": "ucwitestuser",
    # The filename of the uploaded file, used for policy matching during inspection
    "filename": "test.txt",
    "queryID": str(uuid.uuid4()),
    # Optional parameter, file encoding method, default is UTF-8
    "encoding": "UTF-8",
    # Optional parameter, whether to perform antivirus operation, default is False
    "antivirus": False,
    # Optional parameter, default is an empty string, used for final event display
    "md5": "09e066b382d4225de7f3c0594aa89b5f",
    "uploadtype": "file",
    "callback_url": UCWIConfig.callback_url + "/webserviceapp"
}

headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path)
files = {
    "request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()

if response.status_code != 200:
    print("Bad request, response code:", response.status_code)
    print(response.text)
else:
    result = response.json()
    print(result["message"])

cURL Request Example - WebService Application Channel (Asynchronous Mode)

The following example shows how to use cURL code to call the interface to upload files in the WebService channel in asynchronous mode for content security review.

The following examples are for the S3 upload type:
  • With callback: 
    curl -F 'metadata={"uploadtype": "s3", "callback_url": "http://172.22.113.12:9999/post/webserviceapp ", "queryID": "000864b0-4b2c-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0410user1", "filename": "DLPencrypt.rar"}' 
-F 'request=http://172.22.78.91:8070/test-webserviceapp/home/test/testfile4/DLPencrypt.rar ' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async
  • Without callback: 
    curl -F 'metadata={"uploadtype": "s3", "queryID": "000864b0-4b2c-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0410user1", "filename": "DLPencrypt.rar"}' 
-F 'request=http://172.22.78.91:8070/test-webserviceapp/home/test/testfile4/DLPencrypt.rar ' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async
The following examples are for the localhost upload type:
  • With callback: 
    curl -F 'metadata={"uploadtype": "localhost", "callback_url": "http://172.22.113.12:9999/post/webserviceapp ", "queryID": "44130fdc-4b2e-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0410user1", "filename": "DLPencrypt.rar"}' 
-F 'request=@/home/test/testfile4/DLPencrypt.rar' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async
  • Without callback: 
    curl -F 'metadata={"uploadtype": "localhost","queryID": "44130fdc-4b2e-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0601user1", "filename": "DLPencrypt.rar"}' 
-F 'request=@/home/test/testfile4/DLPencrypt.rar' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async

Example for return code

The Content inspection request returns the following parameters in the results:
Full Name Description
result Whether the request is successful, 0 means success, and 1 means failure.
actionCode When the request is successful, the user can choose a remediation action on the detected content. The default operations include 1-allow data transmission and 2-block data transmission.
errorCode Error code returned when the request failed
message Error Message returned when the request failed

The response to the Content inspection request is as follows.

  • Request successfully
    {
"result" : 0,
"actionCode" : 1/2
}
actionCode: 1 - allow, 2 - block
    Note: If the policy is matched and the violation content is found, the system returns the policy matching information. Refer to The return value for policy match.
  • Request failed
    {
"result" : 1,
"errorCode" : 500,
"message" : "Invalid parameter"
}