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

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 750 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


Value:

Must be String


Metadata:
Type: URL
debug
optional

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


Value:

Must be 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.


Value:

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.


Value:

Must be 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.


Value:

Must be String


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

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


Value:

Must be 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)


Value:

Must be 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


Value:

Must be String


Metadata:
Type: payload
destination_hosts
optional

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


Value:

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


Value:

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


Value:

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


Value:

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.


Value:

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.


Value:

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.


Value:

Must be String


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