Skip to main content

Fingerbank Data Source

Follow the instructions below to create a new data flow that ingests data from a Fingerbank source in Nexla.
fingerbank_api.png

Fingerbank

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Fingerbank connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Fingerbank instance, and click Next; or, create a new Fingerbank credential for use in this flow.

  3. In Nexla, Fingerbank data sources can be created using pre-built endpoint templates, which expedite source setup for common Fingerbank endpoints. Each template is designed specifically for the corresponding Fingerbank endpoint, making source configuration easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Fingerbank sources can also be configured manually, allowing you to ingest data from Fingerbank endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Fingerbank endpoints. Each template is designed specifically for the corresponding Fingerbank endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    Retrieve Full Database Dump

    This endpoint fetches all information about all devices in the Fingerbank database. Use this endpoint when you need to access complete device information, device databases, or device identification data from Fingerbank.

    • Enter the fields you want to include in the dump in the Fields field. This should be a comma-delimited list of fields. Allowed fields are: id, name, parent_id, virtual_parent_id, details. The default value is id,name,parent_id,virtual_parent_id,details if not specified.

    • The endpoint uses GET requests to https://api.fingerbank.org/api/v2/devices/base_info?key={api_key}&fields={fields} where {api_key} is your API Key from the credential configuration and {fields} is the Fields you provide. The endpoint URL is automatically constructed based on the Fingerbank API base URL, the API key, and the fields.
    • The endpoint does not use pagination and returns all device information in a single request.
    • The endpoint will return all device information in the Fingerbank database. The response data is extracted from the root-level array in the API response ($[*]), with each device record processed individually.

    The Fields parameter should be a comma-delimited list of allowed field names: id, name, parent_id, virtual_parent_id, details. The endpoint uses a static URL (iteration.type: static.url) and does not require pagination. The response data path is $[*], which extracts all items from the root-level array in the API response. For detailed information about retrieving full database dumps, see the Fingerbank API documentation.

    Interrogate Fingerbank DB with DHCP info

    This endpoint interrogates Fingerbank with DHCP information and obtains the device that matches the most of those attributes. Use this endpoint when you need to identify devices based on DHCP fingerprints or obtain device information from DHCP data.

    • Enter the DHCP fingerprint in the DHCP Fingerprint field. This 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. The default value is 128,229,32,44,52,64,17 if not specified.

    • The endpoint uses GET requests to https://api.fingerbank.org/api/v2/combinations/interrogate?key={api_key}&dhcp_fingerprint={dhcp_fingerprint} where {api_key} is your API Key from the credential configuration and {dhcp_fingerprint} is the DHCP Fingerprint you provide. The endpoint URL is automatically constructed based on the Fingerbank API base URL, the API key, and the DHCP fingerprint.
    • The endpoint does not use pagination and returns the matching device information in a single request.
    • The endpoint will return the device that matches the most of the DHCP attributes. The response data is extracted from the root-level object in the API response ($), and Nexla will process the entire response structure.

    The DHCP Fingerprint must be a comma-delimited list of numbers following the standard format. The order of the options must be the same as in the DHCP packet and nothing else than commas and numbers are allowed. The endpoint uses a static URL (iteration.type: static.url) and does not require pagination. The response data path is $, which extracts the entire root-level object from the API response. For detailed information about interrogating with DHCP information, see the Fingerbank API documentation.

    Interrogate Fingerbank DB with DHCP info from Lookup

    This endpoint interrogates Fingerbank with DHCP information stored in a Nexla lookup and obtains the device that matches the most of those attributes. Use this endpoint when you need to identify devices based on DHCP fingerprints stored in a Nexla lookup table.

    • Select the Nexla lookup that contains DHCP Fingerprints to iterate over from the Lookup for fetching DHCP Fingerprints dropdown menu. This is the Nexla lookup that contains DHCP Fingerprints to iterate over.

    • Enter the DHCP Fingerprint column name in the lookup in the DHCP Fingerprint column name in Lookup field. This is the column name in the lookup that contains the DHCP Fingerprint values.

    • The endpoint uses a two-step process: first, it iterates over the Nexla lookup to retrieve DHCP fingerprints, then it makes GET requests to https://api.fingerbank.org/api/v2/combinations/interrogate?key={api_key}&dhcp_fingerprint={dhcp_fingerprint} for each DHCP fingerprint from the lookup. The endpoint URL is automatically constructed based on the Fingerbank API base URL, the API key, and the DHCP fingerprint from the lookup.
    • The endpoint does not use pagination and returns the matching device information for each DHCP fingerprint in a single request per fingerprint.
    • The endpoint will return the device that matches the most of the DHCP attributes for each DHCP fingerprint in the lookup. The response data is extracted from the root-level object in the API response ($), and Nexla will process the entire response structure for each lookup entry.

    This endpoint requires a Nexla lookup table containing DHCP Fingerprints. The endpoint iterates over the lookup table and makes API requests for each DHCP fingerprint found in the lookup. The DHCP Fingerprint column name should match the column name in your lookup table. The endpoint uses a lookup iteration (iteration.type: data.map.key.queue) followed by a static URL (iteration.type: static.url) for each lookup entry. The response data path is $, which extracts the entire root-level object from the API response. For detailed information about interrogating with DHCP information, see the Fingerbank API documentation.

    Get Device Information

    This endpoint gets the detailed information about a specific device. Use this endpoint when you need to access detailed device information, device details, or device identification data for a specific device ID from Fingerbank.

    • Enter the Device ID for which you want to get information in the Device ID field. This is the unique identifier of the device for which you want to get detailed information.

    • The endpoint uses GET requests to https://api.fingerbank.org/api/v2/devices/{device_id}?key={api_key} where {device_id} is the Device ID you provide and {api_key} is your API Key from the credential configuration. The endpoint URL is automatically constructed based on the Fingerbank API base URL, the device ID, and the API key.
    • The endpoint does not use pagination and returns the complete device information in a single request.
    • The endpoint will return detailed information for the specified device. The response data is extracted from the root-level object in the API response ($), and Nexla will process the entire response structure.

    Device IDs can be obtained from other Fingerbank API endpoints, such as the "Retrieve Full Database Dump" endpoint, which returns all devices with their corresponding IDs. The endpoint uses a static URL (iteration.type: static.url) and does not require pagination. The response data path is $, which extracts the entire root-level object from the API response. For detailed information about getting device information, see the Fingerbank API documentation.

    Get Device Information from Lookup

    This endpoint gets the detailed information about devices stored in a Nexla lookup table. Use this endpoint when you need to access detailed device information for multiple device IDs stored in a Nexla lookup.

    • Select the Nexla lookup that contains Device IDs to iterate over from the Lookup for fetching Device IDs dropdown menu. This is the Nexla lookup that contains Device IDs to iterate over.

    • Enter the Device ID column name in the lookup in the Device ID column name in Lookup field. This is the column name in the lookup that contains the Device ID values.

    • The endpoint uses a two-step process: first, it iterates over the Nexla lookup to retrieve device IDs, then it makes GET requests to https://api.fingerbank.org/api/v2/devices/{device_id}?key={api_key} for each device ID from the lookup. The endpoint URL is automatically constructed based on the Fingerbank API base URL, the device ID from the lookup, and the API key.
    • The endpoint does not use pagination and returns the complete device information for each device ID in a single request per device ID.
    • The endpoint will return detailed information for each device ID in the lookup. The response data is extracted from the root-level object in the API response ($), and Nexla will process the entire response structure for each lookup entry.

    This endpoint requires a Nexla lookup table containing Device IDs. The endpoint iterates over the lookup table and makes API requests for each device ID found in the lookup. The Device ID column name should match the column name in your lookup table. The endpoint uses a lookup iteration (iteration.type: data.map.key.queue) followed by a static URL (iteration.type: static.url) for each lookup entry. The response data path is $, which extracts the entire root-level object from the API response. For detailed information about getting device information, see the Fingerbank API documentation.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Fingerbank data sources can be manually configured to ingest data from any valid Fingerbank API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Fingerbank sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom authentication headers or request parameters.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Fingerbank API from the Method pulldown menu. The most common methods are:

    • GET: For retrieving data from the API
    • POST: For sending data to the API or triggering actions
    • PUT: For updating existing data
    • PATCH: For partial updates to existing data
    • DELETE: For removing data

API Endpoint URL​

  1. Enter the URL of the Fingerbank API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters. Fingerbank API endpoints typically follow the pattern https://api.fingerbank.org/api/v2/{endpoint_path}.

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL. The endpoint requires API Key authentication via the key query parameter, which is handled automatically by your credential configuration. For detailed information about Fingerbank API endpoints and available APIs, see the Fingerbank API documentation.

Path to Data​

  1. Enter the JSON path that identifies the location of the relevant data within the API response in the Path to Data field. JSON paths use dot notation to navigate through nested JSON structures.

    • For example, if your API response has the structure [{"id": 1, "name": "..."}, ...], you would enter $[*] to extract all items from the root-level array.
    • Use $[*] to extract all items from a root-level array.
    • Use $ to extract the entire root-level object.

JSON paths are case-sensitive and must match the exact structure of your API response. Fingerbank API responses may use different structures like root-level arrays or objects depending on the endpoint. Use the Test button to verify that your JSON path correctly extracts the desired data from the API response.

Save the Data Source​

  1. Once all configuration steps have been completed, click the Save button to save your data source configuration.

  2. The data source will now be available in your data flow and will begin ingesting data according to the configured schedule and endpoint settings.