You can use the public version of Fingerbank in two different ways:
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.
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": ""
}
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+"
}
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+"
}
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.
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. |
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. |
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.
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.
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
|
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.
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.