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 50 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. There are some important things to know about reports before using the Detection On Demand service:

  • Today, you do not have access to the /reports collection, so you cannot get a list of all reports run by your API key or account. If you want to look up reports later, you must store your report IDs for future lookups.
  • 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 hashes are supported, but plans to support other hashes are in the pipeline.

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.