Welcome to RansomCoinDB, which is a RESTful json API for studying the impacts of ransomware, and eventually other Cryptocurrency enabled crime. To get started, you will need to be able to make requests of the service with an api key. You can use CURL or WGET to see how the service works initially, and eventually progress to your favourite programming language.
RansomCoinDB was born from an experiment in light malware analysis and Bitcoin transaction analysis. It is primarily designed to work for people who want to quantify the risk of ransomware, and calculate the frequency and severity of the problem. However, we have also found some forensics groups also value this approach, as a low cost rapid triage, saving their analyst time from reworking things.
The short answer is hashes, transactions, and dates. One of our design principles is not to share data about victims, both to be GDPR compliant, but also because so far it has not really aided our analysis. So we stick to meta data about the ransomware and associated payments, which happened to be enormously useful for risk calculations. We have some in house risk models we have already built from this data, but we thought you might just prefer to build your own, instead of taking our word for it.
We will discuss the data fields in minute detail below, to aid your use of the endpoints. The hashes could be from ransomware samples or ransom notes, or even emails. We choose to keep those emails private, for a variety of reasons, and we do not store them. We simply link a hash to an account number of a crypto-currency. We personally do not negotiate ransoms, so all our data comes from other trusted sources.
The basic idea here is that if you have a hash that you think is part of a historical ransomware campaign, you can simply look up the associated crypto-currency address found within it. Conversely, if you have an account number provided in an email, you can see if it turns up in binaries or malicious code previously. Depending on the crypto-currency, you can even see how many ransoms were paid, and what the amounts were.
Just to be clear, our focus is on historical evidence. If you're an elite malware analyst looking for the freshest samples, you probably won't get great value here. We update the data quarterly at this time, which is more than fast enough for our clients building actuarial tables. If you know what hashes and crypto-currencies are already, jump ahead to using your API Key.
Nearly 10.
We have many ways of finding new samples, and learning the associated ransom addresses. These range from getting malware samples, reports from insurance partners, or ransom negotiators. In some cases we have had a report that an account is used for ransomware, but we don't have file evidence. Where this is the case, we include the address, but encourage some caution. If it has an associated matching file hash, you can be much more confident that it ransomware.
It is always possible that we make a mistake, or that a particular address is a free software donation address embedded inside some other malware. If you find an address included in our database that you think should not be there (and we do make efforts to exclude software donation addresses), then please contact us at [email protected].
We can't be sure, but on a quarterly basis we update it with new data from both our live and historical investigations. We specifically thank Virus Share, Hatching, and PolySwarm for giving us access to historical and live streams of malware. Check them out.
Cryptocurrencies are digital currencies that allow the transfer of funds over the internet or via mobile phone. While they are certainly not the only form of payment seen in ransomware, they are common enough to be useful for risk analysis purposes. Currently we support Bitcoin, whose ticker symbol is BTC. Some crypto-currencies have public transaction ledgers, like Bitcoin. This allows us to see the ransoms paid, and thus to improve our estimation of the risk of ransomware. Other crypto-currencies are privacy preserving, which means we cannot view their transactions. However, there are still interesting statistics that can be gleaned by how many malware samples they can be found in.
A hash is a unique, fixed-length string that is the result of cryptographic algorithms, such as Message Digest 5 (MD5) or Secure Hash Algorithm 1 (SHA-1). Hashes can tell you whether two files are identical without revealing the contents of the files.
RansomCoinDB supports MD5, SHA-1, SHA-256, and TLSH.
Your API key is displayed on the Settings page, and is 64 character hex value. It must be used in the HTTP request header as an x-api-key.
So for example, with CURL you would use the key like this:
curl -X GET "https://ransomcoindb.concinnity-risks.com/help" -H "accept: application/json" -H "x-api-key: insert_your_sixty_four_char_hex_api_key_here"
If you wanted to access the base API endpoint with Python3:
import requests
api_key = 'insert_your_sixty_four_char_hex_api_key_here'
response = requests.get(
'https://ransomcoindb.concinnity-risks.com/api/v2',
headers={'accept': 'application/json','x-api-key': api_key},
)
response.content
b'{"help":"\\n# About\\n\\nThis app provides a simple RESTful API for the ransomcoin DB.\\n
Please see http://marjorie.lo-res.org:8000/docs\\n\\nExample:\\n```\\n
GET /api/v2/bin2btc/all?limit=1000&offset=1000\\n```\\n
Will return all results of the bin2btc table starting at offset 1000 and only send back 1000 results.\\n
The default value for limit is 1000.\\n\\n\\n
Error codes:\\n
HTTP 200 --> OK\\n
HTTP 204 --> OK but no results\\n
HTTP 401 --> not authorized\\n
HTTP 408 --> timeout\\n
HTTP 404 --> invalid endpoint or request\\n
HTTP 500 --> internal server error\\n"}
MD5 is a 128-bit (16-byte) hash value typically 32 digits long.
SHA-1 is a 160-bit (20-byte) hash value typically 40 digits long.
SHA-256 is a 256-bit (32-byte) hash value typically 64 digits long.
TLSH can generate 70 or 134 characters hash string, and we use the 70 character string. The important feature of this hash as opposed to the other three, is that it is a locally sensitive hash. In other words, if there are two files with only slight edits, the distance function will return a low number. This means it can be used to see how similar two files are to each other.
Bitcoin addresses can be 25-34 characters in length, and can be thought of as an account number. Using such an address, you can see the transactions into and out of that account.
The dates presented in transactions are in YYYY-MM-DD HH:mm:ss format. You can also filter transactions before and after with the same format.
The amount of Bitcoin exchanged.
The hourly US dollar conversion price of Bitcoin at the time of transaction.
The hourly Euro conversion price of Bitcoin at the time of transaction.
No parameters needed. Just use it to explore the API while programming.
No parameters needed. Just use it to explore the API while programming
Returns all stored cryptocurrency transactions (up to {limit} entries at once).
GET Parameters:
limit .... how many entries should we return?
offset.... starting at {offset}
before.... only show transactions before this timestamp. Format: 'YYYY-MM-DD HH:mm:ss"
after..... only show transactions after this timestamp. Format: 'YYYY-MM-DD HH:mm:ss"
Output (JSON):
timestamp
from_btc address.. the sender
to_btc address ... the receiver
BTC amount
EUR amount as of the timestamp
USD amount as of the timestamp
This endpoint selects all transactions with the given BTC address as recipient.
Input:
{btc} ... the receiver's BTC address
GET Parameters:
limit .... how many entries should we return?
offset.... starting at {offset}
before.... only show transactions before this timestamp. Format: 'YYYY-MM-DD HH:mm:ss"
after..... only show transactions after this timestamp. Format: 'YYYY-MM-DD HH:mm:ss"
Output (JSON):
timestamp
from_btc address.. the sender
to_btc address ... the receiver
BTC amount
EUR amount as of the timestamp
USD amount as of the timestamp
This endpoint selects all transactions with a receiving BTC address in at least one file that we know of. That file is usually a binary such as an exe, pe file. Sometimes it is a phishing document like a docx or an html page. occasionally it is a ransomnote. Usually this doesn't matter to risk research, the point is that we can get you evidence that this was associated with ransomware for all matches. Use matches when you want to be certain that the data was associated with a crime rather than when you want to look at what is suspicious addresses that might turn out later to be benign.
GET Parameters:
limit .... how many entries should we return?
offset.... starting at {offset}
before.... only show transactions before this timestamp. Format: 'YYYY-MM-DD HH:mm:ss"
after..... only show transactions after this timestamp. Format: 'YYYY-MM-DD HH:mm:ss"
Output (JSON):
timestamp
from_btc address.. the sender
to_btc address ... the receiver
BTC amount
EUR amount as of the timestamp
USD amount as of the timestamp
This endpoint allows you to fetch all binary samples to BTC address mappings.
GET Parameters:
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON):
BTC ......... bitcoin address
corpus_id ... The corpus where the binaries came from
TLSH ........ the trend micro fuzzy hash (see https://github.com/trendmicro/tlsh)
md5, sha1, sha256 .... the hashes of the binary
This endpoint allows you to fetch all binary samples associated with a certain BTC address.
GET Parameters:
btc ... the BTC address associated with the binary
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON):
BTC ......... bitcoin address
corpus_id ... The corpus where the binaries came from
TLSH ........ the trend micro fuzzy hash (see https://github.com/trendmicro/tlsh)
md5, sha1, sha256 .... the hashes of the binary
This endpoint allows you to fetch all BTC addresses associated with a certain binary (given by the md5).
GET Parameters:
md5 ...... md5 hash of the binary
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON):
BTC ......... bitcoin address
corpus_id ... The corpus where the binaries came from
TLSH ........ the trend micro fuzzy hash (see https://github.com/trendmicro/tlsh)
md5, sha1, sha256 .... the hashes of the binary
This endpoint allows you to fetch all BTC addresses associated with a certain binary (given by the sha1).
GET Parameters:
sha1 ..... sha1 hash of the binary
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON):
BTC ......... bitcoin address
corpus_id ... The corpus where the binaries came from
TLSH ........ the trend micro fuzzy hash (see https://github.com/trendmicro/tlsh)
md5, sha1, sha256 .... the hashes of the binary
GET Parameters:
sha256 ..... sha256 hash of the binary
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON):
BTC ......... bitcoin address
corpus_id ... The corpus where the binaries came from
TLSH ........ the trend micro fuzzy hash (see https://github.com/trendmicro/tlsh)
md5, sha1, sha256 .... the hashes of the binary
This endpoint allows you to fetch all BTC addresses associated with a file in our database. For example, you could find the highest earning binary of all time.
GET Parameters:
currency.... The currency output format which should be shown, either "USD" or "EUR" or "BTC". Defaults to USD.
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON):
BTC ......... bitcoin address
corpus_id ... The corpus where the binaries came from
TLSH ........ the trend micro fuzzy hash (see https://github.com/trendmicro/tlsh)
md5, sha1, sha256 .... the hashes of the binary
This endpoint allows you to pivot over a BTC address and calculate all binaries which contain this BTC address, the corresponding BTC addresses and the total amount (in USD, EUR, BTC) of all related transactions belonging to ransomware connected to this BTC address.
GET Parameters:
btc ...... The BTC address associated with the binary
currency.. The currency output format which should be shown, either "USD" or "EUR" or "BTC". Defaults to USD.
limit .... how many entries should we return?
offset.... starting at {offset}
Output (JSON): A list of :
{ 'address': , 'amount': , 'currency': } records. Where coin is the coin address associated by the pivot BTC address, and amount is the total inflowing amount (in the requested currency) to that particular BTC address.