【YD通讯标准】 移动互联网恶意程序疑似样本报送接口规范

ICS33.060
中华人民共和国通信行业标准
YD/T2849-2015
移动互联网恶意程序疑似样本报送接口规范
Data interfaces specification for submitting mobileInternetmaliciouscodesamples2015-04-30发布
2015-07-01实施
中华人民共和国工业和信息化部发布前言
1范围·
2规范性引用文件
3术语、定义和缩略语
3.1术语和定义·
3.2缩略语
4移动互联网恶意程序疑似样本报送和结果反馈流程总述.5移动互联网恶意程序疑似样本报送接口5.1接口描述·
5.2接口协议
5.3接口流程
5.4接口消息
6移动互联网恶意程序疑似样本报送结果查询接口6.1接口描述··
接口协议
6.3接口流程
6.4接口消息·
7移动互联网恶意程序样本传播源报送接口·7.1接口描述
7.2接口协议
7.3接口流程
7.4接口消息
8移动互联网恶意程序疑似样本报送信息查询接口·接口描述·
8.2接口协议
接口流程
8.4接口消息
9移动互联网恶意程序样本库查询接口9.1接口描述
9.2接口协议
9.3接口流程
9.4接口消息
附录A（资料性附录）接口使用示范代码·附录B（规范性附录）接口API密钥约定说明YD/T2849-2015
YD/T2849-2015
本标准按照GB/T1.1-2009给出的规则起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由中国通信标准化协会提出并归口。本标准起草单位：国家计算机网络应急技术处理协调中心、中国联合网络通信集团有限公司、中国移动通信集团公司、中国电信集团公司、恒安嘉新（北京）科技有限公司、安天科技股份有限公司。本标准主要起草人：云晓春、舒敏、王明华、陈阳、李海灵、何能强、纪玉春、潘宣晨、殷豪、俊、王文磊、张
王维晟、胡
HiiKAoNiKAca
1范围
移动互联网恶意程序疑似样本报送接口规范YD/T2849-2015
本标准规定了移动互联网恶意代码疑似样本报送接口的接口定义、接口流程、接口传递数据结构等内容。
本标准适用于移动互联网恶意代码似样本报送及信息数据交互使用。2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅所注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YD/T2439
IETFRFC2246
IETFRFC2818
IETFRFC4627
3术语、定义和缩略语
3.1术语和定义
移动互联网恶意程序描述格式
安全传输层协议(TheTLSProtocol)基于安全传输的超文本传输协议(HTTPOverTLS)一种轻量级的数据交换格式（JavaScriptObjectNotation）下列术语和定义适用于本文件：3.1.1
样本报送服务平台SamplesSubmittingServicePlatform用于提供样本报送数据接收和结果反馈服务的Web服务系统，即建立在国家互联网应急技术处理协调组织的样本报送服务平台。
疑似样本报送者SuspiciousSamplesReporter提交疑似样本数据的发送方，例如各地互联网应急协调组织、运营商、安全厂商、研究机构或个人。3.2缩略语
下列缩略语适用于本文件：
Hypertext Transfer Protocol over Secure Socket LayerJavaScript Object Notation
Message Digest version 5
Secure Sockets Layer
Transmission ControlProtocolUniform Resource Locator
8-bitUnicodeTransformationFormatWebService
基于HTTP的加密传输通道
JavaScript对象表示法
报文摘要版本5
安全套接层
传输控制协议
统一资源定位符
8位元通用字符集
Web服务
iiKAoNiKAca
YD/T2849-2015
4移动互联网恶意程序疑似样本报送和结果反馈流程总述移动互联网恶意程序疑似样本通过本标准规定的接口进行样本文件数据和样本相关信息的报送（例如，样本分析报告数据和样本文件相关的基础信息数据）。疑似样本报送和结果反馈的总体流程如图1所示，后续各章将会将这些流程拆分进行叙述。总体来说，疑似样本报送者向样本报送服务平台发报送请求消息，请求消息包括疑似样本报送结果请求消息、疑似样本报送结果查询消息、样本传播源报送消息、疑似样本报送信息查询消息和样本库查询消息这五类（分别见第5、6、7、8、9章）。请求的消息通过HTTPS协议，采用JSON格式将相关数据报送至样本报送服务平台。服务平台在接收数据后，会对数据的有效性进行验证，若符合本标准规定则会对数据进行相关处理并反馈结果。根据结果中反馈的内容，疑似样本报送者可以根据反馈信息中包含的信息进行处理，也可以采用异步的方式，根据样本报送任务标识访问样本报送服务平台的结果查询接口获得处理结果的更新。
聚似样本报送者
移动互联网恶意程序贬似样本报送接口请求消息
移动互联网恶意程序疑似样本报送接口反馋嘴消息
移动互联网似样本报送结果查询接口请求消息
移动互联网疑似样本报送结果查询接口反馈消息
移动互联网恶意程序样本传播源报送接口请求消息
移动互联网恶意程序样本传播源报送接口反馈消息
移动互联网疑似样本报送信息查询接口请求消息
移动互联网爱似样本报送信息查询接口反馈消息
移动互联网恶意程序样本库查询接口请求消息
移动互联网恶意程序样本库查询接口反馈消息
样本报送服务平台
接收/处理疑似
查询处理状态/
结果信息
接收/处理悉意
程序传播源
查询基本/
统计信息
查询已审核
恶意样本
图1移动互联网恶意程序疑似样本报送和结果反馈流程图HiiKAoNiKAca
5移动互联网恶意程序疑似样本报送接口5.1接口描述
YD/T2849-2015
本接口用于各地互联网应急协调组织、运营商、安全厂商、研究机构或个人向国家互联网应急技术处理协调组织提交疑似样本文件数据和其相关数据，包括样本的基本信息数据、样本文件数据样本分析报告数据。如报送者需修改上报信息，可多次调用该接口发送补充数据，样本报送服务平台接收到的数据，将以最新上报的数据为准进行覆盖或者补充操作。本接口的名称为“cncert_submit_sample”。5.2接口协议
系统数据的交互接口使用HTTPS协议，使用POST方式提交数据。接口定义遵循IETFRFC2818、IETFRFC4627。接口消息会以JSON文档的格式通过HTTPS协议传输。5.3接口流程
此流程完成移动互联网恶意代码疑似样本相关数据的上报，其流程如下，具体如图2所示。a）疑似样本报送者根据本标准的要求和约定按照指定的数据结构构造报送请求，并调用本接口。b）样本报送服务平台所提供的接口数据服务器根据请求数据产生相应的反馈数据，并结束本次报送流程。
爱似样本报送者
5.4接口消息
5.4.1接口请求消息
移动互联网恶意程序疑似样本报送接口请求消息
移动互联网恶意程序疑似样本报送接口反馈消息
样本报送服务平台
接收/处理疑似
图2移动互联网恶意程序疑似样本报送接口流程图请求消息的数据主要包含3个主要组成部分：基本信息数据、样本文件数据、样本分析报告数据。其中样本分析报告数据段为可选部分。请求消息使用POST方式进行提交，在消息报头中指定\Content-Type”为“multipart/form-data”，在请求正文中存放请求消息的参数数据，使用multipart/form-data方式进行数据段分隔。
其示例可以参见附录A，其基本结构定义见表1。表1报送接口数据段定义
字段名称
basicinfo
report
可选性bZxz.net
数据类型
String
String
String
描述样本的基本信息
疑似样本程序数据
疑似样本分析报告数据
iiikAoNiKAca
YD/T2849-2015
5.4.2基本信息数据
数据段名称为“basicinfo”，其内容为JSON文本的字符串格式，文本采用UTF-8编码（具体实现中，例如PHP中使用jsonencode函数进行编码，Python中使用json.dumps，其他语言可参考IETFRFC4627）。PHP语言可参见附录A.1编写相关报送程序。详细参数及描述见表2。
表2基本信息数据段请求参数表
字段名称
action
firsttime
virusname
behavior
behavior_net
behavior_local
controlserven
malurl
version
callback
5.4.2.1样本文件数据段
可选性
数据类型
String
String
String
String
String
String
String
String
String
String
String
String
接口消息名称，本接口为“cncert_submit_sample\请求者密钥，用于确认请求者身份，防止请求者仿冒，该字段内容由国家互联网应急技术处理协调组织提供给请求者。详情见附录B
样本的MD5，全文使用大写
请求者首次发现该样本的时间，使用\nnnn-mm-ddhh:mm:ss\形式，对应表示“年-月-日时：分：秒”恶意程序建议名称，使用YD/T2439“移动互联网恶意程序描述格式”定义的标准名称
建议危害等级，分为3级：分别为“1”，“2”，“3”。其中1级为轻危等级，2级为中危等级，3级为高危等级典型行为，用于请求者描述该样本典型行为，采用UTF-8编码网络行为，用于描述该样本的网络行为，采用UTF-8编码本地行为，用于描述该样本的本地行为，采用UTF-8编码控制域名或IP，用于请求者提交该样本的控制域或控制IP，如果有多个，使用分号（;）进行分隔，采用UTF-8编码恶意程序请求URL，用于请求者提交该样本的恶意请求URL，如果有多个，使用分号（;）进行分隔，采用UTF-8编码接口版本，默认为1.0，用于协商接口版本，用于以后扩展，默认版本为1.0
接收反馈结果的回调URL地址，系统会自动将将结果反馈到此接口，关于回调接口的详细定义见5.4.4“结果反馈回调接口”数据段名称为“file”，文件上传基于IETFRFC1867，“name”指定为“file”，“filename”指定为文件原始名，在数据部分为样本文件数据。文件名应使用UTF-8编码。5.4.2.2样本分析报告数据段
数据段字段名称为“report”，文件上传基于IETFRFC1867，“name”指定为“report”，可以通过数组形式上传多个分析报告文件，但名称应以样本MD5.***格式命名，在数据载荷部分为样本分析报告文件数据。文件名应使用UTF-8编码。5.4.3接口反馈消息
接口反馈消息其内容为JSON文本的字符串格式，文本采用UTF-8编码。具体参数形式见表3。TiikANnikAca
字段名称
result
errorinfo
virusname
submitid
5.4.4结果反馈回调接口
可选性
表3基本信息数据段请求参数表
数据类型
String
String
String
请求情况：
0表示请求成功：
1表示请求错误
当请求参数错误时，返回错误指示信息。result-1时，会返回如下几种信息：1）接口名称错误：
2）身份认证失败；
3）文件未上传：
4）上传的文件为空：
5）文件的md5值校验失败：
6）firsttime值为空
报送的恶意代码数据的当前状态：0表示“样本尚未确认”：
1表示“该样本为白样本”；
2表示“该样本为黑样本”
YD/T2849-2015
用于描述恶意代码名称，state-2时必选，返回YD/T2439定义的标准名称
报送ID，state-0时必选，返回用户可以通过该报送ID，查询样本的报送情况
疑似样本报送方在报送样本时，可以提供按照本标准中定义实现的回调接口地址。在完成疑似样本的判定工作后，报送服务平台会将相关结果采用异步消息方式反馈至回调接口。PHP语言可参见附录A.3编写相关报送程序。反馈的数据基本结构见表4。
表4Callback反馈结果数据段定义序号
字段名称
result
可选性
数据类型
String
String
JSON格式的结果基本信息，与主动查询到的信息字段相同便于报送者进行安全校验，详情见附录B结果反馈回调接口的消息result内容为JSON文本的字符申格式，文本采用UTF-8编码。具体参数形式见表5。
表5callback反馈结果参数表
字段名称
virusname
submit_id
可选性
数据类型
String
String
String
样本的MD5，全文使用大写
报送的恶意代码数据的当前状态：0表示“样本尚未确认”：
1表示“该样本为白样本”；
2表示“该样本为黑样本”
state-2时必选，返回YD/T2439
用于描述恶意代码名称，
定义的标准名称
报送ID，state-0时必选，返回用户可以通过该报送ID，查询样本的报送情况
HiiKAoiKAca
YD/T2849-2015
6移动互联网恶意程序疑似样本报送结果查询接口6.1接口描述
供各地互联网应急协调组织、运营商、安全厂商、研究机构或个人查询已经向国家互联网应急技术处理协调组织提交的样本的审核结果，通过查询ID获取报送样本处理的状态信息和处理结果信息本接口的名称为“cncert_result_query”。6.2接口协议
系统数据的交互接口使用HTTPS协议，使用POST方式提交数据。接口定义遵循IETFRFC2818、IETFRFC4627。接口消息会以JSON文档的格式通过HTTPS协议传输。6.3接口流程
此流程完成移动互联网恶意代码疑似样本报送结果的查询，其流程如下，具体如图3所示。a）疑似样本报送者根据本标准的要求和约定按照指定的数据结构构造查询请求，并调用本接口。b）样本报送服务平台所提供的接口数据服务器根据请求数据产生相应的反馈数据，并结束本次查询流程
疑似样本报送者
移动互联网恶意程序疑似样本报送结果查询接口请求消息
移动互联网恶意程序疑似样本报送结果查询接口一反馈消息
样本报送服务平台
接收/处理状态
结果信息
图3移动互联网恶意程序疑似样本报送结果查询接口流程图对于部分报送请求，其处理结果难以实时生成，因此会导致一定的延时。对于此类报送任务，疑似样本报送者可以通过自已的报送身份密钥，和疑似样本报送接口返回的“submitid”来访问本接口查询最新的数据结果。约定可以通过对疑似样本报送结果查询接口进行固定频率的轮询访问来进行报送结果信息的同步和获取。轮训访问的周期时间不得快于5min。疑似样本报送者，还可以提供结果反馈回调URL接口，按照本标准中定义的回调接口进行参数解析和实现。在系统完成判定后，会自动将结果发送至指定的回调URL接口。6.4接口消息
6.4.1接口请求消息
请求消息采用HTTPS协议，使用POST方式进行提交，在消息的请求正文部分存放请求消息的参数数据。其采用JSON文本，UTF-8编码。详细参数及描述见表6。PHP语言可参见附录A.2编写相关报送程序。表6查询接口请求参数表
字段名称
action
submitid
version
可选性
数据类型
String
String
String
String
接口消息名称，本接口为“cncertresultquery”请求者API密钥，请求者密钥，用于确认请求者身份，防止请求者仿冒，该字段内容由国家互联网应急技术处理协调组织提供给请求者。详情见附录B需要查询的“报送ID”
接口版本，默认为1.0，用于协商接口版本，用于以后扩展，默认版本为1.0
HiiKAoNiKAca
6.4.2接口反馈消息
接口反馈消息其内容为JSON文本，文本采用UTF-8编码。具体参数形式见表7。表7
字段名称
result
errorinfo
virusname
可选性
查询接口返回结果参数表
数据类型
String
String
移动互联网恶意程序样本传播源报送接口接口描述
YD/T2849-2015
请求情况，0表示请求成功，1表示请求错误当请求参数错误时，返回错误指示信息。中文使用UTF-8编码
报送的恶意代码数据的当前状态，0表示“样本尚未确认”，1表示“该样本为白样本”，2表示“该样本为黑样本”
用于描述恶意代码名称，state=2时必选，返回YD/T2439定义的标准名称
供各地互联网应急协调组织、运营商、安全厂商、研究机构或个人根据时间段向样本报送服务平台上报恶意程序的传播源。
本接口的名称为“cncert submitspread”。7.2接口协议
系统数据的交互接口使用HTTPS协议，使用GET方式提交数据。接口定义遵循IETFRFC2818、IETFRFC4627。接口消息会以JSON文档的格式通过HTTPS协议传输。7.3接口流程
此流程完成已经审核确认的移动互联网恶意程序查询，其流程如下，具体如图4所示。a）报送者根据本标准的要求和约定按照指定的数据结构构造查询请求，并调用本接口。b）样本报送服务平台所提供的接口数据服务器根据请求数据产生相应的反馈数据，并结束本次查询流程。
聚似样本报送者
7.4接口消息
7.4.1接口请求消息
移动互联网恶意程序样本传播源报送接口请求消息
移动互联网恶意程序样本传播源报送接口反馈消息
样本报送服务平台
接收/处理恶意
程序传播源
图4移动互联网恶意程序样本传播源报送接口流程图请求消息采用HTTPS协议，使用POST方式进行提交，在消息的请求正文部分存放请求消息的参数数据。其采用JSON文本，UTF-8编码。详细参数及描述见表8。7
YD/T2849-2015
字段名称
Action
spread
version
7.4.2接口反馈消息
可选性
表8样本库查询接口请求参数表
数据类型
String
String
String
接口消息名称，本接口为“cncert_submit_spread”请求者API密钥，请求者密钥，用于确认请求者身份，防止请求者仿冒，该字段内容由国家互联网应急技术处理协调组织提供给请求者。详情见附录B二维数组，例如[url:下载地址,md5:样本MD5],[url:下载地址2,md5:样本MD5]]。包含不超过100条传播源信息，MD5不一定是报送者自己上报的样本，只要国家互联网应急技术处理协调组织公开的黑样本即可接口版本，默认为1.0，用于协商接口版本，用于以后扩展，默认版本为1.0
接口反馈消息其内容为JSON文本，文本采用UTF-8编码。具体参数形式见表9。表9传播源上报接口返回结果参数表序号
字段名称
result
errorinfo
可选性
数据类型
String
8移动互联网恶意程序疑似样本报送信息查询接口8.1接口描述
请求情况：
0表示请求成功
1表示请求错误
当请求参数错误时，返回错误指示信息。中文使用UTF-8编码
供各地互联网应急协调组织、运营商、安全厂商、研究机构或个人查询报送账号基本信息，包括各地互联网应急协调组织、运营商、安全厂商、研究机构或个人基本信息、报送样本统计信息、报送平台样本统计信息、CNCERT/CC样本报送服务平台样本统计信息等。本接口的名称为“cncertinfo_query”。8.2接口协议
系统数据的交互接口使用HTTPS协议，使用POST方式提交数据。接口定义遵循IETFRFC2818、IETFRFC4627。接口消息会以JSON文档的格式通过HTTPS协议传输。8.3接口流程
此流程完成疑似样本报送者基本信息的查询，其流程如下，具体如图5所示。a）疑似样本报送者根据本标准的要求和约定按照指定的数据结构构造查询请求，并调用本接口。b）样本报送服务平台所提供的接口数据服务器根据请求数据产生相应的反馈数据，并结束本次查询流程。
8.4接口消息
疑似样本报送者
移动互联网恶意程序疑似样本报送信息查询接口请求消息
移动互联网恶意程序疑似样本报送信息查询接口反馈消息
样本报送服务平台
图5移动互联网恶意程序疑似样本报送信息查询接口流程图8.4.1接口请求消息
YD/T2849-2015
查询基本/
统计信息
请求消息采用HTTPS协议，使用POST方式进行提交，在消息的请求正文部分存放请求消息的参数数据。其采用JSON文本，UTF-8编码。讠详细参数及描述见表10。
表10查询接口请求参数表
字段名称
Action
Version
接口反馈消息
可选性
数据类型
String
String
String
接口消息名称，本接口为“cncertinfo_query”请求者API密钥，请求者密钥，用于确认请求者身份，防止请求者仿冒，该字段内容由国家互联网应急技术处理协调组织提供给请求者。详情见附录B
接口版本，默认为1.0，用于协商接口版本，用于以后扩展，默认版本为1.0
接口反馈消息内容为JSON文本，文本采用UTF-8编码。具体参数形式见表11。查询接口返回结果参数表
字段名称
result
errorinfo
submitter_name
submitter_all
submitter_distinct
submitter_black
platform_all
platform_black
cncert all
cncert black
可选性
数据类型
String
String
移动互联网恶意程序样本库查询接口接口描述
请求情况，0表示请求成功，1表示请求错误当请求参数错误时，返回错误指示信息。中文使用UTF-8编码报送者单位名称
查询者报送样本的总数
查询者报送样本按照MD5去重后的数量查询者报送样本中被确认为黑样本的个数（已按MD5去重）按操作系统平台分类统计样本的个数（已按MD5去重）按操作系统平台分类统计黑样本的个数（已按MD5去重）样本报送服务平台捕获的样本总数（已按MD5去重）样本服务平台捕获的黑样本总数（已按MD5去重）供各地互联网应急协调组织、运营商、安全厂商、研究机构或个人根据时间段向样本报送服务平台查询已经审核确认的移动互联网恶意程序，本接口可以按时间段批量查询样本处理结果信息，该接口需要样本报送服务平授权后方可使用。9
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。