Submit URL request for analysis

Uploads a single URL for scanning. This is supported from version 10.0.1 and later.

POST https://<address>/wsapis/mvx/v2.0.0/submissions/url

Required headers:

X-FeApi-Token: [API-Token]
X-FeClient-Token: [Client-Token]

Parameters

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.
(optional) Client-Token—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.

The JSON-formatted attachment should include the following values:

{
  \"priority\":\"value\",
  \"analysistype\":\"value\",
  \"force\":\"value\",
  \"prefetch\":\"value\",
  \"urls\":\"value\"
}

`priority`	Sets the analysis priority. The default value is normal low normal high urgent
`force`	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 malware. The default value is set to false. false — Do not analyze duplicate URL. true — Force analysis.
`analysistype`	Specifies the analysis mode. 1 — Live: analyze suspected URLs within the Malware Analysis Multi-Vector Virtual Execution (MVX) analysis engine. 2 — Sandbox: analyze suspected URLs in a closed, protected environment.
`prefetch`	Specifies whether to determine the URL target based on an internal determination instead of navigating to the target location. If you do not pass prefetch value in options field, this is set to true as a default value. false — No. true — Yes. If analysistype is set to 2 for sandbox analysis, prefetch must be set to true.
`url`	Specifies the URL to submit for analysis.

Example request

POST https://xxx.xxx.xxx.xxx/wsapis/mvx/v2.0.0/submissions/url

Request headers:

X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-FeClient-Token: BigDataInc

Request Body:

"{\"analysistype\":\"1\",\"prefetch\":\"true\",\"force\":\"true\",\"priority\":\"low\",\"url\":\"www.xxxx.com\"}"

Submission response

After the Central Management System appliance receives the submission request, it forwards the submission request to the managed appliance. The managed appliance acknowledges the request and supplies the submission key. The submission key identifies the unique URLsubmitted for analysis.

The submission key is in JSON format.

HTTP/1.1 [Response Code] [Response Message]
Date: [Date]

Body:

[Submission_Key]

Response fields

Response Code—A standard HTML response code.
- 200—Request successful.
- 400—Request unsuccessful because the filter value was invalid.
Response Message—A standard HTML response message.
- OK—Request successful.
- Bad Request—Request unsuccessful because the filter value was invalid.
Date—Standard HTML date format.
Submission_Key—A JSON-formatted unique submission key that identifies the submitted file for subsequent status and retrieval requests.

Example

HTTP/1.1 200 OK
Date: Fri, 17 Nov 2017 08:00:00 GMT

Body:

{"uuid":"57ee22a2-0ae2-44df-a8a4-a5fef41881cc","brokerId":"0CC47A39D7D0"}

cURL code sample: malware object 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 -qgsSkH 
--no-progress-bar
--header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

-H "Content-Type: application/json"
-d "{\"analysistype\":\"1\",\"prefetch\":\"true\",\"force\":\"true\",\"priority\":\"low\",\"url\":\"www.xxxx.com\"}"
https://xxx.xxx.xxx.xxx:443/wsapis/mvx/v2.0.0/submissions/url

This cURL sample includes the following options:

-q—This option specifies that the curlrc config file is not read or used. Although this is an optional setting, Trellix recommends that you include this option.
-g—This option turns off the URL globbing parser. Although this is an optional setting, Trellix recommends that you include this option.
-s—This option turns off the progress meter and error message. Although this is an optional setting, Trellix recommends that you include this option.
-S—When used with the -s option, this option shows error messages if your cURL switch fails. Although this is an optional setting, Trellix recommends that you include this option.
-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—This option allows you to specify a custom header with the --header switch.
Content-Type: multipart/form-data—This option encodes the data as a multipart form.
--no-progress-bar—This option suppresses the cURL download progress bar, which can interfere with the request.
--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 the auth.txt file. Replace the token in the sample with the token received in the response to your authentication request.
-d "{\"priority\":\"low\", \"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.
https://xxx.xxx.xxx.xxx:443/wsapis/mvx/v2.0.0/submissions/url — The submission request URL. Replace the IP address xxx.xxx.xxx.xxx with the IP address of your appliance.

Results

The requested submission returns a submission key. This key is used to retrieve status and test results.

Submission status by UUID

Reads the status of submissions for a given UUID.

API URL

GET "https://[host}/wsapis/mvx/v2.0.0/submissions/result/uuid?format=v2.0"

Sample curl request

curl -gsk -H "$c" "https://{host}/wsapis/mvx/v2.0.0/submissions/result/8eda82ed-5528-4cd4-bbdd-2144ffced38c?format=v2.0"

Parameters

uuid – UUID values

Response

HTTP OK with JSON, containing the array of status objects with UUID value:

{"uuid": "4fd13694-bd53-48c5-bd4c-61fd11f957bd","type": "url", "verdict": "NON-MALICIOUS", 
"status": "SUCCESS", "name": "www.xxxx.xom", "signature_name": "Binary.url", 
"sha256": "191347bfe55d0ca9a574db77bc8648275ce258461450e793528e0cc6d2dcf8f5",  
"submission_time": "2024-01-03T04:29:29.393108", "complete_time": "2024-01-03T04:29:58.160898", 
"submitter_name": "admin","compute_node": "fireeye-012231"}

Authentication

Standard WSAPI authentication.

Response mime type

application/json

Profile

The default profile is hard coded in case of url submission in java code as given below:

"os_id" –  68
"app_id" –  -1