单条内容审查

介绍如何调用接口在WebService应用通道中进行单条内容的审查。

请求方式

POST

接口地址

/skg/v1/dlp/channel/webserviceapp/<WebService应用ID>/<请求模式>

请求参数

以下表格对接口地址中的参数做了介绍。
参数名称 参数位置 是否必须 描述
<WebService应用ID> URL参数 WebService的应用ID。登录统一内容安全管理平台UCSS,并进入DLP管理 > 策略元素 > WebService应用页面,在页面列表的ID栏中,查找对应的WebService ID。

Note: WebService ID需要绑定到数据防泄漏DLP策略中才能生效。

具体绑定步骤如下:
  1. UCSS > DLP管理 > 策略元素 > WebService应用页面,点击添加按钮,添加一个WebService应用,仅填写名称即可。添加完成后会自动生成ID。
  2. DLP管理 > 策略页面,选择编辑或新建一个策略。
  3. 点击下方的来源/目标选项卡,点击添加匹配,在下拉菜单中,点击目标
  4. 添加目标匹配页面,在条件行,选择添加目标。在选项的最后面,勾选WebService应用,点击添加按钮,将刚刚创建的WebService加入进来。
  5. 点击确定保存匹配设置。再次点击确定保存策略。
<请求模式> URL参数 指定请求模式为同步或异步。具体参数值包括:
  • sync
  • async

以下表格对请求头的参数做了介绍。

元数据参数

metadata参数定义

参数名 类型 适用状态 说明
user String(必选) 同步和异步 生成事件的用户名 - 支持域用户,格式为域名\用户名。
customAttribute String(可选) 同步和异步 支持用户自定义的参数名。
filename String(可选) 同步和异步 文件名 - 可做根据文件名设置的策略匹配
encoding String(可选) 同步和异步 文件编码
queryID String(必选) 同步和异步 与此请求关联的事件查询ID,保持唯一。若请求无事件生成则无法查询到事件详情。
注: queryid的值对应于第三方云服务中的流量UUID。
redaction Dict(可选) 同步和异步 脱敏后内容的处理。
  • response:将脱敏后的内容返回至当前路径。以下为代码示例:
    "redaction": {
    "sendBackType": "response",
    }
  • httpUpload:将脱敏后的内容发送至指定URL。以下为代码示例:
    "redaction": {
    "sendBackType": "httpUpload",
    "url": "http://172.22.148.115/upload",
    }
  • S3:将脱敏后的内容上传至云存储。以下为适用于S3的代码示例:
    "redaction": {
        "sendBackType": "s3",
        "s3Bucket": "skyguardts",
        "accessKey": "skyguardts",
        "secretKey": "skyguardts",
        "endpointUrl": "http://172.22.148.117:9000",
        },

    此步骤同样适用于SwiftCOSOSS云端服务。具体相关配置参数,请参考章节异步模式下审查云服务存储内容的objectinfo参数

md5 String(可选) 同步和异步 文件MD5值,用于记录和缓存加速。支持MD5和文档一同送检,也支持仅送检MD5。
"md5":"09e066b382d4225de3c0594aa89b5fi"
operation int(可选) 同步和异步 操作ID。创建WebService应用时定义,在API流量日志的Webservice操作字段中将会显示操作ID对应的操作名称。默认有以下四种,用户也可以自定义:
  • 1 - 读取
  • 2 - 写入
  • 3 - 添加
  • 4 - 删除
antivirus Bool(可选) 同步和异步 是否进行病毒检查,默认为False。
md5 String(可选) 同步和异步 文件MD5值,仅用于记录。
callback_url String(可选) 异步 只限于异步模式填写,call back的监听地址
uploadtype String(必选) 异步 只限于异步。支持AWS S3、阿里云OSS、腾讯云COS、Swift等云存储,以及本地文件和下载URL。
  • swift
  • oss
  • cos
  • s3
  • file
  • http
objectInfo Dict(可选) 异步 只限于异步模式并使用对象存储时使用。异步模式支持审查存储在亚马逊S3、Swfit、阿里云OSS、腾讯云COS等云服务的对象存储。具体设置参数,参阅章节:异步模式下审查云服务存储内容的objectinfo参数

返回参数

内容审查请求返回结果中包含以下参数:

名称 描述
result 请求是否成功,成功为0,失败为1
actionCode 请求成功时,用户可选择对符合请求条件的内容进行默认操作,默认操作包括1-允许数据传输和2-阻断数据传输
errorCode 请求失败时返回的错误代码
message 请求失败时返回的错误消息

Python请求示例 - WebService通道(同步模式)

以下示例为使用Python代码调用接口,以在同步模式下,对WebService通道中的文件进行内容安全审查。

注: 在如下Python代码示例中,导入的Header文件ucwi_config ucwi_auth的需事先创建,如需详细参考示例,请参阅Header文件示例
注: 在如下Python代码示例中,app_id为WebService应用ID,如需获取该ID,参照获取WebService应用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",
    # 发送数据的用户,用于内容安全审查时的策略匹配,以及内容安全审查完成后的事件显示
    "filename": "test.txt",
    # 上传文件的文件名,用于内容安全审查时的策略匹配
    "queryID": str(uuid.uuid4()),
    # 此次请求关联的UUID,需要唯一,在异步模式下,用于事件查询
    "encoding": "UTF-8",
    # 可选参数,文件的编码方式,默认是UTF-8
    "antivirus": False,
    # 可选参数,是否执行反病毒检查,默认值为False,即忽略,如需反病毒检查,可改为True
    "md5": "09e066b382d4225de7f3c0594aa89b5f"
    # 可选参数,默认为空字符串,用于内容安全审查完成后的事件显示
}

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:允许; 2:阻断;3:确认;4:删除附件;5:邮件加密;6:邮件隔离;7:终端系统加密;8:邮件内容加密;9:终端个人密钥加密"
        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请求示例 - WebService通道(异步模式)

以下示例为使用Python代码调用接口,以在异步模式下,上传WebService通道中的文件,以供内容安全审查。

注: 在如下Python代码示例中,导入的Header文件ucwi_config ucwi_auth的需事先创建,如需详细参考示例,请参阅Header文件示例
注: 在如下Python代码示例中,app_id为WebService应用ID,如需获取该ID,参照获取WebService应用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)

# 从UCSS上获取webserviceapp的id
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 = {
    # 数据是哪个用户发送的,用于检查时匹配策略和最后事件的显示
    "user": "ucwitestuser",
    # 上传文件的文件名,用于检查时匹配策略
    "filename": "test.txt",
    "queryID": str(uuid.uuid4()),
    # 可选参数,文件的编码方式,默认是UTF-8
    "encoding": "UTF-8",
    # 可选参数,是否执行反病毒操作,默认是False
    "antivirus": False,
    # 可选参数,默认为空字符串,用于最后事件的显示   
    "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请求示例 - WebService应用通道 (异步模式)

以下示例为使用cURL代码调用接口,以在异步模式下,上传WebService通道中的文件,以供内容安全审查。

以下示例适用于上传类型为S3的情况:
  • 带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
  • 不带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
以下示例适用于上传类型为localhost的情况:
  • 带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
  • 不带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

返回示例

内容审查请求的回复如下。

  • 请求成功:
    {
    "result" : 0,
    "actionCode" : 1/2
    }
    actionCode: 1 - allow, 2 - block
    注: 若匹配策略,发现违规内容,系统还将返回策略匹配信息,具体请参照送检策略匹配返回值定义
  • 请求失败:
    {
    "result" : 1,
    "errorCode" : 500,
    "message" : "Invalid parameter"
    }