API Documentation

The Sandbox API was designed to be simple to understand and easy to use. It's easy to implement in virtually any application and requires only a small amount of code. The values returned by the Sandbox API calls can come back as either text or as binary data.

Note if you have a set of binaries you would like to submit please contact us we would be happy to add them into the repository.

Data Usage Restrictions

We are granting access to the Shadowserver Sandbox API for research purposes only. You agree not to disseminate or resell the retrieved data to any person or entity. Access to the Shadowserver Sandbox API is for the exclusive use of the person & company named on this correspondence. Shadowserver provides the data with no warranty of any kind, and is not liable in any way for its use by the subscriber.

Querying The API

You send requests (queries) to the Sandbox API by using a URL with attached parameters. The URL goes to the Sandbox API code, is processed, and then returns a simple string of data that tells you what it found. There are 4 kinds of queries you can send to the API:

Status Query

http://innocuous.shadowserver.org/api/?query=#md5-or-sha1# Returns the md5, sha1, first seen date (UTC), last seen date (UTC), file type, and ssdeep hash on the first line as a CSV value. The second line is a JSON object containing antivirus vendor and signature details for the given sample.

 "aca4aad254280d25e74c82d440b76f79","6fe80e56ad4de610304bab1675ce84d16ab6988e",\"Tuesday, 15 June 2010 03:09:41",\"Tuesday, 15 June 2010 03:09:41","exe","12288:gOqOB0v2eZJys73dOvXDpNjNe8NuMpX4aBaa48L/93zKnP6ppgg2HFZlxVPbZX:sOA2eZJ8NI8Nah8L/4PqmTVPlX"
 {"AVG7":"Downloader.Generic9.URM","AntiVir":"WORM/VB.NVA","Avast-Commercial":"Win32:Zbot-LRA","Clam":"Trojan.Downloader-50691","DrWeb":"Win32.HLLW.Autoruner.6014","F-Prot6":"W32/Worm.BAOX","F-Secure":"Trojan.Win32.Cosmu.nyl","F-Secure":"Worm:W32/Revois.gen!A","G-Data":"Trojan.Generic.2609117","Ikarus":"Trojan-Downloader.Win32.VB","Kaspersky":"Trojan.Win32.Cosmu.nyl","McAfee":"Generic","NOD32":"Win32/AutoRun.VB.JP","Norman":"Suspicious_Gen2.SKLJ","Panda":"W32/OverDoom.A","QuickHeal":"Worm.VB.at","Sophos":"Troj/DwnLdr-HQY","TrendMicro":"TROJ_DLOADR.SMM","VBA32":"Trojan.VBO.011858","Vexira":"Trojan.DL.VB.EEDT","VirusBuster":"Worm.VB.FMYJ"}

Example:

[freed0@paladin test]$ wget -q -O - http://innocuous.shadowserver.org/api/?query=aca4aad254280d25e74c82d440b76f79

White Listed Entries

Returns the following when the hash is on our whitelist: ! Whitelisted: Company Name, Application Name, File Name

Example:

[freed0@paladin test]$ wget -q -O - http://innocuous.shadowserver.org/api/?query=00000142988AFA836117B1B572FAE4713F200567
! Whitelisted: Microsoft, Applications Microsoft Office Family, J0180794.JPG

No Match

Returns the following when no match is found:

! No match found for #md5-or-sha1#

Example:

[freed0@paladin test]$ wget -q -O - http://innocuous.shadowserver.org/api/?query=aca4aad254280d25e74c82d440b76f70
! No match found for aca4aad254280d25e74c82d440b76f70

Anti-Virus Vendor List

http://innocuous.shadowserver.org/api/?avvendors Returns a CSV list of vendor names.

 "AVG7","AntiVir","Avast-Commercial","BitDefender","Clam","DrWeb","F-Prot6","F-Secure","G-Data","Ikarus","Kaspersky","McAfee","NOD32","Norman","Panda","QuickHeal","Sophos","TrendMicro","VBA32","Vexira","VirusBuster"

API Error Handling

In the event of an API error or query limit, the API will return an exclamation mark (!) followed by a single space, and then the text of the error message. For example:

! Sorry, but that doesn't appear to be a valid API command

Extended API

Access to the extended API calls are controlled by IP/CIDR Whitelisting. To gain access please send an email to request_api <AT> shadowserver.org with an explanation of why you would like access. We will need to know the following information:

  • IP/CIDR
  • Full Name
  • Phone Number
  • E-Mail address for contact
  • Company

Sample Download

https://innocuous.shadowserver.org/api/?download=#md5# Returns the malware sample as a binary download.

AV Results

http://innocuous.shadowserver.org/api/?avresult=#md5# Returns the anti-virus results for the specified sample.

"name","classification","engine_version","signature_version","timestamp"
Norman,W32/Opanki.EQ,5.91.10,5.90,2008-02-01 00:00:0
DrWeb,Win32.HLLM.Brontok,4.33,4.33.0,2008-02-01 00:00:0
McAfee,W32/Opanki.worm.gen,v5.1.00,v4100,2008-02-01 00:00:0
NOD32,Win32/VB.ES,"2.70.5,",2841,2008-02-01 00:00:0
Clam,PUA.Packed.MEW-1,0.92,5110,2008-02-01 00:00:0
AntiVir,WORM/Brontok.Z.1,2.1.11-58,7.0.2.78,2008-02-01 00:00:0
F-Prot6,W32/Sillyworm.VS,4.4.2.54,200802010107dcb36f30cb7df6bfd6eb04644a603164,2008-02-01 00:00:0
F-Prot,W32/Sillyworm.VS,3.16.15,25 January 2008,2008-02-01 00:00:0
Panda,Adware/AccesMembre,9.04.03.0001,31/01/2008,2008-02-01 00:00:0
VBA32,Worm.Win32.VB.es,3.12.2.1,2007.07.19,2008-02-01 00:00:0
Avast,Win32:Vbgen-DZ-MEW,1.0.8,000777-1,2008-02-01 00:00:0
F-Secure,Worm.Win32.VB.es,1.10  build 6192,2007-12-12_06,2008-02-01 00:00:0
AVG7,Worm/VB.AKX,7.5.51 442,269.19.18/1254,2008-02-01 00:00:0

Ssdeep Matching

A list of up to 1,000 matching samples at 90% or greater can be obtained with the following query:

http://innocuous.shadowserver.org/api/?ssdeep=768:oMzk06sDnriJ3OGKeKNh/UkECjMtvR1VF2r+R5nOwekfZOO7:npDnq+5h/tDSZ15Wwdz7