Graph API Version

/malware_families

This API call enables searching for malware families stored in ThreatExchange. With this call you can search for families by free text or all families created in a specific time window. Combinations of these query types are also allowed.

Parameters

The following query parameters are available (bold params are required):

  • access_token - The key for authenticating to the API, in the format <your-app-id>|<your-app-secret>. For example, if our app ID was 555 and our app secret aSdF123GhK, our access_token would be "555|aSdF123GhK".
  • limit - Defines the maximum size of a page of results. The maximum is 1,000.
  • text - Freeform text field with a value to search for. This can be a file hash or a string found in other fields of the objects.
  • sort_order - A given SortOrderType
  • sort_by - Sort search results by RELEVANCE or by CREATE_TIME. When sorting by RELEVANCE, your query will return results sorted by similarity against your text query.
  • strict_text - When set to 'true', the API will not do approximate matching on the value in text
  • since - Returns malware collected after a timestamp
  • until - Returns malware collected before a timestamp
  • fields - A list of fields to return in the response

Example query for all malware in a 24 hour window:

https://graph.facebook.com/v2.8/malware_families?access_token=555|aSdF123GhK&since=yesterday&until=now

Data returned:

{
  "data": [
    {
      "added_on": "2015-11-20T01:14:17+0000",
      "family_type": "PE_CERT_SHA256",
      "description": "Automatic family based on  PE Certificate SHA256 Hash",
      "malicious": "UNKNOWN",
      "name": "PE Certificate SHA256 Hash 0aaea3d8716662fa0113dcbc6e1ed471ad56d66afdd0f9c3b917f9c72ffbc732",
      "id": "1526384041014322"
    },
    ...
  ]
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "OTk5"
    },
    "next": "https://graph.facebook.com/malware_analyses?pretty=0&since=yesterday&until=now&limit=25&after=OTk5"
  }
}

The same query using a cURL:

curl -i -X GET \
 "https://graph.facebook.com/v2.8/malware_families?since=yesterday&until=now&access_token=555%7C1234"

The same query in Python:

import requests
import json
import ast
import urllib

app_id = '555' # Replace this with your app ID
app_secret = '1234' # Replace this with your app secret
start_time = 'yesterday'
end_time = 'now'

query_params = urllib.urlencode({
    'access_token' : app_id + '|' + app_secret,
    'since' : start_time,
    'until' : end_time
    })

r = requests.get('https://graph.facebook.com/v2.8/malware_families?' + query_params)

print json.dumps(ast.literal_eval(r.text), sort_keys=True,indent=4,separators=(',', ': '))

The same query in Java:

import java.io.InputStream;
import java.net.URL;
import java.net.URLConnection;
import java.util.Scanner;

public class MalwareFamilies {

    public final static void main(String[] args) throws Exception {
        String url = "https://graph.facebook.com/v2.8/malware_families?";
        String appID = "555"; // Replace this with your app ID
        String appSecret = "1234"; // Replace this with your app secret
        String since = "yesterday";
        String until = "now";

        String query = String.format("access_token=%s&since=%s&until=%s",
                appID + "|" + appSecret,
                since,
                until
                );
        URLConnection connection = new URL(url + query).openConnection();
        InputStream response = connection.getInputStream();
        System.out.print(convertStreamToString(response));
        response.close();
    }

    static String convertStreamToString(InputStream inputStream){
        Scanner scanner = new Scanner(inputStream).useDelimiter("\\A");
        return scanner.hasNext() ? scanner.next() : "";
    }

}

The same query in PHP:

<?php
  $appID = "555"; // Replace this with your AppID
  $appSecret = "1234"; // Replace this with your App Secret
  $since = 'yesterday';
  $until = 'now';
  $access_token = $appID . "|" . $appSecret;

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL,
    "https://graph.facebook.com/v2.8/malware_families?" .
    "access_token=" . $access_token .
    "&since=" . $since .
    "&until=" . $until);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  $response = curl_exec($ch);
  $json = json_encode(json_decode($response), JSON_PRETTY_PRINT);
  print($json . PHP_EOL);
  curl_close($ch);
?>