GET /api/v2/combinations/interrogate

POST /api/v2/combinations/interrogate

NOTE: If you’re migrating from the v1 API, read the following guidelines to adjust your requests

How it works

This method allows you to interrogate Fingerbank with different network patterns (DHCP informations, HTTP+UPnP User-Agents, MAC address, etc) and obtain the device that matches the most those attributes. It will also provide a confidence level (score) on a scale of 100 for the patterns you provided.

Providing more attributes will provide more accurate matching with a higher score. See the following page for a detailed example.

Scoring

The score is based on a scale of 0 to 100 and represents the confidence level Fingerbank has on the result it is providing (device and version)

Computation of the score:

The score is computed by passing the attributes through all the patterns known by Fingerbank. Once all the patterns have been extracted, they are put together by which device that pattern matches. Fingerbank then analyses which device has the strongest patterns (for example matching DHCP informations has more weight than an HTTP User-Agent since the latest is easily spoofable).

Once it has found the device with the strongest matching patterns, it weights the score using the following rules:

  • 33% of the score is related to the top scoring pattern that has matched the device itself.
  • 33% of the score is related to the top scoring pattern that has matched the device itself or a device its related to (parent or derivation)
  • 25% of the score is related to the ratio of patterns that have matched the device or a device its related to versus compared to the total amount of patterns that have matched.
  • 9% of the score is related to the amount of patterns that have matched the device
  • Then this score can be decreased by up to 27% by the top competing pattern that has matched (not related to the device)

Interpretation of the score:

  • Lower than 30: very little confidence on the result that was returned.
  • Between 31 and 50: Moderate confidence on the result that was returned. Either the attributes didn’t match patterns on attributes that provide confidence (DHCP informations, TCP fingerprinting, etc) or the attributes matched competing patterns (ex: matched both Windows and Android patterns).
  • Between 51 and 75: High confidence on the result that was returned. The result will be based on at least an attribute that provide confidence and didn’t or almost didn’t match competing patterns.
  • Higher than 76: Very high confidence on the result that was returned. The result will be based on multiple attributes that provide confidence and didn’t or almost didn’t match competing patterns.

Supported Formats

Request : application/json, Response : application/json

Errors

Code Description
401 This request is unauthorized. Either your key is invalid or wasn't specified.
403 This request is forbidden. Your account may have been blocked.
429 The amount of requests per minute has been exceeded. All accounts (even the unlimited ones) are rate limited to 250 requests per minute unless agreed otherwise with Inverse.
502 No API backend was able to process the request. The system may be overloaded, in maintenance or experiencing an issue. Retrying shortly after should work.
404 No device was found the the specified combination. It will be added to the unknown combinations list if you are part of the approved API submitters.

Examples

Example body:
{"dhcp_fingerprint":"1,15,3,6,44,46,47,31,33,121,249,43"}
Example response:
{
    "device": {
        "created_at": "2014-09-09T15:09:51.000Z",
        "id": 33,
        "name": "Microsoft Windows Kernel 6.0",
        "parent_id": 7536,
        "parents": [
            {
                "created_at": "2015-09-18T12:51:27.000Z",
                "id": 7536,
                "name": "Microsoft Windows Kernel 6.x",
                "parent_id": 1,
                "updated_at": "2015-09-22T08:11:35.000Z",
                "virtual_parent_id": null
            },
            {
                "created_at": "2014-09-09T15:09:50.000Z",
                "id": 1,
                "name": "Windows OS",
                "parent_id": 16879,
                "updated_at": "2017-09-20T15:46:53.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": "2015-09-18T12:53:32.000Z",
        "virtual_parent_id": null
    },
    "device_name": "Operating System/Windows OS/Microsoft Windows Kernel 6.x/Microsoft Windows Kernel 6.0",
    "score": 75,
    "version": "Vista/Server 2008"
}
Example using curl using DHCPv4 fingerprint:
curl -X GET -d "{\"dhcp_fingerprint\":\"1,15,3,6,44,46,47,31,33,121,249,43\"}" --header "Content-type: application/json" https://api.fingerbank.org/api/v2/combinations/interrogate?key=
Example using curl without a body payload:
curl 'https://api.fingerbank.org/api/v2/combinations/interrogate?dhcp_fingerprint=1,15,3,6,44,46,47,31,33,121,249,43&key='
Example using curl using DHCPv4 fingerprint, User-Agent and MAC address:
curl -X GET -d "{\"dhcp_fingerprint\":\"1,121,3,6,15,119,252\", \"user_agents\":[\"Mozilla/5.0 (iPad; CPU OS 9_3_5 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13G36 Safari/601.1\"], \"mac\": \"e0b9ba88158a\"}" --header "Content-type: application/json" https://api.fingerbank.org/api/v2/combinations/interrogate?key=
Example using curl with behavioral analysis parameters:
curl  -X GET -d "{\"dhcp_fingerprint\":\"1,15,3,6,44,46,47,31,33,121,249,43\", \"destination_hosts\":[\"updates.microsoft.com\"], \"mdns_services\":[\"_printer._tcp.local\"]}" --header "Content-type: application/json" 'https://api.fingerbank.org/api/v2/combinations/interrogate?key='

Params

Param name Description
key
required

Your API key

Validations:

  • Must be a String


Metadata:
Type: URL
debug
optional

Whether or not to add additionnal debug information in the response. ‘on’ activates it

Validations:

  • Must be a String


Metadata:
Type: URL
user_agents
optional

The HTTP User Agents of the endpoint as seen in the User-Agent header of the HTTP requests the endpoint does.

Validations:

  • Must be an array of String


Metadata:
Type: payload
Limit: The amount of elements must be limited to 5 elements. If not, only the 5 first
  will be taken into account in the discovery process.
dhcp_fingerprint
optional

The DHCP fingerprint of the endpoint. Must be a comma-delimited list of numbers following this standard: 1,2,3,4,5,6,7. The order of the options must be the same as in the DHCP packet and nothing else than commas and numbers are allowed in this field.

Validations:

  • Must be a String


Metadata:
Type: payload
Example: '128,229,32,44,52,64,17'
dhcp6_fingerprint
optional

The DHCPv6 fingerprint of the endpoint. Must be a comma-delimited list of numbers following this standard: 1,2,3,4,5,6,7. The order of the options must be the same as in the DHCP packet and nothing else than commas and numbers are allowed in this field.

Validations:

  • Must be a String


Metadata:
Type: payload
Example: '24,25,58,24'
dhcp_vendor
optional

The DHCP vendor of the endpoint as seen in the DHCP packet.

Validations:

  • Must be a String


Metadata:
Type: payload
Example: MSFT 5.0
dhcp6_enterprise
optional

The DHCPv6 enterprise of the endpoint. Must be the identifier present in the packet (a number)

Validations:

  • Must be a String


Metadata:
Type: payload
mac
optional

The MAC address of the device following any of the following formats: 001122334455, 00-11-22-33-44-55, 00:11:22:33:44:55

Validations:

  • Must be a String


Metadata:
Type: payload
destination_hosts
optional

The destination hosts (domains) this endpoint has send data to

Validations:

  • Must be an array of String


Metadata:
Type: payload
Limit: The amount of elements must be limited to 5 elements. If not, only the 5 first
  will be taken into account in the discovery process.
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.
mdns_services
optional

The MDNS services that this endpoint has advertised

Validations:

  • Must be an array of String


Metadata:
Type: payload
Limit: The amount of elements must be limited to 5 elements. If not, only the 5 first
  will be taken into account in the discovery process.
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.
upnp_user_agents
optional

The UPnP User Agents (USER-AGENT header) that this endpoint has advertised

Validations:

  • Must be an array of String


Metadata:
Type: payload
Limit: The amount of elements must be limited to 5 elements. If not, only the 5 first
  will be taken into account in the discovery process.
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.
upnp_server_strings
optional

The UPnP Server strings (SERVER header) that this endpoint has advertised

Validations:

  • Must be an array of String


Metadata:
Type: payload
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.
tcp_syn_signatures
optional

The TCP SYN signatures detected for this endpoint. The signatures must follow the p0f standard.

Validations:

  • Must be an array of String


Metadata:
Type: payload
Limit: The amount of elements must be limited to 5 elements. If not, only the 5 first
  will be taken into account in the discovery process.
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.
Example: 4:128+0:0:1460:8192,2:mss,nop,ws,nop,nop,sok:df,id+:0
tcp_syn_ack_signatures
optional

The TCP SYN-ACK signatures detected for this endpoing. The signatures must follow the p0f standard.

Validations:

  • Must be an array of String


Metadata:
Type: payload
Limit: The amount of elements must be limited to 5 elements. If not, only the 5 first
  will be taken into account in the discovery process.
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.
Example: 4:128+0:0:1460:8192,2:mss,nop,ws,nop,nop,sok:df,id+:0
hostname
optional

The hostname of the endpoint.

Validations:

  • Must be a String


Metadata:
Type: payload
Behavioral data: This is behavioral data and will not be persisted to the Fingerbank
  database.

Returns

Code: 200

Description:

Device profiling result

Param name Description
device
required

The device object that was profiled using the input parameters

Validations:

  • Must be a Hash

device[can_be_more_precise]
required

Whether or not the result can be more precise than the one that is returned. This can be used as an indicator that the profiling result cannot be improved.

Validations:

  • Must be one of: true, false.

device[child_devices_count]
required

The amount of direct childs the device has

Validations:

  • Must be a Integer

device[child_virtual_devices_count]
required

The amount of virtual childs the device has

Validations:

  • Must be a Integer

device[created_at]
required

The date that the device was created in Fingerbank

Validations:

  • Must be a Date

device[id]
required

The numeric identifier of the device in Fingerbank

Validations:

  • Must be a Integer

device[name]
required

The name of the device

Validations:

  • Must be a String

device[parent_id]
required

The numeric identifier of the parent of this device

Validations:

  • Must be a Integer

device[parents]
required

A list of simple representations of the parents of this device

Validations:

  • Must be an Array of nested elements

device[parents][created_at]
required

The date that the device was created in Fingerbank

Validations:

  • Must be a Date

device[parents][id]
required

The numeric identifier of the device in Fingerbank

Validations:

  • Must be a Integer

device[parents][name]
required

The name of the device

Validations:

  • Must be a String

device[parents][parent_id]
required

The numeric identifier of the parent of this device

Validations:

  • Must be a Integer

device[parents][updated_at]
required

The date that the device was last updated in Fingerbank

Validations:

  • Must be a Date

device[parents][virtual_parent_id]
required

The numeric identifier of the virtual parent of this device (if any, defaults to null if there is none). Virtual parents are non-mandatory and will usually link a physical device (ex: Generic Android) with its operating system (Android OS)

Validations:

  • Must be a Date

device_name
required

The unique device name with all its hierarchy separated by the ‘/’ character

Validations:

  • Must be a String

manufacturer
required

Optional object that follows the exact same structure as the ‘device’ attribute of the response. When present, it will contain the manufacturer of the device that was profiled. For example, in the case of a Samsung Galaxy S8, this will contain the hardware manufacturer Samsung. This will only be true if enough information is provided to tie the Samsung Galaxy S8 result to Samsung and will not be present for that device if for example only the HTTP User-Agent is provided which doesn’t allow to tie the device to the manufacturer. In our current example tying the device to the manufacturer is done through the MAC address of the device.

Validations:

  • Must be a Hash

manufacturer[can_be_more_precise]
required

Whether or not the result can be more precise than the one that is returned. This can be used as an indicator that the profiling result cannot be improved.

Validations:

  • Must be one of: true, false.

manufacturer[child_devices_count]
required

The amount of direct childs the device has

Validations:

  • Must be a Integer

manufacturer[child_virtual_devices_count]
required

The amount of virtual childs the device has

Validations:

  • Must be a Integer

manufacturer[created_at]
required

The date that the device was created in Fingerbank

Validations:

  • Must be a Date

manufacturer[id]
required

The numeric identifier of the device in Fingerbank

Validations:

  • Must be a Integer

manufacturer[name]
required

The name of the device

Validations:

  • Must be a String

manufacturer[parent_id]
required

The numeric identifier of the parent of this device

Validations:

  • Must be a Integer

manufacturer[parents]
required

A list of simple representations of the parents of this device

Validations:

  • Must be an Array of nested elements

manufacturer[parents][created_at]
required

The date that the device was created in Fingerbank

Validations:

  • Must be a Date

manufacturer[parents][id]
required

The numeric identifier of the device in Fingerbank

Validations:

  • Must be a Integer

manufacturer[parents][name]
required

The name of the device

Validations:

  • Must be a String

manufacturer[parents][parent_id]
required

The numeric identifier of the parent of this device

Validations:

  • Must be a Integer

manufacturer[parents][updated_at]
required

The date that the device was last updated in Fingerbank

Validations:

  • Must be a Date

manufacturer[parents][virtual_parent_id]
required

The numeric identifier of the virtual parent of this device (if any, defaults to null if there is none). Virtual parents are non-mandatory and will usually link a physical device (ex: Generic Android) with its operating system (Android OS)

Validations:

  • Must be a Date

operating_system
required

Optional object that follows the exact same structure as the ‘device’ attribute of the response. When present, it will contain the most probable operating system for the device based on the result contained in the ‘device’ field of the response. For example, in the case of a Samsung Galaxy S8, this will contain the operating system Android OS. This will only be true if enough information is provided to tie the Samsung Galaxy S8 result to Android OS and will not be present for that device if for example only the hostname is provided which doesn’t allow to tie the device to the Android OS operating system. In our current example tying the device to the OS is done through the DHCP fields, HTTP User-Agent, etc.

Validations:

  • Must be a Hash

operating_system[can_be_more_precise]
required

Whether or not the result can be more precise than the one that is returned. This can be used as an indicator that the profiling result cannot be improved.

Validations:

  • Must be one of: true, false.

operating_system[child_devices_count]
required

The amount of direct childs the device has

Validations:

  • Must be a Integer

operating_system[child_virtual_devices_count]
required

The amount of virtual childs the device has

Validations:

  • Must be a Integer

operating_system[created_at]
required

The date that the device was created in Fingerbank

Validations:

  • Must be a Date

operating_system[id]
required

The numeric identifier of the device in Fingerbank

Validations:

  • Must be a Integer

operating_system[name]
required

The name of the device

Validations:

  • Must be a String

operating_system[parent_id]
required

The numeric identifier of the parent of this device

Validations:

  • Must be a Integer

operating_system[parents]
required

A list of simple representations of the parents of this device

Validations:

  • Must be an Array of nested elements

operating_system[parents][created_at]
required

The date that the device was created in Fingerbank

Validations:

  • Must be a Date

operating_system[parents][id]
required

The numeric identifier of the device in Fingerbank

Validations:

  • Must be a Integer

operating_system[parents][name]
required

The name of the device

Validations:

  • Must be a String

operating_system[parents][parent_id]
required

The numeric identifier of the parent of this device

Validations:

  • Must be a Integer

operating_system[parents][updated_at]
required

The date that the device was last updated in Fingerbank

Validations:

  • Must be a Date

operating_system[parents][virtual_parent_id]
required

The numeric identifier of the virtual parent of this device (if any, defaults to null if there is none). Virtual parents are non-mandatory and will usually link a physical device (ex: Generic Android) with its operating system (Android OS)

Validations:

  • Must be a Date

request_id
required

The unique identifier of the request

Validations:

  • Must be a String

score
required

The confidence level in the result that is provided. See the ‘Scoring’ section of this page for more details.

Validations:

  • Must be a Integer

version
required

The version of the device. When it cannot be found, an empty string is provided. Example: A Samsung Galaxy S8 running Android version 9.0.0 will have the value ‘9.0.0’ in the version field if the input data allowed Fingerbank to detect the version properly.

Validations:

  • Must be a String

Code: 404

Description:

Unknown device profiling result

Param name Description
errors
required

The errors that have occured

Validations:

  • Must be a Hash

errors[details]
required

An explanation on why the device profiling yielded an unknown result

Validations:

  • Must be a String

request_id
required

The unique identifier of the request

Validations:

  • Must be a String