Returns reports on selected alerts by specifying the alert's id or by specifying the infection_id and infection_type.
Availability
This command is available on the following appliances:
Central Management System
Malware Analysis
Email Security — Server
File Protect
Network Security
The following syntax can be used to request a report:
Report request using the ID
GET https://<address>/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&&infection_id=<infectionID>& infection_type=<infectionType>
Header:
X-FeApi-Token: [API-Token] X-FeClient-Token: [Client-Token]
Options
address—This is 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.
Report Type—Specify the report type using the
report_typeoption and the output type using thetypeoption:
Report | report_type | type |
|---|---|---|
Alert Details Report | alertDetailsReport |
Infection ID and Infection Type (Optional)—Use the combination of
infection_idandinfection_typeoptions to specify a unique alert to describe in the Alert Details Report. If one option is used alone and does not specify a unique alert, an error message is produced. The following infection types are supported:malware-object
ID (Optional)—The
idoption is an alternative to theinfection_idandinfection_typeoptions. Specify a unique alert using the internal database unique ID of the alert record.
Example requests
https://<address>/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&infection_id=8351&infection_type=malware-object
https://<address>/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&id=1664
cURL code sample: finding the infection type and infection ID
To obtain the infection type and infection ID of an alert, submit an alert request. An alert request returns the infection type and infection ID of all alerts that match your filters.
The following code sample can be copied and executed from any command-line interface that includes the cURL library.
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" https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&infection_id=8351&infection_type=malware-object
This cURL sample includes the following options:
-q—This option specifies that thecurlrcconfig 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-soption, 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--headerswitch.--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 provides the API-Token that was returned during the authentication request. In the authentication cURL code sample, this token was included in theauth.txtfile. Replace the token value in the code sample with the token value received in the response to your authentication request.Note
By default, the
X-FeApi-Tokentimes out after 15 minutes of inactivity.
https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&infection_id=8351&infection_type=malware-object—The report request. Replace the IP addressxxx.xxx.xxx.xxxwith the IP address of your appliance. In this example, the?report_type=alertDetailsReport&infection_id=8351&infection_type=malware-objectfilter specifies the infection ID and type.
Results
The infection type and infection ID of all alerts that match your filters are returned.
Alert ID response
Look for the line with alert id="8351" name="malware-object" in the following example to find the infection ID and the infection type.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alerts appliance="MAS" version="MAS (MAS) 7.7.0.406866" msg="concise" xmlns:ns2=
"http://www.fireeye.com/alert/2013/AlertSchema">
<ns2:alert id="8351" name="malware-object" severity="minr" product=MAS">
<ns2:explanation>
<ns2:malware-detected>
<ns2:malware name="Trojan.Downloader">
<ns2:md5sum>2c72f5572741eab4d47afa5d3575b7b8</ns2:md5sum>
</ns2:malware>
</ns2:malware-detected>
</ns2:explanation>
<ns2:src>
<ns2:ip>xxx.xxx.xxx.xxx</ns2:ip>
</ns2:src>
<ns2:alert-url>https://localhost:8080/botnets/events_for_bot?ma_id=8351</ns2:alert-url>
<ns2:action>notified</ns2:action>
<ns2:occurred>2014-08-06T18:00:44.467Z</ns2:occurred>
<ns2:dst>
<ns2:port>123</ns2:port>
<ns2:ip>xxx.xxx.xxx.xxx</ns2:ip>
</ns2:dst>
</ns2:alert>
</alerts>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 encountered a problem.
Response Message—A standard HTML response message.
OK—Request successful.
Bad Request—Request unsuccessful because the filter value was invalid.
Internal Server Error—Request unsuccessful because the server encountered a problem.
cURL code sample: generating a report for a unique alert
Use the infection ID and infection type in a report request to get details about a specific alert.
The following code sample can be copied and executed from any command-line interface that includes the cURL library.
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" "https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/reports/ report?report_type=alertDetailsReport&infection_id=8351&infection_type=malware-object"
This cURL sample includes the following options:
-q—This option specifies that thecurlrcconfig 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-soption, 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--headerswitch.--no-progress-bar—This option suppresses the cURL download progress bar. This progress bar can interfere with the request.--header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"—This custom header provides the API-Token that was returned during the authentication request. In the authentication cURL code sample, this token was included in theauth.txtfile. Replace the token value in the code sample with the token value received in response to your authentication request.Note
By default, the
X-FeApi-Tokentimes out after 15 minutes of inactivity.
"https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&infection_id=8351&infection_type=malware-object"—The report request URL. Replace the IP addressxxx.xxx.xxx.xxxwith the IP address of your appliance. The generated Alert Details Report will provide details of a malware object with an infection ID of8351.
Results
The requested report is returned inline as unformatted data. You need to redirect the output to a PDF file to see a formatted version.
cURL code sample: specifying the location of the generated report
The following code sample can be copied and executed from any command-line interface that includes the cURL library.
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 -qgsSk --no-progress-bar --header "Accept: application/pdf" --header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" "https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/reports/ report?report_type=alertDetailsReport&infection_id=6713675&infection_type=malware-object" -o ./results_pdf/wso.report.6713675.pdf
This cURL sample includes the following options:
-q—This option specifies that thecurlrcconfig 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-soption, 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.--no-progress-bar—This option suppresses the cURL download progress bar. This progress bar can interfere with the request.--header "Accept: application/pdf"—This option specifies a PDF version of the report.--header "X-FeApi-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"—This custom header provides the API-Token that was returned during the authentication request. In the authentication cURL code sample, this token was included in theauth.txtfile. Replace the token value in the code sample with the token value received in the response to your authentication request.Note
By default, the
X-FeApi-Tokentimes out after 15 minutes of inactivity.
"https://xxx.xxx.xxx.xxx:443/wsapis/v1.2.0/reports/report?report_type=alertDetailsReport&infection_id=6713675&infection_type=malware-object"—The report request URL. Replace the IP addressxxx.xxx.xxx.xxxwith the IP address of your appliance. The generated Alert Details Report will provide details of a malware object with an infection ID of6713675.-o—This option redirects the output to a file../results_pdf/wso.report.6713675.pdf—This path specifies where the generated report will be saved.
Results
The requested report is saved to the specified path.