POST https://<address>/wsapis/[v1.2.0|v2.0.0]/submissions/url
Availability
This command is available on the following appliances:
Central Management System
Malware Analysis
Required headers:
X-FeApi-Token: [API-Token] X-FeClient-Token: [Client-Token]
Body:
MIME Type application/json
Options
address—The IP address of the appliance running the Web Services API.
API-Token—This token authenticates the session. By default, the session times out after 15 minutes of inactivity.
Client-Token—(Optional) This client token is provided by Trellix. For more information about the client token, contact your sales representative.
Submission options
These options are added as the first part of a multipart MIME attachment to the body of the document. The options should be encoded as a JSON attachment.
Format
The JSON-formatted attachment should include the following values:
{\"timeout\":[value], \"priority\":[value], \"profiles\":[\"value\"], \"application\":[value], \"force\":[value], \"analysistype\":[value], \"prefetch\":[value], \"urls\":\"[value]\"}
| Sets the analysis timeout (in seconds). |
| Sets the analysis priority: (default: Normal)
|
| Selects the Malware Analysis profile to use for analysis. To determine the available profiles, use the Malware Analysis configuration request. For more information, see Configuration information request. |
| Specifies the ID of the application to be used for the analysis. To determine the available applications for a specific profile, use the Malware Analysis configuration request. For more information, see Configuration information request. NoteSetting the application value to 0 allows the Malware Analysis appliance to choose the application for you. |
| Specifies whether to perform an analysis on the URL even if the URL exactly matches an analysis that has already been performed. In most cases, it is not necessary to reanalyze the URLs. (default:
|
| Specifies the analysis mode.
|
| Specifies whether to determine the file target based on an internal determination rather than browsing to the target location.
|
| Specifies the URLs to submit for analysis. Separate the URLs with a comma. |
Example request
POST https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions/url
Request headers:
X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx X-FeClient-Token: BigDataInc
Request Body:
MIME Type application/json
{"timeout":200, "priority":1, "profiles":[ "win7-sp1","winxp-sp3"],
"application":2,"force":true,"analysistype":2,"prefetch":1,
"urls":["http://172.16.225.87/malsust/File_share/treasury65malware/
1134220120630 letter.pdf.xdp", "http://172.16.225.87/malsust/File_share/
treasury65malware/ContagioEncryptedXLS_D116C745FE94C202934EF49F59D19950.xls"]}Submit URL response
After the submission request is received, the managed appliance acknowledges the request and supplies the list ID. The list ID identifies the URLs submitted for analysis.
The list ID is in JSON format.
HTTP/1.1 [Response Code] [Response Message] Date: [Date]
Body:
[List_ID]
Response fields
Response Code—A standard HTML response code.
200—Request successful.
400—Request unsuccessful because the filter value was invalid.
500—Request unsuccessful because the server has encountered a problem; retry later.
Response Message—A standard HTML response message.
OK—Request successful.
Invalid Client Request—Request unsuccessful because the filter value was invalid.
Error trying to process submission—Request unsuccessful because the server has encountered a problem; retry later.
Date—Standard HTML date format.
List_ID—A JSON-formatted unique value that identifies the submitted URLs for subsequent status and retrieval requests.
Example
HTTP/1.1 200 OK Date: Fri, 17 Nov 2017 08:00:00 GMT
Body—Central Management System:
[{"id":"L135_5"}]Body—Intelligent Virtual Execution - Server:
[{"id":"473"}]cURL code sample: URL submission
The following code sample can be copied and executed from any command-line interface that includes the cURL library. This sample builds on the authentication cURL code sample.
Note
In this sample, line breaks are added for readability. Remove these line breaks before you paste the code sample into your command-line tool.
curl -k -H "Content-Type: application/json" --header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -d "{\"timeout\":200, \"priority\":1, \"profiles\":[\"win7-sp1\", \"application\":\"2\", \"force\":\"true\", \"analysistype\":\"2\", \"prefetch\":1, \"urls\":[\"http://xxx.xxx.xxx.xxx/stats/flashdata.php\"]}" "https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions/url"
This cURL sample includes the following options:
-k—This option explicitly allows cURL to perform insecure SSL connections and transfers. This allows you to test your SSL connection without installing a CA certificate.-H Content-Type: application/json—This custom header specifies that the response is in JSON format.--header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"—This custom header includes the API-Token that was returned by your appliance during the authentication request. In the authentication cURL code sample, this token was included in theauth.txtfile. Replace the token in the sample with the token received in the response to your authentication request.-d "{\"timeout\":200, \"priority\":1, \"profiles\":[\"win7-sp1\", \"application\":\"2\", \"force\":\"true\", \"analysistype\":\"2\", \"prefetch\":1, \"urls\":[\"http://xxx.xxx.xxx.xxx/stats/flashdata.php\"]}"—This set of options defines the submission parameters for the URL being submitted. For more information, see Submission options .
"https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions/url"—The submission request URL. Replace the IP addressxxx.xxx.xxx.xxxwith the IP address of your appliance.
Results
Central Management System:
{"response":[{"id":"L135_5","link":{"rel":"status","href":"/submissions/status/L135_5"}}]}
Managed appliances:
{"response":[{"id":"L473","link":{"rel":"status","href":"/submissions/status/L473"}}]}