Usage

You can use the public version of Fingerbank in two different ways:

Online

Query the fingerprints online.

API

Use the free public API. Register and you'll get a free key that you can use to make API calls from your applications. See the API documentation.

Examples

Query using a DHCP fingerprint

Input
curl \
  -X GET \
  -H "Content-Type: application/json" \
  'https://api.fingerbank.org/api/v2/combinations/interrogate?key=YOURFINGERBANKAPIKEY' \
  -d '{"dhcp_fingerprint":"1,33,3,6,12,15,28,51,58,59,119"}'
                      
Output
{
    "device": {
        "created_at": "2017-09-18T17:12:14.000Z",
        "id": 33453,
        "name": "Android OS",
        "parent_id": 33452,
        "parents": [
            {
                "created_at": "2017-09-18T17:08:09.000Z",
                "id": 33452,
                "name": "Google OS",
                "parent_id": 16879,
                "updated_at": "2017-09-20T15:46:34.000Z",
                "virtual_parent_id": null
            },
            {
                "created_at": "2017-09-14T18:41:06.000Z",
                "id": 16879,
                "name": "Operating System",
                "parent_id": null,
                "updated_at": "2017-09-18T16:33:18.000Z",
                "virtual_parent_id": null
            }
        ],
        "updated_at": "2017-09-18T17:12:14.000Z",
        "virtual_parent_id": null
    },
    "device_name": "Operating System/Google OS/Android OS",
    "score": 75,
    "version": ""
}
We get that it is an Android device, with a score of 75.

Query using a DHCP fingerprint and a DHCP vendor

Input
curl \
  -X GET \
  -H "Content-Type: application/json" \
  'https://api.fingerbank.org/api/v2/combinations/interrogate?key=YOURFINGERBANKAPIKEY' \
  -d '{"dhcp_fingerprint":"1,33,3,6,12,15,28,51,58,59,119","dhcp_vendor":"dhcpcd-5.5.6"}'
Output
{
    "device": {
        "created_at": "2017-09-18T17:12:14.000Z",
        "id": 33453,
        "name": "Android OS",
        "parent_id": 33452,
        "parents": [
            {
                "created_at": "2017-09-18T17:08:09.000Z",
                "id": 33452,
                "name": "Google OS",
                "parent_id": 16879,
                "updated_at": "2017-09-20T15:46:34.000Z",
                "virtual_parent_id": null
            },
            {
                "created_at": "2017-09-14T18:41:06.000Z",
                "id": 16879,
                "name": "Operating System",
                "parent_id": null,
                "updated_at": "2017-09-18T16:33:18.000Z",
                "virtual_parent_id": null
            }
        ],
        "updated_at": "2017-09-18T17:12:14.000Z",
        "virtual_parent_id": null
    },
    "device_name": "Operating System/Google OS/Android OS",
    "score": 75,
    "version": "4+"
}
We now see it's an Android 4+ device, with the same score.

Query using a DHCP fingerprint, a DHCP vendor and a User Agent

Input
curl \
  -X GET \
  -H "Content-Type: application/json" \
  'https://api.fingerbank.org/api/v2/combinations/interrogate?key=YOURFINGERBANKAPIKEY' \
  -d '{"dhcp_fingerprint":"1,33,3,6,12,15,28,51,58,59,119","dhcp_vendor":"dhcpcd-5.5.6","user_agents":["Mozilla/5.0 (Linux; Android 5.0.2; SM-G920F Build/LRX22G; wv) AppleWebK"]}'
Output
{
    "device": {
        "created_at": "2015-04-16T19:41:45.000Z",
        "id": 6368,
        "name": "Galaxy S6",
        "parent_id": 3809,
        "parents": [
            {
                "created_at": "2014-11-13T12:45:57.000Z",
                "id": 3809,
                "name": "Samsung Android",
                "parent_id": 202,
                "updated_at": "2015-04-24T03:09:27.000Z",
                "virtual_parent_id": null
            },
            {
                "created_at": "2014-09-09T15:09:52.000Z",
                "id": 202,
                "name": "Generic Android",
                "parent_id": 11,
                "updated_at": "2017-09-20T21:28:38.000Z",
                "virtual_parent_id": 33453
            },
            {
                "created_at": "2014-09-09T15:09:50.000Z",
                "id": 11,
                "name": "Phone, Tablet or Wearable",
                "parent_id": null,
                "updated_at": "2017-09-18T14:58:01.000Z",
                "virtual_parent_id": null
            }
        ],
        "updated_at": "2015-04-20T06:39:02.000Z",
        "virtual_parent_id": null
    },
    "device_name": "Phone, Tablet or Wearable/Generic Android/Samsung Android/Galaxy S6",
    "score": 81,
    "version": "4+"
}
Now we've got an exact match with a high score for a Samsung Galaxy S6 phone running Android 4+.

v1 Migration Guide

Migrating from the first version of the API won't require much changes to the requests but may certainly require changes on the interpretation you do of the responses you get. Given devices have been reorganized and now have virtual parents and derivations, simply relying on the parents to see if devices are related isn't enough anymore. See the details below on how to adjust to the new structure.

Request parameters changed

Parameter Status Description
behavioral_analysis removed This parameter isn't used anymore as all requests in v2 will perform behavioral analysis of the attributes that are sent in the request.
user_agent removed This parameter has been removed as the API now support receiving multiple HTTP User-Agents via the user_agents parameter.

Response parameters changed

Parameter Status Description
combination_id removed This parameter isn't sent anymore as not all of the attributes are persisted (particularly the behavioral patterns). You shouldn't rely on this attribute anymore.
score maxed to 100 This parameter is now maxed to 100 and represents the confidence level based on a various conditions. See the API documentation for details.

Changes to the devices hierarchy

The devices in v1 were organized in a tree where a device had a single branch that would lead to its top level parent, so for example to determine an LG G6 phone was an Android, you simply had to look if his parents included Generic Android. In v2, it is a bit more complex than that since devices can derive from each other and the branches that lead to all the parents the device has can split.

In order to simplify the process of discovering if a device is the child or derived from another device, we provide an API call to which you provide the two device IDs. This way using the device ID you received in the interrogate reply, you can simply know if that device is a more precise form of the device that interests you.

Example

You have an application that uses Fingerbank to determine if devices you are seeing are Android devices. Like before, you will call /combinations/interrogate to obtain the most accurate device given the set of attributes you have for that device.

Here is the shortened reply you will now receive in v2:

{
    "device": {
        "id": 12658,
        "name": "LG G6",
        "parent_id": 2805,
        "parents": [
            ... list of parents ...
        ],
        "virtual_parent_id": null
    },
    "device_name": "Phone, Tablet or Wearable/Generic Android/LGE Android/LG G6",
    "score": 31,
    "version": "7.0"
}
                

From this reply, we should now take the returned device ID (device.id) and match it against 33453 which represents all devices that run Android (see below for other common device IDs). In order to know if 12658 is related to 33453, we use

/devices/12658/is_a/33453

which will tell us if that device is a child, virtual child or a derivation of 33453.

Here is an example using cURL:

$ curl https://api.fingerbank.org/api/v2/devices/12658/is_a/33453?key=YOUR_FINGERBANK_KEY

{
    "result": true,
    "message": "Phone, Tablet or Wearable/Generic Android/LGE Android/LG G6 is a virtual child of Operating System/Google OS/Android OS"
}
                

As you can see, you can rely on the result attribute in the reply to validate it and use the content of message to have an explanation on how the devices are related.

Some common checks

Is the device an Android? GET /api/v2/devices/:device_id/is_a/33453
Is the device a BlackBerry? GET /api/v2/devices/:device_id/is_a/33471
Is the device running iOS? GET /api/v2/devices/:device_id/is_a/33450
Is the device running Linux? GET /api/v2/devices/:device_id/is_a/5
Is the device running Windows? GET /api/v2/devices/:device_id/is_a/1

Database download

The second version of the API removes the distribution of the SQLite3 database as it became very hard to scale it to the amount of data Fingerbank was keeping as it grew from 15MB to 1.9GB since fingerbank.inverse.ca was launched in 2014. This data is still kept by Fingerbank for continuous improvement of our device profiling rules but isn't distributed anymore. This database also wasn't adapted to the new behavioral analysis functionality as it will exponentially increment the amount of data Fingerbank is seeing.

Also, since Fingerbank is now able to perform cloud-based analysis of the TCP fingerprints through the Fingerbank Collector, it has discontinued the distribution of its p0f map.

Submitting Fingerprints

When you query the Fingerbank database using the API, if this combination of data is unknown to Fingerbank, it will be automatically added to the Fingerbank database.

You can also submit manually your information using our Web interface.