File/URL submission

The URL below is to upload a file/web URL for dynamic analysis by using the provided Analyzer Profile. Only single file/web URL can be submitted at a time.

Resource URL

POST https://<MATD_IP>/php/fileupload.php

The following HTTP headers should be specified in the resource URL request:

  • Accept: application/vnd.ve.v1.0+json
  • VE-SDK-API: Base64 encoded "session:user id" string
Note: You can specify an optional Expect: parameter in the HTTP header.
Note: You can specify an optional skipTaskId: (string - 1 or 0) in REST API. The performance of McAfee Advanced Threat Defense improves for version 1.5.0 and above, as REST client adds the new optional request parameter: 'skipTaskId': '1'. If endpoint products use 'skipTaskId':'1', API returns the JSON response with taskId -1 along with actual Job Id, without waiting for the taskId from AMAS.
Note: Endpoint products need to use 64-bit integer instead of 32-bit for taskId.

Input parameters

Input parameter Description
amas_filename

The name of the sample file.

This parameter is optional for URL submissions.

data Contains the following parameters defined in a json string.
  • vmProfileList: Analyzer profile ID. The profile ID number can be found in the UI Policy/Analyzer Profile page.
  • submitType: This parameter accepts four values — '0', '1', '2' and '3'.
    • 0 — Regular file upload
    • 1 — URL submission — URL link is processed inside analyzer VM
    • 2 — Submit file with URL
    • 3 — URL Download — File from URL is firstly downloaded and then analyzed
  • url: Any valid web URL.
  • messageId: (Optional) Maximum 128-character string.
  • srcIp: (Optional) IPv4 address of the source system or gateway from where the file is downloaded.
  • destIp: (Optional) IPv4 address of the target endpoint.
  • skipTaskId: Optional parameter with values either 0 or 1.
    Note: Value '0' indicates corresponding taskid in API response. Value '1' indicates -1 as taskid in API response.
  • analyzeAgain: Optional parameter with values either 0 or 1.
    Note: Value '0' indicates skip sample analysis if it is analyzed previously . Value '1' indicates do not skip sample analysis if it is not analyzed previously.
  • xMode: Optional parameter with values either 0 or 1.
    Note: Value '0' indicates no user interaction is needed during sample analysis. Value '1' indicates user interaction is needed during sample analysis.
  • filePriorityQ: Optional parameter with values either run_now or add_to_q. This parameter indicates priority of sample analysis. run_now assigns highest priority (i.e., sample is analyzed right away), add_to_q puts sample in waiting state if there is a waiting queue of samples.

For submitType ‘2’, we submit the file and also the URL from which the file is downloaded. McAfee GTI URL look up is done on the submitted URL in addition to file analysis.

Examples:

{'data': '{"data":{"xMode":0,"overrideOS": 1,"messageId":"","vmProfileList":"12","submitType":"0","url":""}, "filePriorityQ":"run_now" }'}

{'data': '{"data":{"vmProfileList":"1","messageId":"04788b1b-8dbe-4dd3-94cb-a129552af5de","submitType":1,"url":"http://www.google.com/news"}, "filePriorityQ":"run_now" }’}

{'data': '{"data":{"vmProfileList":"1","messageId":"03188b1b-8dbe-a4a3-94cb-a129552af5ee","submitType":2,"url":"http://the.earth.li/~sgtatham/putty/latest/"}, "filePriorityQ":"add_to_q" }’}

{'data': '{"data":{"vmProfileList":"11","messageId":"06488b1b-8dbe-a4c3-94cb-a129552af5dd","submitType":3,"url":"http://www.javascriptenlightenment.com/JavaScript_Enlightenment.pdf"}, "filePriorityQ":"run_now" }’}

Output parameters

Output parameter Description
Results Contains json data with following parameters.

md5: MD 5 hash value of the submitted sample.

sha1: SHA 1 hash value of the submitted sample.

sha256: SHA 256 hash value of the submitted sample.

subId: JobId assigned for the sample.

taskId: Assigned for the submitted sample. taskId is -1 for a zip file and has the same value (-1), in case skipTaskId is enabled.

messageId: String that is sent in the request to identify the sample.

filesWait: Number of samples in waiting state.

estimatedTime: Estimated time for the analysis to finish on the submitted sample.

Example

submitType:0

Input

An example of data json string:
{'data': '{"data":{"xMode":0,"overrideOS":1,"messageId":"","vmProfileList":"11","submitType":"0","url":""}, "filePriorityQ":"run_now" }'}

Client sends the input stream of sample to the fileupload.php. An example in Python:

postdata = {'data': '{"data":{"xMode":0,"overrideOS":
1,"messageId":"","vmProfileList":"11","submitType":"0","url":""}, "filePriorityQ":"run_now" }'}
file_up = {'amas_filename':open('/home/samples/temp/vtest32.exe','r')}
file_upload_req =requests.post(url,postdata,files=file_up,headers=headers,verify=False)

Output

{"success":true,"subId": ,"mimeType": "", "fileId": "","filesWait": 0,"estimatedTime": 0,"results": [{"taskId": ,"messageId": "","file": "","submitType": "0","url": "","destIp": null,"srcIp": "","md5": "","sha1": "","sha256": "","size": "", "cache":}]}

submitType:1

Input

An example of data json string:
{'data': '{"data":{"xMode":0,"overrideOS":
1,"messageId":"","vmProfileList":"11","submitType":"1","url":"http://www.yahoo.com"}}'}

Client sends the input stream of sample to the fileupload.php. An example in Python:

postdata = {'data': '{"data":{"xMode":0,"overrideOS":
1,"messageId":"","vmProfileList":"12","submitType":"1","url":"http://news.google.co.in/"}}'}
upload_rest_req = requests.post(url,postdata,headers=headers,verify=False)

Output

{"success": true,"subId": 17,"mimeType": "text\/plain","filesWait": 1,"estimatedTime":
88,"results": [{"taskId": 23,"messageId": "","file": "URL1419314922.url","submitType":
1,"url": "http: \/\/news.google.co.in\/","destIp": null,"srcIp": null,"md5":
"839f551f97e669dddb348bddb907d32c","sha1": "D9C1CB1FCD53530212317800CC1B935657042CDF","sha256": "9A33B63558EE78AFA9A4DFD063B6B118ADFC455E20C2752B7F7977F88C2361CD","size": 25}]}

submitType:2

Input

An example of data json string:
{'data': '{"data":{"vmProfileList":"1","messageId":"06488b1b-8dbe-a4c3-94cb-a129552af5dd","submitType":2,"url":"http://the.earth.li/~sgtatham/putty/latest/x86/"}’}
Client sends the input stream of sample to the fileupload.php. An example in Python:
postdata = {'data': '{"data":{"xMode":0,"overrideOS":
1,"messageId":"","vmProfileList":"12","submitType":"2","url":"http://the.earth.li/~sgtatham/
putty/latest/x86/"}}'}
file_up = {'amas_filename':open('/home/samples/vtest32.exe','r')}
upload_rest_req = requests.post(url,postdata,files=file_up,headers=headers,verify=False)

Output

{"success": true,"subId": 16,"mimeType": "application\/x-dosexec","filesWait":
1,"estimatedTime": 77,"results": [{"taskId": 22,"messageId": "","file":
"vtest32.exe","submitType": 2,"url": "http://the.earth.li/~sgtatham/putty/latest/
x86/","destIp": null,"srcIp": null,"md5": "e2cfe1c89703352c42763e4b458fc356","sha1": "D9C1CB1FCD53530212317800CC1B935657042CDF","sha256": "9A33B63558EE78AFA9A4DFD063B6B118ADFC455E20C2752B7F7977F88C2361CD","size":45056}]}

submitType:3

Input

An example of data json string:
{'data': '{"data":{"xMode":0,"overrideOS":1,"messageId":"","vmProfileList":"11","submitType":"3","url":"http://10.213.248.238/Automation/vtest32.exe"}}'}

Output

{"success": true,"subId": 210,"mimeType": "text\/plain","filesWait": 1,"estimatedTime":
68,"results": [{"taskId": -1,"file": "URL1418981249.url","md5":
"67b32fa8adaa0ae9025920c775615b96","sha1": "D9C1CB1FCD53530212317800CC1B935657042CDF","sha256": "9A33B63558EE78AFA9A4DFD063B6B118ADFC455E20C2752B7F7977F88C2361CD","size": "44"}]}

Note: If skip analysis feature is enabled and a previously analyzed file has been submitted, then the API response is as follows.
{"success": true, "subId": 28, "mimeType": "application/x-dosexec", "filesWait": 0,
"estimatedTime": 0, "results": [ {"taskId": 28, "file": "File was previously analyzed -
(vtest32.exe )", "md5": "E2CFE1C89703352C42763E4B458FC356","sha1": "D9C1CB1FCD53530212317800CC1B935657042CDF","sha256": "9A33B63558EE78AFA9A4DFD063B6B118ADFC455E20C2752B7F7977F88C2361CD","size": 45056} ]}