--- title: "Submit malware object request" slug: "submit-malware-object-request" tags: ["Reference"] updated: 2026-09-03T18:40:47Z published: 2026-09-03T18:40:47Z canonical: "docs.trellix.com/submit-malware-object-request" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.trellix.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit malware object request Uploads a single file for scanning. Central Management System and Malware Analysis: ``` POST https://
/wsapis/[v2.0.0]/submissions ``` 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] ``` Request Body: ``` MIME Type application/json MalwareFile1.zip ``` ### 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. - 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 Malware Analysis and Central Management System: The JSON-formatted attachment should include the following values: ``` { \"application\":\"value\", \"timeout\":\"value\", \"priority\":\"value\", \"profiles\":\"value\", \"analysistype\":\"value\", \"force\":\"value\", \"prefetch\":\"value\" } ``` | `application` | 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](/docs/configuration-information-request). ### Note For Malware Analysis appliances (7.7 and higher) and Central Management System appliances that manage Malware Analysis appliances (7.7 and higher), setting the application value to `–1` allows the Malware Analysis appliance to choose the application for you. For other appliances, setting the application value to `0` allows the Malware Analysis appliance to choose the application for you. | | --- | --- | | `timeout` | Sets the analysis timeout (in seconds). | | `priority` | Sets the analysis priority: (default: Normal) - `0`—Normal: adds analysis to the bottom of queue. - `1`—Urgent: places the analysis at the top of the queue. | | `profiles` | 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](/docs/configuration-information-request). | | `analysistype` | Specifies the analysis mode. - `1`—Live: analyze suspected files live within the Malware Analysis Multi-Vector Virtual Execution (MVX) analysis engine. - `2`—Sandbox: analyze suspected files in a closed, protected environment. | | `force` | Specifies whether to perform an analysis on the file even if the file exactly matches an analysis that has already been performed. In most cases, it is not necessary to reanalyze malware. (default: `false`) - `false`—Do not analyze duplicate files. - `true`—Force analysis | | `prefetch` | Specifies whether to determine the file target based on an internal determination rather than browsing to the target location. - `0`—No - `1`—Yes. If `analysistype` is set to `2` for sandbox analysis, `prefetch` must be set to 1. | | `enable_vnc` | Optional. Specifies whether to enable VNC while making a submission on an Malware Analysis appliance. Default: false. (v2.0.0 only). | | `properties` | Optional. Specifies additional context about the submission on an Malware Analysis appliance. This context is then sent to Guest Images. The following fields are defined: - `application_context`—Meta information about the application including but not limited to: - arguments - file name - file path - parent path - file owner/creator - permissions - `guest_config`—Guest images configuration. - `artifact_extract_config`—Artifact extraction parameters. | ### Example request for a single file (Malware Analysis) ``` POST https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions ``` Request headers: ``` X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx X-FeClient-Token: BigDataInc ``` Request Body: ``` MIME Type application/json ``` `{"analysistype":"1", "priority":"0", "profiles":["win7-sp1"], "force":"true", "application":"69", "prefetch":"0", ``"timeout":"500", ``"enable_vnc":"true", "application_context": {"file_name":"xyz.pdf"}} MalwareFile1.exe` ### Example request for multiple files using a zip file `POST https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions ` Request headers: ``` X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx X-FeClient-Token: BigDataInc ``` Request body: `<!-- Request File Set 1 -->` `MIME Type application/json ` `{"analysisType":"1", "priority":"0", "profiles":["win7-sp1"], "force":"true","application":"69", "prefetch":"0", ``"timeout":"500"} `` MalwareFile1.zip` ### 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 file submitted 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—Central Management System: ``` [{"ID":"3831_5"}] ``` Body—Intelligent Virtual Execution - Server: ``` {"uuid":"57ee22a2-0ae2-44df-a8a4-a5fef41881cc","brokerId":"0CC47A39D7D0"} ``` Body—Malware Analysis: ``` [ { "ID":"347", "submission_details":"[{"vnc_port":[],"id":347,"uuid":"31d31602-39c0-4e6a-b60b-b98290f5f609"}]" } ] ``` ### 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. Malware Analysis and Central Management System: ``` curl -qgsSkH "Content-Type: multipart/form-data" --no-progress-bar --header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -F "filename=@cygdrive/c/tmp/test.txt" -F "options={\"application\":\"2\",\"timeout\":\"500\",\"priority\":\"0\", \"profiles\":[\"win7-sp1\"],\"analysistype\":\"1\",\"force\":\"true\", \"prefetch\":\"0\", \"properties\":{\"application_context\":{\"file_name\":\"xyz.pdf\"}}}" https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions ``` Intelligent Virtual Execution - Server only: ``` curl -qgsSkH "Content-Type: multipart/form-data" --no-progress-bar --header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -F "filename=@cygdrive/c/tmp/test.txt" -F "options={\"application\":\"2\",\"profiles\":[\"win7-sp1\"],\"analysistype\":\"2\",\"force\":\"true\",\"prefetch\":\"0\",\"password\":\"test\"}" https://xxx.xxx.xxx.xxx:443/wsapis/mvx/v2.0.0/submissions ``` 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. - `-F "filename=@cygdrive/c/tmp/test.txt`—This option includes the `test.txt` file as an attachment to the message body. ### Note This example assumes you are using a Windows PC and referencing the following file name and location: `C:/tmp/test.txt`. The file location `cygdrive/c/tmp/test.txt` is the Cygwin-defined POSIX-equivalent location and file. - -`F "options={\"timeout\":\"500\"}`"—This option defines the submission parameters for the first file. For more information, see [Submission options](/network-and-platform/docs/submit-malware-object-request#UUID-0d145907-30d5-b860-db84-6edbba0c1a0d_id_submissi). - `https://xxx.xxx.xxx.xxx:443/wsapis/v2.0.0/submissions`—The submission request URL. Replace the IP address `xxx.xxx.xxx.xxx` with the IP address of your appliance. - VX Series: `https://xxx.xxx.xxx.xxx:443/wsapis/mvx/v2.0.0/submissions`—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. :