URLhaus API

URLhaus offers an API to both, receive (download) and submit malware URLs from the URLhaus database. The API is documented below.

Retrieve (download) malware URLs ClamAV signatures Submit malware URLs Submission Policy Your Account API for automated bulk queries Terms of Services (ToS)

Retrieve malware URLs


Depending on your need, you can choose one or more delivery methods / formats from the list below.

Database dump (CSV)

The URLhaus database dump is a simple CSV feed that contains all malware URLs that are currently known to URLhaus. The CSV contains the following items:

The CSV gets generated every 5 minutes. Please do not fetch it more often than every 5 minutes.

Download CSV

DNS Response Policy Zone (RPZ)

By using an DNS Reponse Policy Zone (RPZ), also known as DNS firewall, you can block the resolution of certain domain names on your DNS resolver. URLhaus extracts the domain names from malware URLs and offers them in an RPZ dataset. More information about DNS RPZ can be found on dnsrpz.info.

The RPZ zone file gets generated every 5 minutes. Please do not fetch it more often than every 5 minutes.

Download RPZ

Snort / Suricata Ruleset

If you are using a network intrusion detection and preventation systems (IDS / IPS) like Snort or Suricata (or any other IDS that supports the Snort / Suricata Ruleset format), you may use the URLhaus IDS Ruleset to identify network traffic towards known malware URLs. The ruleset will only trigger on the extact URL in a HTTP stream (HTTP GET request).

The IDS ruleset gets generated every 5 minutes. Please do not fetch it more often than every 5 minutes.

Download IDS Ruleset

Download IDS Ruleset (tar.gz)

Plain-Text URL List (URLs only)

The Plain-Text URL List is a dump of all malware URLs known to URLhaus. It does not contain anything else than one URL per line, which is useful if you want to use the URLhaus dataset as an IOC (Indicator Of Compromise). You can match them against certain log files of your security permieter, for example web proxy logs. You may also use it as a blocklist with a low false positive rate.

The Plain-Text URL List gets generated every 5 minutes. Please do not fetch it more often than every 5 minutes.

Download Plain-Text URL List

Collected Payloads (CSV)

URLhaus regularely checks the content served by malicious URLs that are known to URLhaus. This CSV contains all payloads collected by URLhaus, identified by a hash (MD5 / SHA256 hash). Please consider that not all payloads are malicious. As a matter of fact, a URL can e.g. serve any content once it has been cleaned up.

Download Collected Payloads (CSV)

URLhaus ClamAV signatures

URLhaus generates a ClamAV signature database which gets updated once per minute. This allows you to add almost real time detection of malware distribution sites (e.g. such ones being used by Emotet/Heodo) on your email gateway / spam filter. As the signature file only contains active malware distribution sites or such that have been added to URLhaus in past 48 hours, the false positive rate should be very low. You can download the signature file here:

Download ClamAV signature database

If you plan to implement the URLhaus ClamAV signatures, please ensure that you update the signature file once per minute to receive the best protection / spam catch rate. You can do so by setup a cron that executes the following script every minute:

I do also recommend you to either REJECT or QUARANTINE any email message that contains a link blacklisted in the URLhaus ClamAV signature file. In case you decide to REJECT emails containing blacklisted urls, you are free to put the following link into the error message you send back to the user:

Further information about the implementation of ClamAV can be found on the following websites:

Submit malware URLs


Collecting and maintaing a list of malware URLs means a lot of work. I therefore appreciate any submissions from 3rd parties like security researchers, SOC analysts or vendors to URLhaus. If you would like to submit malware URLs to URLhaus, there are two ways to do so:

Submissions via web interface

You can use the web interface to submit a malware URL to URLhaus. In order to do so, you will need to login with your Twitter account. Please consider that your Twitter handle will be public visible unless stated otherwise (by selecting the option anonymous report).

Submissions via API

There is a web API you can use for automated or bulk submissions. You can call the API through Python, perl or your prefered scripting language.

To submit a malware URL to URLhaus through bulk API, you must send a POST request to https://urlhaus.abuse.ch/api/. The post request must contain the following fields (JSON):

tokenYour personal API key
anonymousIf set to 1, your submission will be anonymous (required)
submissionList of URLs (required)
URLURL you want to submit (required)
ThreatThreat (required, must be malware_download)
TagsTag. Allowed characters: [A-Za-z0-9.- ] (optional)

In order to optain an API key for bulk submissions to URLhaus, you must login with your Twitter account first. Once you have authenticated yourself you can view your API key in the page section your account.

If you want to send malware URLs to URLhaus using python, your python script may look like this:

          import json
          import requests

          '''
          URLhaus sample python3 code for submitting malware URLs the bulk API
          See https://urlhaus.abuse.ch/api/
           - token (required)
           - anonymous (optional, default: 0)
           - url (required)
           - threat (required, supported values: malware_download)
           - tags (optional)
          '''

          url = 'https://urlhaus.abuse.ch/api/'
          api_key = YOUR_API_KEY

          jsonData = {
            'token' : api_key,
            'anonymous' : '0',
            'submission' : [
              {
                'url' : 'http://evildomain1.tld/bad',
                'threat' : 'malware_download',
                'tags': [
                  'Retefe',
                  'exe'
                ]
              },
              {
                'url' : 'http://itgetsworse.tld/file.exe',
                'threat' : 'malware_download',
                'tags': [
                  'Ransomware'
                  ]
              },
              {
                'threat' : 'malware_download'
                'url' : 'http://swiss-cheese-is-the-best-cheese.tld/file.exe',
              }
            ]
          }

          headers = {
              "Content-Type"  :   "application/json"
          }
          r = requests.post(url, json=jsonData, timeout=15, headers=headers)
          print(r.content)
      

@cocaman has published a neat python3 script to submit malware URLs to URLhaus:

Submission Policy

URLhaus is currently only collecting websites (URLs) that are directly being used to distribute malware. Please note that any other submissions will be ignored / deleted from URLhaus.
Before you start to submit URLs to URLhaus, I encourage you to read the following submission policy:

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

Your Account


API for automated bulk queries


If you would like to query URLhaus for e.g. an URL or malware sample in an automated way, there is a dedicated API available for this purpose. It also allows you to download a specific malware sample or daily batches:

Terms of Services (ToS)


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