Endpoints

If you are looking for the Detection On Demand API docs, you can find them here. Our API docs are all written in the OpenAPI 3.0.0 specification and include everything you need to start making requests to the API. In this section, you will find related information that supports the API doc. Generally, if you have a question beyond what the API doc shows, then you should find the answer here.

Files

Today the /files collection only allows a single operation: creating a new file with a POST to /files. You can send files to the Detection On Demand API, but please note that you cannot delete them.

Filesize Limitations

Currently, files of 100 MB or less are supported. Files greater than this size will be rejected with a 403 "Forbidden". It is not advisable to try and truncate a large file to make it fit within the file size limit because FireEye cannot guarantee the file is not malicious, since malware can be embedded anywhere in a file.

Supported File Extensions

The following is a comprehensive list of supported file extensions, with more being added as we see new attacks in the wild or based on customer feedback.

accdb(accde,accdt,accdr), rtf, mpkg, docm, gz(tar,tgz), jpeg, mp4, alz, mp3, lsp, sct, ps1, mach-o, xml, jar, ahk, wma, aspx, pptx(potm,ppam,pptxml,sldm,sldx,thmx,ppsx,pptm,ppsm,potx,odp,otp), mpg, docx(docm,dotm,dotx,odt,odm,ott), scf, daa, fas, woff(woff2), lurl, mov, lzh, xdp, gen, elf, bat(hta), qt, wsf, eml, fdf, au3, mht, xls(dqy,iqy,slk,xla,xlk,xll,xlm,xlshtml,xlthtml,xlw,xlt,odc,csv), xsl, pkg, settingcontent-ms, cmd(svg), hta, com1, htm(html,shtml,mht,mhtml), dylib, hlp, lnk, arj, rmi, ico, vcf, hwpx, dll, vcs, rb, 3gp, jtd(jtdc,jaw,jbw,jfw,jsw,jtt,jttc,jtw,juw,jvw), mhtml, reg, asp, pub, js(jse), asf, uue(xx,xxe), ace, midi(rmi), vbs(vbe,wsf), ashx, pdf(fdf,xfdf,xdp,pdx,acrobatsecuritysettings), unk, com, tiff, app, a3x, one(onepkg), pps, apk, ppt(pot,pothtml,ppa,ppthtml,pwz,pps), ps, php, zip(iso,tbz,xz,img,z), raw64, py, chm, swf, mso, gif, msi, xps(dwfx,easmx,edrwx,eprtx,jtx,oxps), wav, war, xlsx(xlam,xltm,xlsm,xltx,xlsb,ods,ots), hml, msg, png, dmg, lz, flv, applet, pl, cab, tnef, ppsx, xcoff, jpg(bmp), rar(zipx), avi, acrobatsecuritysettings, inf, 7zip(7z,cpio), contact, dwg, csv, css, rm, url-applet, jsp, hwt, pyc, hwp, bz2, exe(scr,pif), url, doc(dochtml,docxml,dot,dothtml,wbk,wiz), sh, eot, egg, txt

File Retention

You cannot delete files once they have been sent to the Detection On Demand service. Files found not to be malicious will automatically be removed, while files found to be malicious will be kept for further analysis.

Supported Operating Systems

Currently, your submitted files will be executed in the following environments:

Windows 10
Windows 7
Windows XP
CentOS 7.2
Mac OS X 11.2

URLs

One or more public URLs can be submitted for scanning using the /urls endpoint. Each URL will be opened by the detection engine, which will attempt to detonate the file or webpage and check for malicious behavior. A detailed report of all of the artifacts (files, images, executables, nested URLs, etc.) contained within the website will be included in the report along with the a malicious or non-malicious verdict. A max of 10 URLs are allowed to be submitted in each call to /urls.

URL quota

The /url endpoint will use the same quota limit as the /files endpoint. For example, if your subscription is for 100 file submissions per month, then each call to the /urls endpoint will count against the 100 submissions. Submitting multiple URLs in a single call to /urls will only count as 1 submission against the quota.

Reports

Today, the /reports collection allows a single operation: retrieving reports with a GET request from /reports/{report_id}. Reports are tied to the report_id that is returned when you submit a file to the /files endpoint, so be sure to keep track of the report ID returned from /files so you can look up the results later.

Some important things to note:

You cannot retrieve bulk reports using the /reports endpoint; it only supports retrieval of single reports via the /reports/{report_id} endpoint. To obtain reports in bulk, use the /telemetry endpoint, which offers various query parameters for filtering reports.
Reports, by default, include only high-level information. If you want to see the full report, you must pass the extended=true parameter.

Report Definition

The report response object schema has been fully defined in our API docs. If you would like to understand what fields in the report mean, please refer to the API docs.

OS Change Reports

OS change reports describe the changes that your file made when it was run in different operating systems. To understand the OS Change report, please refer to the API docs.

Presigned URLs

Being able to view detection reports in a human friendly way can be invaluable to analyzing, responding to, and remediating attacks. The Detection API provides a /presigned-url endpoint that will generate an authenticated link to an in-browser report viewer for any report of your choosing. The default time to live for a link is 72 hours, but this can be configured for 1 hour to 8760 hours (365 days), depending on your needs.

browser-report

Hashes

Today, the /hashes collection only allows a single operation: retrieving hash reports with a GET request from /hashes/{hash_id}, where {hash_id} is an MD5 hash. Currently, only MD5 hashe lookup is supported.

Hash Response

Hash responses are similar but not identical to reports. To understand the hash response schema, please refer to the API docs.

Artifacts

Artifacts, like GIFs of the detonation of a file, can be retrieved from a file submission report using this endpoint. Artifacts provide additional forms of media that can help visualize and support evidence of malicious files.

Telemetry

The /telemetry endpoint provides an interface for retreiving submissions in bulk, with various query parameters to filter submissions. This endpoint not only returns information on reports submitted via the API, but also via integrations with certain third-party services like Box, Slack, and S3. Each submission returned contains basic information about where it came from (ex. API, Box, Slack, etc.), whether or not the submission is malicious, and the report ID that can be used to obtain more details on a specific submission.