AnalysisRequest

用 JSON 表示;按数据包列表、事务和分析引擎提供分析过程当前状态的内容。

响应是包含以下条目的字典:

  • transactionAnalysisStatus – 事务的列表,如下所述
  • reportId – 分析过程的标识符
  • name – 已分析数据包列表的名称
  • id – 已分析数据包列表的 ID

对于与数据包列表关联的每个事务,事务列表中都包含一个条目。

每个条目都是一个字典,包含事务 ID (id)、名称 (name) 和分析状态 (analysisStatusPerEngine)。

分析状态是一个字典,其键是分析引擎,值为 API 文档中指定的状态。

PUT

[基本地址]/shunra/api/analysis/request/{plid}

例如: http://localhost:8182/shunra/api/analysis/request/620984c9a31b4ef694a1ac47d61b6a7e

其中,"plid" 是 Extract Packet List 请求返回的数据包列表的唯一 ID。

正文

包含分析参数,例如端口、SSL 加密密钥和分析的仿真结果 (.ved 或 .pcap 文件) ID,还包含文件系统路径,因为系统不会永久保存 (保留) 文件。正文采用 JSON 格式:

{
"ports":"80, 8080",
"sslEncryptionKey":"172.30.2.31,443,http,C:\\keys\\secret.key",
"runResultHandle":"C:\\tmp\\Sample.ved"
}
		

响应包括每个事务、每个已安装分析引擎的当前分析状态以及用于标识分析参数的已生成分析报告 ID:

{
	"transactionAnalysisStatus":[{
		"analysisStatusPerEngine":{
			"networkmeasurements":"Started",
			"harExport":"Started",
			"generalWaterfall":"Started",
			"http":"Started",
			"iostats":"Started",
			"metrics":"Started",
			"best practices":"Started"
		},
		"name":"Undefined",
		"id":"ccb8713e522241c9a691c4ed1ce72d27"
	}],
	"reportId":"-561678026",
	"name":"Packet List 1",
	"id":"620984c9a31b4ef694a1ac47d61b6a7e"
}

可能的分析状态有:

public enum WorkStatus {

// 作业仍未启动、未在进行、未分析等

Idle(0),

// 作业 (如仿真或分析) 已启动

Started(1),

// 作业 (如仿真或分析) 已完成

Finished(2),

// 作业 (如分析) 失败

Failed(3);

}

备注: 用于推断分析过程是否完成的启发法是所有项的状态均为 Finished 或 Failed;否则表示分析作业池中的一些项尚未完成。

客户端应继续处理分析请求,直到分析过程完成。

返回

  • 200“正常”
  • 404“找不到”
  • 500“内部服务器错误”

代码示例

def analyze(inputfilepath, packetlist_id, settings={}):
	"""
	calls analysis on a given file (use settings to pass special analysis parameters such as port numbers and ssl keys)
	
	packetlist_id should be the id return by get_packetlists for a specific packet list.
	
	
	The response is a dictionary with the following entries:
		* transactionAnalysisStatus - a list of transactions as described below
		* reportId - an identifier for the analysis process
		* name - name of the analyzed packet list
		* id - id of the analyzed packet list
	
	The list of transactions contains an entry for each transaction assoicated with the packet list.
	Each entry is a dictionary, containing the transaction id (id), name (name) and analysis status (analysisStatusPerEngine).
	Analysis status is a dictionary whose keys are the analysis engine, and the values are their status as specified in the API documentation.
	
	>>> inputfilepath = os.path.join(SAMPLE_FOLDER, 'Sample.ved')
	>>> packetlists = get_packetlists(inputfilepath)
	>>> packetlist_id = packetlists['Packet List 1']
	>>> resp = start_analysis(inputfilepath, packetlist_id)['transactionAnalysisStatus']
	>>> len(resp) # only one tranasction is associated with this packet list
	1
	>> resp[0]['name']
	u'Undefined'
	>>> resp[0]['analysisStatusPerEngine']['http'] in ['Idle', 'Started', 'Finished', 'Failed']
	True
	"""
	params = dict(settings)
	params['runResultHandle'] = inputfilepath
	resp = put('/shunra/api/analysis/request/'+packetlist_id, params)
	return resp
	def get_report_id(inputfilepath, packetlist_id, settings={}):
	return analyze(inputfilepath, packetlist_id, settings)['reportId']
	
	def get_transactions(inputfilepath, packetlist_id, settings={}):
"""
	Gets all the transactions associated with a given packetlist.
	The result is a list of pairs, the first element of each pair is the transaction id, and the second is the transaction's name
	
	>>> inputfilepath = os.path.join(SAMPLE_FOLDER, 'Sample.ved')
	>>> packetlists = get_packetlists(inputfilepath)
	>>> packetlist_id = packetlists['Packet List 1']
	>>> result = get_transactions(inputfilepath, packetlist_id)
	>>> len(result) # only one transaction is associated with this packet list
	1
	>>> result[0][1]
	u'Undefined'
	"""
	return [(transaction['id'], transaction['name']) for transaction in analyze(inputfilepath, packetlist_id, settings)['transactionAnalysisStatus']]
	
	
	def start_analysis(inputfilepath, packetlist_id, settings={}):
"""
Starts analysis on a given file.
	
	The response is a list, with an entry for each transaction assoicated with the packet list.
	Each entry is a dictionary, containing the transaction id (id), name (name) and analysis status (analysisStatusPerEngine).
	Analysis status is a dictionary whose keys are the analysis engine, and the values are their status as specified in the API documentation.
	"""
	return analyze(inputfilepath, packetlist_id, settings)
	
def is_analysis_done(inputfilepath, packetlist_id, settings={}):
	"""
	Returns True if all the transactions associate with the given packet list were analyzed and their reports are ready to be fetched.
	"""
	resp = analyze(inputfilepath, packetlist_id, settings)['transactionAnalysisStatus']
	for transaction in resp:
	for engine_status in transaction['analysisStatusPerEngine'].values():
if engine_status in ['Idle','Started']:
return False
return True