MalwareBazaar API

MalwareBazaar offers the following APIs to not only submit (upload) or download malware samples but also to do automated bulk queries obtaining intel form MalwareBazaar.

API key Submission Policy Submit (upload) a malware sample Retrieve (download) a malware sample Query a malware sample (hash) Query tag information Query signature information Update an entry Add a comment Query latest malware samples (recent additions) Download daily malware batches Example python3 scripts Terms of Services (ToS)

API-Key


In order to submit (upload) a malware sample to MalwareBazaar, an API key is needed. You can obtain one by logging in to MalwareBazaar with your Twitter account. Afterwards you can access your API key in your Account settings.

Submission Policy


Before you start to submit malware samples to MalwareBazaar, please read the following submission policy:

Note: Should you repeatedly violate the submission policy documented above, your account may get banned from contributing to MalwareBazaar.

Upload malware samples


You can upload (submit) malware samples to MalwareBazaar by using the API documented below, sending a multipart form POST request with file (the actual file you want to submit) and json_data (see documentation below) to https://mb-api.abuse.ch/api/v1/.

KeyRequired?CommentExample
anonymousNoIf set to 1, your submission will be anonymous. Default: 00
fileYesThe malware sample you want to upload 
tagsNoList of tags. Allowed characters: [A-Za-z0-9.- ]exe
referencesNoReferences for this malware sample
KeyExample
urlhaushttps://urlhaus.abuse.ch/url/318612/
any_runhttps://app.any.run/tasks/XYZ
joe_sandboxhttps://www.joesecurity.org/reports/XYZ/
malpediahttps://malpedia.caad.fkie.fraunhofer.de/details/win.gozi
twitterhttps://twitter.com/abuse_ch/status/1224269018506330112
linkshttps://domain.tld/blog/interesting-malware.php
contextNoContext for this malware sample
KeyExample
dropped_by_md568b329da9893e34099c7d8ad5cb9c940
dropped_by_sha25601ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b
droped_by_malwareGozi
dropping_md55fb882846518a38b42b74348bb3a838b
dropping_sha256ddf42fa0c0c9f5e7c33dfe7cc6743f812b796b53c759e6e19ec18daa6b98364e
dropping_malwareLoki
commentThis malware sample is very nasty!
delivery_methodNoDelivery method used to spread this malware sample
ValueMeaning
email_attachmentDistributed via e-mail attachment
email_linkDistributed via e-mail link
web_downloadDistributed via web download
web_drive-byDistributed via drive-by
multipleMultiple delivery methods used
otherOther delivery methods used

To authenticate your request, you must send the HTTP header API-KEY with your personal API-Key with every request. You can view your API-Key here.
Example HTTP header:

API-KEY: XYZ123

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
no_api_keyYou did not provide an API key. You can obtain one here
user_blacklistedYour API key is blacklisted. Please contact coSntacPtAmeM@abuse.ch (remove all capital letters)
file_already_knownThe malware sample you have tried to submit is already known
insertedThe malware sample has been inserted into MalwareBazaar
file_expectedYou did not send any file

Here's a sample python3 script that submits malware sample to MalwareBazaar

#!/usr/bin/env python3
import requests
import sys
import json

if len(sys.argv) > 1:
    file = sys.argv[1]
else:
    print("Usage: python3 malware_Bazaar_submit.py <file>")
    quit()

headers = {'API-KEY': 'XYZ123'}
data = {
    'anonymous': 1,
    'delivery_method': 'email_attachment',
    'tags': [
        'exe',
        'test'
    ],
    'references': {
            'any_run': [
                'https://app.any.run/tasks/1',
                'https://app.any.run/tasks/2'
            ],
            'joe_sandbox': [
                'https://www.joesecurity.org/reports/1',
                'https://www.joesecurity.org/reports/2'
            ],
            'malpedia': [
                'https://malpedia.caad.fkie.fraunhofer.de/details/win.gozi'
            ],
            'twitter': [
                'https://twitter.com/abuse_ch/status/1224269018506330112'
            ],
            'links': [
                'https://urlhaus.abuse.ch/url/306613/',
            ]
    },
    'context': {
            'dropped_by_md5': [
                '68b329da9893e34099c7d8ad5cb9c940'
            ],
            'dropped_by_sha256': [
                '01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b',
                '4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865'
            ],
            'dropped_by_malware': [
                'Gozi'
            ],
            'comment': 'this malware sample is very nasty!'
    }
}
files = {
    'json_data': (None, json.dumps(data), 'application/json'),
    'file': (open(file,'rb'))
    }
response = requests.post('https://mb-api.abuse.ch/api/v1/', files=files, verify=False, headers=headers)
        

Retrieve (download) a malware sample


You can download (fetch) malware samples from MalwareBazaar by using the API documented below, sending an HTTP POST request to https://mb-api.abuse.ch/api/v1/. Please note that any malware sample you download from MalwareBazaar will be zipped and password protected using the password "infected" (without "").

KeyExampleComment
API-KEYXYZ123Your personal API-Key. You can obtain one here
queryget_file 
sha256_hash094fd325049b8a9cf6d3e5ef2a6d4cc6a567d7d49c35f8bb8dd9e3c6acf3d78dSHA256 hash of the malware sample you want to download

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
illegal_sha256_hashIllegal SHA256 hash provided
no_sha256_hashNo SHA256 hash provided
file_not_foundThe file was not found or is unknown to MalwareBazaar

Here's a sample wget request on how to fetch a file:

wget --post-data "query=get_file&sha256_hash=094fd325049b8a9cf6d3e5ef2a6d4cc6a567d7d49c35f8bb8dd9e3c6acf3d78d" https://mb-api.abuse.ch/api/v1/
        

Query a malware sample (hash)


You can check if a particular malware sample is known to MalwareBazaar by query the API for the corresponding hash (using HTTP POST form data):

KeyExampleComment
queryget_info 
hash094fd325049b8a9cf6d3e5ef2a6d4cc6a567d7d49c35f8bb8dd9e3c6acf3d78dSHA256, MD5 or SHA1 hash of the malware sample you want to query

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
hash_not_foundThe file (hash) you wanted to query is unknown to MalwareBazaar
illegal_hashThe hash you provided is not a valid SHA256 hash
no_hash_providedYou did not provide a hash
sha256_hashe167b20f1acf48f7ce0ae33a218e2c1b300b41c012ededf03e7a3522a4ebe95eSHA256 hash of the malware sample
sha1_hasheb0e81598d8526d88cac4695a3e9360cc8fbb331SHA1 hash of the malware sample
md5_hash7338b335ad5471cb67658f27836374f0MD5 hash of the malware sample
first_seen2020-02-28 05:57:01TS when the file has been first seen by MalwareBazaar (UTC)
last_seen2020-03-01 08:11:45TS when the file has been last seen by MalwareBazaar (UTC)
file_nameJamil Marzouka Co.pdf.jarMalware sample's file name
file_size62118File size in bytes
file_typejarFile type
reporterviqlTwitter handle of the report (or anonymous for anonymous submissions)
anonymous01 (true) or 0 (false)
signatureAdwindMalware family (if available)
imphashf34d5f2d4577ed6d9ceec516c1f5a744imphash (only available for PE executables)
tlsh11B2194E3FA98856C4BC177486B5965003B091870423EE2FCDC550CBAFB3AD92D88AF9Trend Micro Locality Sensitive Hash (tlsh)
ssdeep1536:sGZWpdxayQAcj7gwluW14Z2II0ocL8ppVy8U+M76JMaDZVB0pI6lxYGinsPF9WPzssdeep
file_size
tagsAdwind, jar, qualist of tags
delivery_methodemail_attachmentDistributed via e-mail attachment
email_linkDistributed via e-mail link
web_downloadDistributed via web download
web_drive-byDistributed via drive-by
multipleMultiple delivery methods used
otherOther delivery methods used

Here's a sample wget request on how to query the API for a hash:

wget --post-data "query=get_info&hash=b5c24d94b63f844c5350bedb4312499887b61490b2080a98611c28320c3a7274" https://mb-api.abuse.ch/api/v1/
        

Query tag information


You can get a list of malware samples (max 1'000) associated with a specific tag by query the API as follow (using HTTP POST form data):

KeyExampleComment
queryget_taginfo 
tagTrickBotTag you want to get malware samples for

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
tag_not_foundThe tag you wanted to query is unknown to MalwareBazaar
illegal_tagNo valid tag provided
no_tag_providedYou did not provide a tag
no_resultsYour query yield no results
sha256_hashe167b20f1acf48f7ce0ae33a218e2c1b300b41c012ededf03e7a3522a4ebe95eSHA256 hash of the malware sample
sha1_hasheb0e81598d8526d88cac4695a3e9360cc8fbb331SHA1 hash of the malware sample
md5_hash7338b335ad5471cb67658f27836374f0MD5 hash of the malware sample
first_seen2020-02-28 05:57:01TS when the file has been first seen by MalwareBazaar (UTC)
last_seen2020-03-01 08:11:45TS when the file has been last seen by MalwareBazaar (UTC)
file_nameJamil Marzouka Co.pdf.jarMalware sample's file name
file_size62118File size in bytes
file_typejarFile type
reporterviqlTwitter handle of the report (or anonymous for anonymous submissions)
anonymous01 (true) or 0 (false)
signatureAdwindMalware family (if available)
imphashf34d5f2d4577ed6d9ceec516c1f5a744imphash (only available for PE executables)
tlsh11B2194E3FA98856C4BC177486B5965003B091870423EE2FCDC550CBAFB3AD92D88AF9Trend Micro Locality Sensitive Hash (tlsh)
ssdeep1536:sGZWpdxayQAcj7gwluW14Z2II0ocL8ppVy8U+M76JMaDZVB0pI6lxYGinsPF9WPzssdeep
file_size
tagsAdwind, jar, qualist of tags
delivery_methodemail_attachmentDistributed via e-mail attachment
email_linkDistributed via e-mail link
web_downloadDistributed via web download
web_drive-byDistributed via drive-by
multipleMultiple delivery methods used
otherOther delivery methods used

Here's a sample wget request on how to query the API for a tag:

wget --post-data "query=get_taginfo&tag=TrickBot" https://mb-api.abuse.ch/api/v1/
        

Query signature information


You can get a list of malware samples (max 1'000) associated with a specific signature by query the API as follow (using HTTP POST form data):

KeyExampleComment
queryget_siginfo 
signatureTrickBotTag you want to get malware samples for

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
signature_not_foundThe signature you wanted to query is unknown to MalwareBazaar
illegal_signatureThe text you provided is not a valid signature
no_signature_providedYou did not provide a signature
no_resultsYour query yield no results
sha256_hashe167b20f1acf48f7ce0ae33a218e2c1b300b41c012ededf03e7a3522a4ebe95eSHA256 hash of the malware sample
sha1_hasheb0e81598d8526d88cac4695a3e9360cc8fbb331SHA1 hash of the malware sample
md5_hash7338b335ad5471cb67658f27836374f0MD5 hash of the malware sample
first_seen2020-02-28 05:57:01TS when the file has been first seen by MalwareBazaar (UTC)
last_seen2020-03-01 08:11:45TS when the file has been last seen by MalwareBazaar (UTC)
file_nameJamil Marzouka Co.pdf.jarMalware sample's file name
file_size62118File size in bytes
file_typejarFile type
reporterviqlTwitter handle of the report (or anonymous for anonymous submissions)
anonymous01 (true) or 0 (false)
signatureAdwindMalware family (if available)
imphashf34d5f2d4577ed6d9ceec516c1f5a744imphash (only available for PE executables)
tlsh11B2194E3FA98856C4BC177486B5965003B091870423EE2FCDC550CBAFB3AD92D88AF9Trend Micro Locality Sensitive Hash (tlsh)
ssdeep1536:sGZWpdxayQAcj7gwluW14Z2II0ocL8ppVy8U+M76JMaDZVB0pI6lxYGinsPF9WPzssdeep
file_size
tagsAdwind, jar, qualist of tags
delivery_methodemail_attachmentDistributed via e-mail attachment
email_linkDistributed via e-mail link
web_downloadDistributed via web download
web_drive-byDistributed via drive-by
multipleMultiple delivery methods used
otherOther delivery methods used

Here's a sample wget request on how to query the API for a signature:

      wget --post-data "query=get_siginfo&signature=TrickBot" https://mb-api.abuse.ch/api/v1/
        

Update an entry


You can update an existing entry by sending a HTTP POST request to https://mb-api.abuse.ch/api/v1/ as documented below (using HTTP POST form data). Please note that you can only update entries that you have created by your own.

KeyExampleComment
API-KEYXYZ123Your personal API-Key. You can obtain one here
queryupdate 
sha256_hash094fd325049b8a9cf6d3e5ef2a6d4cc6a567d7d49c35f8bb8dd9e3c6acf3d78dSHA256 hash of the malware sample you want to update
keyThe information you want to add. Possible values:
add_tagAdd a tag
remove_tagRemove a tag
urlhausLink to URLhaus entry
any_runLink to ANY.RUN report
joe_sandboxLink to JoeSandbox report
malpediaLink to Malepdia entry
twitterLink to Tweet
linksLink to website
dropped_by_md5Malware (MD5 hash) that dropped this sample
dropped_by_sha256Malware (SHA256 hash) that dropped this sample
dropped_by_malwareMalware family name that dropped this sample
dropping_md5Malware (MD5 hash) that got dropped by this sample
dropping_sha256Malware (SHA256 hash) that got dropped by this sample
dropping_malwareMalware family name that got dropped by this sample
commentYour comment on the malware sample
valuehttps://twitter.com/abuse_ch/status/1230163243093630980Value you want to add

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
no_api_keyYou did not provide an API key. You can obtain one here
user_blacklistedYour API key is blacklisted. Please contact coSntacPtAmeM@abuse.ch (remove all capital letters)
hash_not_foundThe file (hash) you wanted to update is unknown to MalwareBazaar
illegal_hashThe hash you provided is not a valid SHA256 hash
permission_deniedThe database entry you have tried to update is not owned by your account
unknown_keyThe key (add parameter) you wanted to update is not known
existsThe key -> value already exists
updatedEntry has been updated

Here's a sample python3 script that submits malware sample to MalwareBazaar:

  #!/usr/bin/env python3
  import requests
  import json

  headers = { 'API-KEY': 'XYZ' }

  data = {
      'query': 'update',
      'sha256_hash': 'd9b05da007d51cf86d4a6448d17183ab69a195436fe17b497185149676d0e77b',
      'key': 'links',
      'value': 'https://www.abuse.ch'
  }

  response = requests.post('https://mb-api.abuse.ch/api/v1/', data=data, timeout=15, headers=headers)
  print(response.content.decode("utf-8", "ignore"))
        

Add a comment


You can comment a malware sample by sending a HTTP POST request to https://mb-api.abuse.ch/api/v1/ as documented below (using HTTP POST form data).

KeyExampleComment
API-KEYXYZ123Your personal API-Key. You can obtain one here
queryadd_comment 
sha256_hash094fd325049b8a9cf6d3e5ef2a6d4cc6a567d7d49c35f8bb8dd9e3c6acf3d78dSHA256 hash of the malware sample you want comment
commentSwiss chocolate is the best chocolateYour comment on the sample

Possible response values are:

KeyValueComment
query_statushttp_post_expectedThe API expected a HTTP POST request
no_api_keyYou did not provide an API key. You can obtain one here
user_blacklistedYour API key is blacklisted. Please contact coSntacPtAmeM@abuse.ch (remove all capital letters)
hash_not_foundThe file (hash) you wanted to comment is unknown to MalwareBazaar
illegal_hashThe hash you provided is not a valid SHA256 hash
successThe comment has been saved successfully

Here's a sample python3 script for commenting a malware sample:

  #!/usr/bin/env python3
  import requests
  import json

  headers = { 'API-KEY': 'XYZ' }

  data = {
      'query': 'add_comment',
      'sha256_hash': 'd9b05da007d51cf86d4a6448d17183ab69a195436fe17b497185149676d0e77b',
      'comment': 'Swiss chocolate is the best chocolate'
  }

  response = requests.post('https://mb-api.abuse.ch/api/v1/', data=data, timeout=15, headers=headers)
  print(response.content.decode("utf-8", "ignore"))
        

Query latest malware samples (recent additions)


I you can retrieve a list of malware samples added to MalwareBazaar within the last 60 minutes as documented below (using HTTP POST form data):

KeyExampleComment
queryget_recent 
selectortimeGet additions made within the past 60 minutes

Alternatively, you can query the API for the most recent 100 additions as documented below:

KeyExampleComment
queryget_recent 
selector100Get the latest 100 additions

Possible response values are:

KeyValueComment
query_statusokAll good!
no_selectorNo selector provided. Please use either time or limit as selector
unknown_selectorUnknown selector provided. Please use either time or limit as selector
no_resultsYour query yield no results
sha256_hashe167b20f1acf48f7ce0ae33a218e2c1b300b41c012ededf03e7a3522a4ebe95eSHA256 hash of the malware sample
sha1_hasheb0e81598d8526d88cac4695a3e9360cc8fbb331SHA1 hash of the malware sample
md5_hash7338b335ad5471cb67658f27836374f0MD5 hash of the malware sample
first_seen2020-02-28 05:57:01TS when the file has been first seen by MalwareBazaar (UTC)
last_seen2020-03-01 08:11:45TS when the file has been last seen by MalwareBazaar (UTC)
file_nameJamil Marzouka Co.pdf.jarMalware sample's file name
file_size62118File size in bytes
file_typejarFile type
reporterviqlTwitter handle of the report (or anonymous for anonymous submissions)
anonymous01 (true) or 0 (false)
signatureAdwindMalware family (if available)
imphashf34d5f2d4577ed6d9ceec516c1f5a744imphash (only available for PE executables)
tlsh11B2194E3FA98856C4BC177486B5965003B091870423EE2FCDC550CBAFB3AD92D88AF9Trend Micro Locality Sensitive Hash (tlsh)
ssdeep1536:sGZWpdxayQAcj7gwluW14Z2II0ocL8ppVy8U+M76JMaDZVB0pI6lxYGinsPF9WPzssdeep
file_size145405Size of the file in bytes
tagsAdwind, jar, qualist of tags
intelligenceclamavClamAV detection (offical and unofficial rules)
downloadsnumber (int) of downloads from MalwareBazaar
uploadsnumber (int) of uploads to MalwareBazaar
mailMail intelligence using spamtrap data

Here's a sample wget request on how to fetch a list of recent malware samples for the past 60 minutes:

wget -O- --post-data "query=get_recent&selector=time" https://mb-api.abuse.ch/api/v1/
        

A response from the API looks like this:

    {
    	"query_status": "ok",
    	"data": [
        {
    			"sha256_hash": "e167b20f1acf48f7ce0ae33a218e2c1b300b41c012ededf03e7a3522a4ebe95e",
    			"sha1_hash": "eb0e81598d8526d88cac4695a3e9360cc8fbb331",
    			"md5_hash": "7338b335ad5471cb67658f27836374f0",
    			"first_seen": "2020-03-01 05:57:01",
    			"last_seen": null,
    			"file_name": "file",
    			"file_size": 145408,
    			"file_type_mime": "application\/x-dosexec",
    			"file_type": "exe",
    			"reporter": "viql",
    			"anonymous": 0,
    			"signature": "RevengeRAT",
    			"imphash": "f34d5f2d4577ed6d9ceec516c1f5a744",
          "tlsh": "11B2194E3FA98856C4BC177486B5965003B091870423EE2FCDC550CBAFB3AD92D88AF9",
    			"ssdeep": "1536:sGZWpdxayQAcj7gwluW14Z2II0ocL8ppVy8U+M76JMaDZVB0pI6lxYGinsPF9WPz:7dPIocwpPMGP9SBlxp+st9gTp5",
    			"tags": [
    				"revengerat"
    			],
    			"intelligence": {
    				"clamav": "Win.Trojan.Generic-6332612-0",
    				"downloads": "0",
    				"uploads": "1",
    				"mail": null
    			}
    		},
    		{
    			"sha256_hash": "7c032beb567b18670073727a6b1fba146e2daf128c5abd51279c7ad0b7d3c482",
    			"sha1_hash": "9189b6d2493ef46e9bc100c8703e2562982a98fc",
    			"md5_hash": "c7a583745df676615eb1b7cab158d397",
    			"first_seen": "2020-02-18 10:43:15",
    			"last_seen": null,
    			"file_name": "Jamil Marzouka Co.pdf.jar",
    			"file_size": 62118,
    			"file_type_mime": "application\/zip",
    			"file_type": "jar",
    			"reporter": "abuse_ch",
    			"anonymous": 0,
    			"signature": "Adwind",
    			"imphash": null,
          "tlsh": "11B2194E3FA98856C4BC177486B5965003B091870423EE2FCDC550CBAFB3AD92D88AF9",
    			"ssdeep": "1536:3M+ZXQ4\/0d0JUxYpugXo9dboZ89cn+xzl0rHfFcMjrYaOK+UyBstRgFq:3M+Np0dKUGLo9doZMXxp43uszgFq",
    			"tags": [
    				"Adwind",
    				"jar",
    				"qua"
    			],
    			"intelligence": {
    				"clamav": null,
    				"downloads": "0",
    				"uploads": "1",
    				"mail": {
    					"IT": "low",
    					"Generic": "low"
    				}
    			}
    		}
    	]
    }
      

Download daily malware batches


MalwareBazaar creates daily batches of malware sample). The daily batches are created once a day at midnight (00:00 UTC). Please consider that it takes a few minutes to create the batch. So I kindly ask you to not fetch the daily batch before 00:15 UTC. The daily batches are available here:

Example python3 scripts


@cocaman has created a github repository with a handful example scripts on how to leverage the MalwareBazaar API:

Terms of Services (ToS)


By using the website of MalwareBazaar, or any of the services / datasets referenced above, you agree that: